GIFs

Um GIF é um item de mídia animada do provedor ativo da instância. Os resultados incluem URLs do provedor e URLs do Media Proxy.

Toda rota requer credencial de sessão. Um token de bot e uma credencial bearer OAuth2 são ambos recusados com 403 ACCESS_DENIED. Salvar meme por URL salva um resultado na coleção própria da conta.

Disponibilidade do provedor

klipy é o único nome de provedor que uma implantação vincula. Obter descoberta de instância o publica como o objeto provedor de GIF. Uma instância que não vinculou nenhuma chave de provedor recusa toda rota desta página com 403 FEATURE_TEMPORARILY_DISABLED. gif_enabled na disponibilidade de serviço indica se essa chave está vinculada, exceto quando um operador definiu o flag manualmente. Um cliente que lê gif_enabled como true pode ainda receber o 403.

Uma falha do provedor, uma requisição além do prazo e um payload de provedor ilegível retornam todos 503 SERVICE_UNAVAILABLE. O prazo é de 12 segundos em toda parte, exceto em Registrar um compartilhamento de GIF, que usa 3 segundos. Um operador pode alterar ambos.

Locale e país

Toda rota aceita um locale opcional extraído do registro de locales suportados, na query string nas rotas GET e no corpo de Registrar um compartilhamento de GIF. O padrão é en-US. Uma tag fora do registro falha com 400 INVALID_FORM_BODY.

O Decoding Chat também deriva um país de dois dígitos do endereço da requisição por geolocalização, e usa US quando a geolocalização não resolve nenhum. Nenhuma rota aceita o país como parâmetro, portanto um cliente não pode substituí-lo. Obter sugestões de busca de GIF é a única rota que o ignora.

Cabeçalhos do provedor

Toda resposta sob /gifs, /tenor e /klipy tem estes cabeçalhos, incluindo respostas de erro e respostas a um caminho não reivindicado por nenhuma rota. Os valores repetem o objeto provedor de GIF, portanto um cliente acompanha uma mudança de provedor sem refazer a busca em /.well-known/fluxer.

Campo	Tipo	Descrição
X-Fluxer-GIF-Provider¹	string	O nome de máquina do provedor ativo, que é `klipy` em toda implantação hoje
X-Fluxer-GIF-Provider-Display-Name¹	string	O nome do provedor que um cliente exibe
X-Fluxer-GIF-Provider-Attribution-Required¹	string	O literal `true` ou `false`, indicando se um cliente mostra a marca de atribuição do provedor

¹ Todos estão ausentes juntos enquanto a instância não vinculou nenhuma chave de provedor, que é a mesma condição que responde 403 FEATURE_TEMPORARILY_DISABLED

Atualidade dos resultados

O Decoding Chat armazena resultados em cache, portanto um resultado pode atrasar em relação ao provedor. Repetir uma requisição não força uma atualização.

Objeto GIF

Um objeto GIF é um item de mídia pertencente ao provedor ativo. Toda URL nele resolve bytes que o provedor hospeda.

Estrutura

Campo	Tipo	Descrição
id¹	string	O identificador estável do GIF no provedor
slug¹	string	O slug canônico usado para compartilhar o GIF ou resolvê-lo novamente
provider	string	O nome do provedor que produziu o GIF (1-32 caracteres)
title	string	O título que o provedor dá ao GIF
url	string	A URL da página do provedor para o GIF
src²	string	A URL de mídia direta do formato escolhido pelo servidor
proxy_src²	string	A URL do Media Proxy desse mesmo formato
width²	integer	A largura do formato escolhido em pixels
height²	integer	A altura do formato escolhido em pixels
media³	map[string, formato de mídia GIF object]	Os formatos com chave por nome de formato de mídia GIF
placeholder?⁴	?string	O placeholder thumbhash compacto renderizado enquanto o GIF carrega

¹ O provedor ativo escreve o mesmo slug em ambos, então id é o valor que Registrar um compartilhamento de GIF aceita

² Copiado da entrada webm de media quando o provedor retornou uma, e da primeira entrada retornada caso contrário

