Referência da API

URL Base

https://agentgif.com/api/v1/

Todos os endpoints são relativos a esta URL base. HTTPS é obrigatório — requisições HTTP são redirecionadas.

Autenticação

Os endpoints de leitura (GET) são abertos e gratuitos — sem autenticação necessária. Os endpoints de escrita (POST, PATCH, DELETE) requerem uma chave de API passada pelo cabeçalho X-API-Key:

curl -H "X-API-Key: YOUR_API_KEY" https://agentgif.com/api/v1/gifs/upload/ \
  -F "[email protected]" -F "title=Demo"

Get your API key at Settings → API Key. You can reset it at any time via the settings page or the /api/v1/users/me/api-key/reset/ endpoint.

Formato de Resposta

Todas as respostas são application/json. As datas usam o formato ISO 8601. Os IDs de GIF são strings nanoid de 8 caracteres (ex., xK9mQ2pL).

Um objeto GIF típico se parece com:

{
  "id": "xK9mQ2pL",
  "title": "Git Interactive Rebase",
  "slug": "git-rebase",
  "command": "git rebase -i HEAD~3",
  "shell": "zsh",
  "description": "Interactive rebase to squash commits",
  "gif_url": "https://media.agentgif.com/xK9mQ2pL.gif",
  "mp4_url": "https://media.agentgif.com/xK9mQ2pL.mp4",
  "cast_url": "https://media.agentgif.com/xK9mQ2pL.cast",
  "thumbnail_url": "https://media.agentgif.com/xK9mQ2pL_thumb.png",
  "width": 1000,
  "height": 580,
  "frames": 142,
  "duration_ms": 8500,
  "file_size_bytes": 245760,
  "visibility": "public",
  "view_count": 1234,
  "tags": ["git", "rebase", "version-control"],
  "user": {"username": "agentgif"},
  "tool": {"name": "git", "slug": "git"},
  "theme": {"name": "Catppuccin Mocha", "slug": "catppuccin-mocha"},
  "created_at": "2026-03-15T10:30:00Z",
  "detail_url": "https://agentgif.com/@agentgif/git-rebase/",
  "embed_codes": {
    "markdown": "[![Git Rebase](https://media.agentgif.com/xK9mQ2pL.gif)](https://agentgif.com/xK9mQ2pL)",
    "html": "<a href=\"https://agentgif.com/xK9mQ2pL\"><img src=\"...\" /></a>"
  }
}

Paginação

Os endpoints de listagem retornam resultados paginados. Use os parâmetros de consulta page e page_size:

GET /api/v1/gifs/?page=2&page_size=20

A resposta inclui metadados de paginação:

{
  "count": 886,
  "next": "https://agentgif.com/api/v1/gifs/?page=3",
  "previous": "https://agentgif.com/api/v1/gifs/?page=1",
  "results": [...]
}

O tamanho de página padrão é 20. O máximo é 100.

Limites de Taxa

Cabeçalhos de limite de taxa são incluídos em cada resposta: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

GIFs

Listar GIFs

GET /api/v1/gifs/

Retorna todos os GIFs públicos e não excluídos ordenados por data de criação (mais recentes primeiro).

Parâmetros de consulta: page, page_size, tag, shell, user.

curl -s https://agentgif.com/api/v1/gifs/?tag=docker&page_size=5 | jq '.count'

Detalhe do GIF

GET /api/v1/gifs/{id}/

Metadados completos de um único GIF incluindo códigos de embed, URLs de download e dimensões do arquivo.

curl -s https://agentgif.com/api/v1/gifs/xK9mQ2pL/ | jq '.title, .gif_url'

Dados Cast

GET /api/v1/gifs/{id}/cast/

Returns the raw asciinema v2 cast file — a JSON header line followed by newline-delimited event tuples [timestamp, event_type, data]. This is the machine-readable layer that AI agents use to understand the terminal session.

Transcrição

GET /api/v1/gifs/{id}/transcript/

