API-Referenz

Basis-URL

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

Alle Endpunkte sind relativ zu dieser Basis-URL. HTTPS ist erforderlich — HTTP-Anfragen werden umgeleitet.

Authentifizierung

Lese-Endpunkte (GET) sind offen und kostenlos — keine Authentifizierung erforderlich. Schreib-Endpunkte (POST, PATCH, DELETE) erfordern einen API-Schlüssel, der über den X-API-Key-Header übergeben wird:

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.

Antwortformat

Alle Antworten sind application/json. Daten verwenden das ISO 8601-Format. GIF-IDs sind 8-Zeichen-nanoid-Strings (z.B. xK9mQ2pL).

Ein typisches GIF-Objekt sieht so aus:

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

Seitenumbruch

Listen-Endpunkte geben paginierte Ergebnisse zurück. Verwenden Sie page und page_size-Abfrageparameter:

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

Die Antwort enthält Paginierungs-Metadaten:

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

Standard-Seitengröße ist 20. Maximum ist 100.

Ratenlimits

Rate-Limit-Header sind in jeder Antwort enthalten: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

GIFs

GIFs auflisten

GET /api/v1/gifs/

Gibt alle öffentlichen, nicht gelöschten GIFs geordnet nach Erstellungsdatum zurück (neueste zuerst).

Abfrageparameter: page, page_size, tag, shell, user.

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

GIF-Details

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

Vollständige Metadaten für ein einzelnes GIF einschließlich Einbettungscodes, Download-URLs und Dateiabmessungen.

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

Cast-Daten

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.

Transkript

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

Klartext-Transkript der Terminal-Sitzung — Befehle und ihre Ausgabe, von ANSI-Escape-Codes bereinigt. Nützlich für Volltextsuche und LLM-Kontext.

Empfohlene GIFs

GET /api/v1/featured/

Kuratierte Auswahl hochwertiger GIFs, handverlesen vom AgentGIF-Team.

Hochladen (Authentifizierung erforderlich)

POST /api/v1/gifs/upload/

Ein GIF mit Metadaten hochladen. Akzeptiert 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]"

GIF aktualisieren (Authentifizierung erforderlich)

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

Titel, Beschreibung, Tags oder Sichtbarkeit aktualisieren. Nur der GIF-Eigentümer kann bearbeiten.

GIF löschen (Authentifizierung erforderlich)

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

Löscht das GIF weich. Es kann innerhalb von 30 Tagen wiederhergestellt werden.

Suche

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

Volltextsuche über GIF-Titel, Beschreibungen, Befehle, Tags und Transkripte. Minimum 2 Zeichen.

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

Tags

Tags auflisten

GET /api/v1/tags/

Alle Tags mit GIF-Anzahl, nach Beliebtheit geordnet.

GIFs nach Tag

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

Paginierte Liste von GIFs mit einem bestimmten Tag.

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

Sammlungen

Sammlungen auflisten

GET /api/v1/collections/

Empfohlene Sammlungen

GET /api/v1/collections/featured/

Sammlungsdetails

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

Gibt Sammlungsmetadaten und die geordnete GIF-Liste zurück.

Sammlung erstellen (Authentifizierung erforderlich)

POST /api/v1/collections/create/

Sammlungs-GIFs verwalten (Authentifizierung erforderlich)

Benutzer

Benutzerprofil

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

GIFs des Benutzers

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

Authentifizierter Benutzer

GET /api/v1/users/me/

Gibt Ihr Profil zurück, einschließlich API-Schlüssel und Upload-Statistiken. Authentifizierung erforderlich.

API-Schlüssel zurücksetzen

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

Generiert einen neuen API-Schlüssel. Der alte Schlüssel wird sofort ungültig.

Themes

Themes auflisten

GET /api/v1/themes/

Alle 15 Terminal-Themes mit ihren Farbpaletten (Vordergrund, Hintergrund, ANSI-Farben).

Theme-Details

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

Vollständige Farbpalette für ein bestimmtes Theme. Verwenden Sie diese, um Cast-Dateien mit korrekten Farben zu rendern.

Badge-Dienst

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

Mit Abfrageparametern anpassen: ?theme=dracula, ?style=flat.

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

KI-Tape-Generator

VHS-Tape-Skripte aus natürlichsprachlichen Beschreibungen mit KI generieren.

Generierungs-Job erstellen

POST /api/v1/gifs/generate/

Startet einen asynchronen Generierungs-Job. Gibt eine job_id zurück, nach der der Status abgefragt werden kann.

Generierungsstatus prüfen

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

Gibt den Generierungsstatus zurück (pending, processing, completed, failed) und das generierte Tape-Skript nach Abschluss.

Fehlercodes

Fehlerantworten enthalten ein detail-Feld mit einer lesbaren Nachricht:

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

OpenAPI-Spezifikation

Die vollständige OpenAPI 3.1-Spezifikation ist verfügbar unter:

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

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