Okuma ve varlık yolları¶

Bir medya okuma yolu, tek bir yolu tek bir dosyaya çözümler ve o dosyayı döndürür. Görsel varlık ve saklanan nesne yolları, örnek keşfinin endpoints.media olarak yayımladığı temel URL'nin (https://tebhos.com/api/v1) altında bulunur. Medya vekili yolları sitenin kökünde (https://tebhos.com) bulunur.

Ortak yol sözleşmesi¶

Metotlar ve Yetkilendirme, buradaki her yolun kullandığı sözleşmeyi tanımlar. Buradaki hiçbir yolda istek sayısına dayalı hız sınırı yoktur. Medya yollarında hangi aralıkların tanındığını Bayt aralıkları tanımlar.

Ortak yanıtlar¶

endpoints.media altındaki her yol, kendi tablosundakilere ek olarak bu durumları da üretebilir. Hata gövdeleri Yanıtlar ve sınırlar bölümünde açıklanır.

Görsel varlık sözleşmesi¶

Görsel varlık, TEBHOS'un istenen boyut ve biçimde sunduğu saklanmış bir resimdir; örneğin kullanıcı avatarı veya sunucu simgesi. API, varlığın hash değerini sahip kaynak üzerinde döndürür (örneğin bir kullanıcıdaki avatar veya bir sunucudaki icon). URL; varlık sınıfını, sahibin kimliğini, bu hash'i ve bir dosya uzantısını birleştirir:

{endpoints.media}/{asset_class}/{owner_id}/{hash}.{ext}

https://tebhos.com/api/v1/avatars/1290847135893127168/3f9a0c5b7e2d41a6b8c9d0e1f2a3b4c5.webp?size=64

Hash'i tam olarak API'nin döndürdüğü şekilde kullanın. Görselden kendiniz bir hash hesaplamayın. a_ ile başlayan bir hash hareketli bir varlığı belirtir; önek hash'in parçasıdır ve URL'de korunmalıdır.

null bir hash, kaynağın özel bir görseli olmadığı anlamına gelir. Bu durumda TEBHOS'un sunacağı bir şey yoktur: istemciler varsayılan bir avatarı veya yer tutucuyu yerel olarak çizer ve medya isteği yapmaz.

Yol kuralları:

• owner_id bir tamsayı kimlik olmalıdır; aksi hâlde 400.
• ext çıktı biçimini seçer ve webp, png, jpg, jpeg veya gif (büyük/küçük harf duyarsız) olmalıdır; aksi hâlde 400. Uzantısız bir dosya adı saklanan biçimi döndürür.
• Hash, isteğe bağlı a_ önekinden sonra 1–64 ASCII harf ve rakamdan oluşmalıdır; aksi hâlde 400.

Boyut sınıflarını Varlık boyutu seçimi tanımlar.

Sorgu parametreleri¶

Diğer tüm sorgu parametreleri yok sayılır. Yol, seçilen temsil üzerinde bir Range kabul eder.

Yanıt¶

Ortak yanıtlar da uygulanır. Başarılı yanıtlar bir yıl önbelleğe alınır ve immutable olarak işaretlenir: yeni bir yükleme her zaman yeni bir hash, dolayısıyla yeni bir URL alır.

Kullanıcı avatarını getir¶

GET {endpoints.media}/avatars/{user_id}/{hash}.{ext}

Bir kullanıcının avatarını simge boyut sınıfında döndürür. Bot kullanıcıları ve webhook'lar aynı yolu kendi kimlikleriyle kullanır.

Kullanıcı afişini getir¶

GET {endpoints.media}/banners/{user_id}/{hash}.{ext}

Bir kullanıcının profil afişini afiş boyut sınıfında döndürür.

Sunucu simgesini getir¶

GET {endpoints.media}/server-icons/{guild_id}/{hash}.{ext}

Bir sunucu simgesini simge boyut sınıfında döndürür. hash, sunucunun icon değeridir.

Sunucu afişini getir¶

GET {endpoints.media}/server-banners/{guild_id}/{hash}.{ext}

Bir sunucu afişini afiş boyut sınıfında döndürür.

Sunucu davet arka planını getir¶

GET {endpoints.media}/server-invite-bg/{guild_id}/{hash}.{ext}

Sunucunun davet sayfasında gösterilen arka plan görselini afiş boyut sınıfında döndürür.

Sunucu gömme arka planını getir¶

GET {endpoints.media}/server-embed-bg/{guild_id}/{hash}.{ext}

Sunucu gömüldüğünde kullanılan arka plan görselini afiş boyut sınıfında döndürür.

Canlı oda afişini getir¶

GET {endpoints.media}/live-room-banners/{user_id}/{hash}.{ext}

Canlı bir ses odasının afişini afiş boyut sınıfında döndürür. API bu URL'yi oda nesnesinde tam olarak döndürür.

Saklanan nesneyi getir¶

GET {endpoints.media}/files/{key}

Saklanan herhangi bir nesneyi depolama anahtarıyla, isteğe bağlı olarak yeniden boyutlandırıp dönüştürerek döndürür. Bu, kanonik URL'si yüklenen dosya CDN'inde olan nesneler (ekler, özel emojiler ve çıkartmalar gibi) için yeniden boyutlandırma yoludur: anahtar, CDN URL'sinin yoludur.

https://cdn.tebhos.com/emojis/1290847135893127168/7b0f.../a61c9e2d.png
https://tebhos.com/api/v1/files/emojis/1290847135893127168/7b0f.../a61c9e2d.png?size=48

key, / içerebilir. Boş olan veya .. içeren bir anahtar 400 döndürür.

Sorgu parametreleri¶