Transcrição em texto simples da sessão de terminal — comandos e sua saída, sem os códigos de escape ANSI. Útil para pesquisa de texto completo e contexto de LLM.

GIFs em Destaque

GET /api/v1/featured/

Seleção curada de GIFs de alta qualidade, escolhidos à mão pela equipe do AgentGIF.

Enviar (Autenticação Necessária)

POST /api/v1/gifs/upload/

Envie um GIF com metadados. Aceita multipart/form-data.

curl -X POST https://agentgif.com/api/v1/gifs/upload/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "[email protected]" \
  -F "title=Docker Compose Up" \
  -F "command=docker compose up -d" \
  -F "tags=docker,compose,containers" \
  -F "[email protected]"

Atualizar GIF (Autenticação Necessária)

PATCH /api/v1/gifs/{id}/edit/

Atualize título, descrição, tags ou visibilidade. Somente o proprietário do GIF pode editar.

Excluir GIF (Autenticação Necessária)

DELETE /api/v1/gifs/{id}/delete/

Exclui suavemente o GIF. Pode ser recuperado em até 30 dias.

Pesquisa

GET /api/v1/search/?q={query}

Pesquisa de texto completo em títulos, descrições, comandos, tags e transcrições de GIFs. Mínimo de 2 caracteres.

curl -s "https://agentgif.com/api/v1/search/?q=git+rebase&sort=views" | jq '.results[0].title'

Tags

Listar Tags

GET /api/v1/tags/

Todas as tags com contagem de GIFs, ordenadas por popularidade.

GIFs por Tag

GET /api/v1/tags/{slug}/gifs/

Lista paginada de GIFs com uma tag específica.

curl -s https://agentgif.com/api/v1/tags/docker/gifs/ | jq '.count'

Coleções

Listar Coleções

GET /api/v1/collections/

Coleções em Destaque

GET /api/v1/collections/featured/

Detalhe da Coleção

GET /api/v1/collections/{slug}/

Retorna metadados da coleção e sua lista ordenada de GIFs.

Criar Coleção (Autenticação Necessária)

POST /api/v1/collections/create/

Gerenciar GIFs da Coleção (Autenticação Necessária)

Usuários

Perfil do Usuário

GET /api/v1/users/{username}/

GIFs do Usuário

GET /api/v1/users/{username}/gifs/

Usuário Autenticado

GET /api/v1/users/me/

Retorna seu perfil, incluindo chave de API e estatísticas de upload. Requer autenticação.

Redefinir Chave de API

POST /api/v1/users/me/api-key/reset/

Gera uma nova chave de API. A chave antiga é imediatamente invalidada.

Temas

Listar Temas

GET /api/v1/themes/

Todos os 15 temas de terminal com suas paletas de cores (primeiro plano, plano de fundo, cores ANSI).

Detalhe do Tema

GET /api/v1/themes/{slug}/

Paleta de cores completa para um tema específico. Use isso para renderizar arquivos cast com as cores corretas.

Serviço de Badges

Terminal-themed package badges — a developer-friendly alternative to shields.io. See the Badge Playground for a visual builder.

Personalize com parâmetros de consulta: ?theme=dracula, ?style=flat.

<img src="https://agentgif.com/badge/pypi/requests/version.svg?theme=catppuccin-mocha" />

Gerador de Tape para IA

Gere scripts de tape VHS a partir de descrições em linguagem natural usando IA.

Criar Trabalho de Geração

POST /api/v1/gifs/generate/

Inicia um trabalho de geração assíncrono. Retorna um job_id para verificar o status.

Verificar Status de Geração

GET /api/v1/gifs/generate/{job_id}/

Retorna o status de geração (pending, processing, completed, failed) e o script de tape gerado quando concluído.

Códigos de Erro

As respostas de erro incluem um campo detail com uma mensagem legível por humanos:

{
  "detail": "Authentication credentials were not provided."
}

Spec OpenAPI

A especificação completa OpenAPI 3.1 está disponível em:

https://agentgif.com/api/openapi.json

Import it into Swagger UI, Insomnia, or any OpenAPI-compatible tool.