³ Vazio quando nenhum formato retornado pelo provedor pôde ser proxiado. Nenhuma chave é garantida, então um cliente verifica os nomes de formato que prefere em ordem e usa o primeiro presente

⁴ O provedor ativo não emite nenhum, então o campo está ausente de todo GIF que estas rotas retornam. Resolver URLs de GIF é a operação que produz um

Um GIF não tem snowflake nem timestamp de criação. id é o identificador próprio do provedor, então não ordena por tempo, e nenhuma outra rota do Decoding Chat o resolve.

Exemplo

{
  "id": "goat-plays-banjo-4",
  "slug": "goat-plays-banjo-4",
  "provider": "klipy",
  "title": "Goat Plays Banjo",
  "url": "https://klipy.com/gifs/goat-plays-banjo-4",
  "src": "https://static.example.com/goat-plays-banjo.webm",
  "proxy_src": "https://media.example.com/external/9f21c0/goat-plays-banjo.webm",
  "width": 220,
  "height": 229,
  "media": {
    "webm": {
      "src": "https://static.example.com/goat-plays-banjo.webm",
      "proxy_src": "https://media.example.com/external/9f21c0/goat-plays-banjo.webm",
      "width": 220,
      "height": 229
    },
    "tinygif": {
      "src": "https://static.example.com/goat-plays-banjo-tiny.gif",
      "proxy_src": "https://media.example.com/external/4ad117/goat-plays-banjo-tiny.gif",
      "width": 137,
      "height": 90
    }
  }
}

Objeto de categoria GIF

Um objeto de categoria GIF combina um termo de busca de categoria com um GIF de prévia para aquele termo.

Estrutura

Campo	Tipo	Descrição
name	string	O termo de busca que a categoria representa, traduzido para o locale solicitado
src¹	string	A URL de mídia direta do GIF de prévia
proxy_src¹	string	A URL do Media Proxy do GIF de prévia
gif	?GIF object	O GIF de prévia, ou null quando a busca de prévia não retornou nada

¹ Copiado do mesmo campo de gif, e string vazia quando gif é null

Para abrir a categoria, um cliente envia name como o q de Buscar GIFs.

Caminhos de fornecedor obsoletos

Os prefixos com nome de fornecedor servem os mesmos handlers que /gifs. Cada um responde exatamente como seu sucessor e tem os mesmos cabeçalhos do provedor.

Método	Caminho obsoleto	Sucessor
GET	`/v1/tenor/search`	Buscar GIFs
GET	`/v1/tenor/featured`	Obter GIFs em destaque
GET	`/v1/tenor/trending-gifs`	Obter GIFs em tendência
GET	`/v1/tenor/suggest`	Obter sugestões de busca de GIF
POST	`/v1/tenor/register-share`	Registrar um compartilhamento de GIF
GET	`/v1/klipy/search`	Buscar GIFs
GET	`/v1/klipy/featured`	Obter GIFs em destaque
GET	`/v1/klipy/trending-gifs`	Obter GIFs em tendência
GET	`/v1/klipy/suggest`	Obter sugestões de busca de GIF
POST	`/v1/klipy/register-share`	Registrar um compartilhamento de GIF

Uma resposta de um caminho obsoleto tem estes cabeçalhos adicionais.

Campo	Tipo	Descrição
Deprecation	string	O valor literal `true`
Link	string	O valor literal `</gifs>; rel="successor-version"`
Warning¹	string	Um aviso 299 nomeando o prefixo sucessor

¹ O valor exato é 299 - "Use /gifs/* instead - these vendor-specific paths are deprecated and will be removed."

O nome do fornecedor no caminho não seleciona nada. Uma requisição a /v1/tenor/search chega ao mesmo provedor ativo que /v1/gifs/search, e o campo provider de todo GIF que retorna nomeia esse provedor.

Buscar GIFs

GET/v1/gifs/search

Pesquisa o provedor ativo por GIFs correspondendo a uma consulta. Retorna no máximo 50 objetos GIF na ordem que o provedor retornou.

Parâmetros de consulta

