API संदर्भ

आधार URL

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

सभी endpoints इस आधार URL के सापेक्ष हैं। HTTPS आवश्यक है — HTTP अनुरोध रीडायरेक्ट किए जाते हैं।

प्रमाणीकरण

पढ़ने के endpoints (GET) खुले और मुफ्त हैं — कोई प्रमाणीकरण आवश्यक नहीं। लिखने के endpoints (POST, PATCH, DELETE) को X-API-Key header के माध्यम से पास की गई API कुंजी की आवश्यकता है:

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.

प्रतिक्रिया प्रारूप

सभी प्रतिक्रियाएं application/json हैं। तारीखें ISO 8601 प्रारूप उपयोग करती हैं। GIF ID 8-अक्षर nanoid strings हैं (जैसे, xK9mQ2pL)।

एक सामान्य GIF object इस तरह दिखता है:

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

पेजिनेशन

सूची endpoints पेजिनेटेड परिणाम लौटाते हैं। page और page_size क्वेरी पैरामीटर का उपयोग करें:

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

प्रतिक्रिया में पेजिनेशन मेटाडेटा शामिल है:

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

डिफ़ॉल्ट पेज आकार 20 है। अधिकतम 100 है।

दर सीमाएं

दर सीमा headers हर प्रतिक्रिया में शामिल हैं: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset।

GIF

GIF सूची

GET /api/v1/gifs/

निर्माण तारीख के अनुसार क्रमबद्ध सभी सार्वजनिक, न-हटाए गए GIF लौटाता है (नवीनतम पहले)।

क्वेरी पैरामीटर: page, page_size, tag, shell, user.

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

GIF विवरण

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

embed कोड, डाउनलोड URL और फ़ाइल आयाम सहित एकल GIF के लिए पूर्ण मेटाडेटा।

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

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.

Transcript

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

Terminal session का सादा पाठ transcript — कमांड और उनका आउटपुट, ANSI escape कोड हटाए गए। फुल-टेक्स्ट खोज और LLM context के लिए उपयोगी।

विशेष GIF

GET /api/v1/featured/

AgentGIF टीम द्वारा हाथ से चुने गए उच्च-गुणवत्ता वाले GIF का क्यूरेटेड चयन।

अपलोड करें (प्रमाणीकरण आवश्यक)

POST /api/v1/gifs/upload/

मेटाडेटा के साथ GIF अपलोड करें। 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 अपडेट करें (प्रमाणीकरण आवश्यक)

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

शीर्षक, विवरण, टैग या दृश्यता अपडेट करें। केवल GIF स्वामी ही संपादित कर सकता है।

GIF हटाएं (प्रमाणीकरण आवश्यक)

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

GIF को soft-delete करता है। इसे 30 दिनों के भीतर पुनर्प्राप्त किया जा सकता है।

खोज

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

GIF शीर्षक, विवरण, कमांड, टैग और transcript में फुल-टेक्स्ट खोज। न्यूनतम 2 अक्षर।

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

टैग

टैग सूची

GET /api/v1/tags/

GIF संख्या के साथ सभी टैग, लोकप्रियता के अनुसार क्रमबद्ध।

टैग द्वारा GIF

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

एक विशिष्ट टैग वाले GIF की पेजिनेटेड सूची।

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

संग्रह

संग्रह सूची

GET /api/v1/collections/

विशेष संग्रह

GET /api/v1/collections/featured/

संग्रह विवरण

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

संग्रह मेटाडेटा और उसके GIF की क्रमबद्ध सूची लौटाता है।

संग्रह बनाएं (प्रमाणीकरण आवश्यक)

POST /api/v1/collections/create/

संग्रह GIF प्रबंधित करें (प्रमाणीकरण आवश्यक)

उपयोगकर्ता

उपयोगकर्ता प्रोफ़ाइल

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

उपयोगकर्ता के GIF

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

प्रमाणित उपयोगकर्ता

GET /api/v1/users/me/

API कुंजी और अपलोड आँकड़े सहित आपकी प्रोफ़ाइल लौटाता है। प्रमाणीकरण आवश्यक है।

API कुंजी रीसेट करें

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

एक नई API कुंजी बनाता है। पुरानी कुंजी तुरंत अमान्य हो जाती है।

थीम

थीम सूची

GET /api/v1/themes/

उनके रंग पैलेट (अग्रभूमि, पृष्ठभूमि, ANSI रंग) के साथ सभी 15 terminal थीम।

थीम विवरण

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

एक विशिष्ट थीम के लिए पूर्ण रंग पैलेट। सही रंगों के साथ cast फ़ाइलें रेंडर करने के लिए इसका उपयोग करें।

Badge सेवा

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

क्वेरी पैरामीटर के साथ कस्टमाइज़ करें: ?theme=dracula, ?style=flat।

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

AI Tape जनरेटर

AI का उपयोग करके प्राकृतिक भाषा विवरण से VHS tape स्क्रिप्ट बनाएं।

जनरेशन जॉब बनाएं

POST /api/v1/gifs/generate/

एक async जनरेशन जॉब शुरू करता है। स्थिति के लिए poll करने के लिए एक job_id लौटाता है।

जनरेशन स्थिति जांचें

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

जनरेशन स्थिति (pending, processing, completed, failed) और पूरा होने पर उत्पन्न tape स्क्रिप्ट लौटाता है।

त्रुटि कोड

त्रुटि प्रतिक्रियाओं में एक मानव-पठनीय संदेश के साथ detail फ़ील्ड शामिल है:

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

OpenAPI Spec

पूर्ण OpenAPI 3.1 विशिष्टता यहां उपलब्ध है:

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

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