Référence API

URL de base

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

Tous les points d'accès sont relatifs à cette URL de base. HTTPS est requis — les requêtes HTTP sont redirigées.

Authentification

Les points d'accès en lecture (GET) sont ouverts et gratuits — aucune authentification requise. Les points d'accès en écriture (POST, PATCH, DELETE) nécessitent une clé API transmise via l'en-tête 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.

Format de réponse

Toutes les réponses sont en application/json. Les dates utilisent le format ISO 8601. Les identifiants GIF sont des chaînes nanoid de 8 caractères (ex. : xK9mQ2pL).

Un objet GIF typique ressemble à :

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

Pagination

Les points d'accès de liste renvoient des résultats paginés. Utilisez les paramètres de requête page et page_size :

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

La réponse inclut des métadonnées de pagination :

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

La taille de page par défaut est 20. Le maximum est 100.

Limites de débit

Les en-têtes de limite de débit sont inclus dans chaque réponse : X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

GIF

Lister les GIF

GET /api/v1/gifs/

Renvoie tous les GIF publics non supprimés triés par date de création (les plus récents en premier).

Paramètres de requête : page, page_size, tag, shell, user.

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

Détail du GIF

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

Métadonnées complètes pour un seul GIF incluant les codes d'intégration, les URL de téléchargement et les dimensions du fichier.

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

Données 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.

Transcription

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

Transcription en texte brut de la session terminal — commandes et leur sortie, sans codes d'échappement ANSI. Utile pour la recherche plein texte et le contexte LLM.

GIF en vedette

GET /api/v1/featured/

Sélection de GIF de haute qualité, triés sur le volet par l'équipe AgentGIF.

Téléverser (authentification requise)

POST /api/v1/gifs/upload/

Téléversez un GIF avec des métadonnées. Accepte 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]"

Modifier le GIF (authentification requise)

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

Modifiez le titre, la description, les étiquettes ou la visibilité. Seul le propriétaire du GIF peut modifier.

Supprimer le GIF (authentification requise)

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

Suppression logicielle du GIF. Il peut être récupéré dans les 30 jours.

Recherche

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

Recherche plein texte dans les titres, descriptions, commandes, étiquettes et transcriptions des GIF. Minimum 2 caractères.

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

Étiquettes

Lister les étiquettes

GET /api/v1/tags/

Toutes les étiquettes avec le nombre de GIF, triées par popularité.

GIF par étiquette

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

Liste paginée de GIF avec une étiquette spécifique.

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

Collections

Lister les collections

GET /api/v1/collections/

Collections en vedette

GET /api/v1/collections/featured/

Détail de la collection

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

Renvoie les métadonnées de la collection et sa liste ordonnée de GIF.

Créer une collection (authentification requise)

POST /api/v1/collections/create/

Gérer les GIF d'une collection (authentification requise)

Utilisateurs

Profil utilisateur

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

GIF de l'utilisateur

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

Utilisateur authentifié

GET /api/v1/users/me/

Renvoie votre profil, incluant la clé API et les statistiques de téléversement. Nécessite une authentification.

Réinitialiser la clé API

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

Génère une nouvelle clé API. L'ancienne clé est immédiatement invalidée.

Thèmes

Lister les thèmes

GET /api/v1/themes/

Les 15 thèmes terminal avec leurs palettes de couleurs (premier plan, arrière-plan, couleurs ANSI).

Détail du thème

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

Palette de couleurs complète pour un thème spécifique. Utilisez ceci pour afficher les fichiers cast avec les couleurs correctes.

Service de badges

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

Personnalisez avec des paramètres de requête : ?theme=dracula, ?style=flat.

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

Générateur de tape IA

Générez des scripts tape VHS à partir de descriptions en langage naturel avec l'IA.

Créer une tâche de génération

POST /api/v1/gifs/generate/

Démarre une tâche de génération asynchrone. Renvoie un job_id pour interroger le statut.

Vérifier le statut de génération

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

Renvoie le statut de génération (pending, processing, completed, failed) et le script tape généré lorsque terminé.

Codes d'erreur

Les réponses d'erreur incluent un champ detail avec un message lisible par l'humain :

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

Spécification OpenAPI

La spécification complète OpenAPI 3.1 est disponible à :

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

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