Campo	Tipo	Descrição
q	string	O termo de busca (1-256 caracteres)
locale?	string	Um locale suportado, padrão `en-US`

O Decoding Chat não faz stemming, expansão nem correção ortográfica do termo. Um termo que não corresponde a nada retorna 200 com um array vazio.

Resposta

Status	Corpo	Condição
200	array[GIF object]	Resultados foram retornados, possivelmente como array vazio
400	resposta de erro	`q` ausente, vazio ou com mais de 256 caracteres, ou `locale` fora do registro, cada um retornando `INVALID_FORM_BODY`
403	resposta de erro	O chamador é um bot ou apresenta credencial bearer e retorna `ACCESS_DENIED`
403	resposta de erro	A conta tem ação obrigatória pendente e retorna `ACCOUNT_SUSPICIOUS_ACTIVITY`
403	resposta de erro	A instância não vinculou nenhuma chave de provedor e retorna `FEATURE_TEMPORARILY_DISABLED`
503	resposta de erro	O provedor falhou, a requisição superou o prazo ou o serviço `gifs` respondeu com payload ilegível, cada um retornando `SERVICE_UNAVAILABLE`

Rate limit

40 requisições por 10 segundos para cada usuário autenticado, no bucket gif:search.

Obter GIFs em destaque

GET/v1/gifs/featured

Retorna os GIFs em destaque do provedor e os termos de categoria oferecidos junto a eles.

Parâmetros de consulta

Campo	Tipo	Descrição
locale?	string	Um locale suportado, padrão `en-US`

Corpo da resposta

Campo	Tipo	Descrição
gifs¹	array[GIF object]	Os GIFs em destaque para o locale e país resolvidos
categories²	array[categoria GIF object]	Os termos de categoria oferecidos para o locale resolvido

¹ No máximo uma entrada. Obter GIFs em tendência é a rota que retorna uma listagem completa

² No máximo 50 entradas, deduplicadas por termo de busca e mantidas na ordem que o provedor retornou

O Decoding Chat resolve a lista de categorias contra o país US para toda requisição, qualquer que seja o país produzido por geolocalização, portanto dois chamadores em países diferentes recebem as mesmas categories e gifs diferentes. Uma categoria cuja prévia não retornou nada ainda é listada, com gif null e ambas as URLs vazias.

Resposta

Status	Corpo	Condição
200	corpo da resposta	GIFs em destaque e categorias foram retornados
400	resposta de erro	`locale` fora do registro e a requisição retorna `INVALID_FORM_BODY`
403	resposta de erro	O chamador é um bot ou apresenta credencial bearer e retorna `ACCESS_DENIED`
403	resposta de erro	A conta tem ação obrigatória pendente e retorna `ACCOUNT_SUSPICIOUS_ACTIVITY`
403	resposta de erro	A instância não vinculou nenhuma chave de provedor e retorna `FEATURE_TEMPORARILY_DISABLED`
503	resposta de erro	O provedor falhou, a requisição superou o prazo ou o serviço `gifs` respondeu com payload ilegível, cada um retornando `SERVICE_UNAVAILABLE`

O Decoding Chat busca ambas as metades em uma operação. Uma falha em gifs ou categories falha a requisição inteira e não retorna corpo parcial.

Rate limit

40 requisições por 10 segundos para cada usuário autenticado, no bucket gif:featured.

Obter GIFs em tendência

GET/v1/gifs/trending

Retorna no máximo 50 objetos GIF em tendência para o locale e país resolvidos.

Parâmetros de consulta

Campo	Tipo	Descrição
locale?	string	Um locale suportado, padrão `en-US`

Resposta

Status	Corpo	Condição
200	array[GIF object]	GIFs em tendência foram retornados, possivelmente como array vazio
400	resposta de erro	`locale` fora do registro e a requisição retorna `INVALID_FORM_BODY`
403	resposta de erro	O chamador é um bot ou apresenta credencial bearer e retorna `ACCESS_DENIED`
403	resposta de erro	A conta tem ação obrigatória pendente e retorna `ACCOUNT_SUSPICIOUS_ACTIVITY`
403	resposta de erro	A instância não vinculou nenhuma chave de provedor e retorna `FEATURE_TEMPORARILY_DISABLED`
503	resposta de erro	O provedor falhou, a requisição superou o prazo ou o serviço `gifs` respondeu com payload ilegível, cada um retornando `SERVICE_UNAVAILABLE`