size, width ve height negatif olmayan tamsayılar olmalıdır (sayısal olmayan bir değer 400 döndürür). Her biri boyut merdiveninde bir üst basamağa yuvarlanır ve anahtarın ilk bölümünden türetilen boyut sınıfıyla sıkıştırılır; bkz. Varlık boyutu seçimi. Hiçbir boyut verilmezse özgün boyut korunur.

format yoksa ve isteğin Accept başlığı image/webp içeriyorsa, bir PNG, JPEG veya GIF görseli WebP olarak döndürülür ve yanıtta Vary: Accept, Accept-Encoding bulunur. <img> öğelerini yükleyen tarayıcılar böyle bir Accept başlığı gönderir; Accept: */* gönderen bir indirme aracı özgün biçimi alır.

Yanıt¶

Bir görsel temsili bir yıl önbelleğe alınır (public, max-age=31536000; depolama anahtarları kendi benzersiz kimliklerini taşıdığından immutable olmadan).

PNG, JPEG, GIF veya WebP görseli olmayan bir nesne değiştirilmeden döndürülür: sorgu parametreleri yok sayılır, Range uygulanmaz, Content-Type anahtarın uzantısından türetilir (svg, mp3, ogg, m4a, wav, mp4, webm, aksi hâlde application/octet-stream), yanıt yedi gün önbelleğe alınır ve bir SVG'nin betik çalıştıramaması için Content-Security-Policy: default-src 'none'; style-src 'unsafe-inline'; sandbox taşır.

Ortak yanıtlar da uygulanır.

İmzalı harici medyayı getir¶

GET https://tebhos.com/external/{signature}/v2/{target}

Üçüncü taraf bir URL'deki medyayı TEBHOS medya vekili üzerinden getirir; böylece izleyiciler üçüncü taraf ana makineye hiçbir zaman doğrudan bağlanmaz. Yalnızca TEBHOS tarafından imzalanmış URL'ler vekil üzerinden aktarılır; vekil açık bir aktarıcı değildir. İmzalı bir URL'yi Harici bir URL'yi imzala ile alın ya da API'nin zaten döndürdüğü URL'yi kullanın (örneğin bir gömmenin vekil üzerinden verilen görsel URL'si).

Yol parametreleri¶

Desteklenen tek sürüm bölümü v2 değeridir. Yanlış bir sürüm, doğrulanamayan bir imza veya UTF-8'e çözülemeyen bir hedef 400 döndürür.

Hedef doğrulama¶

Vekil, getirmeden önce ve getirme sırasında şunları uygular:

• Hedef şeması http veya https olmalıdır.
• Ana makine localhost veya benzeri bir ad olmamalı; .local, .internal, .lan veya .localhost ile bitmemeli ve bir bulut metadata ana makinesi olmamalıdır.
• Ana makinenin çözümlendiği her adres genel olmalıdır. Loopback, özel, link-local (169.254.169.254 dahil), operatör sınıfı NAT, kıyaslama, belgeleme, çoklu yayın, genel yayın, belirtilmemiş, IPv6 benzersiz-yerel ve IPv4 eşlemeli özel adresler reddedilir.
• Yönlendirmeler en fazla 5 adım izlenir; özel bir ana makine adına yapılan yönlendirme getirmeyi durdurur.
• Kaynak sunucu 2xx ile ve image/, audio/, video/mp4, video/webm veya video/ogg ile başlayan bir Content-Type ile yanıt vermelidir.
• Boyut sınırını aşan bildirilmiş bir Content-Length, gövde okunmadan reddedilir; akış sırasında sınırı aşan bir gövde kesilir.

Sorgu parametreleri¶

format=webp olmadan kaynak baytlar değiştirilmeden aktarılır. format=webp değerinin durağan görseller, GIF'ler ve videolar için ne yaptığını İmzalı harici dönüşümler açıklar.

Yanıt¶

Doğrudan aktarılan bir yanıt kaynağın Content-Type değerini korur ve Cache-Control: public, max-age=86400 ile X-Content-Type-Options: nosniff taşır. Dönüştürülmüş bir yanıt Cache-Control: public, max-age=604800 ile image/webp olur.

OpenGraph meta verisini getir¶

GET https://tebhos.com/og?url={url}

Bir HTML sayfasını getirir ve OpenGraph ile Twitter Card meta verisini JSON olarak döndürür. Aynı hedef doğrulama uygulanır; tek fark, kaynağın text/html veya application/xhtml+xml ile yanıt vermesi gerekmesidir. Sayfanın yalnızca ilk 2 MiB'ı okunur.

Sayfa bir JSON oEmbed belgesine bağlantı veriyorsa ya da ana makine bilinen bir oEmbed sağlayıcısıysa (YouTube, Vimeo, SoundCloud, TikTok, Reddit), TEBHOS bu belgeyi de getirir ve sayfanın kendisinde eksik olduğunda yazar ve sağlayıcı alanlarını, site_name ve image değerlerini doldurmak için kullanır. Yanıt bir saat önbelleğe alınır (public, max-age=3600). Hatalar, text/plain bir nedenle 400 döndürür.

Mesajlardaki zengin bağlantı önizlemeleri için bu yolu doğrudan çağırmak yerine HTTP API unfurl davranışını kullanın.

Harici bir URL'yi imzala¶

GET /media/sign?url={url}

Üçüncü taraf bir URL'yi imzalı harici medya URL'sine dönüştüren HTTP API yolu (/api/v1 altında). Oturum açmış bir kullanıcı oturumu (Authorization: Bearer ...) gerektirir; bot token'ı 403 alır.

{
  "url": "https://tebhos.com/external/Q3Jx...Zw/v2/aHR0cHM6Ly9leGFtcGxlLmNvbS9jYXQuZ2lm"
}

İmzalama hedefi getirmez veya doğrulamaz; doğrulama imzalı URL okunduğunda yapılır.