API Reference

Base URL

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

endpoints ทั้งหมดอยู่สัมพัทธ์กับ base URL นี้ ต้องใช้ HTTPS — คำขอ HTTP จะถูกเปลี่ยนเส้นทาง

การยืนยันตัวตน

endpoints อ่าน (GET) เปิดและฟรี — ไม่ต้องยืนยันตัวตน endpoints เขียน (POST, PATCH, DELETE) ต้องใช้ API key ส่งผ่าน header 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 IDs เป็นสตริง 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>"
  }
}

การแบ่งหน้า

endpoints รายการคืนผลลัพธ์แบบแบ่งหน้า ใช้ query parameters page และ page_size:

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

การตอบกลับรวม metadata การแบ่งหน้า:

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

GIFs

รายการ GIFs

GET /api/v1/gifs/

คืน GIFs สาธารณะที่ยังไม่ถูกลบทั้งหมดเรียงตามวันที่สร้าง (ล่าสุดก่อน)

Query parameters: 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}/

metadata ฉบับสมบูรณ์สำหรับ GIF เดียว รวมถึง embed codes URL ดาวน์โหลด และขนาดไฟล์

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/

Transcript ข้อความธรรมดาของ terminal session — คำสั่งและผลลัพธ์ที่ลบ ANSI escape codes ออกแล้ว มีประโยชน์สำหรับการค้นหาเต็มรูปแบบและ LLM context

GIFs แนะนำ

GET /api/v1/featured/

การคัดเลือก GIFs คุณภาพสูงที่คัดสรรโดยทีม AgentGIF

อัปโหลด (ต้องยืนยันตัวตน)

POST /api/v1/gifs/upload/

อัปโหลด GIF พร้อม metadata รับ 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 คำอธิบาย คำสั่ง แท็ก และ transcripts ต้องใช้ขั้นต่ำ 2 ตัวอักษร

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

แท็ก

รายการแท็ก

GET /api/v1/tags/

แท็กทั้งหมดพร้อมจำนวน GIFs เรียงตามความนิยม

GIFs ตามแท็ก

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

รายการ 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}/

คืน metadata ของคอลเลกชันและรายการ GIFs ที่เรียงลำดับ

สร้างคอลเลกชัน (ต้องยืนยันตัวตน)

POST /api/v1/collections/create/

จัดการ GIFs ในคอลเลกชัน (ต้องยืนยันตัวตน)

ผู้ใช้

โปรไฟล์ผู้ใช้

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

GIFs ของผู้ใช้

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

ผู้ใช้ที่ยืนยันตัวตน

GET /api/v1/users/me/

คืนโปรไฟล์ของคุณ รวมถึง API key และสถิติการอัปโหลด ต้องยืนยันตัวตน

รีเซ็ต API Key

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

สร้าง API key ใหม่ คีย์เก่าจะถูกยกเลิกทันที

ธีม

รายการธีม

GET /api/v1/themes/

ธีม terminal ทั้ง 15 แบบพร้อมชุดสีของแต่ละธีม (foreground, background, สี ANSI)

รายละเอียดธีม

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.

ปรับแต่งด้วย query parameters: ?theme=dracula, ?style=flat

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

AI Tape Generator

สร้างสคริปต์ VHS tape จากคำอธิบายภาษาธรรมชาติโดยใช้ AI

สร้างงานการสร้าง

POST /api/v1/gifs/generate/

เริ่มงานการสร้างแบบ async คืน 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 specification ฉบับสมบูรณ์มีให้ที่:

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

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