Referencia de la API

URL base

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

Todos los endpoints son relativos a esta URL base. HTTPS es obligatorio — las solicitudes HTTP se redirigen.

Autenticación

Los endpoints de lectura (GET) son abiertos y gratuitos — no se requiere autenticación. Los endpoints de escritura (POST, PATCH, DELETE) requieren una clave de API enviada mediante la cabecera 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 respuesta

Todas las respuestas son application/json. Las fechas usan el formato ISO 8601. Los IDs de GIF son cadenas nanoid de 8 caracteres (p. ej., xK9mQ2pL).

Un objeto GIF típico tiene esta forma:

{
  "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>"
  }
}

Paginación

Los endpoints de listado devuelven resultados paginados. Usa los parámetros de consulta page y page_size:

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

La respuesta incluye metadatos de paginación:

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

El tamaño de página predeterminado es 20. El máximo es 100.

Límites de frecuencia

Las cabeceras de límite de frecuencia se incluyen en cada respuesta: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

GIFs

Listar GIFs

GET /api/v1/gifs/

Devuelve todos los GIFs públicos no eliminados ordenados por fecha de creación (más recientes primero).

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'

Detalle del GIF

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

Metadatos completos para un único GIF, incluyendo códigos de incrustación, URLs de descarga y dimensiones del archivo.

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

Datos del 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.

Transcripción

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

Transcripción en texto plano de la sesión de terminal — comandos y su salida, sin códigos de escape ANSI. Útil para búsqueda de texto completo y contexto de LLM.

GIFs destacados

GET /api/v1/featured/

Selección curada de GIFs de alta calidad, elegidos a mano por el equipo de AgentGIF.

Subir (requiere autenticación)

POST /api/v1/gifs/upload/

Sube un GIF con metadatos. Acepta 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]"

Actualizar GIF (requiere autenticación)

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

Actualiza el título, descripción, etiquetas o visibilidad. Solo el propietario del GIF puede editarlo.

Eliminar GIF (requiere autenticación)

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

Elimina el GIF de forma suave. Se puede recuperar en un plazo de 30 días.

Búsqueda

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

Búsqueda de texto completo en títulos, descripciones, comandos, etiquetas y transcripciones de GIFs. Mínimo 2 caracteres.

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

Etiquetas

Listar etiquetas

GET /api/v1/tags/

Todas las etiquetas con conteos de GIFs, ordenadas por popularidad.

GIFs por etiqueta

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

Lista paginada de GIFs con una etiqueta específica.

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

Colecciones

Listar colecciones

GET /api/v1/collections/

Colecciones destacadas

GET /api/v1/collections/featured/

Detalle de colección

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

Devuelve los metadatos de la colección y su lista ordenada de GIFs.

Crear colección (requiere autenticación)

POST /api/v1/collections/create/

Gestionar GIFs de colección (requiere autenticación)

Usuarios

Perfil de usuario

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

GIFs del usuario

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

Usuario autenticado

GET /api/v1/users/me/

Devuelve tu perfil, incluyendo la clave de API y estadísticas de carga. Requiere autenticación.

Restablecer clave de API

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

Genera una nueva clave de API. La clave anterior se invalida de inmediato.

Temas

Listar temas

GET /api/v1/themes/

Los 15 temas de terminal con sus paletas de colores (primer plano, fondo, colores ANSI).

Detalle del tema

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

Paleta de colores completa para un tema específico. Úsala para renderizar archivos cast con los colores correctos.

Servicio de badges

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

Personaliza con parámetros de consulta: ?theme=dracula, ?style=flat.

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

Generador de cintas de IA

Genera scripts de cinta VHS a partir de descripciones en lenguaje natural usando IA.

Crear trabajo de generación

POST /api/v1/gifs/generate/

Inicia un trabajo de generación asíncrono. Devuelve un job_id para consultar el estado.

Verificar estado de generación

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

Devuelve el estado de generación (pending, processing, completed, failed) y el script de cinta generado cuando esté completo.

Códigos de error

Las respuestas de error incluyen un campo detail con un mensaje legible por humanos:

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

Especificación OpenAPI

La especificación completa de OpenAPI 3.1 está disponible en:

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

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