常见问题

关于 AgentGIF 开发者 GIF 托管平台的常见问题。

什么是 AgentGIF？

AgentGIF 是一个采用双层架构的开发者 GIF 托管平台。每个终端演示 GIF 都配有机器可读的 asciinema v2 cast 文件，使人类和 AI 代理都能理解其内容。

人类看到的是动画终端录制。AI 代理看到的是结构化数据：命令、输出、时间戳和元数据。

AgentGIF 免费吗？

是的。上传、托管和嵌入 GIF 完全免费。REST API 的读取操作免费且无需认证。写入操作（上传、编辑、删除）需要从设置页面获取免费 API 密钥。

什么是 cast 文件？

Cast 文件是一种 asciinema v2 录制格式。它是一种文本格式，第 1 行是包含终端元数据的 JSON 头，后续是带时间戳的事件元组：

{"version": 2, "width": 120, "height": 40}
[0.5, "o", "$ docker compose up -d\r\n"]
[1.2, "o", "Creating network...\r\n"]
[2.8, "o", "Container app-1  Started\r\n"]

每个元组的格式为 [时间戳（秒）, 事件类型, 数据]。这使 AI 代理无需 OCR 即可提取命令、输出和时序信息。

如何上传 GIF？

两种方式：

  • 网页: 在 /upload/ 拖放上传（需要 GitHub 登录）
  • CLI: agentgif upload demo.gif --title "My Demo" --tags cli,unix

CLI 支持 5 种语言：Python、Node.js、Go、Rust 和 Ruby。使用 --cast demo.cast 参数附加机器可读层。

如何在 README 中嵌入 GIF？

GitHub README 的推荐模式：

<p align="center">
  <a href="https://agentgif.com/ID">
    <img src="https://media.agentgif.com/ID.gif" alt="demo" width="800">
  </a>
</p>

将 ID 替换为你 GIF 的 8 位 ID。查看完整的嵌入指南了解全部 6 种方法。

什么是 .md 端点？

在任何 AgentGIF URL 后追加 .md 可获得针对 LLM 优化的 text/markdown 响应。所有页面都支持此功能——GIF 详情、标签列表、工具页面、合集、指南和搜索结果。

curl https://agentgif.com/tools/git/.md
curl https://agentgif.com/explore/tags/docker/.md

我需要 API 密钥吗？

操作需要认证
搜索、列表、详情、cast、脚本记录否——完全开放
上传、编辑、删除 GIF是——X-API-Key 请求头
创建/管理合集是——X-API-Key 请求头

使用 GitHub 登录后，在 /settings/ 获取免费 API 密钥。

有哪些终端主题可用？

AgentGIF 支持全部 44 个 VHS 终端主题。热门选择：

主题样式
Catppuccin Mocha暖色深色带柔和色调点缀（默认）
Dracula经典深紫色
Tokyo Night以蓝色为主的现代深色
Nord极地蓝配色
Solarized Dark/Light精确配色
GitHub Dark/LightGitHub 原生主题

浏览所有主题的实时预览：主题画廊。

什么是徽章服务？

AgentGIF 提供终端主题的包徽章，作为 shields.io 的替代方案。它们使用你选择的终端主题颜色渲染。

![PyPI](https://agentgif.com/badge/pypi/requests/version.svg?theme=dracula)
![npm](https://agentgif.com/badge/npm/express/version.svg?theme=nord)
![Stars](https://agentgif.com/badge/github/torvalds/linux/stars.svg)

支持的提供商：PyPI、npm、crates.io、GitHub。使用 ?theme= 和 ?style= 参数自定义。查看徽章演示。

AI 代理如何读取 GIF？

AI 代理可以通过多种渠道访问 GIF 内容：

  • Cast 文件: GET /api/v1/gifs/{id}/cast/ — 带时间戳的完整 asciinema v2 录制
  • 转录文本: GET /api/v1/gifs/{id}/transcript/ — 干净的纯文本，已去除 ANSI 码
  • .md 端点: 在任何页面 URL 后追加 .md 获取 Markdown 输出
  • JSON API: /api/v1/search/?q=docker — 带结构化结果的全文搜索
  • llms.txt: /llms.txt — 面向 AI 爬虫的站点级摘要

查看完整的 AI 代理集成文档。

支持哪些文件格式？

格式最大大小用途
GIF10 MB主要视觉格式——随处可播放
Cast (.cast)5 MB机器可读层（上传时可选）
MP4自动生成高效的播放替代方案

为获得最佳效果，请将 GIF 控制在 5 MB 以内。查看录制指南了解优化技巧。

如何录制终端 GIF？

我们推荐 Charm 的 VHS 进行脚本化、可复现的录制：

# Install VHS
brew install vhs

# Create a tape file (demo.tape)
Output demo.gif
Set Theme "Catppuccin Mocha"
Type "echo 'Hello, world!'"
Enter
Sleep 2s

# Record
vhs demo.tape

完整分步教程：如何录制终端 GIF。

← 关于 · 文档 · 指南 →