API 快速开始：从图片到下载资产

前提条件

开放 API 处于公开测试阶段。你需要已验证的 AnimGen 账户、包含 animations:read 和 animations:write 的 API Key，以及可信服务端或本地机器。生成要求账户积分充足；订阅会提高开发者限额，但不是访问前提。

在账户 → 开发者创建 Key。通过密钥管理器或私有 Shell 会话提供 ANIMGEN_API_KEY 环境变量。不要写进浏览器 JavaScript、发布的游戏、代码仓库或 AI 对话。

基础地址为 https://api.animgen.com/v1。URL 的兼容性版本是 v1，本文对应的契约版本是 1.3.0。

1. 发现可用模型

curl --fail-with-body https://api.animgen.com/v1/models \
  -H "Authorization: Bearer $ANIMGEN_API_KEY"

从 data 中选择支持目标输入模式的 id，检查时长、分辨率、比例和能力标志。不要直接使用旧文章中的模型名。

下面的首帧示例要求模型的 supports_first_frame 为 true，且 modes 支持首帧。示例使用该模型当前公布的默认选项。

2. 准备请求并报价，不启动生成

下载并检查 Python 完整工作流示例。它要求 Python 3.10+，仅使用标准库。

curl --fail-with-body -o animation-workflow.py \
  https://animgen.com/examples/animation-workflow.py

python3 animation-workflow.py prepare \
  --image character.png \
  --model 'PROVIDER:MODEL_FROM_CATALOG' \
  --prompt '单个角色原地跑步，侧面视角，固定镜头。' \
  --state hero-run.json

替换图片路径和模型 ID。准备阶段会检查模型目录，生成 Base64 请求，获取报价与余额，并写入私有状态文件；不会调用付费创建接口。

状态文件包含原图和提示词，请勿提交到版本控制，限制访问，并在不再需要时删除。文件不包含 API Key。

3. 明确批准创建

核对积分报价，将 APPROVED_CREDITS 设置为你接受的金额，再运行：

python3 animation-workflow.py run \
  --state hero-run.json \
  --approve-credits "$APPROVED_CREDITS" \
  --output ./hero-output

首次创建前，脚本会重新报价；超过本地批准金额时停止。它会保存幂等键，以同一请求执行一次逻辑创建，然后轮询并下载产物。

4. 安全恢复并检查结果

命令超时后，使用同一个状态文件重新运行。如果文件已有任务 ID，脚本只恢复轮询，不会再创建。创建响应不明确时，会在保守重试窗口内复用原始幂等键与请求内容。

不要删除状态文件、重新准备来“重试”，那会变成新逻辑操作，可能重复付费。示例对超过 24 小时仍无法确认结果的创建拒绝自动重试；请先检查任务列表或联系支持。

进入任何终态后，脚本都会先保存可用资产，再报告失败或取消。结果不完整时返回非零退出码，不把部分产物当作全部成功。文件名使用资产 ID，不使用远端提供的任意名称。

请求会做什么

示例使用普通模式、完整视频区间，并请求 PNG 帧 ZIP、24 帧、512 × 512 尺寸。这些只是示例选择，不是 API 默认值，也不是适合所有项目的质量建议。

复用上传文件或使用公开图片 URL，见鉴权与图片输入。任务生命周期见轮询与下载、错误与重试。精确契约可下载 OpenAPI JSON。

Python 示例通过本地 Mock 测试验证，没有通过真实付费生成来做测试。正式接入时，使用一个小型且明确批准费用的任务自行验收。其他语言与各自验收范围见完整调用示例，准确参数见自动生成的 API 参考。