O GIF em destaque não é garantido de corresponder ao primeiro resultado em tendência.

Rate limit

40 requisições por 10 segundos para cada usuário autenticado, no bucket gif:trending.

Obter sugestões de busca de GIF

GET/v1/gifs/suggest

Retorna sugestões de termos de busca para uma consulta parcial, como array de strings.

Parâmetros de consulta

Campo	Tipo	Descrição
q	string	O termo de busca parcial (1-256 caracteres)
locale?	string	Um locale suportado, padrão `en-US`

As sugestões dependem do locale e da consulta, não do endereço da requisição.

Resposta

Status	Corpo	Condição
200	array[string]	Sugestões foram retornadas, possivelmente como array vazio
400	resposta de erro	`q` ausente, vazio ou com mais de 256 caracteres, ou `locale` fora do registro, cada um retornando `INVALID_FORM_BODY`
403	resposta de erro	O chamador é um bot ou apresenta credencial bearer e retorna `ACCESS_DENIED`
403	resposta de erro	A conta tem ação obrigatória pendente e retorna `ACCOUNT_SUSPICIOUS_ACTIVITY`
403	resposta de erro	A instância não vinculou nenhuma chave de provedor e retorna `FEATURE_TEMPORARILY_DISABLED`
503	resposta de erro	O provedor falhou, a requisição superou o prazo ou o serviço `gifs` respondeu com payload ilegível, cada um retornando `SERVICE_UNAVAILABLE`

Cada sugestão é um termo que um cliente envia de volta como o q de Buscar GIFs.

Rate limit

40 requisições por 10 segundos para cada usuário autenticado, no bucket gif:suggest.

Registrar um compartilhamento de GIF

POST/v1/gifs/register-share

Informa ao provedor ativo que o chamador está compartilhando um de seus GIFs, e retorna 204 com corpo vazio.

Corpo JSON

Campo	Tipo	Descrição
id¹	string	O `id` do objeto GIF compartilhado (1-300 caracteres)
q?²	?string	O termo de busca que produziu o GIF (0-256 caracteres)
locale?	string	Um locale suportado, padrão `en-US`

¹ O provedor o lê como slug ou token de slug-id. O Decoding Chat não o verifica contra um GIF que retornou, portanto um identificador que o provedor não reconhece falha no provedor

² Um valor omitido ou null é enviado ao provedor como string vazia

O prazo nesta rota é de 3 segundos.

Resposta

Status	Corpo	Condição
204	vazio	O provedor aceitou o registro
400	resposta de erro	`id` ausente, vazio ou com mais de 300 caracteres, `q` com mais de 256 caracteres ou `locale` fora do registro, cada um retornando `INVALID_FORM_BODY`
403	resposta de erro	O chamador é um bot ou apresenta credencial bearer e retorna `ACCESS_DENIED`
403	resposta de erro	A conta tem ação obrigatória pendente e retorna `ACCOUNT_SUSPICIOUS_ACTIVITY`
403	resposta de erro	A instância não vinculou nenhuma chave de provedor e retorna `FEATURE_TEMPORARILY_DISABLED`
503	resposta de erro	O provedor rejeitou o registro, o serviço `gifs` não respondeu dentro do prazo ou respondeu com algo diferente de um reconhecimento, cada um retornando `SERVICE_UNAVAILABLE`

Efeitos colaterais

O registro chega ao provedor e não muda nenhum estado do Decoding Chat, portanto não emite Dispatch pelo Gateway e não adiciona o GIF aos memes da conta.

Cada requisição registra um compartilhamento separado, incluindo requisições repetidas para o mesmo id.

Rate limit

60 requisições por 10 segundos para cada usuário autenticado, no bucket gif:register_share.