Tài liệu tham khảo API

URL gốc

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

Tất cả endpoint đều liên quan đến URL gốc này. Bắt buộc dùng HTTPS — các yêu cầu HTTP sẽ bị chuyển hướng.

Xác thực

Các endpoint đọc (GET) mở và miễn phí — không yêu cầu xác thực. Các endpoint ghi (POST, PATCH, DELETE) yêu cầu API key được truyền qua 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.

Định dạng phản hồi

Tất cả phản hồi đều là application/json. Ngày tháng dùng định dạng ISO 8601. ID GIF là chuỗi nanoid 8 ký tự (ví dụ: xK9mQ2pL).

Một đối tượng GIF điển hình trông như sau:

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

Phân trang

Các endpoint danh sách trả về kết quả phân trang. Sử dụng tham số truy vấn page và page_size:

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

Phản hồi bao gồm metadata phân trang:

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

Kích thước trang mặc định là 20. Tối đa là 100.

Giới hạn tốc độ

Header giới hạn tốc độ được bao gồm trong mỗi phản hồi: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

GIF

Danh sách GIF

GET /api/v1/gifs/

Trả về tất cả GIF công khai chưa bị xóa, được sắp xếp theo ngày tạo (mới nhất trước).

Tham số truy vấn: page, page_size, tag, shell, user.

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

Chi tiết GIF

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

Đầy đủ metadata cho một GIF, bao gồm mã nhúng, URL tải xuống và kích thước tệp.

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

Dữ liệu 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.

Bản ghi chép

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

Bản ghi chép văn bản thuần của phiên terminal — các lệnh và đầu ra của chúng, đã xóa mã escape ANSI. Hữu ích cho tìm kiếm toàn văn và ngữ cảnh LLM.

GIF nổi bật

GET /api/v1/featured/

Tuyển chọn GIF chất lượng cao, được chọn tay bởi đội ngũ AgentGIF.

Tải lên (Yêu cầu xác thực)

POST /api/v1/gifs/upload/

Tải lên một GIF có metadata. Chấp nhận 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]"

Cập nhật GIF (Yêu cầu xác thực)

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

Cập nhật tiêu đề, mô tả, thẻ hoặc chế độ hiển thị. Chỉ chủ sở hữu GIF mới có thể chỉnh sửa.

Xóa GIF (Yêu cầu xác thực)

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

Xóa mềm GIF. Có thể khôi phục trong vòng 30 ngày.

Tìm kiếm

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

Tìm kiếm toàn văn trên tiêu đề, mô tả, lệnh, thẻ và bản ghi chép GIF. Tối thiểu 2 ký tự.

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

Thẻ

Danh sách thẻ

GET /api/v1/tags/

Tất cả thẻ với số lượng GIF, được sắp xếp theo độ phổ biến.

GIF theo thẻ

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

Danh sách GIF phân trang với một thẻ cụ thể.

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

Bộ sưu tập

Danh sách bộ sưu tập

GET /api/v1/collections/

Bộ sưu tập nổi bật

GET /api/v1/collections/featured/

Chi tiết bộ sưu tập

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

Trả về metadata bộ sưu tập và danh sách GIF được sắp xếp.

Tạo bộ sưu tập (Yêu cầu xác thực)

POST /api/v1/collections/create/

Quản lý GIF trong bộ sưu tập (Yêu cầu xác thực)

Người dùng

Hồ sơ người dùng

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

GIF của người dùng

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

Người dùng đã xác thực

GET /api/v1/users/me/

Trả về hồ sơ của bạn, bao gồm API key và thống kê tải lên. Yêu cầu xác thực.

Đặt lại API Key

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

Tạo API key mới. Key cũ bị vô hiệu hóa ngay lập tức.

Themes

Danh sách theme

GET /api/v1/themes/

Tất cả 15 theme terminal với bảng màu của chúng (màu chữ, màu nền, màu ANSI).

Chi tiết theme

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

Bảng màu đầy đủ cho một theme cụ thể. Dùng để hiển thị tệp cast với màu sắc chính xác.

Dịch vụ Badge

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

Tùy chỉnh với tham số truy vấn: ?theme=dracula, ?style=flat.

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

Trình tạo VHS Tape bằng AI

Tạo script VHS tape từ mô tả ngôn ngữ tự nhiên bằng AI.

Tạo công việc tạo

POST /api/v1/gifs/generate/

Bắt đầu công việc tạo bất đồng bộ. Trả về job_id để kiểm tra trạng thái.

Kiểm tra trạng thái tạo

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

Trả về trạng thái tạo (pending, processing, completed, failed) và script tape đã tạo khi hoàn thành.

Mã lỗi

Phản hồi lỗi bao gồm trường detail với thông báo có thể đọc được:

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

Đặc tả OpenAPI

Đặc tả OpenAPI 3.1 đầy đủ có sẵn tại:

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

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