鉴权与图片输入

在可信环境鉴权

开放 API 请求使用 Authorization: Bearer <API_KEY>。Key 仅在账户 → 开发者创建时明文显示。请放在密钥存储中；轮换时先更新调用方，再撤销旧 Key，并避免记录请求头。

API 需要已验证的 AnimGen 账户。注册基础档为 1 并发、3 个排队任务、每分钟 3 次创建和 60 次其他请求；有效订阅会提高这些账户级限额。通过 GET /account 查看当前档位、Key 权限与限额，通过 GET /credits/balance 查看可用积分。

MCP 使用 OAuth 和更细分的权限，不要把这张 API Key 权限表套用到 MCP。

方案 A：上传后复用文件 ID

curl --fail-with-body https://api.animgen.com/v1/files \
  -H "Authorization: Bearer $ANIMGEN_API_KEY" \
  -F "[email protected]"

响应包含 id、MIME 类型、尺寸、字节数和 SHA-256。使用返回的 ID，不要传 Studio 的 uploadId、本地路径或内部任务标识：

{
  "input": {
    "first_frame": {
      "type": "file",
      "file_id": "00000000-0000-4000-8000-000000000001"
    }
  }
}

上面的 UUID 是占位符。支持 PNG、JPEG 和 WebP；multipart 默认限制为 20 MB，服务还会校验图片解码与尺寸。应处理服务返回的限制错误，而不是只相信扩展名或 MIME 声明。

方案 B：内联 Base64

{
  "type": "base64",
  "media_type": "image/png",
  "data": "<PURE_BASE64_IMAGE_BYTES>"
}

传入纯 Base64，不要包含 data:image/...;base64, 前缀。解码后单张上限 10 MB，请求内全部内联图片合计上限 20 MB。Base64/JSON 传输体积大于原始文件；较大或反复使用的图片优先先上传。

创建任务被接受前，Base64 内容会先持久化。幂等重试时应保持原始字节不变。

方案 C：公开 HTTPS 地址

{
  "type": "url",
  "url": "https://your-public-image-host.example/character.png"
}

把示例域名换成实际可访问的图片地址。服务端必须能在没有浏览器 Cookie 的情况下取得图片。要求公开 HTTPS、443 端口，不能有内嵌用户名密码或 fragment。私网、回环和链路本地地址会被阻止，跳转目标也会重新校验。

报价和创建期间，应保持该地址的图片字节稳定。不要使用内网地址或返回登录页的 URL。带签名的输入链接同样敏感，而且可能过期。

匹配模型能力

每次生成都需要首帧。尾帧和额外参考图是否可用，取决于实时模型的模式支持；请求 Schema 的总上限不能覆盖更低的模型专属上限。

通过 GET /models 获取合法模式与参数，并对计划提交的完整请求先报价。透明素材要求见透明动画，完整调用见快速开始。