مرجع API

الرابط الأساسي

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

جميع نقاط النهاية نسبية إلى هذا الرابط الأساسي. HTTPS مطلوب — تُعاد توجيه طلبات HTTP.

المصادقة

نقاط نهاية القراءة (GET) مفتوحة ومجانية — لا تتطلب مصادقة. تتطلب نقاط نهاية الكتابة (POST وPATCH وDELETE) مفتاح API يُمرَّر عبر ترويسة 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.

صيغة الاستجابة

جميع الاستجابات بصيغة application/json. التواريخ بتنسيق ISO 8601. معرفات GIF هي سلاسل nanoid من 8 أحرف (مثل: xK9mQ2pL).

يبدو كائن GIF النموذجي كالتالي:

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

التقسيم بالصفحات

تعيد نقاط نهاية القوائم نتائج مُقسَّمة بالصفحات. استخدم معاملات الاستعلام 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.

حدود المعدل

ترويسات حد المعدل مضمّنة في كل استجابة: X-RateLimit-Limit، X-RateLimit-Remaining، X-RateLimit-Reset.

التسجيلات

قائمة التسجيلات

GET /api/v1/gifs/

يعيد جميع التسجيلات العامة غير المحذوفة مرتبةً حسب تاريخ الإنشاء (الأحدث أولاً).

معاملات الاستعلام: page, page_size, tag, shell, user.

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

تفاصيل التسجيل

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

بيانات وصفية كاملة لتسجيل واحد تشمل رموز التضمين وروابط التنزيل وأبعاد الملف.

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.

النص

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

نص عادي لجلسة الطرفية — الأوامر ومخرجاتها، مع حذف رموز الإفلات ANSI. مفيد للبحث النصي الكامل وسياق النماذج اللغوية الكبيرة.

التسجيلات المميزة

GET /api/v1/featured/

اختيار منتقى من التسجيلات عالية الجودة، اختارها فريق AgentGIF يدوياً.

الرفع (يتطلب مصادقة)

POST /api/v1/gifs/upload/

ارفع تسجيلاً مع بيانات وصفية. يقبل 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]"

تحديث التسجيل (يتطلب مصادقة)

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

تحديث العنوان أو الوصف أو الوسوم أو الظهور. لا يمكن إلا لمالك التسجيل التعديل.

حذف التسجيل (يتطلب مصادقة)

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

يحذف التسجيل بشكل مؤقت. يمكن استعادته خلال 30 يوماً.

البحث

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

بحث نصي كامل في عناوين التسجيلات والأوصاف والأوامر والوسوم والنصوص. الحد الأدنى حرفان.

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

الوسوم

قائمة الوسوم

GET /api/v1/tags/

جميع الوسوم مع أعداد التسجيلات، مرتبةً حسب الشعبية.

التسجيلات حسب الوسم

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

قائمة مقسمة بالصفحات للتسجيلات ذات وسم محدد.

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}/

يعيد البيانات الوصفية للمجموعة وقائمتها المرتبة من التسجيلات.

إنشاء مجموعة (يتطلب مصادقة)

POST /api/v1/collections/create/

إدارة تسجيلات المجموعة (يتطلب مصادقة)

المستخدمون

الملف الشخصي للمستخدم

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

تسجيلات المستخدم

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/

جميع الـ 15 ثيم طرفية مع لوحات ألوانها (المقدمة والخلفية وألوان ANSI).

تفاصيل الثيم

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

لوحة ألوان كاملة لثيم محدد. استخدم هذا لعرض ملفات cast بالألوان الصحيحة.

خدمة الشارات

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" />

مولّد الـ Tape بالذكاء الاصطناعي

توليد سكريبتات VHS tape من أوصاف باللغة الطبيعية باستخدام الذكاء الاصطناعي.

إنشاء مهمة توليد

POST /api/v1/gifs/generate/

يبدأ مهمة توليد غير متزامنة. يعيد job_id للاستطلاع عن الحالة.

التحقق من حالة التوليد

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

يعيد حالة التوليد (pending، processing، completed، failed) والسكريبت المولَّد عند الاكتمال.

رموز الخطأ

تتضمن استجابات الخطأ حقل detail برسالة قابلة للقراءة البشرية:

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

مواصفة OpenAPI

المواصفة الكاملة OpenAPI 3.1 متاحة على:

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

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