API 参考文档

基础 URL

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

所有端点均相对于此基础 URL。必须使用 HTTPS——HTTP 请求将被重定向。

身份验证

读取端点（GET）完全开放且免费——无需身份验证。写入端点（POST、PATCH、DELETE）需要通过 X-API-Key 请求头传递 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 字符串（例如 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。

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

单个 GIF 的完整元数据，包括嵌入代码、下载 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.

转录文本

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

终端会话的纯文本转录——命令及其输出，已剥离 ANSI 转义代码。适用于全文搜索和 LLM 上下文。

精选 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，可在 30 天内恢复。

搜索

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

对 GIF 标题、描述、命令、标签和转录进行全文搜索，最少输入 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/

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

AI Tape 生成器

使用 AI 根据自然语言描述生成 VHS tape 脚本。

创建生成任务

POST /api/v1/gifs/generate/

启动异步生成任务，返回用于轮询状态的 job_id。

查看生成状态

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

返回生成状态（pending、processing、completed、failed）以及完成时生成的 tape 脚本。

错误代码

错误响应包含带有易读信息的 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.