# AnimGen AI（animgen.com）核心指南全文：简体中文

> AnimGen AI 把一张角色图做成 2D 游戏动画，导出带 JSON 的精灵图、PNG 帧、GIF、透明视频，以及 Unity、Godot、Unreal Paper2D、Cocos Creator 和 Construct 3 素材包。免费浏览器工具无需账号即可转换和打包已有的 GIF、视频与帧。

AnimGen AI 由 GeekArt Inc. 运营，与 Epic Games 及 Unreal Engine 的 AnimGen 插件无关。英文入口、价格与安全调用规则见 [llms.txt](https://animgen.com/llms.txt)。

内容最近核对：2026-10-29。这些是公开学习资料，不代表授权花费积分；付费生成前必须取得用户的明确批准。

## 核心指南正文

## AnimGen 使用文档 (zh)

Canonical URL: https://animgen.com/docs/zh

Status: stable. Last verified: 2026-08-31.

## 从一条工作流开始

AnimGen 把源图片变成动画预览，再导出为可以使用的资产。你可以先检查动作，选择有用的片段，再为项目导出所需格式。

先阅读[产品概览](https://animgen.com/docs/zh/getting-started/overview)，理解“生成”和“导出”的区别。也可以打开[交互式 Demo](https://animgen.com/demo)，在创建真实任务前体验整个流程。

## 当前可以使用什么

| 使用入口 | 当前状态 | 从哪里开始 |
| --- | --- | --- |
| Web Studio | 已开放 | [制作第一个动画](https://animgen.com/docs/zh/getting-started/first-animation) |
| 开放 API | 公开测试；需要已验证账户与 API Key | [报价、创建、轮询与下载](https://animgen.com/docs/zh/api/quickstart) |
| 官方远程 MCP | 公开测试；OAuth 与已验证账户 | [连接 AI 客户端](https://animgen.com/docs/zh/mcp/quickstart) |

> [!IMPORTANT]
> 账户中显示的模型选项、积分报价和导出权益是当前事实来源。文档不会承诺固定生成时长，也不会硬编码整份模型清单。

## 如何使用文档

通过左侧目录查找主题，通过本页目录跳转到具体章节。每篇文章都有固定的语言 URL 和最后核实日期。所有代码示例只使用占位符，不包含真实凭据。

按 Ctrl+K / ⌘K 打开本地搜索。让 AI 查找相同的核实内容，可从 [llms.txt](https://animgen.com/llms.txt) 开始。详见[搜索、AI 入口与反馈隐私](https://animgen.com/docs/zh/reference/ai-and-search)。

套餐与购买方式请查看[定价页](https://animgen.com/pricing)。账户问题可[联系支持](mailto:support@geekart.ai)，请勿附带 API Key、Token 或签名下载链接。

## 按任务深入学习

| 你要完成什么 | 教程 |
| --- | --- |
| 选择素材和生成模式 | [输入模式](https://animgen.com/docs/zh/studio/input-modes) · [模型与提示词](https://animgen.com/docs/zh/studio/models-and-prompts) |
| 制作角色过渡与一致外观 | [首尾帧](https://animgen.com/docs/zh/studio/first-and-last-frames) · [参考图](https://animgen.com/docs/zh/studio/reference-images) · [输入画布](https://animgen.com/docs/zh/studio/input-canvas) |
| 精修已有动作 | [导入视频](https://animgen.com/docs/zh/studio/video-import) · [Advanced Editor](https://animgen.com/docs/zh/editing-and-export/advanced-editor) · [画布与 pivot](https://animgen.com/docs/zh/editing-and-export/canvas-and-pivot) |
| 接入游戏或透明视频 | [格式与引擎指南](https://animgen.com/docs/zh/editing-and-export/output-formats) · [透明兼容性](https://animgen.com/docs/zh/editing-and-export/transparent-formats) |
| 整理账户内容 | [工作区与资源](https://animgen.com/docs/zh/getting-started/workspaces-and-assets) · [账户安全](https://animgen.com/docs/zh/account-and-billing/account-security) · [存储清理](https://animgen.com/docs/zh/account-and-billing/storage-and-cleanup) |
| 让 AI 操作工具 | [连接 Perplexity](https://animgen.com/docs/zh/mcp/connect-perplexity) · [其他 MCP 客户端](https://animgen.com/docs/zh/mcp/connect-clients) · [调用流程](https://animgen.com/docs/zh/mcp/standard-workflow) |

[服务条款](https://animgen.com/zh/terms)、[隐私政策](https://animgen.com/zh/privacy)和[退款政策](https://animgen.com/zh/refund-policy)均提供中文译本。如译文与英文版不一致，除非适用的强制性法律另有要求，以英文版为准。

---

## 管理账户与连接授权 (zh)

Canonical URL: https://animgen.com/docs/zh/account-and-billing/account-security

Status: stable. Last verified: 2026-08-30.

## 先确认实际使用的账户

打开[账户中心](https://animgen.com/account)，检查登录邮箱、验证状态、订阅和积分。浏览器登录与 AI 客户端 OAuth 登录可能属于不同账户。

使用多个登录方式时，购买积分或重新连接客户端前，应确认它们进入的是目标账户。显示名相同不等于身份相同，只使用产品提供的账户关联入口。

账户验证、有效订阅、导出权益和可用积分分别检查，详见[积分与访问权益](https://animgen.com/docs/zh/account-and-billing/credits-and-access)。

## 区分订阅取消与账户删除

账户中心显示当前订阅和计费周期信息。对应支付渠道提供管理入口时，可以通过该链接管理订阅。

安排在周期结束时取消，不等于立即删除账户。应读取显示的生效时间和状态，不要假定权限已经结束。积分包不产生循环订阅，也不自动提高存储等级。

降低套餐前先检查空间用量，下载重要资产，不把网站当作唯一备份。

## API Key 应保存在可信环境

在[账户 → 开发者](https://animgen.com/account/developer)创建和管理 Key。按集成分配最小必要权限，密钥不要进入浏览器前端包；不再使用或已经暴露的 Key 应撤销。

不要把 Key 粘贴到提示词、截图、文档反馈、源代码仓库或支持邮件中，也不要把网页登录 Token 当作公开 API Key。

付费请求结果不确定时，换 Key 会改变幂等身份。应先核对已有任务或请求，再决定后续操作，不要换 Key 后盲目重发。详见[安全重试](https://animgen.com/docs/zh/api/errors-and-retries)。

## MCP 使用 OAuth，不复制 API Key

官方远程 MCP 已开放公开测试。按[客户端接入指南](https://animgen.com/docs/zh/mcp/connect-clients)连接，并在 AnimGen 授权页面核对请求权限。

可在开发者账户区域查看已连接的 MCP 应用，撤销不再使用的授权。客户端不再使用时，还应单独移除其本地配置。撤销 OAuth 授权不会取消已提交任务，也不会退回已经发生的消费。

授权只赋予能力，不代表批准所有后续收费。每次付费生成前，仍要确认具体请求、报价和用户批准。

## 怀疑访问泄露时

先停止使用受影响集成，撤销暴露的 Key 或授权，再检查近期任务和消费记录。如果存在结果不明的付费请求，保留任务 ID 便于核对。

[联系支持](mailto:support@geekart.ai)时提供简明问题描述和相关时间。私有标识仅通过适当的私密支持渠道提供；不要附带 Token、签名 URL、密码或完整支付资料。

---

## 积分与访问权益 (zh)

Canonical URL: https://animgen.com/docs/zh/account-and-billing/credits-and-access

Status: stable. Last verified: 2026-09-19.

## 这是三项检查，不是一项

一个任务可能同时受功能访问权限、输出格式权益和积分余额限制。有积分不代表所有功能都可用。

## Web 访问

符合条件的新账户在完成身份验证和自动资格检查后，会获得账户页面显示的欢迎积分。目前欢迎积分有效期为 7 天，不会刷新；重复创建账号不会形成多份有效领取资格。积分仍在确认或未发放时，账号本身仍可正常使用。免费导出范围为 GIF 和 PNG 逐帧 ZIP。

有效付费订阅，或仍在权益有效期内的合资格积分包购买，可以按照当前产品条款解锁高级 Web 导出与商业使用权益。目前积分包导出权益自购买起持续 365 天。具体条款与余额以[价格页](https://animgen.com/pricing)及账户显示为准。

积分包不等于订阅，不会增加订阅存储或开发者限额。余额为零时，高级 Web 导出权益可能仍有效，但有费用的操作仍需足够积分。

## 月付订阅升级

升级按新套餐全价购买，旧套餐剩余时间不抵扣费用。请在[价格页](https://animgen.com/pricing)确认实际扣款金额、币种、追加完整积分及预计下次续费日后再提交。

付款与新套餐确认后，开始新账期并追加完整积分：Expert 为 3,500，Ultra 为 12,500。原有积分保留各自原到期日，新积分在新账期结束时到期；因此升级后余额可能包含多批仍有效的积分。账户页面可查看已确认账期和积分流水。

升级失败或尚未确认时，不发新积分，也不提前移除原到期日前的已付费权益。请求仍在核对时，请使用“核对付款状态”或联系支持，不要重复付款。降级仍在下次续费日生效。

## 开放 API 访问

开放 API 处于公开测试阶段，需要已验证账户。在[账户 → 开发者](https://animgen.com/account/developer)创建 Key，按调用需要授予最小权限，并撤销不再使用的 Key。注册基础档使用基础限额，有效订阅会提高限额。

积分不能绕过邮箱验证、账户暂停或 Key 权限。产生费用的生成在余额低于当前报价时仍会返回 `INSUFFICIENT_CREDITS`。

## 启动前先获取报价

生成及部分导出处理会消耗积分。费用受模型、时长、分辨率和处理设置影响，应使用界面报价或 API 报价接口，不要依据文档示例写死价格。

报价不是已经扣款，也不保证后续创建时价格不变。API 创建任务时会重新计算。已上线的 MCP 为经过批准的工具调用提供[明确支出保护](https://animgen.com/docs/zh/mcp/spending-safeguards)。

## 取消任务与已有资产

### AI 单帧修复

[高级编辑器](https://animgen.com/docs/zh/editing-and-export/advanced-editor)启用 AI 修复时，先冻结你确认的最高积分，再按实际 tokens 与报价费率结算，绝不超过授权上限。预估不是每张图的固定价格，余额必须覆盖最高冻结额。

差额退回原积分批次，不延长原到期时间。修复失败释放预留；成功生成的候选即使被放弃也仍收费。用量缺失或矛盾时单独核对，不影响使用图片；默认 24 小时核对期限内仍无法确认则免收并释放。这不改变视频生成和导出定价。

### 视频生成与其他资产

Seedance 明确因内容审核拒绝、未交付视频时，退回本次原积分，包括注册赠送积分。API/MCP 一键任务在导出尚未开始时退回生成与导出的整笔积分，不等待供应商账单对账。任务和账单展示实际退回金额；账户或支付异常可能需要核验。

有效积分保留原到期时间；原积分已过期时，仅退回部分获得 30 天有效期，不延长付费权益。这是积分返还，不是现金退款。网络超时、下载或导出失败本身不能证明审核拒绝。

取消属于尽力而为。一旦生产开始，取消不代表已扣积分自动退回；未消耗的预占可以释放，前面阶段已完成的产物可能仍可下载。

导出权益到期可能限制新建高级导出。已有资产的访问仍受归属、保留和存储政策影响，不要把签名 URL 当作永久存储。

处理账户问题时，可向支持提供请求 ID 或任务 ID，以及简短描述。不要附上 API Key、OAuth Token、私有原图或带签名的下载链接。

## MCP 访问与账户管理

MCP 已开放公开测试，同样要求已验证账户，使用 OAuth 而不是 API Key。按[连接指南](https://animgen.com/docs/zh/mcp/connect-clients)接入；授权不等于批准消费，订阅只负责提高账户限额。

账户验证、取消时间与撤销授权见[账户管理](https://animgen.com/docs/zh/account-and-billing/account-security)，资源用量和删除语义见[存储清理](https://animgen.com/docs/zh/account-and-billing/storage-and-cleanup)。

---

## 存储、下载与安全清理 (zh)

Canonical URL: https://animgen.com/docs/zh/account-and-billing/storage-and-cleanup

Status: stable. Last verified: 2026-08-30.

## 在账户中心查看用量

[账户中心](https://animgen.com/account)显示总空间、上传文件大小、产出资产大小、资源数量，以及适用的当前配额。所有工作区保留的上传和资产都计入总量，包括已经隐藏或删除的工作区。

配额取决于适用订阅或服务默认值；购买积分包不会升级存储。以当前账户显示为准，不照搬旧指南中的固定额度。

上传或操作预计超过配额时，可能返回 `STORAGE_QUOTA_EXCEEDED`，包含已用、允许和预计用量。积分余额充足不能解除存储限制。

## 先弄清每种删除的作用

| 操作 | 对空间和依赖的影响 |
| --- | --- |
| 删除任务/历史条目 | 隐藏该任务，不删除关联上传源文件和输出文件 |
| 删除工作区 | 隐藏工作区并请求取消任务，保留文件仍占空间 |
| 恢复工作区 | 恢复访问保留内容，不恢复单独删除的文件 |
| 删除资源/资产 | 将该资源从有效资源中移除，并尝试删除存储字节 |
| 取消运行任务 | 尽力停止，不会自动清理所有保留资源 |

不要为了腾空间直接清空整个工作区。必要时先恢复隐藏工作区，再检查真实资源。

## 安全清理顺序

1. 下载重要文件及配套元数据，确认本地副本能打开。
2. 在正确工作区识别大文件或重复资源。
3. 等待活跃生成/导出完成，或明确取消后等待终态。
4. 检查保存的编辑配方和后续导出是否仍需要源视频。
5. 仅删除确定不再需要的具体资源，再刷新用量。

`RESOURCE_IN_USE` 表示活跃任务仍引用文件。删除任务历史不是绕过该保护的安全办法。即使活跃任务保护不再适用，已保存的 composition 也可能继续依赖来源。

资源删除不属于工作区的软删除/恢复功能。单独删除的上传或输出文件，没有文档承诺的回收站恢复路径。不要用唯一副本测试清理。

## 临时链接不是备份

签名上传/下载 URL 会过期，但底层文件可能仍存在。资产存在时应重新获取授权下载链接，而不是重新生成。临时上传到期清理是另一种生命周期，文件可能真正被移除。

拿到资产 ID 不代表永久保留承诺，需要长期保存的交付物应下载到本地。不要把签名链接公开到问题反馈，也不要把链接有效期当作文件保留期限。

## 用量或下载不正常时

清理后刷新账户视图。存储对象清理失败时，即使逻辑资源已移除，也可能需要支持处理；不要因此反复删除无关文件。

文件找不到时，检查工作区、归属、删除历史，以及是否只是签名链接过期。编辑器缺少来源时，应先核对仍保留的资源，再考虑是否需要重新付费生成。

详见[工作区与资源](https://animgen.com/docs/zh/getting-started/workspaces-and-assets)及[导出排障](https://animgen.com/docs/zh/troubleshooting/export-and-transparency)。

---

## 鉴权与图片输入 (zh)

Canonical URL: https://animgen.com/docs/zh/api/authentication-and-inputs

Status: beta. Last verified: 2026-08-31. API schema: 1.4.0.

## 在可信环境鉴权

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

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

| 开放 API Key 权限 | 对应操作 |
| --- | --- |
| `animations:read` | 账户、积分、模型、任务读取与列表、资产查询 |
| `animations:write` | 上传文件、报价、创建任务、请求取消 |

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

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

```bash
curl --fail-with-body https://api.animgen.com/v1/files \
  -H "Authorization: Bearer $ANIMGEN_API_KEY" \
  -F "file=@character.png"
```

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

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

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

## 方案 B：内联 Base64

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

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

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

## 方案 C：公开 HTTPS 地址

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

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

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

## 匹配模型能力

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

通过 `GET /models` 获取合法模式与参数，并对计划提交的完整请求先报价。透明素材要求见[透明动画](https://animgen.com/docs/zh/studio/transparent-animation)，完整调用见[快速开始](https://animgen.com/docs/zh/api/quickstart)。

---

## 错误、幂等与安全重试 (zh)

Canonical URL: https://animgen.com/docs/zh/api/errors-and-retries

Status: beta. Last verified: 2026-08-31. API schema: 1.4.0.

## 保持一次逻辑操作不变

付费创建接口要求 8–200 字符的 `Idempotency-Key`。生成一次后，与完整请求一起保存；超时或断线重试时复用两者。

同一键与同一规范化请求会返回原操作；同一键换了请求内容则冲突。原请求仍在接受过程中时，可能返回可重试的“处理中”冲突。幂等记录至少保留 24 小时，不要假设永久去重。

去重范围包含账户、操作和 API Key 身份（MCP 对应 OAuth 客户端）。更换 API Key 后，即使幂等字符串相同，也可能创建新任务。创建结果不明时，应先找回已知任务 ID，再处理凭据轮换。

创建结果不明确时，应先找回原任务，不能悄悄换新键。确实要重新生成或修改请求时，应重新获得批准，并使用新逻辑键。

## 读取错误结构

```json
{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests",
    "param": null,
    "retryable": true,
    "request_id": "example-request-id",
    "details": {}
  }
}
```

这是结构示意，不承诺错误消息文本完全相同。根据 HTTP 状态和 `error.code` 分支处理，检查 `retryable`，保留 `request_id` 供支持排查。不要记录原始请求头、图片正文、提示词或签名 URL。

## 如何处理

| HTTP / 常见错误码 | 操作 |
| --- | --- |
| 400 `INVALID_REQUEST`、`INVALID_BASE64`、`INVALID_IMAGE` | 修正输入，不要原样重试 |
| 401 `INVALID_API_KEY` | 检查 Key 是否缺失、到期或被撤销 |
| 402 `INSUFFICIENT_CREDITS` | 核对余额和报价，不自动购买 |
| 403 `API_ACCOUNT_NOT_ELIGIBLE`、`API_ACCOUNT_PAUSED`、`INSUFFICIENT_SCOPE` | 分别处理邮箱验证、账户状态或权限 |
| 404 `NOT_FOUND` | 核对公共资源 ID 和归属 |
| 409 `IDEMPOTENCY_CONFLICT` | 停止，同一键已用于不同请求 |
| 409 `IDEMPOTENCY_IN_PROGRESS` | 可重试时等待，复用原请求 |
| 413 `PAYLOAD_TOO_LARGE`、415 `UNSUPPORTED_MEDIA_TYPE`、422 `IMAGE_DIMENSIONS_TOO_LARGE` | 修正图片体积、编码或类型 |
| 429 `RATE_LIMITED`、`QUEUE_LIMIT_EXCEEDED` | 遵循 `Retry-After`，限制按账户计算 |
| 503 `API_DISABLED`、`API_UNAVAILABLE`、`PROVIDER_UNAVAILABLE` | 仅在标记可重试时重试，否则检查可用状态 |

无权访问资源时，服务可能有意返回“未找到”。不要尝试枚举他人的资源 ID。

## 给重试设定边界

遵循 `Retry-After`（秒数或 HTTP 日期）；缺失时使用带随机抖动的指数退避。设置最大尝试次数和总体截止时间。停止本地等待，不代表服务端已接受的任务也停止。

读取操作可在临时传输故障后重试。付费创建结果不明确时，只有已保存幂等键且请求不变，才能重试。不要盲目重试没有幂等保护的上传或其他非幂等操作。

达到截止时间后，保存已知任务 ID，稍后恢复。任务终态失败时，先检查部分产物，再决定重新导出还是重新生成。

## 账户限额与排查

`PROVIDER_CONTENT_REJECTED` 目前覆盖 Seedance 明确内容审核拒绝的终态，不属于应原样自动重试的临时错误。读取任务的 `credits.status`、`credits.refunded` 和 `credits.released`；`credits.charged` 已是净扣费，不要再减一次退分。确认审核拒绝且尚无产物、导出未开始时，一键任务返还原流程整笔积分。客户端超时或导出失败不等同于这一条件，退分也不构成新一轮付费生成的授权。

通过 `GET /account` 获取当前限制；响应中的限流头可能反映当前计数窗口。多建 Key 不会增加账户容量。多个任务的轮询应分散执行，避免所有客户端同时突发请求。

向支持提供公共请求 ID、已知任务 ID、时间、错误码和简短描述。移除凭据和私有输入。不完整结果见[轮询与下载](https://animgen.com/docs/zh/api/polling-and-downloads)，有界重试实现见 [Python 示例](https://animgen.com/examples/animation-workflow.py)。

---

## 四种语言的完整调用示例 (zh)

Canonical URL: https://animgen.com/docs/zh/api/examples

Status: beta. Last verified: 2026-08-31. API schema: 1.4.0.

## 选择完整工作流

每个示例都会发现当前模型、先报价、保存私有状态、轮询同一个任务，并下载实际文件字节。它们是教学示例，不是生产 SDK。下载后先审阅代码再运行。

| 语言 | 下载 | 环境要求 | 验收范围 |
| --- | --- | --- | --- |
| Python | [animation-workflow.py](https://animgen.com/examples/animation-workflow.py) | Python 3.10+，仅标准库 | 离线工作流测试 |
| TypeScript | [typescript.ts](https://animgen.com/examples/typescript.ts) | Node.js 22.14+ | 严格类型检查、离线工作流测试 |
| cURL | [curl.sh](https://animgen.com/examples/curl.sh) | Bash、curl 7.55+、jq、SHA-256 工具；PNG 输入 | Shell 语法、本机 HTTP Mock |
| C# | [csharp.cs](https://animgen.com/examples/csharp.cs) + [项目文件](https://animgen.com/examples/AnimGenPublicApiExample.csproj) | .NET 8 SDK | 仅语法解析；验收机器没有 .NET SDK |

先阅读[示例完整说明](https://animgen.com/examples/README.md)和 [API 快速开始](https://animgen.com/docs/zh/api/quickstart)。准确参数以自动生成的 [API 参考](https://animgen.com/docs/zh/api-reference)为准。

## 准备请求，不启动付费任务

私密提供 `ANIMGEN_API_KEY`，把 `IMAGE_PATH` 设为原图路径，`ANIMGEN_MODEL` 设为 `GET /v1/models` 返回的模型 ID。第一次运行 TypeScript、cURL 或 C# 时，**不要设置** `ANIMGEN_APPROVE_CREDITS`。账户需要完成邮箱验证，正式生成还需积分充足。

根据所选语言，只执行对应命令：

```bash
# TypeScript
node --experimental-strip-types typescript.ts
```

```bash
# cURL
bash curl.sh
```

```bash
# C#：把两个下载文件放入同一个独立目录
dotnet build AnimGenPublicApiExample.csproj
dotnet run --project AnimGenPublicApiExample.csproj
```

Python 使用[快速开始](https://animgen.com/docs/zh/api/quickstart)中分开的 `prepare` 和 `run` 命令。其他语言会在显示报价后停止；核对报价后，明确设置接受的 `ANIMGEN_APPROVE_CREDITS`，再使用原状态重跑同一命令。

> [!WARNING]
> 这是本地费用预检查，不是服务端强制预算。开放 API 创建既不接受 `quote_id`，也不接受 `max_credits`，创建时会重新计算费用。不要静默批准一个默认金额，也不要把报价理解为锁价。

## 保护状态，并恢复同一个操作

TypeScript 和 C# 使用 `ANIMGEN_STATE`（默认 `animgen-state.json`）；cURL 使用 `ANIMGEN_STATE_DIR`（默认 `animgen-curl-state`）；Python 使用 `--state`。状态格式不同，不要切换语言来重试同一个操作。每份状态只运行一个进程。

状态包含原图与提示词，应放在版本控制之外的私有目录。它保存账户与 API Key 的 ID，但不保存密钥。Windows 下请自行限制目录 ACL。TypeScript/C#/cURL 可通过 `ANIMGEN_OUTPUT` 选择输出目录，Python 使用 `--output`。

创建响应不明确时，保留原状态、账户、**原 API Key 身份**、请求体及幂等键。切换 Key 会改变服务端幂等作用域。示例对超过 24 小时仍未知的创建停止自动恢复。本地超时不等于远程任务取消。

已保存任务 ID 后，重跑只轮询该任务，不再创建。失败或取消的任务仍可能有资产，示例会保存它们，再以非零退出码报告结果不完整。签名下载不携带 API Authorization 请求头；链接过期后通过资产元数据获取新链接。

## 验收范围

Python、TypeScript、cURL 通过 Mock 验证只报价、受控创建、状态复用、轮询及部分资产下载。Python/TypeScript 还模拟创建响应丢失，并核对重试沿用原幂等键。文档验收不调用付费供应商。C# 目前仅通过语法检查；实际使用前请在 .NET 8 环境编译并审阅。

适配自己的项目时，继续阅读[错误与重试](https://animgen.com/docs/zh/api/errors-and-retries)及[轮询与下载](https://animgen.com/docs/zh/api/polling-and-downloads)。

---

## 轮询任务并下载可用产物 (zh)

Canonical URL: https://animgen.com/docs/zh/api/polling-and-downloads

Status: beta. Last verified: 2026-08-31. API schema: 1.4.0.

## 创建响应不等于动画完成

`POST /animations` 返回 HTTP `202`、任务 ID 和 `Retry-After`。收到 ID 后优先保存；进入队列不代表生产已经完成。

轮询 `GET /animations/{id}`。优先遵循服务的 `Retry-After`（目前通常约五秒），遇到临时错误使用有界退避，并设置总体截止时间。不要因为轮询慢就创建新任务。当前公开流程以轮询为主，不提供 Webhook 工作流。

## 状态与阶段

| 状态 | 调用方应做什么 |
| --- | --- |
| `queued` | 等待，工作进程尚未完成任务 |
| `running` | 继续轮询，查看阶段和进度 |
| `cancelling` | 已请求取消但未终结，继续轮询 |
| `succeeded` | 终态，检查并下载产物 |
| `failed` | 终态，同时检查错误与已有产物 |
| `cancelled` | 终态，检查已完成产物及积分记账 |

`stage` 在适用时标明 `video_generation` 或 `animation_export`。`progress` 范围为 0 到 1，不是精确剩余时间。两次轮询间任务可能跨过多个状态，不保证你观察到每个中间状态。

`credits.quoted`、`credits.held`、`credits.charged` 分别表示报价、预占和已扣，不要把初始报价当作最终扣费，也不要把三者相加。

## 失败仍可能有可用产物

一键任务可能先成功生成源视频，再在导出阶段失败。进入终态时，无论 `status` 是否为 `succeeded`，都要检查 `outputs`。

先下载已有资产，再记录错误和缺失的请求格式，准确报告部分完成。只重做必要步骤：已有源视频可以通过 `/animation-exports` 重新导出，不必重新生成动作。

## 安全下载

每个资产包含 `id`、`format`、`mime_type`、`byte_size`、`download_url` 和 `download_expires_at`。

1. 用任务 ID 或资产 ID 保存长期应用状态。
2. 使用返回的签名 URL 下载字节。
3. 不要把 API Bearer 头发送给签名 URL 或重定向后的存储主机。
4. 使用应用自己决定的文件名，并确认下载完整。
5. 链接过期时，用 API Key 调用 `GET /assets/{asset_id}` 获取新链接。

链接有效期较短，应读取 `download_expires_at`，不要写死时长。资产已受存储或保留策略移除时，重新查询不会恢复文件。

签名 URL 相当于临时凭据，不应发布到日志、分析事件、工单或 AI 对话记录。

## 取消任务

对归属自己的任务调用 `POST /animations/{id}/cancel`。取消属于尽力而为，返回的可能仍是中间状态；继续轮询到终态。任务完成也可能先于取消生效。

已经执行的生产可能保留扣费，未消耗的预占可以释放。应检查返回的积分数据，不要承诺一定全额退款。

## 先审核再导出：两阶段流程

使用 `POST /video-generations` 创建视频，再轮询 `GET /video-generations/{id}` 取得视频资产。审核后，把 `source_video_asset_id`、选段和导出设置提交到 `POST /animation-exports`，轮询 `GET /animation-exports/{id}`。

每个新的付费创建操作都应先报价，并使用自己的幂等键。源资产 ID 和任务 ID 不是同一种资源，不能互换。[快速开始示例](https://animgen.com/docs/zh/api/quickstart)演示的是更简单的一键生命周期。

---

## API 快速开始：从图片到下载资产 (zh)

Canonical URL: https://animgen.com/docs/zh/api/quickstart

Status: beta. Last verified: 2026-08-31. API schema: 1.4.0.

## 前提条件

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

在[账户 → 开发者](https://animgen.com/account/developer)创建 Key。通过密钥管理器或私有 Shell 会话提供 `ANIMGEN_API_KEY` 环境变量。不要写进浏览器 JavaScript、发布的游戏、代码仓库或 AI 对话。

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

## 1. 发现可用模型

```bash
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 完整工作流示例](https://animgen.com/examples/animation-workflow.py)。它要求 Python 3.10+，仅使用标准库。

```bash
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` 设置为你接受的金额，再运行：

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

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

> [!WARNING]
> 开放 API 不接受 `max_credits` 或 `quote_id`。此示例的批准金额只是**本地预检查**，不是服务端原子支出上限或锁价承诺；创建时会按当前价格重新计算。如果自动化必须有服务端强制上限，不应使用此示例替代该保障。已上线的 MCP 在独立 OAuth 工具流程中提供[服务端支出保护](https://animgen.com/docs/zh/mcp/spending-safeguards)。

## 4. 安全恢复并检查结果

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

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

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

## 请求会做什么

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

复用上传文件或使用公开图片 URL，见[鉴权与图片输入](https://animgen.com/docs/zh/api/authentication-and-inputs)。任务生命周期见[轮询与下载](https://animgen.com/docs/zh/api/polling-and-downloads)、[错误与重试](https://animgen.com/docs/zh/api/errors-and-retries)。精确契约可下载 [OpenAPI JSON](https://animgen.com/openapi/v1.json)。

Python 示例通过本地 Mock 测试验证，没有通过真实付费生成来做测试。正式接入时，使用一个小型且明确批准费用的任务自行验收。其他语言与各自验收范围见[完整调用示例](https://animgen.com/docs/zh/api/examples)，准确参数见自动生成的 [API 参考](https://animgen.com/docs/zh/api-reference)。

---

## 预览、选区与 FPS 导出 (zh)

Canonical URL: https://animgen.com/docs/zh/api/selection-and-fps

Status: beta. Last verified: 2026-09-15. API schema: 1.4.0.

## 先生成视频，再决定如何导出

用 `/v1/video-generations` 生成视频，保存任务 `outputs[]` 中的视频**资产 ID**。用这个 ID 查询元数据、预览和创建导出。改变选区或 FPS 只调用 `/v1/animation-exports`，无需重新调用生成模型。

`GET /v1/assets/{id}` 和任务视频输出中的 `media` 返回实测的 `duration_seconds`、源平均 `fps`、解码 `frame_count`、显示 `width`、`height`。无法确认的字段是 `null`，不使用供应商标称时长或估算帧数替代。平均 FPS 不能代替可变帧率视频的呈现时间戳。

新视频会记录媒体时间轴；旧视频首次预览、FPS 导出或资产查询时按需探测。无法确定实际时长的 FPS 导出会失败，源视频下载仍可用。

## 预览源素材

向 `/v1/assets/{asset_id}/preview` 发送：

```json
{
  "timestamps_seconds": [0, 1, 2, 3, 4],
  "max_frame_size": 256
}
```

时间点必须位于 `[0, 实际时长)`，允许重复和非顺序输入。返回一张按请求顺序排列、带时间标签的联系表：`image` 是可刷新的图片资产，`width`、`height` 是联系表尺寸；`cells[]` 包含 `index`、`requested_time_seconds`、`source_time_seconds` 和 `rect`。矩形使用左上角原点的像素坐标，不包含下方标签。

用 `image.download_url` 下载图片，不携带 API 或 OAuth 凭据。链接过期后用 `image.id` 查询资产刷新。预览展示原视频，不做生成、抠图、补帧，也不代表最终 Alpha 质量。

当前预览不扣积分，缓存图片计入账户存储。同一源资产与相同参数会复用仍有效的预览。缓存遵循普通资产保留规则，没有独立的按时间到期策略。

## 按 FPS 导出

先向 `/v1/animation-exports/quote` 发送下面的请求，核对费用及 `resolved_export`；确认后向 `/v1/animation-exports` 发送相同请求，并提供新的 `Idempotency-Key`。示例 UUID 需替换为自己的视频资产 ID。

```json
{
  "source_video_asset_id": "00000000-0000-4000-8000-000000000003",
  "selection": {
    "mode": "range",
    "start_seconds": 1,
    "duration_seconds": 2
  },
  "export": {
    "fps": 12,
    "output_formats": ["spritesheet", "spritesheet_json"],
    "output_width": 512,
    "output_height": 512,
    "transparent": {"enabled": true}
  }
}
```

透明导出仍需先按 `alpha_key` 流程生成来源，普通视频不能凭此字段自动去背景。不需要透明处理时省略 `transparent`。

首版 FPS 模式只支持 `spritesheet` 与 `spritesheet_json` 的组合；省略格式时自动选择这两个格式。其他组合明确拒绝。旧 `frame_count` 模式继续支持已有格式。

### 时间契约

- FPS 是按源视频原速采样的频率，不是播放变速或 AI 补帧。
- 起点 `S`、时长 `T`、FPS `F` 的选区是 `[S, S+T)`；采样点是 `S+i/F`，不采终点。
- 帧数为 `ceil(T×F)`。仅在整数帧边界吸收相对 `10^-12` 内的十进制序列化误差，不截断 FPS 输入。
- 按实际呈现时间戳选择当时正在显示的源帧。重复采到源帧或目标 FPS 超过源平均帧率时，`resolved_export.warnings` 提供 `SOURCE_FRAMES_REPEATED`，不自动插帧。
- 对累计播放边界做正数半入的毫秒取整，再相减生成各帧 `duration`。1 秒／24 FPS 的帧时长为 41 或 42 ms，总和为 1000 ms。
- 1.1 秒／12 FPS 得到 14 帧，尾帧为 17 ms，总和为 1100 ms。尾段不丢弃，也不均摊到其他帧。
- 如果尾帧量化为 0 ms，返回 `TIME_PRECISION_UNSUPPORTED`，需要调整选区。
- Aseprite JSON 的逐帧 `duration` 是播放依据。`meta.animgen.fps` 始终是目标频率；时长不统一时 `frameDurationMs` 为 `null`。

报价与任务共享持久化采样计划；成功任务的 `resolved_export` 与 Manifest 对应。摘要只包含选区、目标 FPS、帧数、总毫秒数和警告，不在轮询中重复返回全部采样点。

## 限额、兼容与恢复

默认 FPS 上限为 60、帧数上限为 240，单帧尺寸为 64～1024 像素，选区时长为 0.1～15 秒。图集每边最多 8192 像素、总像素最多 67,108,864。实际配置以 [OpenAPI](https://animgen.com/openapi/v1.json) 中的 Schema 和 `x-animgen-media-limits` 为准。超限报错，不自动降低 FPS。

预览最多 12 个时间点，单帧最长边为 32～512 像素；默认总像素上限 4,194,304、输出上限 10 MiB。媒体探测／预览默认最多同时处理 2 个请求（每个服务进程），媒体处理预算 30 秒，下载每次连接／读取最多 5 秒。源视频最多 256 MiB、120 秒、18,000 个解码帧、单帧 16,777,216 像素。繁忙返回可重试的 `MEDIA_BUSY`；解码超时返回 `MEDIA_TIMEOUT`。所有预算均可由服务配置调整。

`fps` 与 `frame_count` 互斥；两者均省略仍默认 24 帧。历史任务和 `frame_count` 请求保留旧采样、默认值与选区容差。新 FPS 请求严格拒绝越界，`full` 使用实际完整时长，禁止非零起点或额外时长。

一键 `/v1/animations` 和 MCP `generate_animation` 仍使用帧数，明确拒绝 FPS。需要 FPS 时使用分阶段流程，从已存在的视频准确计算导出帧数与报价。API 报价不锁价，也不接受 MCP 专用的 `quote_id`／`max_credits`。

相同凭据、相同幂等键和相同请求复用同一任务；修改选区／FPS 时使用新键。已失败任务的幂等重试仍返回原失败任务；修正后用新键重新导出，继续复用源资产。取消或失败的导出不会删除源视频。

源视频没有独立的按时间自动到期字段；访问仍受资产／任务删除及账户策略影响，不能视为永久备份。签名 URL 到期不等于资产到期，需要长期保存的素材应下载保管。

## MCP 对应流程

1. `quote_video_generation` → 批准费用 → `generate_video` → `get_video_generation`。
2. 保存视频资产 ID，使用 `download_asset` 查询 `media`，使用 `preview_video` 查看候选区间。
3. `quote_animation_export` → 批准费用 → `export_animation` → `get_animation_export`。
4. 下载产物，按 Manifest 逐帧时长导入。

两种创建工具的 `quote_id`／`max_credits` 和 `idempotency_key` 都与 `request` 同级。报价绑定操作类型；导出报价还绑定源视频、选区与导出参数。取消分别使用 `cancel_video_generation` 或 `cancel_animation_export`，参数为 `task_id`。图片上传沿用现有上传工具。

---

## 使用 Advanced Editor 逐帧精修 (zh)

Canonical URL: https://animgen.com/docs/zh/editing-and-export/advanced-editor

Status: preview. Last verified: 2026-09-23.

## 进入当前编辑器

在快速模式中打开已就绪的生成视频或导入视频，选择**精细调整动画**。编辑器面向宽度至少 1024 px 的桌面窗口；小屏幕请使用快速模式或扩大窗口。编辑器控件会跟随所选界面语言，服务端返回的错误详情仍可能显示英文。

源视频不会被修改。保存的 composition 是引用源帧的编辑配方，不是重新生成的视频。再次进入同一来源时，可能复用已有默认配方；替换内容前先检查当前序列。

## 理解五个面板

| 面板 | 用途 |
| --- | --- |
| 源视频监视器 | 用独立播放头检查原始视频 |
| 动画预览 | 预览输出序列、画布与节奏 |
| 源视频帧 | 从解码后的源视频选择帧 |
| 动画序列 | 排列最终需要导出的帧 |
| 画布与逐帧设置 | 切换全局画布设置与选中输出帧的调整 |

源视频与输出序列的播放头相互独立。选中帧不一定等于移动播放头，检查修改时要观察对应预览。

## 建立输出序列

1. 点击源帧缩略图；Shift 点击扩展范围，Ctrl/⌘ 点击切换单帧选择。
2. 使用**插入到播放头后**插入，或用**追加到末尾**、拖放操作把源帧加入序列。
3. 选择输出帧后可移动、重复或删除；成组移动会保留组内顺序。
4. **复制选中帧**会把每个选中项复制到自身旁边，可用于延长姿势停顿。
5. **倒序**反转的是整个序列，不只是选中部分。
6. 通过**撤销／重做**按钮纠正当前编辑会话中的近期操作。

当前上限为 **240 个展开后的输出帧**，重复帧也计入。界面没有独立的单帧时长编辑器；可通过重复帧形成停顿，并检查最终序列长度。

## 调整节奏并理解具体结果

输出 FPS 范围为 1–60。固定 FPS 下，时长等于展开帧数除以 FPS。例如 24 帧以 12 FPS 播放，时长两秒；额外重复其中三帧后，27 帧为 2.25 秒；再改为 24 FPS 则为 1.125 秒。

修改 FPS 不会补出新的中间动作。循环播放只是重复序列，不会修复首尾接缝，应检查边界处的脚底、轮廓与速度。

源帧时间来自视频实际解码的呈现时间戳。经过重排或重复后，源帧编号不等于输出序列编号。

## 调整单帧与替换画面

右侧**整个动画**修改全局画布、位置、缩放和轴心。切到**选中帧**后，在**动画序列**中选择输出帧，可调整该项的 X/Y 偏移与缩放，或直接拖动**动画预览**中的画面。同一个源帧的其他重复项不会一起改变；多选时按相对变化批量调整，保留已有差异。

**重置变换**只重置选中项的变换，不删除替换图片。暂停时开启**洋葱皮**可叠加前后输出帧，辅助观察对齐；叠加层不会导出。

选中一项后，点击**帧图片 → 导出 PNG** 可下载当前已采用的图像（未替换时使用源视频帧）。导出前会保存待提交修改，文件保留源视频原尺寸和透明通道，不烘焙位置、缩放、输出画布或洋葱皮，避免重新导入后重复应用变换。文件名包含保存时的序列编号，例如 `animgen-frame-0012.png`。

在自己的绘图工具中修改 PNG，尽量保持画布尺寸，再选中同一项使用**导入图片**。支持单张 PNG/WebP/JPEG（最多 20 MB）；其他尺寸会保留比例适配源视频画布，不自动裁剪。先用候选区域的**显示修改前**对比，选择**采用图片**才会保存；**丢弃预览**只放弃当前预览。可从**已保存图片版本**重新预览已存版本，或用**恢复源图片**还原源视频帧。未确认候选时，单帧和整段动画导出均不可用。单帧导出不调用 AI 生成，也不扣生成积分。

**选中帧**和**帧图片**标题旁的 **?** 按钮收纳详细调整及导入/导出说明。点击或使用 Enter/空格打开，Escape 或点击外部关闭。错误、处理进度和扣费信息仍在面板直接显示。

部署启用 **AI 修复**后，可拖选矩形区域并输入修改要求。生成前确认预计积分与最高预留额；完成后按实际 token 用量与报价费率结算，扣费不会超过确认的上限，未用积分释放。用量不完整时，候选仍可使用，费用进入待核对；核对期限内仍无法确认则免收并释放预留积分，通常为 24 小时。修复失败也会释放预留积分。

生成会将当前帧及可用的相邻/角色参考图发送至 OpenAI。生成成功的候选需手动接受，放弃候选不退回生成费用。服务端保留修复底图选区外的像素，但不能保证动画连续性；接受前检查相邻帧和循环边界。未启用服务端配置时，AI 按钮不可用，不影响手动调整和图片导入。

## 离开或导出前确认保存

停止修改片刻后会自动保存，观察状态：**未保存 → 正在保存… → 已保存**。**保存失败**不代表已保存。解决错误前保持页面打开，并保留重要编辑内容的记录。

同一配方尽量只在一个标签页编辑，避免版本冲突。编辑器的**返回快速模式**和**导出素材**会尝试提交待保存修改；直接关闭标签页或断网不能保证保存。撤销历史属于当前编辑会话，不是永久的服务端版本历史。

导出使用已保存的 composition 版本和配方快照。确认前核对帧数、FPS、画布、格式和报价。之后继续编辑，不会改写已经提交的导出。

## 当前能力边界

当前提供全局与单帧变换、图片替换，以及部署启用后的矩形局部 AI 修复；不提供变换关键帧插值、自由画笔遮罩、批量 AI 重绘、自动姿势对齐、多轨合成或音频编辑。公开 API/MCP 生成工具也不接受高级编辑器配方。

继续阅读[画布与 pivot](https://animgen.com/docs/zh/editing-and-export/canvas-and-pivot)、[输出格式](https://animgen.com/docs/zh/editing-and-export/output-formats)和[导出排障](https://animgen.com/docs/zh/troubleshooting/export-and-transparency)。

---

## 设置输出画布、对齐与 pivot (zh)

Canonical URL: https://animgen.com/docs/zh/editing-and-export/canvas-and-pivot

Status: preview. Last verified: 2026-09-28.

## 画布改变像素，pivot 改变原点

在 [Advanced Editor](https://animgen.com/docs/zh/editing-and-export/advanced-editor) 中，画布和角色控件影响实际渲染的输出帧；pivot 告诉引擎把精灵原点放在哪里。移动 pivot **不会**改变 PNG 内已经绘制的像素位置。

这与生成前准备源图的[输入画布](https://animgen.com/docs/zh/studio/input-canvas)不同。输出摆放只复用已有动作。

## 选择一致的帧画布

当前 Inspector 的宽高范围为 64–1024 px，并提供 256、512、1024 方形预设。应结合目标显示尺寸和纹理预算选择；放大画布会增加文件量，但不会恢复源图没有的细节。

画布背景可选 **Transparent** 或 **Solid**。透明画布只让没有绘制内容的区域透明，不会自动去掉源画面已有的不透明背景。

| 角色设置 | 效果 |
| --- | --- |
| Center / Bottom center | 在画布中全局居中或底部居中 |
| Contain | 完整放入原图，可能留下空白 |
| Cover | 填满画布，可能裁掉部分原图 |
| Original pixels | 从源图原始像素大小开始 |
| Scale | 额外全局缩放，范围 0.1–3 |
| X / Y offset | 以输出像素为单位的全局位移 |

修改后应检查多个姿势。站立帧放得下，不代表跳跃帧不会裁切。全局对齐不会自动跟踪脚底，也不会逐帧独立校准。

## 有意识地设置 pivot

Pivot 的两个坐标范围均为 0–1，原点在**左下角**：

| 目标原点 | X | Y |
| --- | --- | --- |
| 底部居中 | 0.5 | 0 |
| 画布中心 | 0.5 | 0.5 |
| 左下角 | 0 | 0 |

地面角色可从底部居中开始。它表示画布原点，不是自动检测出的脚底。多段动画共用引擎变换时，应保持一致的画布构图。

## 读取导出的坐标约定

`animgen-manifest.json` 的 schema 为 `animgen.sprite-export.v1`。帧矩形使用 `rectOrigin: "top_left"`，而 `pivot.origin` 为 `"bottom_left"`。两套坐标约定不同是有意设计。

清单还记录帧尺寸、图集尺寸、FPS、循环、帧数、名称和矩形位置。应读取这些值，不要凭纹理大小猜测网格，尤其是图集包含补边时。

Unity 元数据保存逐精灵 pivot；Godot 场景通过 offset 应用 pivot，只赋 SpriteFrames 资源不会带上场景偏移；Cocos 示例播放器可把导出的 pivot 应用到 UITransform。对应操作见[引擎导入指南入口](https://animgen.com/docs/zh/editing-and-export/output-formats)。

Construct 3 的图像原点以左上角为基准。导出器在动画导入配置中自动转换为 `originX = pivotX`、`originY = 1 - pivotY`，不要再次翻转 Y。详见 [Construct 3 导入](https://animgen.com/docs/zh/editing-and-export/construct3)。

## 交付前如何检查

在固定背景或网格下检查首尾帧、动作伸展部位和原点标记，再把同一段序列放到小型引擎场景中对照。

导出透明视频时，需要透明画布及合法的透明来源处理。纯色画布与透明视频输出冲突。结果不同于预期时，先做[导出与透明排障](https://animgen.com/docs/zh/troubleshooting/export-and-transparency)，再决定是否重新付费生成。

---

## 导入 Cocos Creator 3 动画 (zh)

Canonical URL: https://animgen.com/docs/zh/editing-and-export/cocos-creator

Status: stable. Last verified: 2026-08-30.

## 了解导出文件

选择 `cocos_creator_pack`，ZIP 内包含 `spritesheet.png`、`spritesheet.plist`、`AnimGenSpritePlayer.ts`、`animgen-manifest.json` 和 README。

PLIST 使用 Cocos2d-x 图集格式 3。TypeScript 文件是 Sprite 组件播放器示例，不是原生 AnimationClip，也不是完整游戏控制器。

## 图集成对导入

保持 PNG 与 PLIST 名称不变，同时导入同一个 Assets 目录。生成的 SpriteAtlas 可以展开为独立 SpriteFrame 子资源。配对导入说明见 [Cocos 官方 Atlas 文档](https://docs.cocos.com/creator/3.8/manual/en/asset/atlas.html)。

导入播放器脚本并等待编译。创建 Sprite 节点，挂载 **AnimGenSpritePlayer**，把导入的 SpriteAtlas 赋给 **atlas** 属性。

## 配置播放器

| 属性 | 行为 |
| --- | --- |
| `atlas` | 提供逐帧精灵的图集 |
| `fps` | 播放速度，初始值来自导出 FPS |
| `loop` | 循环或停在最后一帧 |
| `playOnLoad` | 加载后开始播放 |
| `applyExportedPivot` | 将 UITransform 锚点设为本脚本内嵌的导出 pivot |

脚本按帧名的数字顺序排序，先显示首帧，再按经过时间推进，并提供 `play()`、`stop()` 供集成。修改运行行为后，应验收自己的组件，不再假定它与生成示例完全一致。

## 多份导出复用同一个组件

每份包都使用 `AnimGenSpritePlayer` 类名。不要为项目中的每段动画重复导入一份同名类。

复用一个播放器组件，为各节点明确指定 atlas、FPS 和循环设置。脚本内嵌的是生成该脚本时的 pivot。如果其他导出需要不同 pivot，关闭 `applyExportedPivot`，分别设置各节点的 UITransform 锚点，或有意识地改造成自己的通用播放器。

## 验收结果

按 `animgen-manifest.json` 核对帧数和 FPS，再在小场景中检查首尾接缝、节点缩放、锚点、透明和绘制顺序，最后接入游戏逻辑。

节点空白时，检查脚本编译、atlas 赋值、Sprite 组件及图集子资源是否存在。显示整张图时，确认使用的是 SpriteAtlas，而不是独立纹理。

缺帧时，确认 PNG 与 PLIST 来自同一次导出且一起导入。切换动画时锚点跳动，则检查上面的逐导出 pivot 处理。详见[画布与 pivot](https://animgen.com/docs/zh/editing-and-export/canvas-and-pivot)和[透明格式](https://animgen.com/docs/zh/editing-and-export/transparent-formats)。

生成示例面向 Cocos Creator 3.x；包检查不能替代在你实际编辑器和目标构建中的导入运行测试。

---

## 将透明动画导入 Construct 3 (zh)

Canonical URL: https://animgen.com/docs/zh/editing-and-export/construct3

Status: stable. Last verified: 2026-09-28.

## 先用实测示例验证

[下载 Construct 3 示例包](https://animgen.com/demo/animgen-demo-construct3.zip)：包含 **96 张 96 × 96 的透明 PNG 帧，以 24 FPS 播放**。无需先生成或购买动画，就能验证导入流程。

本指南于 **2026 年 9 月 28 日，在 macOS / Chrome / Construct r495.2 免费版** 中验证。检查覆盖导入参数、实际播放、透明度，以及保存后的工程与原始导出帧对照。这是动画资产工作流，不是 Construct 插件，也不是完整的 `.c3p` 游戏项目。

## 在 AnimGen 中准备动画

生成或导入视频，选取有效片段并检查帧序。需要透明效果时，使用合适的源素材并开启透明导出；仅选择引擎包不会自动去掉背景，详见[透明动画工作流](https://animgen.com/docs/zh/studio/transparent-animation)。

在导出对话框中选择 **Construct 3 包**。Web 工作台导出此包需要付费导出权益；公开示例可免费下载，用于兼容性测试。详见[积分与访问权益](https://animgen.com/docs/zh/account-and-billing/credits-and-access)。

需要逐帧调整时，使用[高级编辑器](https://animgen.com/docs/zh/editing-and-export/advanced-editor)，设置播放帧率和循环，并等待编辑配方保存后再导出。高级导出保留已保存的循环设置；快速导出和开放 API 默认循环，也可以在 Construct 导入后调整。

## 只解压外层 ZIP

下载包的结构如下：

```text
AnimGen_<id>_Construct3/
  animation.zip
    c3-import-settings.json
    frame_0000.png
    frame_0001.png
    ...
  spritesheet.png
  animgen-manifest.json
  README_Construct3.md
```

解压外层包，**保持内部 `animation.zip` 完整，不要解压它**。真正要导入的是内层 ZIP，其中的配置保存帧序、动画名称、帧率、循环和图像原点。图集仅作参考，不要把它当成额外一帧导入。

## 从顶部工具栏导入

1. 在 Construct 小型测试项目中创建 **Sprite（精灵）**，或打开已有精灵的动画编辑器。
2. 找到**顶部工具栏** 的文件夹图标，打开旁边的下拉菜单。
3. 选择 **Load animations（导入动画表）**，选取内部 **`animation.zip`**。
4. 选中新导入的动画并检查属性；这个流程不要使用 **Load frames（导入图像）**。
5. 关闭动画编辑器，在精灵实例的 **Initial animation（初始动画）** 中选择新动画，再预览场景；尤其注意不要仍然使用空白默认动画。

![Construct 动画编辑器顶部工具栏中的“导入动画表”入口](https://animgen.com/docs-assets/construct3/load-animations-menu.png)

截图为简体中文界面，第二项“导入动画表”对应英文 **Load animations**。[Construct 官方动画编辑器手册](https://www.construct.net/en/make-games/manuals/construct-3/interface/animations-editor)介绍了动画 ZIP 导入机制。

> [!WARNING]
> r495.2 实测中，Animations 面板的右键导入仅加载了 PNG，没有应用导入配置。请使用上面的顶部工具栏入口。已经通过其他入口导入的动画，应重新核对帧率、循环和原点，不能只以“图片出现了”判断导入正确。

## 检查导入结果

![Construct 中的 tactician_slash：96 帧、速度 24、循环开启，原点为 48,96](https://animgen.com/docs-assets/construct3/imported-animation.png)

这是实际测试编辑器截图，不是模拟图。示例动画是 `tactician_slash`；截图中的其他名称属于独立的 QA 测试素材。

| 检查项 | 示例包的预期结果 |
| --- | --- |
| 动画名称 | `tactician_slash` |
| 帧数与尺寸 | 96 帧，每帧 96 × 96 |
| 播放速度 | 24 FPS |
| 循环 / 重复次数 / 往返播放 | 开启 / 1 / 关闭 |
| 原点 | 像素 (48, 96)，即底部中央 |
| 透明度 | 角色外可见棋盘格，放到场景中没有不透明矩形背景 |
| 运行时 | 完整周期结束后继续播放，首末帧顺序正确 |

预览场景，与 AnimGen 中的动作对照。另一个独立测试使用 **45 帧、23.976 FPS、关闭循环**，实际停在第 44 帧；AnimGen pivot 为 (0.25, 0.75) 时，在 96 × 96 图像中导入为像素原点 (24, 24)。

AnimGen 的归一化 pivot 以左下角为原点，Construct 图像原点以左上角为基准。导出器已经自动转换 Y：`originY = 1 - pivotY`，不要再手工翻转一次。详见[画布与 pivot](https://animgen.com/docs/zh/editing-and-export/canvas-and-pivot)。

## 通过 API 或 MCP 使用同一格式

在**按帧数导出** 的工作流中，把 `construct3_pack` 放入 `export.output_formats`。分阶段 API 的 `export.fps` 采样路径目前仅支持精灵图与 JSON 组合，不要把 Construct 包加入这个 FPS 请求。详见[选段与 FPS](https://animgen.com/docs/zh/api/selection-and-fps)。

仍需遵循报价、确认消费、创建、轮询和下载流程。API/MCP 访问遵循开发者契约，商业使用权限仍遵循付费条款。参见 [API 快速开始](https://animgen.com/docs/zh/api/quickstart)和 [MCP 工作流](https://animgen.com/docs/zh/mcp/standard-workflow)。

## 常见问题

- **出现整张大图或重复图片：** 确认选择的是内部 ZIP，而不是外层包或参考图集。
- **速度、循环或锚点不对：** 使用顶部工具栏导入，对照 `animgen-manifest.json`，并确认选中了目标动画。
- **场景空白或不动：** 检查初始动画、播放速度，以及是否真正预览了场景，而不只是停在图像编辑器中。
- **切换动作时角色跳位：** 各动画保持一致的画布尺寸和 pivot。pivot 不是自动识别的脚底位置。
- **碰撞形状不合适：** 在 Construct 项目中检查碰撞多边形和玩法行为。导出包不配置碰撞、事件、角色控制器或专用 VFX 材质。

返回[输出格式](https://animgen.com/docs/zh/editing-and-export/output-formats)、[导出问题排查](https://animgen.com/docs/zh/troubleshooting/export-and-transparency)，或[用自己的素材开始制作](https://animgen.com/app?mode=register)。

---

## 导入 Godot 4 动画 (zh)

Canonical URL: https://animgen.com/docs/zh/editing-and-export/godot

Status: stable. Last verified: 2026-09-09.

## 包内有什么

导出 `godot_pack` 后，命名根目录内包含 `spritesheet.png`、`animation.tres`、`animation.tscn`、`animgen-manifest.json` 和 README。

`.tres` 是由 AtlasTexture 帧矩形组成的 Godot 4 SpriteFrames 资源；`.tscn` 包含使用该资源的 AnimatedSprite2D，配置了自动播放及 pivot 对应的偏移。它不是 Godot 3 的 AnimatedSprite 资源。

## 保持根路径一致

解压后，把包中的**命名根目录放到 Godot 项目根目录下**。README 会给出预期的 `res://<导出目录>/` 路径。

生成文件中的资源引用包含这个目录名。只移动 `animation.tres`、重命名根目录，或将其额外嵌套一层但不更新引用，都会导致找不到纹理或资源。

等待 Godot 导入 PNG，再打开 `animation.tscn`，或把它实例化到小型测试场景中。

## 使用现成场景或已有节点

最快的方式是使用包内场景。已有 AnimatedSprite2D 时，可把 `animation.tres` 赋给 Sprite Frames，选中导出的动画并配置播放。

[Godot 官方二维精灵动画指南](https://docs.godotengine.org/en/stable/tutorials/2d/2d_sprite_animation.html)说明 AnimatedSprite2D、SpriteFrames、播放和 FPS。AnimGen 资源已经写入帧、循环标志及速度，无需重新切割 PNG。

只赋 SpriteFrames **不会**复制生成场景中的 offset。需要保留非居中的 pivot 时，还应同步场景偏移，或在已有节点中设置对应原点。

## 检查节奏与对齐

按 `animgen-manifest.json` 核对帧数和 FPS，确认父节点变换或项目脚本没有额外修改速度和位置。至少播放一个完整循环，用固定基准线检查落地姿势。

节点完全不可见时，先查缺失资源报错、纹理导入、所选动画、可见性与场景位置。帧内容不对时，检查是否混用了不同导出任务的纹理和 `.tres`。

边缘显示与 Studio 不同时，应使用同一份 PNG 基线检查目标纹理过滤和渲染设置，详见[透明格式](https://animgen.com/docs/zh/editing-and-export/transparent-formats)。

## 安全复用

尽量保留包内名称和路径。确实需要整理目录时，同时修改 `animation.tres` 的纹理路径与 `animation.tscn` 的资源路径，再重新打开验证。

包生成测试通过，不等于你的 Godot 项目已完成运行时验收。接入游戏逻辑或导出到目标设备前，先完成小项目导入测试。

## 复现已经实测的样例

[Godot 4 导入实测文章](https://animgen.com/zh/blog/import-transparent-animation-into-godot-4)记录了 Godot 4.7.2 中的真实导入和播放检查，并提供公开资产包、可下载最小项目、运行录屏和测试边界。可以先复现这份样例，再用自己的导出素材和目标环境重复检查。

---

## 选择输出格式 (zh)

Canonical URL: https://animgen.com/docs/zh/editing-and-export/output-formats

Status: stable. Last verified: 2026-10-05.

## 从使用目标开始选择

想快速检查结果，先下载 PNG 帧 ZIP。自研运行时通常使用精灵图与配套 JSON。需要引擎导入时，选择对应引擎包，并阅读包内说明。

Web 导出对话框初始选择 PNG 帧 ZIP；一键开放 API 省略 `output_formats` 时默认是 `spritesheet`。如果流水线依赖固定产物，请显式指定格式。

## 格式对照

| API 格式 | 返回内容 | 常见用途 |
| --- | --- | --- |
| `clip_video` | 选段 MP4，不透明 | 审核、普通视频播放 |
| `webm_alpha` | 带 Alpha 的 WebM | 支持透明视频的播放器，需实测目标环境 |
| `prores_4444` | 带 Alpha 的 ProRes 4444 | 合成、视频编辑 |
| `gif` | GIF 动图，可选透明背景 | 分享短动画 |
| `frames_zip` | PNG 逐帧 ZIP | 逐帧检查、自定义导入 |
| `spritesheet` | PNG 纹理图集 | 打包成单张纹理 |
| `spritesheet_json` | 配套帧元数据 | 帧矩形和时间信息 |
| `unity_meta` | Unity 纹理元数据 | 与匹配的精灵图配套使用 |
| `unity_pack` | Unity ZIP | 图集、元数据、JSON、清单与说明 |
| `godot_pack` | Godot 4 ZIP | SpriteFrames 与 AnimatedSprite2D 资源 |
| `unreal_paper2d_pack` | Unreal Paper2D ZIP | PNG 图集及 Paper2D 精灵描述 |
| `cocos_creator_pack` | Cocos Creator 3.x ZIP | PNG/PLIST 图集和示例播放器 |
| `construct3_pack` | Construct 3 动画导入包 | PNG 帧、原生导入配置、参考图集与说明 |

Construct 3：解压外层包，通过 Sprite 动画编辑器顶部工具栏的 **Load animations（导入动画表）**载入内部 `animation.zip`。配置包含帧序、帧率、循环和原点。完整步骤、截图、播放验收和 r495.2 右键导入注意事项见 [Construct 3 导入指南](https://animgen.com/docs/zh/editing-and-export/construct3)，也可先[下载示例包](https://animgen.com/demo/animgen-demo-construct3.zip)。它不是 `.c3p` 完整项目，也不是插件。

元数据本身不是图片，应同时请求或保存配套纹理。以响应中的 `outputs` 为实际资产清单，不要假设某个数组位置或固定扩展名一定存在。

## 透明是来源与格式的共同约定

普通 MP4 和原始生成视频保持不透明。透明 PNG、图集、引擎资源、透明 WebM 和 ProRes 4444 需要合适的来源及导出设置。

开放 API 只支持 Alpha Key 来源的透明处理，不对任意背景进行抠图，详见[透明动画](https://animgen.com/docs/zh/studio/transparent-animation)。

即使文件包含 Alpha，播放器也可能不显示。请在目标软件中测试；可以用 PNG 帧或适配的编辑器，区分显示兼容问题和导出问题。

## 完整保留引擎包结构

引擎 ZIP 内包含 `animgen-manifest.json` 和说明文件。不要随意打乱相对路径；Godot 资源会引用包内路径，Unreal Paper2D 导入也需要相应引擎工具。

清单中的帧矩形使用左上角原点；归一化 pivot 使用左下角原点。读取清单，不要仅凭纹理尺寸推断。先在小型测试场景检查帧顺序、播放速度、缩放、锚点和透明效果，再接入整个项目。

## 积分、权益与下载

免费 Web 访问包含 GIF 和 PNG 帧 ZIP。高级格式需要付费导出权益；积分余额与格式权益是独立检查，详见[积分与访问权益](https://animgen.com/docs/zh/account-and-billing/credits-and-access)。

资产下载使用短期签名链接，应保存文件而不是 URL。API 调用方请查看[轮询与下载](https://animgen.com/docs/zh/api/polling-and-downloads)。

## 按引擎完成导入

导出后继续阅读 [Unity](https://animgen.com/docs/zh/editing-and-export/unity)、[Godot 4](https://animgen.com/docs/zh/editing-and-export/godot)、[Unreal Paper2D](https://animgen.com/docs/zh/editing-and-export/unreal-paper2d)或 [Cocos Creator 3](https://animgen.com/docs/zh/editing-and-export/cocos-creator)。各指南对应包内真实文件、路径和播放器，不假定所有引擎已经完成运行时验收。

Construct 3 用户请继续阅读[分步导入指南](https://animgen.com/docs/zh/editing-and-export/construct3)，其中的可下载示例已在 r495.2 实测。

需要调整摆放时参考[画布与 pivot](https://animgen.com/docs/zh/editing-and-export/canvas-and-pivot)，需要视频合成时参考[透明格式兼容性](https://animgen.com/docs/zh/editing-and-export/transparent-formats)。

如果正在三种通用 Alpha 输出之间做选择，可以继续查看实测的 [WebM Alpha、ProRes 4444 与 PNG 序列对比](https://animgen.com/zh/blog/webm-alpha-vs-prores-4444-vs-png-sequence)。

面向 2D 游戏运行时，可以继续查看实测的[精灵图与 PNG 序列对比](https://animgen.com/zh/blog/sprite-sheet-vs-png-sequence)：同一组 96 帧对比文件体积、解码 RGBA 基线、元数据和最大纹理尺寸。

## GIF 导出

免费账号可以导出 GIF 和 PNG 帧 ZIP。在导出对话框勾选 GIF；普通工作台和高级编辑器都会使用编辑后的最终帧。普通工作台默认循环，高级编辑器沿用循环设置。完成后选择导出任务即可预览 GIF 并查看文件大小。

GIF 调色板最多 256 色，仅支持完全透明或不透明，柔和阴影和发光可能变化。帧时长按 10 毫秒精度取整，总时长保持到该精度；最高支持 50 FPS。需要更小文件时降低尺寸、帧率或缩短片段。AI 生成和收费抠图沿用原报价，GIF 编码不额外扣积分，也不额外授予商业使用权。

公开 API/MCP 使用 `output_formats: ["gif"]` 和 `frame_count`。独立的 `fps` 采样模式仍仅支持精灵图与 JSON；GIF 按所选时长和帧数播放。

---

## 透明格式与播放兼容性 (zh)

Canonical URL: https://animgen.com/docs/zh/editing-and-export/transparent-formats

Status: stable. Last verified: 2026-09-13.

## 透明有三个检查点

透明结果需要：合适的来源/处理流程、能保存 Alpha 的格式、实际使用该通道的播放器或渲染器。满足其中一点，不代表其余两点也成立。

公开 API/MCP 流程应从带有效 Alpha 的图片开始，使用 `video.transparency.mode: "alpha_key"` 并开启透明导出。这不是任意背景移除服务。原始生成视频使用临时键色背景，本身仍不透明。

## 按目标环境选择格式

| 输出 | 当前编码或结构 | 如何验收 |
| --- | --- | --- |
| PNG 帧 ZIP | 独立 RGBA 图片 | 在深浅背景上检查代表帧 |
| 精灵图 / 引擎包 | PNG 加帧信息或引擎元数据 | 检查纹理 Alpha、材质和导入设置 |
| WebM Alpha | 带 Alpha 元数据的 VP8 | 实测应用使用的浏览器、系统、设备和解码器 |
| ProRes 4444 | MOV 容器中的 Alpha 兼容 ProRes | 使用支持该 profile 的剪辑或合成软件 |
| MP4 片段 / 原始视频 | 不透明视频 | 不应期待透明输出 |

当前 WebM Alpha 编码使用 **VP8**，不是 VP9。仅显示“支持 WebM”不能证明支持此组合中的 Alpha。ProRes 4444 面向编辑和交换，不承诺在所有浏览器内嵌播放。

不能只看扩展名。任意 MOV 或 PNG 都可能是不透明文件；同一个透明文件也可能在某个查看器里显示黑底，在另一个软件中正确合成。

## 用同一帧做对照排查

1. 选择包含动作和细边缘的短片段。
2. 在权益和报价允许时，同时导出 PNG 帧与目标格式。
3. 将同一帧分别放到白色、深灰和对比色背景上。
4. PNG Alpha 正确但视频显示异常时，先检查解码与合成，不要直接重新生成动作。
5. 各种输出都出现同一不透明区域时，检查来源模式、导出透明开关、画布背景和源图 Alpha。

原图中画上去的棋盘格不是透明；只把输出画布设成透明，也不会消除每帧内部已有的不透明背景。

## 不只看四角，还要看边缘

检查头发、烟雾、半透明服装、运动模糊和接近键色的区域。光晕可能来自源图污染、键色溢出、缩放、滤波或目标软件对 Alpha 的解释方式。

对照时优先使用原始导出文件，避免经过可能压平透明通道的中间转换器。引擎纹理还应检查目标平台的过滤、压缩和材质设置。改扩展名不能修复丢失的通道。

导出校验失败时仍可能有部分可用资产。应保存这些文件并检查报错，不能仅因视频已经生成就把整个任务判为成功。

## 预算与交付

高级格式需要导出权益，处理也可能消耗积分。大批量交付前先做小范围兼容性测试；下游需要备用路径时，保留通用的 PNG 基线和匹配元数据。

需要接入网站时，可以直接使用经过实测的[网页透明角色动画 HTML 指南](https://animgen.com/zh/blog/add-transparent-character-animation-to-website)及其 WebM／PNG 下载示例。然后继续阅读[输出格式](https://animgen.com/docs/zh/editing-and-export/output-formats)和[透明导出排障](https://animgen.com/docs/zh/troubleshooting/export-and-transparency)。

需要直接做选择时，可以查看 [WebM Alpha、ProRes 4444 与 PNG 序列实测对比](https://animgen.com/zh/blog/webm-alpha-vs-prores-4444-vs-png-sequence)：同一段 96 帧动画提供三种真实文件，并公布文件大小、解码后 Alpha 检查与原始下载。

---

## 选段与导出 (zh)

Canonical URL: https://animgen.com/docs/zh/editing-and-export/trim-and-export

Status: stable. Last verified: 2026-08-30.

## 生成和导出是两个步骤

生成负责创建源动作；导出负责从选定区间采样并打包结果。你可以先检查源视频，再多次导出不同版本，不必每次重新调用视频模型。

在 Studio 选择已生成的视频，或通过“导入动画”使用你有权处理的现有视频。来源的背景和透明条件仍会影响可用的导出处理。

## 选择有效区间

先播放源视频，再调整时间线的起止手柄。逐帧检查，避开动作被截断的位置和变形的过渡。需要循环时，重复预览所选区间。

循环是否自然取决于素材本身；选段和重复播放不会自动生成匹配的结束姿态。

## 设置帧率与尺寸

打开导出对话框前，设置导出帧率和尺寸。区间时长与帧率决定需要打包的帧数；例如一秒区间在 24 FPS 下约为 24 帧，实际以选段边界和界面汇总为准。

帧数越多，文件越大，也可能增加处理费用。放大输出尺寸不会恢复源视频中不存在的细节。首次测试引擎导入时，先用适中的尺寸检查效果。

## 确认导出

点击“导出”后：

1. 选择一种或多种[输出格式](https://animgen.com/docs/zh/editing-and-export/output-formats)。
2. 如果需要透明结果，检查透明处理设置。
3. 核对帧数、尺寸、权益限制和积分报价。
4. 点击一次“开始导出”，观察任务状态。

格式锁定时，查看[积分与访问权益](https://animgen.com/docs/zh/account-and-billing/credits-and-access)。无法估算费用不等于费用为零。

## 找到文件

在左侧项目面板打开“当前片段的导出”，选择已完成的记录并下载资产。导入引擎包时，保持 PNG 与配套 JSON、元数据或引擎资源之间的目录关系。

后续导出失败，不代表源视频或先前成功的产物无效。重新提交前先检查现有结果。下载链接过期时，从结果界面重新获取，不要继续分享旧的签名 URL。

## API 中的对应流程

一键 API 默认选择整个源视频。指定区间时，以秒为单位：

```json
{
  "selection": {"mode": "range", "start_seconds": 1.0, "duration_seconds": 1.0},
  "export": {"frame_count": 24, "output_width": 512, "output_height": 512}
}
```

API 使用 `frame_count`，不是顶层 `fps`。这只是请求片段，不能单独创建任务。需要先审核再导出时，使用 `/video-generations` 创建视频，再通过 `/animation-exports` 导出它的视频资产；详见[轮询与下载](https://animgen.com/docs/zh/api/polling-and-downloads)。

## 需要不连续选帧或重排时

快速裁剪适合连续片段。需要重复姿势、移除中间帧、反转或调整全局画布时，使用 [Advanced Editor](https://animgen.com/docs/zh/editing-and-export/advanced-editor)。先确认配方保存，再导出；它不会重新 AI 生成动作。

---

## 导入 Unity 动画 (zh)

Canonical URL: https://animgen.com/docs/zh/editing-and-export/unity

Status: stable. Last verified: 2026-08-30.

## 导出 Unity 包

在导出对话框或公开请求中选择 `unity_pack`，核对[导出权益与报价](https://animgen.com/docs/zh/account-and-billing/credits-and-access)，等待导出完成并下载 ZIP 文件。

包内包含 `spritesheet.png`、`spritesheet.png.meta`、配套 JSON、`animgen-manifest.json` 和 README。先解压到新目录，避免意外覆盖项目已有资产或 GUID。

## 纹理和元数据一起导入

把整个导出目录复制到 Unity 项目的 `Assets`，保持 PNG 与相邻 `.meta` 的文件名关系。元数据配置了多精灵导入，并携带帧矩形和 pivot。只先导入 PNG 而不带元数据时，Unity 可能生成另一套导入设置。

在 Project 窗口选择纹理，检查 **Sprite (2D and UI)**、**Multiple**，并在 Sprite Editor 中查看切片。控件说明见 [Unity 官方 Sprite Editor 文档](https://docs.unity3d.com/Manual/sprite/sprite-editor/use-editor.html)。

不要直接按不透明边界重新自动切片，否则可能改变统一帧尺寸、对齐和透明留白。某版本需要手工修复时，应按导出矩形和 pivot 配置，不要猜网格。

## 创建所需动画

导出包提供精灵资源，不提供预制 Animator Controller 或游戏状态机。按数字后缀顺序（`_0000`、`_0001` 等）选择精灵，通过项目自身的动画流程创建 Animation Clip。Unity 精灵名以导出任务 ID 为前缀；配套 JSON 中的 `frame_0000.png` 并不是同名的 Unity 资产。

按 `animgen-manifest.json` 中的 `animation.fps` 设置采样节奏，并明确设置循环行为。循环前检查首尾是否重复造成停顿；Transform 缩放和 pixels-per-unit 应与游戏其他资源保持一致。

## 在小场景中验收

对照 `animation.frameCount` 检查精灵数量，再与 Studio 播放对比。用固定基准线检查脚底、对象变换原点处的 pivot、透明边缘和首尾接缝。

只看到整张图集时，检查多精灵设置和正确的 `.meta` 是否一起导入。动作抖动时，先比对帧矩形与 pivot，不要立即改生成参数。像素模糊或光晕也可能与目标项目的过滤、压缩和材质有关。

## 保留可复查的交付

保存 ZIP 和清单，便于复核。更换元数据可能影响项目中的已有资产引用，建议通过版本控制或副本测试重新导入。

本指南对应 AnimGen 实际包结构与 Unity 导入流程，不代表所有 Unity 版本和渲染管线都已认证。显示不同于预期时，查看[画布与 pivot](https://animgen.com/docs/zh/editing-and-export/canvas-and-pivot)和[透明格式](https://animgen.com/docs/zh/editing-and-export/transparent-formats)。

---

## 导入 Unreal Paper2D 动画 (zh)

Canonical URL: https://animgen.com/docs/zh/editing-and-export/unreal-paper2d

Status: stable. Last verified: 2026-08-30.

## 导出配套资源包

选择 `unreal_paper2d_pack`，检查报价和权益，再下载解压。保持 `animation.paper2dsprites` 与 `spritesheet.png` 相邻；包内还包含清单和 README。

描述文件保存了明确帧矩形。纹理会补成 2 的幂尺寸，但原来的帧矩形位置不会移动。新增空白不是动画帧，不能通过补边后的纹理宽高直接推算帧数。

## 导入描述文件，不只导入 PNG

在当前 Unreal 安装中启用内置 Paper 2D 及其导入器支持，按提示重启编辑器。通过 Content Browser/Content Drawer 导入 `animation.paper2dsprites`。

JSON 精灵图导入可以生成纹理、Sprite 和 Flipbook。如果当前流程只产生精灵，可按帧数字顺序选择后创建 Flipbook。操作参考 [Epic 官方 Paper 2D Flipbooks 指南](https://dev.epicgames.com/documentation/en-us/unreal-engine/paper-2d-flipbooks-in-unreal-engine)。

只导入 PNG 不会自动还原包中的帧描述。AnimGen 通用精灵图 JSON 也不能代替 Paper2D 专用描述文件。

## 对齐动画设置

打开导入或新建的 Flipbook，按 `animgen-manifest.json` 核对精灵数量、顺序及 Frames Per Second。导入器默认 FPS 不一致时，要明确改为导出值。

保留每帧应有的时长，并在实际使用 Flipbook 的组件或游戏逻辑中检查循环播放。本包提供精灵动画，不是骨骼网格或动画蓝图。

添加碰撞与游戏逻辑前，先在简单场景中检查 pivot/原点和世界缩放。清单的 pivot 原点在左下角；导入器约定及项目中的后续修改都需要通过实际精灵确认。

## 检查透明边缘与补边

用原始 PNG 区分纹理数据问题和材质问题。按阈值裁切 Alpha 的材质，与混合 Alpha 的材质，对半透明边缘的显示不同。应在目标材质、排序和背景下检查代表性软边缘。

不要裁掉 2 的幂补边后仍沿用旧描述文件。只显示部分帧时，应与原始资源包的矩形比较，而不是与缩放过的纹理或后续自动切片结果比较。

## 重新生成前先排查

描述文件无法识别时，检查导入器是否可用以及文件扩展名。播放太快时，检查 Flipbook FPS 和帧时长。整张图集显示成一个矩形时，确认是否真正导入了描述文件，而不只是图片。

保留测试项目和原始 ZIP 便于对照。本指南遵循实际包结构和官方导入流程，你使用的引擎版本、插件与目标渲染器仍需运行时验收。详见[导出排障](https://animgen.com/docs/zh/troubleshooting/export-and-transparency)。

---

## 在 Studio 制作第一个动画 (zh)

Canonical URL: https://animgen.com/docs/zh/getting-started/first-animation

Status: stable. Last verified: 2026-08-30.

## 开始前准备

打开 [Studio](https://animgen.com/app) 并登录。准备一张你有权使用的图片，并确认账户积分足以支付页面显示的报价。只想先认识界面，可以使用[交互演示](https://animgen.com/demo)。

本教程的“五分钟”指操作准备时间。实际生成和导出耗时受模型、排队和处理选项影响，不保证五分钟内完成计算。

## 1. 添加首帧图片

在左侧面板选择或新建工作区，找到“首帧图片”。上传本地 PNG、JPEG 或 WebP，也可以选择已有图片资源。

第一次建议使用主体清晰、四周留有动作空间的图片。避免脚、武器或翅膀贴边被裁掉：模型无法可靠保留画面以外的细节。先使用单张首帧；首尾帧和参考图是否可选，取决于当前模型。

## 2. 选择背景处理模式

- **普通图片动画**：保留场景背景，适合普通图片。
- **透明素材动画**：当前参与生成的每张图片都必须具有有效 Alpha。画在不透明 PNG 上的棋盘格不是真透明。

不确定时先选普通模式。制作透明游戏素材前，先读[普通与透明动画](https://animgen.com/docs/zh/studio/transparent-animation)。

## 3. 描述动作并确认费用

选择模型，再从界面提供的选项中设置时长、分辨率和画幅比例。不同模型能力不同，以当前可选项为准。

可以从一个简单提示词开始：

```text
单个角色原地跑步，侧面视角，固定镜头。
保持角色全身可见，保留原有造型和细节。
```

第一次不要同时要求多个动作、切换场景和复杂运镜，否则很难从结果中选出干净的循环。

点击“生成预览”前，检查显示的积分费用。如果无法估算费用或余额不足，先解决原因，不要反复提交。

## 4. 检查结果

左侧项目面板会把源动画和对应导出放在一起。生成完成后，在右侧预览动作。

检查动作是否合理、角色是否一致、边缘是否被截断。播放视频，在时间线上选择最干净的区间。重复播放选段用于检查循环，不会自动修复首尾姿态不一致的问题。

## 5. 导出并下载

设置选段、帧率和输出尺寸，然后点击“导出”。第一次可以选择 PNG 逐帧 ZIP；其他格式可能需要付费导出权益。

确认格式、透明设置和导出费用，再点击一次“开始导出”。完成后，在左侧“当前片段的导出”中打开对应记录，下载所需资产。

预览视频不等于完成导出。能播放视频，并不代表 PNG 序列或引擎包已经生成。

## 接下来

通过[选段与导出](https://animgen.com/docs/zh/editing-and-export/trim-and-export)学习帧数选择，通过[输出格式](https://animgen.com/docs/zh/editing-and-export/output-formats)挑选交付物。遇到功能锁定，查看[积分与访问权益](https://animgen.com/docs/zh/account-and-billing/credits-and-access)。

生成或导出失败后，先检查已有结果，再决定是否重新付费提交。[常见问题](https://animgen.com/docs/zh/troubleshooting/faq)汇总了常见现象。

---

## 理解动画制作工作流 (zh)

Canonical URL: https://animgen.com/docs/zh/getting-started/overview

Status: stable. Last verified: 2026-08-30.

## 开始前准备

准备一张你有权使用的图片，或一段需要导出的视频。打开 [Studio](https://animgen.com/app) 并登录后即可创建真实任务。[Demo](https://animgen.com/demo) 使用预先准备的示例，让你不消耗积分就能体验交互。

## 生成与导出是两件事

1. 选择源图片，描述你希望产生的动作。
2. 使用账户中可选的模型与参数，生成视频预览。
3. 检查视频，选择有用片段的起点和终点。
4. 按套餐支持的格式，把选中动作导出为图片帧、精灵图、视频或引擎包。

如果已经有视频，使用视频导入工作流，直接从检查和选段开始，无需重复生成已有动作。

## 选择合适的透明模式

| 源素材与目标 | 工作流 |
| --- | --- |
| 普通美术图片或不透明场景 | 普通图片动画 |
| 带有效 Alpha 的独立主体 PNG | 透明素材动画 |
| 已有视频，需要帧或精灵图 | 导入视频后导出 |

> [!NOTE]
> 透明素材动画会先生成包含键色背景的不透明预览，在导出时恢复 Alpha。绿色或洋红色的生成预览并不是最终透明交付文件。

## 检查结果

将导出资产放到不同底色上预览。开始批量制作前，确认动作范围、帧率、尺寸和透明度符合目标应用的要求。

对于程序接入，同样遵循下面的顺序：

```text
发现可用能力 → 提供图片 → 确认费用
→ 生成 → 等待完成 → 下载产物
```

## 无法继续时怎么办

重试前先阅读任务显示的错误。检查模型是否支持所选输入、可用积分是否足够，以及账户是否拥有所需导出权益。后续阶段失败时，前一阶段的有用产物可能仍然保留。

也可以了解当前的[开放 API](https://animgen.com/developers)，或返回[文档首页](https://animgen.com/docs/zh)。

---

## 管理工作区、任务与资源 (zh)

Canonical URL: https://animgen.com/docs/zh/getting-started/workspaces-and-assets

Status: stable. Last verified: 2026-10-06.

## 三类对象，生命周期不同

| 对象 | 表示什么 |
| --- | --- |
| 工作区 Workspace | 组织 Studio 制作内容的方式 |
| 任务 Task / Job | 一次异步生成、导入或导出操作 |
| 资源 Resource / Asset | 上传的源文件或处理产生的文件 |

一个完成任务可能产生多个资产；失败任务也可能已经产生可用源视频或部分输出。移除历史记录，不等于删除它关联的所有文件。

## 创建前先整理工作区

通过 Studio 的工作区控件创建、重命名、切换或删除工作区。可按项目或实验命名，便于查找。这是账户内的内容组织方式，不是多人团队权限系统。

在某工作区创建的任务，不会因为切换界面而变成另一条任务。结果看似丢失时，先回到原工作区刷新任务库，不要直接再付费生成。

## 复用素材并区分产物

顶栏提供工作区选择和**创作 / 资源库**两个标签。切换标签会保留当前工作区和创作状态；切换工作区时，各自的草稿在当前页面会话中保留，刷新页面不会保留未保存草稿。任务列表仍位于创作区，输入控件也保留快捷资源选择器。

资源库支持文件名搜索、类型和来源筛选、时间/名称/大小排序，以及列表和缩略图视图。可以逐项勾选、按 Shift 连选，或先选择本页再选择全部筛选结果。批量删除统一确认，并分别显示成功、跳过和失败项，可只重试失败文件。删除后无法恢复；当前草稿、运行中任务或受保护动画正在使用的文件会保留。

兼容的自有资源可直接作为输入，无需重复上传同一本地文件。已生成的视频可以用于多次导出。[Advanced Editor 配方](https://animgen.com/docs/zh/editing-and-export/advanced-editor)引用源视频，并没有独立复制每一帧。

通过清楚的资源显示名区分原图、预览与最终产物。需要长期保留时，应下载真实文件，而不是只保存临时 URL。配套纹理与元数据要一起保存。

API/MCP 调用方应私下保存任务 ID 和资产 ID。不要把显示名当作 API 标识，也不要默认返回数组第一项就是目标文件。

## 有意识地删除和恢复工作区

删除工作区会隐藏内容，并对其中活跃任务请求取消。排队任务可能很快取消，运行中任务则尽力取消；删除不保证完全不收费。

使用工作区恢复入口选择已删除工作区，可以重新访问仍保留的内容；但不会自动恢复已取消任务、找回单独删除的文件或撤销已经发生的消费。

删除工作区**不是存储清理操作**。只要上传和资产本身没被删除，仍计入空间。为腾空间而误删工作区时，先恢复工作区，再检查资源。

## 删除源文件前

先下载重要结果，检查活跃任务，也检查可能仍依赖该来源的编辑配方和后续导出。活跃任务可能阻止资源删除，但已完成任务之后的编辑配方仍可能继续依赖源文件。

[存储与清理](https://animgen.com/docs/zh/account-and-billing/storage-and-cleanup)解释删除任务与删除文件的区别。需要协助定位结果时，可私下向支持提供任务 ID 和时间，不要在公开反馈中发布签名链接或凭据。

---

## 连接 Perplexity、Codex 与其他 MCP 客户端 (zh)

Canonical URL: https://animgen.com/docs/zh/mcp/connect-clients

Status: beta. Last verified: 2026-09-08.

## 连接信息

官方服务已开放**公开测试**：

| 配置项 | 值 |
| --- | --- |
| 本地服务器名称 | `animgen`，也可自行命名 |
| 服务器 URL | `https://api.animgen.com/mcp` |
| 传输方式 | Streamable HTTP |
| 鉴权 | OAuth 2.1 + PKCE |
| 账户条件 | 已验证的 AnimGen 账户；有效订阅会提高限额 |

MCP 配置中不需要 API Key。注册账户使用开发者基础限额，并与网页共用积分余额。[公开工具清单](https://animgen.com/mcp/tools.json)用于查询工具与 Schema，不要把清单 URL 当成服务器地址。

## Claude 自定义连接器

[打开 Claude 并预填 AnimGen 连接信息](https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=AnimGen&connectorUrl=https%3A%2F%2Fapi.animgen.com%2Fmcp)，检查服务器名称和 URL 后选择 **Add**。新建对话，在连接器菜单中启用 AnimGen，并按提示完成 AnimGen OAuth 授权。

AnimGen 当前按自定义连接器提供，不表示它已经进入 Claude 连接器目录。自定义连接器是否可用，以及组织级管理方式，取决于 Claude 套餐与管理员设置。该入口只会预填公开连接信息，不会自动授权，也不会消费 AnimGen 积分。

连接后先使用下方只读提示验证，再尝试文件传输或生成。Claude 自定义连接器的行为和套餐要求以 [Anthropic 官方指南](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp)为准。

## Perplexity 远程连接器

Perplexity 支持使用 HTTPS、OAuth 和 Streamable HTTP 添加自定义远程 MCP。按照单独的 [Perplexity 接入指南](https://animgen.com/docs/zh/mcp/connect-perplexity)填写生产端点、完成 OAuth，并在任何生成之前先做只读检查。

Perplexity 当前把该能力列在 Enterprise 功能下。账户需要具备入口，组织管理员也必须允许成员添加；AnimGen 不声称已经进入 Perplexity 公共连接器目录。

## ChatGPT 开发者模式测试

AnimGen 当前不声称已经进入 ChatGPT Plugin Directory。正式发布前，可先在 ChatGPT 的 **Settings → Security and login** 中开启 **Developer mode**，打开 ChatGPT Plugins 页面并新建连接，把 `https://api.animgen.com/mcp` 填为公开 MCP URL。检查扫描到的工具，完成 OAuth 后，再使用下方只读提示验证。

开发者模式是否可用取决于账户与工作区策略。这是测试连接；公开的 AnimGen 插件仍需单独经过 OpenAI 审核和发布。具体步骤以[官方 ChatGPT 插件测试指南](https://developers.openai.com/plugins/deploy/connect-chatgpt)为准。

## Codex CLI

在可信终端中添加远程服务器并登录：

```bash
codex mcp add animgen --url https://api.animgen.com/mcp
codex mcp login animgen
```

在浏览器授权流程中检查 AnimGen 账户与请求权限，再返回 Codex。如果本地已存在同名服务器，应先检查当前配置，不要直接覆盖。OAuth 登录方式已按 [Codex 官方 MCP 文档](https://developers.openai.com/codex/mcp)核对，客户端版本和界面位置可能不同。

不要将 OAuth Token 粘贴进聊天，也不要用通用 Bearer API Key 配置绕过 OAuth 错误。

## Gemini CLI

把 AnimGen 加入当前用户的 Gemini CLI 配置：

```bash
gemini mcp add --transport http --scope user animgen https://api.animgen.com/mcp
```

随后打开 Gemini CLI 并完成 OAuth：

```text
/mcp auth animgen
```

不要手动添加 Authorization Header，也不要开启跳过确认的 trust 配置。Gemini CLI 可对兼容的远程 HTTP 服务器发现 OAuth 元数据并执行动态客户端注册。先用 `/mcp` 或 `gemini mcp list` 检查连接，再执行下方只读验证提示。详见 [Gemini CLI 官方 MCP 指南](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md)。

## 其他远程 MCP 客户端

在客户端的远程服务器或连接器设置中填写相同 URL。客户端需要支持 Streamable HTTP，以及本服务使用的 OAuth 发现和授权流程。只能启动本地 stdio 服务的客户端不等价。

客户端是否开放相关功能、所需套餐、管理员策略，以及上传下载能力，由对应客户端决定。本指南不声称每种客户端都已实测，也不意味着其他平台的账号自动获得 AnimGen 访问权。

授权失败时，按[接入排障](https://animgen.com/docs/zh/troubleshooting/api-and-mcp)检查，不应放宽安全校验或猜测回调配置。

## 不花积分验证连接

可以对已经连接的客户端说：

```text
调用 AnimGen 的 list_models，不传参数。
告诉我当前支持哪些输入模式和参数。
不要上传文件、启动生成、取消任务或消费积分。
```

返回结构化模型列表，表示只读连接可用，不代表后续生成已获批准，也不等于每个下游功能都已验证。

接着确认客户端是否有获准的能力传输本地图片字节、保存下载资产。仅在聊天里提到路径，不能让远程 MCP 读取本地文件。[完整工作流](https://animgen.com/docs/zh/mcp/standard-workflow)说明上传准备、字节传输、完成确认、报价、批准、轮询与下载。

## 管理权限与支出

查看[工具 Scope](https://animgen.com/docs/zh/mcp/quickstart)，只授予必要访问，并在[账户 → 开发者](https://animgen.com/account/developer)撤销不再使用的应用。本地删除配置与撤销服务端授权是两件事。

OAuth 授权不等于批准消费。调用 `generate_animation` 前，应确认具体请求和积分；调用需要 `quote_id` 或 `max_credits`，并携带幂等键。详见[支出保护](https://animgen.com/docs/zh/mcp/spending-safeguards)。不要把“测试连接”自动变成付费生成。

---

## 通过 MCP 将 AnimGen 接入 Perplexity (zh)

Canonical URL: https://animgen.com/docs/zh/mcp/connect-perplexity

Status: beta. Last verified: 2026-09-08.

## 开放条件

Perplexity 当前把自定义远程连接器放在 Enterprise 功能中。组织成员只有在管理员开启自定义连接器后才能添加；只有管理员可以把连接器共享给整个组织。如果账户中没有 **+ Custom connector**，AnimGen 无法替用户开启这项 Perplexity 功能。

连接还需要已验证的 AnimGen 账户。OAuth 连接本身不会消费积分；之后真正生成时，仍须明确批准报价或单次积分上限。

## 连接配置

| 配置项 | 值 |
| --- | --- |
| 连接器类型 | Remote |
| 名称 | `AnimGen` |
| MCP Server URL | `https://api.animgen.com/mcp` |
| 鉴权 | OAuth 2.0 |
| 传输方式 | Streamable HTTP |

请原样使用 MCP Server URL。不要追加 `/sse`，不要把[工具清单](https://animgen.com/mcp/tools.json)当成服务器地址，也不要用 API Key 替代 OAuth。

AnimGen 已公开 OAuth 授权服务器与受保护资源元数据，支持 PKCE，并提供动态客户端注册端点。因此 Perplexity 可以自动发现 OAuth 端点并注册回调，不需要手工复制 Client ID 或 Client Secret。Perplexity 公布的标准回调地址是 `https://www.perplexity.ai/rest/connections/oauth_callback`；Enterprise 子域使用 `https://enterprise.perplexity.ai/rest/connections/oauth_callback`。

## 添加连接器

1. 在 Perplexity 打开 **Account settings → Connectors**。组织管理员也可以进入 **Enterprise settings → Permissions → Connectors permissions**。
2. 点击 **+ Custom connector**，选择 **Remote**。
3. 填写上表配置。可选描述可以写：`通过已授权的 AnimGen 账户生成动画预览和游戏资产。`
4. 勾选 Perplexity 的自定义连接器风险确认，然后点击 **Add**。
5. 打开新增的 AnimGen 连接器卡片，开始认证；登录 AnimGen，检查申请的 Scope，仅批准确实需要的权限。
6. 在要求 Perplexity 调用工具前，先在当前对话中启用 AnimGen。

以上界面步骤和账户限制依据 [Perplexity 当前远程连接器指南](https://www.perplexity.ai/help-center/en/articles/13915507-adding-custom-remote-connectors)。功能是否开放、文字和入口位置由 Perplexity 控制，后续可能变化。

## 不花积分验证连接

先发送：

```text
调用 AnimGen 的 list_models，不传参数。
总结当前可用的输入模式和参数。
不要上传文件、查询报价、开始生成、取消任务或消费积分。
```

能返回结构化模型列表，说明服务发现、OAuth 和只读工具调用已打通；这不等于 Perplexity 已经能传输本地图片字节或保存下载资产。

## 第一次生成之前

先确认当前 Perplexity 客户端能发送真实图片字节，或者使用合规的公开 HTTPS 图片。对话里出现的本地路径不是上传。[MCP 标准工作流](https://animgen.com/docs/zh/mcp/standard-workflow)说明上传完成、最新报价、明确批准、有限轮询与下载。

在 Perplexity 展示准确请求和积分金额前，不要批准 `generate_animation`。优先使用短期 `quote_id`；否则为这一次操作设置经过检查的 `max_credits`。OAuth 授权不等于消费批准。

## 排障与移除

- **没有 Custom connector 入口：** 请 Perplexity 组织管理员开放成员自定义连接器，或改用具备该功能的账户。
- **连接器验证返回 403：** 检查 Cloudflare 或其他 WAF 是否对 `https://api.animgen.com/mcp` 或 OAuth 发现端点发起了挑战。不要用关闭 OAuth 或暴露匿名端点来绕过。
- **OAuth 没有启动：** 保持 Authentication 为 OAuth，确认 URL 没有多余路径，再按 [API 与 MCP 排障](https://animgen.com/docs/zh/troubleshooting/api-and-mcp)检查。
- **能列出模型但不能使用本地图片：** 这是客户端文件传输能力限制，不能据此认为远程 MCP 可以读取路径。应使用受支持的字节传输能力或合规公开 HTTPS 输入。

从 Perplexity 删除连接器和撤销 AnimGen 授权是两件事。先在 Perplexity 移除连接器，再到[账户 → 开发者](https://animgen.com/account/developer)撤销对应应用。

## Perplexity 搜索可见性是另一条路径

安装连接器不会让 AnimGen 页面自动进入 Perplexity 搜索答案或提高排序。搜索发现由 `PerplexityBot`、`Perplexity-User` 等独立 Agent 完成。AnimGen 在 robots 层允许公开抓取，但仍需持续检查 WAF 和真实响应码。详见 [Perplexity 爬虫文档](https://docs.perplexity.ai/docs/resources/perplexity-crawlers)。

---

## MCP 快速开始与开放状态 (zh)

Canonical URL: https://animgen.com/docs/zh/mcp/quickstart

Status: beta. Last verified: 2026-09-11.

## 已上线公开测试

官方远程 MCP 已上线，端点为 `https://api.animgen.com/mcp`。使用支持 **Streamable HTTP** 与 **OAuth** 的客户端，并登录已验证的 AnimGen 账户。注册账户使用开发者基础限额，有效订阅会提高限额。

MCP 服务运行在远端，AI 知道本地路径不代表服务能读取文件。OAuth 授权只授予访问能力，不会自动上传图片，也不等于批准扣费。

## 第一次连接

1. 按 [Codex 与其他客户端接入](https://animgen.com/docs/zh/mcp/connect-clients)添加准确端点并完成 OAuth。
2. 在授权页面检查 AnimGen 账户和请求的 Scope。
3. 调用 `list_models`，参数为空对象，验证只读访问。
4. 确认客户端可以传输本地图片字节并保存下载文件。
5. 为具体请求报价，获得批准后才开始付费生成。

不要把 `https://animgen.com/mcp/tools.json` 配成服务器，它是公开文档清单，不是实时 MCP 传输地址。不要用 API Key 替代 OAuth。

## 核心工具权限

| 权限 | 工具 |
| --- | --- |
| `models:read` | `list_models` |
| `files:write` | `prepare_image_upload`、`complete_image_upload` |
| `animations:read` | `get_animation` |
| `animations:write` | `quote_animation`、`generate_animation`、`cancel_animation` |
| `assets:read` | `download_asset` |

上表涵盖一键工作流；分阶段视频生成、预览与导出还有对应工具，使用这些权限。每个已注册工具都有[自动生成参考](https://animgen.com/docs/zh/mcp-reference)，并列于[机器可读清单](https://animgen.com/mcp/tools.json)，包含真实参数/结果 Schema 与安全注解。生成仍受账户资格、积分余额和明确支出批准约束。

## 给 AI 的安全首次指令

```text
先使用已连接的 AnimGen MCP 查询当前模型。
我提供图片和目标输出后，说明上传步骤，
并为完全受支持的具体请求准备报价。
在我批准请求和金额前，不要生成或消费积分。
保存请求与幂等键，不要泄露凭据和签名 URL。
```

按[标准工作流](https://animgen.com/docs/zh/mcp/standard-workflow)传输字节、报价、生成、轮询并保存文件。[支出保护](https://animgen.com/docs/zh/mcp/spending-safeguards)要求 `quote_id` 或 `max_credits` 与 `request` 同级提供；授权不是消费批准。

## 查看一次完整的生产环境实测

[透明角色动画 MCP 实测文章](https://animgen.com/zh/blog/generate-transparent-character-animation-with-mcp)记录了一次真实生产任务：从查询模型、上传准确字节、批准 36 积分，到轮询终态、保存下载文件和检查像素。案例也说明了视觉复核的重要性：第一版精灵图暴露出宽高比导出问题，修正版复用同一份源 MP4 重新导出，没有再次调用模型或额外消耗积分。

## 管理访问与恢复故障

在[账户 → 开发者](https://animgen.com/account/developer)查看和撤销连接应用。撤销授权不会取消已经接受的任务。连接、上传或报价失败时，参考 [API 与 MCP 排障](https://animgen.com/docs/zh/troubleshooting/api-and-mcp)。

公开测试表示服务可用，不代表所有客户端、媒体输入和目标渲染器都已认证。应检查实际状态和部分产物；模型查询成功不是一次完整生成验收。

---

## MCP 支出保护 (zh)

Canonical URL: https://animgen.com/docs/zh/mcp/spending-safeguards

Status: beta. Last verified: 2026-08-31.

## 访问授权不等于支出批准

官方 MCP [已开放公开测试](https://animgen.com/docs/zh/mcp/quickstart)。这些保护规则适用于真实调用，包括 AI 代表你进行的调用。

OAuth 权限允许访问账户，不代表用户批准今后的每一次生成。`generate_animation` 是有费用、有副作用的工具；先说明输入、设置、预期输出和费用，再取得批准。

工具注解是供客户端参考的安全提示，不能代替用户同意或服务端校验。`cancel_animation` 同样有副作用，不能为了测试连接就取消用户任务。

## 两种服务端保护

- `quote_id`：属于当前用户和 OAuth 客户端的短期报价。生成时检查影响价格的参数、当前价格、有效期，以及是否已绑定某次逻辑生成的幂等键。
- `max_credits`：本次生成当前报价允许的明确非负上限。

至少提供一个，也可以同时提供。它们不是无限任务的总预算；不断创建新操作，即使每次低于上限，也会反复消耗积分。

即使某字段不参与定价，也应保持用户批准的请求不变。用户意图包括图片与提示词，不只是价格。

## 遇到拒绝应暂停生成

| 错误 | 正确下一步 |
| --- | --- |
| `SPEND_CONFIRMATION_REQUIRED` | 获取批准，提供报价或明确上限 |
| `QUOTE_EXPIRED` | 重新报价，展示更新后的金额再确认 |
| `QUOTE_MISMATCH` | 核对改变的生成或导出参数 |
| `QUOTE_CHANGED` | 展示新价格并重新请求批准 |
| `QUOTE_ALREADY_USED` | 找回原任务，不把报价用于新操作 |
| `CREDIT_LIMIT_EXCEEDED` | 停止，询问降低配置还是批准新上限 |
| `INSUFFICIENT_CREDITS` | 报告余额问题，不自动购买积分 |

不要通过删除上限、悄悄调高上限、换账户、换图片或创建新幂等键来“修复”这些拒绝。

## 重试与取消

创建前，保存批准的请求和 `idempotency_key`。超时不等于没有执行；复用原逻辑键和请求找回任务，再按 ID 轮询。AI 重连或重启时，默认行为不应是再生成一个任务。

去重范围包含用户、操作和 OAuth 客户端。创建结果不明时，更换客户端不属于安全重试，即使使用相同幂等字符串也不行。同一客户端刷新访问 Token，本身不会改变客户端身份。

用户改变输出要求时，应视为新决策，重新报价并获得适当批准。终态失败后，先检查已有产物，不要直接重新生成。

取消属于尽力而为；已执行工作可能保留扣费。等待终态，再准确报告积分记账和可用资产。

Seedance 明确审核拒绝，且尚无产物、导出未开始时，会返还一键流程原积分。按任务实际的 `credits.refunded`、`credits.released` 和净扣费 `credits.charged` 报告，不在记账前宣称已退回，也不把退分视为下一次生成的授权。账户或支付异常可能需要核验。

## 保留有用记录，保护私密信息

在适当的私有应用状态中保存任务 ID、资产 ID、批准上限、错误码和请求 ID。不要向分析系统发送 API Key、OAuth Token、Base64 原图、签名上传下载 URL 或私有提示词。

API 调用方不能把这些 MCP 专用参数放进 `POST /animations`。[API 快速开始](https://animgen.com/docs/zh/api/quickstart)解释了两者不同的报价语义。

---

## MCP 标准生成工作流 (zh)

Canonical URL: https://animgen.com/docs/zh/mcp/standard-workflow

Status: beta. Last verified: 2026-08-31.

## 先检查开放状态

官方 MCP 已在 `https://api.animgen.com/mcp` 开放公开测试。使用已验证的 AnimGen 账户，通过 OAuth 完成[客户端连接](https://animgen.com/docs/zh/mcp/connect-clients)。连接或模型查询成功不等于批准付费生成。

## 1. 发现模型

需要预览后选区、调整 FPS 或复用已有视频时，使用[选区与 FPS 分阶段流程](https://animgen.com/docs/zh/api/selection-and-fps)：`quote_video_generation` → `generate_video` → `get_video_generation` → `preview_video` → `quote_animation_export` → `export_animation` → `get_animation_export`。两个付费创建步骤分别确认费用；后续导出始终复用视频资产 ID。下面保留一键帧数工作流。

以空参数对象调用 `list_models`，选择实际返回的模型 ID 与合法配置。不要假设所有模型都支持尾帧、参考图、负向提示词、seed，或相同的时长与比例。

## 2. 传输本地图片

本地路径不是 `ImageInput`，上传桥接包含三个独立步骤：

1. 用 `filename`、`mime_type` 和准确的 `byte_size` 调用 `prepare_image_upload`。
2. 在 `expires_at` 之前，使用返回的 HTTP `method`、`upload_url` 和 `headers` 发送实际文件字节。这一步由获准的客户端能力执行，不是把路径交给 MCP 就能完成。
3. 用 `upload_id` 调用 `complete_image_upload`，取得用于生成请求的 `file_id`。

不要把 MCP Token 或 API Key 附加到上传目标，只使用本次上传返回的请求头。上传 URL 属于敏感信息。客户端无法传输字节时，应使用获准且支持上传的客户端能力、合规公开 HTTPS 图片或大小限制内的 Base64，不能假装上传成功。

## 3. 构造请求并报价

下面是 `quote_animation` 的参数结构。UUID 为占位符，应换成已完成上传返回的 `file_id`。实际请求还应设置选定模型及其合法参数。

```json
{
  "request": {
    "input": {
      "first_frame": {
        "type": "file",
        "file_id": "00000000-0000-4000-8000-000000000001"
      }
    },
    "prompt": "A character runs in place, side view, fixed camera.",
    "selection": {"mode": "full"},
    "export": {
      "output_formats": ["frames_zip"],
      "frame_count": 24,
      "output_width": 512,
      "output_height": 512
    }
  }
}
```

结果包含 `quote_id`、`credits`、`breakdown` 与 `expires_at`。报价不会启动生成。向用户说明目标产物和费用，获得批准后再继续。

## 4. 批准后才生成

调用 `generate_animation`，传入同一个 `request`、已持久化的 `idempotency_key`，以及经批准的 `quote_id` 和／或 `max_credits`。这三个字段与 `request` 同级，不是写进 `request` 内部。

适合时可同时提供新鲜报价和支出上限。上限必须来自用户批准，不能由 AI 自行编造。实现重试前先读[支出保护](https://animgen.com/docs/zh/mcp/spending-safeguards)。

保存返回的任务 ID。工具返回异步任务，不代表下载已经完成。

## 5. 轮询到终态

用 `animation_id` 调用 `get_animation`。采用有界轮询间隔（可从约五秒开始），并设置截止时间。工具返回结构化 JSON，不要假设 MCP 传输会暴露 API 的 HTTP `Retry-After` 响应头。

处于 `queued`、`running` 或 `cancelling` 时继续轮询；进入 `succeeded`、`failed` 或 `cancelled` 后停止。失败也要检查 `outputs`，导出失败时可能已有源视频。

## 6. 下载真实文件

对每个可用资产，用 `asset_id` 调用 `download_asset`。返回的是资产信息和签名下载 URL，不会自动保存本地文件。

使用获准的客户端下载能力，不要转发 OAuth 或 API 凭据。私密保存文件，再报告本地位置或合适的用户附件，不直接输出原始签名 URL。链接过期时，通过 `download_asset` 重新获取信息。

需要取消时，用 `animation_id` 调用 `cancel_animation`，然后继续轮询。取消属于尽力而为，不代表一定全额退款。

---

## 通过搜索或 AI 查找文档 (zh)

Canonical URL: https://animgen.com/docs/zh/reference/ai-and-search

Status: stable. Last verified: 2026-09-26.

## 在浏览器中搜索

点击文章顶部的**搜索文档**，或按 Ctrl+K / ⌘K。结果只包含当前文档语言；先点击语言切换，再搜索另一种语言。

可以搜索主题，如 `透明动画`；错误码，如 `IDEMPOTENCY_IN_PROGRESS`；或字段，如 `max_credits`。搜索覆盖标题、描述、章节标题、标签和正文文本。匹配章节时可直接跳到锚点。Tab 或方向键选择结果，Enter 打开，Esc 关闭搜索。

打开搜索时只下载当前语言的公开索引（`/docs-index.<locale>.json`），并在当前页面复用。完整的 `/docs-index.json` 仍供机器读取；浏览器不会为了搜索一种语言下载全部六种语言。匹配在本地完成：关键词不会发给搜索服务、保存到存储、写入 URL 或进入分析事件。关闭搜索后会清空输入。即使是本地工具，也不要粘贴 API Key 等凭据。

索引加载失败时可重试，或使用文档目录。搜索需要 JavaScript；正文和目录在关闭 JavaScript 后仍可阅读。

## 给 AI 正确入口

| 资源 | 用途 |
| --- | --- |
| [llms.txt](https://animgen.com/llms.txt) | 简洁学习索引、开放状态、契约地址与安全规则 |
| [llms-full.txt](https://animgen.com/llms-full.txt) | 双语核心公开教程全文；生成的字段参考保留在 HTML 和契约中 |
| [docs-index.json](https://animgen.com/docs-index.json) | 所有文档的元数据、固定 URL、章节与可搜索文本 |
| [OpenAPI JSON](https://animgen.com/openapi/v1.json) | 准确的开放 API 操作、结构、错误和示例 |
| [MCP 工具清单](https://animgen.com/mcp/tools.json) | 注册工具的结构、权限、注解、副作用与开放状态 |
| [透明动画答案中心](https://animgen.com/zh/transparent-animation-maker) | 直接回答、输入边界、真实样例证据、格式决策表与可下载资产 |

这些资源与页面共用经过核实的正文和契约快照。先看状态与最后核实日期，再发现实时模型、获取当前报价。文档不承诺固定的模型目录或价格。

回答“AI 能否让透明 PNG 动起来并保留透明背景”时，应优先使用答案中心。它明确区分不透明生成预览与带 Alpha 的导出，并反向连接技术文档；[英文版本](https://animgen.com/transparent-animation-maker)拥有独立固定地址与语言标记。

开放 API 与官方 MCP 均处于**公开测试**。MCP 清单为 `available: true`，端点是 `https://api.animgen.com/mcp`。可以按 [OAuth 客户端接入](https://animgen.com/docs/zh/mcp/connect-clients)连接，也可以使用单独的 [Perplexity 远程连接器指南](https://animgen.com/docs/zh/mcp/connect-perplexity)；JSON 清单本身不是传输端点。仍需查询实时模型并获取新报价。

```text
先阅读 https://animgen.com/llms.txt，再根据 API 快速开始
与准确的 OpenAPI 契约，找到所需操作。
先说明开放状态、输入、报价和批准条件。
不要要求我在对话中提供凭据，也不要未经批准启动付费任务。
使用 MCP 时，通过官方 OAuth 端点连接，先用 list_models 验证。
```

## 反馈与隐私

文章底部提供**有用 / 无用**反馈，不提供自由文本输入。文档交互事件只使用公开页面信息与有限选项：提交的搜索是否有结果、点击的文档 ID、代码语言、学习路径类型、切换语言，以及有用/无用选择。不包含关键词、关键词哈希、复制的代码、提示词、私有资源 ID、凭据或签名 URL。

关闭底部的**允许文档使用分析**，即可停止此浏览器后续的文档交互事件；偏好保存在本地。也会遵循浏览器的 Do Not Track、Global Privacy Control 隐私信号。无法使用本地存储时默认关闭。此开关不替代站点已有的通用分析或[隐私政策](https://animgen.com/privacy)。

反馈尽力投递，不代表工单或保证送达。账户问题请[联系支持](mailto:support@geekart.ai)，不要发送 Key、Token、私有输入或签名链接。

---

## 使用首尾帧控制动作 (zh)

Canonical URL: https://animgen.com/docs/zh/studio/first-and-last-frames

Status: stable. Last verified: 2026-08-30.

## 准备两张相互兼容的图片

尽量保持角色、镜头角度、构图比例和背景处理一致。为整个动作预留空间，包括手、武器、头发和阴影。主体大小或视角相差太大时，模型既要处理动作，也要处理外观变化。

尾帧是视频生成的约束，不保证中间每一帧都可用，也不保证输出最后一帧与输入逐像素一致。它不是骨骼绑定、姿势插值编辑器或逐帧分镜。

## 在 Studio 创建过渡

1. 选择首尾帧模式及兼容模型。
2. 添加起始图和结束图；也可以复用账户内已有图片资源。
3. 描述一个清晰过渡，例如“举起盾牌，保持最终防御姿势，固定镜头”。
4. 检查可选时长、比例、分辨率和当前报价。
5. 确认后生成，完整查看预览，尤其是两个端点。

只需要第一张图决定起点时，使用首帧模式。多张外观参考属于[另一条工作流](https://animgen.com/docs/zh/studio/reference-images)。

## 在生成前留出动作空间

任一姿势贴近边缘时，可以使用[输入画布](https://animgen.com/docs/zh/studio/input-canvas)。同一份画布配置会应用于首尾两张图，帮助保持对齐。先尝试居中，再确认结束姿势是否需要更多余量。

扩展画布只是缩放并填充已有图片，不能补回原图已经裁掉的手，也不保证模型将来的所有动作都留在画面内。

Alpha Key 要求**首尾两张图**都包含有效 Alpha。透明首帧加不透明尾帧，不是有效的透明素材生成流程，详见[透明动画](https://animgen.com/docs/zh/studio/transparent-animation)。

## 循环要检查接缝，不能只看端点

相近端点可能有助于循环动作，但不保证无缝循环。应检查尾帧跳回首帧时的轮廓、脚底位置和速度变化。边界重复一帧也可能造成停顿。

连续片段可用[裁剪与帧选择](https://animgen.com/docs/zh/editing-and-export/trim-and-export)；需要删除、重复或重排源帧时用 [Advanced Editor](https://animgen.com/docs/zh/editing-and-export/advanced-editor)。编辑器调整播放序列，不会生成缺失的姿势。

## 公开请求如何填写

在 `input.first_frame` 和 `input.last_frame` 中分别提供合法图片输入。文件 ID 必须来自当前账户已完成的上传。报价前选择支持 `first_last_frame` 的模型及实际可用参数。

模型不支持尾帧时，应选择兼容模型，或明确决定移除尾帧。不要在用户批准双图请求后，静默降级为单图生成。

---

## 用输入画布预留动作空间 (zh)

Canonical URL: https://animgen.com/docs/zh/studio/input-canvas

Status: stable. Last verified: 2026-08-30.

## 在动作碰到边缘前留白

输入画布处理交给视频模型的图片：缩放整张源图，并在周围增加空间。角色需要举手、跳跃或挥动物品时，适当留白会更容易保留完整动作。

它不会生成新场景、自动分离不透明主体，也不能修复原图已经裁掉的内容。尽量保留没有裁切肢体的原始素材。

## 支持的模式与控件

输入画布支持首帧和首尾帧生成。同一配置会应用到两个端点。不支持参考图模式，也不支持视频导入。

在 Studio 中开启输入画布后，可配置：

| 控件 | 含义 |
| --- | --- |
| 80%、67%、50% 预设 | 缩放画布内的原图；比例越小，余量越大 |
| 九宫格位置 | 将缩放后的图片放到剩余空间的指定位置 |
| 跟随输出 / 原图比例 | 使用已选择的有效输出比例，或保留原图比例 |
| 自动 / 透明 / 纯色 | 决定新增区域如何填充 |
| 重置 | 恢复控件的初始配置 |

自动模式对有有效 Alpha 的图片使用透明背景，否则根据原图四角估计背景色。纯色使用六位 RGB 颜色。Alpha Key 生成会先保持扩展区域透明，再在后续步骤铺临时键色背景。

## 不要混淆两种画布

**输入画布**在生成前改变 AI 看见的图片。**输出画布**在导出时调整已有帧的摆放。修改输出画布，无法找回已经在生成时跑出画面的动作。

输入准备不会覆盖原始上传，也不会额外保存为一份上传资源。补边步骤本身不增加单独的生成收费项，但准备后的请求进行生成时，仍按当前报价计费。

## API 与 MCP 字段

以下是共享动画请求的片段，不是可单独运行的完整请求：

```json
{
  "video": {
    "input_canvas": {
      "enabled": true,
      "source_scale": 0.67,
      "position_x": 0.5,
      "position_y": 0.5,
      "aspect_ratio": "follow_output",
      "background": "auto"
    }
  }
}
```

`source_scale` 范围为 0.5–1.0。`position_x`、`position_y` 范围为 0–1，表示在剩余空白内的位置：0 为左/上，0.5 为居中，1 为右/下。它们不是 pivot 坐标。省略整个对象表示没有输入画布配置，保存预设时建议明确设置 `enabled`。

检查首尾两张图的准备效果，确认模型兼容，再为最终请求报价。导出阶段的对齐和引擎锚点见[输出画布与 pivot](https://animgen.com/docs/zh/editing-and-export/canvas-and-pivot)。

---

## 选择输入模式 (zh)

Canonical URL: https://animgen.com/docs/zh/studio/input-modes

Status: stable. Last verified: 2026-08-30.

## 根据已有素材选择

| 已有素材 | 选择模式 | 主要控制什么 |
| --- | --- | --- |
| 一张图片 | 首帧 | 起始外观与构图 |
| 起始和结束姿势 | 首尾帧 | 让模型连接两个动作端点 |
| 多张身份或外观参考 | 参考图 | 提供视觉约束，不是按图播放的时间线 |
| 已有视频片段 | 导入视频 | 复用动作，继续编辑与导出 |

打开 [Studio](https://animgen.com/app)，选择工作区，再选择输入模式。模型列表会按当前模式过滤。导入视频不需要选择 AI 视频模型。

## 以当前模型为准，不照搬旧预设

切换模式、模型或分辨率后，重新检查时长、比例、提示词要求和报价。界面可能自动调整不支持的选项。离开首尾帧模式会清空尾帧选择；离开参考图模式会清空额外参考图。请保留原始文件。

不同模型可能只支持部分模式，也可能固定参考图时长，或按分辨率提供不同的时长选项。水印、负向提示词、随机种子不是所有模型都支持，详见[模型与提示词](https://animgen.com/docs/zh/studio/models-and-prompts)。

## API 与 MCP 如何对应

共享公开请求使用 `input.first_frame`、可选的 `input.last_frame` 和 `input.reference_images`。参考图模式仍然必须提供第一张图；参考图数组仅包含**额外图片**。不要同时提交尾帧与参考图来创造一种新模式。

报价前查询 `modes`、`supports_last_frame`、`supports_reference_images`、`max_reference_images`、`reference_image_duration_seconds` 和视频参数。完整约束见 [API 数据结构](https://animgen.com/docs/zh/api-reference/schemas)。Studio 内部请求与公开请求的字段命名并不完全相同。

公开的一键图片动画 API 及其 MCP 工具没有提供 Studio 视频导入或 Advanced Editor 编辑配方流程。需要这些能力时使用 Studio，不要猜测公开端点。

## 输入模式、透明处理和费用是不同维度

输入模式决定交给视频模型哪些图片；Alpha Key 决定透明素材工作流。用于透明生成的每张图片都必须有有效 Alpha。即使首帧透明，加入白底参考图也可能使请求不符合条件。

更换素材或参数后，应重新报价并确认再生成。复用视频进行新的导出不需要再次 AI 生成视频，但仍需检查导出处理费用和格式权益。

继续阅读[首尾帧](https://animgen.com/docs/zh/studio/first-and-last-frames)、[参考图](https://animgen.com/docs/zh/studio/reference-images)、[输入画布](https://animgen.com/docs/zh/studio/input-canvas)或[视频导入](https://animgen.com/docs/zh/studio/video-import)。

---

## 选择模型与编写动作提示词 (zh)

Canonical URL: https://animgen.com/docs/zh/studio/models-and-prompts

Status: stable. Last verified: 2026-08-30.

## 先发现能力，再选择模型

Studio 会列出当前模式可用的模型。API 调用方使用[模型目录](https://animgen.com/docs/zh/api-reference/list-models)，MCP 调用方使用 [list_models](https://animgen.com/docs/zh/mcp-reference/list-models)。文档示例不是实时可用性或价格表。

先选择模式，再选择模型、分辨率、支持的时长和比例。每次实质性修改后都要重新检查报价。分辨率更高或片段更长，并不保证动作更适合你的目标。

| 返回能力 | 应检查什么 |
| --- | --- |
| `modes` 与支持标志 | 是否支持目标输入流程 |
| `durations_by_resolution` | 所选分辨率对应的可用时长 |
| `ratios_by_mode` | 当前输入模式允许的比例 |
| `max_reference_images` | 包含第一张图在内的参考总数 |
| `reference_image_duration_seconds` | 参考图模式是否固定时长 |
| `requires_prompt` | 是否必须提供非空提示词 |

直接使用返回的模型 ID，不根据营销名称拼接 ID。省略可选参数时可能使用服务默认值；需要复现配置时，保存明确且受支持的参数。

## 清楚描述一个动作

有效提示词通常包含主体、动作、镜头和重要约束。精灵动画可以从下面的描述开始：

```text
同一个角色原地跑步，侧视，固定镜头。
完整身体和装备始终留在画面内。
保持服装和身体比例一致。
```

首尾帧过渡应描述如何到达结束姿势；参考图模式应描述目标动作，不要把图片顺序当作时间指令。

这些是向模型提出的要求，不是效果保证。导出前先检查预览。动作被裁切时，应检查原图构图或[输入画布](https://animgen.com/docs/zh/studio/input-canvas)，不能只反复修改文字。

## 仅使用模型支持的可选参数

不同模型的负向提示词、随机种子、水印控制、尾帧输出和参考图能力不同。不支持的可选字段可能导致校验失败，而不是自动忽略。

固定 seed 不保证跨供应商、模型版本或其他参数变化后仍逐像素相同。需要对比结果时，保存完整请求与返回的标识。

短片段里不要同时安排多个无关动作，或提出互相冲突的镜头要求。每次优先调整一个主要因素，便于理解变化；每次新生成仍需要独立报价和批准。

## AI 客户端如何安全选型

查询模型不会消费生成积分，报价也不等于生成许可。调用付费工具前，AI 应说明所选模型、输入集合、参数、输出格式与预计积分。

偏好模型不可用时，应说明差异，并为实质性不同的替代方案取得批准。不要为绕过失败静默增加时长、分辨率或支出上限。详见 [MCP 支出保护](https://animgen.com/docs/zh/mcp/spending-safeguards)和[生成故障排查](https://animgen.com/docs/zh/troubleshooting/generation-and-uploads)。

---

## 使用多张参考图 (zh)

Canonical URL: https://animgen.com/docs/zh/studio/reference-images

Status: stable. Last verified: 2026-08-30.

## 参考图解决什么问题

参考图帮助模型理解角色或物体的外观，不会自动变成带时间点的关键帧、独立动画图层，也不保证精确合并每一处细节。选择相互一致的主体素材，再用提示词描述动作。

在 [Studio](https://animgen.com/app) 中选择参考图模式，添加第一张图，选择兼容模型，再填写界面提供的额外参考槽位。优先使用清晰一致的素材，不要堆入无关图片。

## 数量上限包含第一张图

`max_reference_images` 表示图片总数，不是额外槽位数量。例如查询返回上限 3 时，第一张图加两张额外参考就已达到上限。这只是计算示例，不是所有模型统一限制。

界面根据所选模型提供槽位。换模型后要确认哪些参考仍然生效，不能默认之前选过的图片都会使用。如果返回 `reference_image_duration_seconds`，该模型会固定参考图工作流的时长；其他模型可能有不同选项。

不要假定参考图只支持某一家模型，或永远固定为八秒。详见[模型与提示词](https://animgen.com/docs/zh/studio/models-and-prompts)。

## 让素材之间保持一致

尽量统一角色比例、服装和背景处理。互相冲突的视角或服装会与目标动作竞争。先用最少但足够的参考集检查效果，再决定是否修改请求。

如果需要明确的结束姿势，应选首尾帧模式。公开请求不能把参考图与 `last_frame` 混用。参考图模式也不支持[输入画布](https://animgen.com/docs/zh/studio/input-canvas)。

Alpha Key 要求参与生成的每张参考图，包括第一张图，都包含有效 Alpha。普通 JPEG 不会因为其他图片透明就自动变透明。

## API 与 MCP 如何填写

`input.first_frame` 是第一张参考；`input.reference_images` 只放**额外图片**，不要在数组中重复首图。每张本地图片均需完成上传后再使用 `file_id`。公开图片输入不提供 Studio 内部的角色或标签字段。

选择 `supports_reference_images` 和 `modes` 均支持参考图的实时模型，再按其图片总数上限、时长、分辨率和模式比例构造请求。[生成的 Schema](https://animgen.com/docs/zh/api-reference/schemas) 说明字段限制，具体模型还可能有更严格的限制。

报价应包含完整图片集和参数。批准后又增减参考图时，应重新报价并确认变更。通过 AI 使用本地图片时，遵循 [MCP 标准流程](https://animgen.com/docs/zh/mcp/standard-workflow)传输文件字节并安全生成。

---

## 普通与透明动画 (zh)

Canonical URL: https://animgen.com/docs/zh/studio/transparent-animation

Status: stable. Last verified: 2026-08-30.

## 先选对源素材流程

| 目标 | 素材 | 工作流 |
| --- | --- | --- |
| 保留场景或照片背景 | 普通图片 | 普通图片动画 |
| 让已分离背景的角色动起来 | 带有效 Alpha 的图片 | 透明素材动画 / Alpha Key |
| 移除普通视频的复杂背景 | 不透明视频 | Studio 中单独的导出处理，以界面可用功能为准；不是开放 API 能力 |

扩展名为 PNG 不代表一定透明，要检查实际 Alpha 通道。透明生成中使用的每张图片，包括参与生成的尾帧和参考图，都必须满足要求。

## 为什么预览可能带纯色背景

Alpha Key 会先把分离好的主体放在临时键色背景上，再交给视频模型生成。因此“原始生成视频”可能呈绿色或品红色，并且仍然不透明。

正常透明预览和适配的透明导出会清理这层临时背景。下载“原始生成视频”或普通 MP4 片段，不等于下载带 Alpha 的结果。

> [!IMPORTANT]
> 不要直接覆盖临时键色，也不要认为 MP4 自带透明通道。继续在原工作流中使用生成的视频及其透明处理信息。

## 导出需要的结果

选择透明 PNG 序列、适合的精灵图或引擎包、透明 WebM，或者 ProRes 4444。各文件的用途见[输出格式](https://animgen.com/docs/zh/editing-and-export/output-formats)。

重点检查细发丝、半透明边缘、运动模糊，以及接近键色的像素。分别放在浅色和深色背景上检查。预览通过是参考，不保证每一帧的边缘都完美。

对于其他源素材，Studio 可能提供纯色扣除或 AI 抠图。这些属于独立导出处理，有各自的参数、费用和可用条件，不能与“从透明图片开始生成”混为一谈。

## 开放 API 的边界

公开请求的 `video.transparency.mode` 支持 `standard` 和 `alpha_key`。透明导出要求 Alpha Key 来源。开放 API 不提供任意图片 AI 去背景、rembg 或自动回退抠图服务。

素材满足条件时，可以在请求中使用：

```json
{
  "video": {"transparency": {"mode": "alpha_key", "key_selection": "auto"}},
  "export": {
    "output_formats": ["frames_zip"],
    "transparent": {"enabled": true}
  }
}
```

这是请求片段，不能单独提交；还需要首帧及模型支持的参数。完整流程见 [API 快速开始](https://animgen.com/docs/zh/api/quickstart)。

## 效果不符合预期时

- 文件不透明：核对输出格式和来源模式，不要只看扩展名。
- 原始视频有纯色背景：选择透明导出，不要下载原始源视频代替。
- 主体边缘缺失：检查输入 Alpha、键色冲突及生成动作。
- 无法选择透明输出：检查素材条件与[导出权益](https://animgen.com/docs/zh/account-and-billing/credits-and-access)。

先区分素材、选段、导出配置和播放软件的问题，再决定是否重新付费生成。

## 深入检查输入与兼容性

贴边素材先考虑[输入画布](https://animgen.com/docs/zh/studio/input-canvas)。多图生成需逐一检查[首尾帧](https://animgen.com/docs/zh/studio/first-and-last-frames)或[参考图](https://animgen.com/docs/zh/studio/reference-images)的 Alpha。文件有透明但显示不对时，参考[格式兼容性](https://animgen.com/docs/zh/editing-and-export/transparent-formats)和[导出排障](https://animgen.com/docs/zh/troubleshooting/export-and-transparency)。

---

## 导入已有视频继续制作 (zh)

Canonical URL: https://animgen.com/docs/zh/studio/video-import

Status: stable. Last verified: 2026-08-30.

## 从已有动作开始

已有角色渲染、之前生成的片段，或你有权使用的录像，都可以走视频导入流程。它会创建供 Studio 编辑使用的视频导入任务，不会让视频模型重新创造动作。

打开 [Studio](https://animgen.com/app)，选择工作区，切换到导入视频，上传文件或选择兼容的自有视频资源。在上传和处理完成前，保留本地原文件。

## 先上传，再准备片段

文件选择器支持 MP4、WebM、MOV。扩展名不能保证实际编码可解码，把损坏或不支持的文件改名为 `.mp4` 并不等于转码。

等待上传完成，查看 Studio 显示的准备报价，再开始导入。应观察任务状态，不能把上传成功直接当成片段已经可编辑。大文件需要上传时间、处理时间和足够存储空间。

服务端会验证声明大小、真实字节、媒体信息与账户配额。限制取决于当前配置，请按界面及错误详情处理，不照搬记忆中的大小上限。

## 选择快速编辑或逐帧精修

导入任务就绪后：

1. 完整预览源视频，确认时长和方向。
2. 连续片段使用[裁剪与导出](https://animgen.com/docs/zh/editing-and-export/trim-and-export)。
3. 需要不连续选帧、停顿或重排时，进入 [Advanced Editor](https://animgen.com/docs/zh/editing-and-export/advanced-editor)。
4. 检查输出尺寸、帧数/FPS、格式与导出报价。
5. 下载真实文件，在目标软件中验收。

导入不需要再次 AI 生成视频，但不代表后续处理和高级格式都免费，详见[积分与访问权益](https://animgen.com/docs/zh/account-and-billing/credits-and-access)。

## 透明需要单独检查

导入不透明视频不会自动将其变成 Alpha Key 来源。只能使用 Studio 对该来源实际开放的背景移除选项，并在深浅背景上检查边缘。

MOV 或 WebM 容器本身不能证明文件包含透明，也不能保证所有解码器都保留透明。需要可靠地逐帧检查时，对照预览与导出的 PNG，详见[透明格式与兼容性](https://animgen.com/docs/zh/editing-and-export/transparent-formats)。

## 能力边界与恢复

输入画布和 AI 模型参数不适用于导入的现成动作。公开 API/MCP 的图片生成请求也不是视频导入 API。

上传完成但任务失败时，先检查错误和已有资源，再决定是否重新上传。空间不足时，查看[存储与清理](https://animgen.com/docs/zh/account-and-billing/storage-and-cleanup)。仍被编辑配方或导出使用的源视频不要删除。

---

## 排查 API 与 MCP 接入 (zh)

Canonical URL: https://animgen.com/docs/zh/troubleshooting/api-and-mcp

Status: stable. Last verified: 2026-08-31.

## 使用正确地址和凭据

| 集成方式 | 地址 | 鉴权 |
| --- | --- | --- |
| 公开 API | `https://api.animgen.com/v1` | 带适当 Scope 的 Bearer API Key |
| 官方远程 MCP | `https://api.animgen.com/mcp` | 兼容 Streamable HTTP 客户端中的 OAuth |
| 工具清单 | `https://animgen.com/mcp/tools.json` | 公开文档，不是 MCP 连接端点 |

MCP 已上线公开测试。浏览器未带 OAuth 直接打开 MCP URL 时，可能收到鉴权响应；它不是普通 HTML 页面。仅凭这一点不能判断服务不可用。

不要用 API Key 替代 MCP OAuth，不要把网页登录 Token 当作 API Key，也不要自行加 `/sse` 路径。按 [MCP 客户端接入](https://animgen.com/docs/zh/mcp/connect-clients)配置。

## 登录成功但工具失败

检查所登录的 AnimGen 账户是否已验证、开发者访问是否暂停，以及是否授予所需 Scope；产生费用的生成还要检查积分余额。

授权被撤销、权限缺失或客户端授权流程不兼容，都需要单独处理，不是增加余额就能解决。必要时通过官方流程重新连接，不要为了绕过错误禁用 PKCE 或放宽回调校验。

首先使用 `list_models` 做只读检查。它成功只能证明连接与读权限正常，不能证明客户端可以上传文件、用户已批准生成，或完整输出质量已验收。

## 上传或下载未完成

远程服务不能读取本地路径。调用 `prepare_image_upload` 后，必须用获准的客户端能力传输真实字节，再通过 `complete_image_upload` 获得可用文件 ID。

同样，`download_asset` 返回的是元数据和临时 URL，不是已经保存到电脑的文件。下载字节时不要转发 API/OAuth 凭据。客户端缺少相关能力时，应说明限制，使用获准且受支持的替代方式。

## 报价与支出拒绝

| 错误码 | 下一步 |
| --- | --- |
| `SPEND_CONFIRMATION_REQUIRED` | 取得具体批准并提供必需保护参数 |
| `QUOTE_EXPIRED` | 重新报价并核对更新后的金额 |
| `QUOTE_MISMATCH` / `QUOTE_CHANGED` | 核对参数或价格变化，再请求批准 |
| `QUOTE_ALREADY_USED` | 找回原操作，不把原报价用于新任务 |
| `CREDIT_LIMIT_EXCEEDED` | 停止，缩小请求或询问是否批准新上限 |
| `INSUFFICIENT_CREDITS` | 说明余额问题，不自动购买 |

`quote_id` 和 `max_credits` 是 MCP 中与 `request` **同级**的工具参数，不是公开 API 请求体字段。单次上限也不是整个会话总预算。详见[支出保护](https://animgen.com/docs/zh/mcp/spending-safeguards)。

## 安全恢复结果不明的创建请求

保留相同请求、幂等键、账户及凭据身份：API 对应 Key ID，MCP 对应 OAuth 客户端。不能换 Key 或客户端后，仍假定幂等去重会跟随。

已知任务 ID 时先轮询，再决定是否重试创建。遵守可重试标志及 API 返回的 `Retry-After`；MCP 结构化错误不保证携带这个 HTTP 响应头。为重试和本地等待设上限。

本地超时不会取消远端任务；终态失败也可能有部分输出和收费。求助时，通过私密渠道提供请求/任务 ID、时间、错误码、客户端类型和失败阶段，不附带凭据或签名链接。

---

## 排查编辑、导出与透明效果 (zh)

Canonical URL: https://animgen.com/docs/zh/troubleshooting/export-and-transparency

Status: stable. Last verified: 2026-09-28.

## 从来源和已保存配方开始

确认源视频、选段或输出序列、帧数/FPS、画布和目标格式。在 Advanced Editor 中，导出前检查 **Saved**。已提交导出使用保存时的快照，不会随之后的编辑变化。

出现 `COMPOSITION_CONFLICT` 或 **Save failed** 时，保持页面打开，避免其他标签页继续编辑。协调新版本前先记录重要修改，不要盲目覆盖其他版本，也不要假定刷新会保留未保存内容。

## 格式不可选或导出被拒绝

`PAID_EXPORT_REQUIRED` 表示 Studio/网页请求缺少所选高级格式的权益；它不同于表示本次报价积分不足的 `INSUFFICIENT_CREDITS`。Public API/MCP 导出遵循开发者契约，商业使用权仍按适用的付费条款判断。

检查格式和实际来源条件。透明视频需要合法透明处理及透明输出画布。公开 API/MCP 的透明导出必须来自 Alpha Key，不能自动回退为任意 AI 去背景。

## 不透明背景或异常键色

| 现象 | 优先检查哪里 |
| --- | --- |
| 原始生成视频有绿/品红背景 | Alpha Key 中间结果，应该选择透明导出 |
| 下载 MP4 后不透明 | 格式不携带所需 Alpha |
| PNG 透明，但视频显示黑底 | 播放器、解码器或合成支持 |
| 所有格式都有同样背景 | 源图透明、处理模式或纯色画布 |
| 细光晕或主体细节被切掉 | 源图 Alpha、键色溢出、缩放与目标材质 |
| 只有某些帧校验失败 | 检查对应帧，不能由首帧推断全部质量 |

使用同一组导出设置的 PNG 做基线，详见[透明格式与兼容性](https://animgen.com/docs/zh/editing-and-export/transparent-formats)。查看器的棋盘背景与文件真实编码的 Alpha 不是一回事。

## 时长、帧顺序或对齐不正确

核对展开帧数与 FPS。固定 FPS 时，重复帧会延长序列；Reverse 影响整个序列。循环标志不会让不匹配的端点姿势自动无缝连接。

检查引擎是否导入了配套纹理和元数据、保留帧顺序并应用预期 pivot。只复用部分导出包时，尤其注意 Godot 场景偏移和 Cocos 脚本内嵌 pivot。

按对应的 [Unity](https://animgen.com/docs/zh/editing-and-export/unity)、[Godot](https://animgen.com/docs/zh/editing-and-export/godot)、[Unreal](https://animgen.com/docs/zh/editing-and-export/unreal-paper2d)或 [Cocos](https://animgen.com/docs/zh/editing-and-export/cocos-creator)教程检查。

Construct 3 请确认通过顶部工具栏的 **Load animations（导入动画表）**载入内部 `animation.zip`。r495.2 实测中，右键导入加载了图片但忽略配置；请依照 [Construct 3 指南](https://animgen.com/docs/zh/editing-and-export/construct3)核对初始动画、帧率、循环与图像原点。

## 导出失败但已有部分产物

任务可能在生成源视频或部分资产之后失败。重试前先查看 `outputs` 和错误，保存可用文件，区分部分交付与完整成功，并核实实际积分。

如果保留的视频可再次导出，就未必需要重新 AI 生成。新的处理仍需报价及必要批准，不能仅凭最终失败状态就承诺退款。

## 下载失败或来源消失

签名链接过期时，通过授权资产信息刷新。真正的找不到资源，还可能是已删除、归属不符或源存储对象缺失。查看[存储与清理](https://animgen.com/docs/zh/account-and-billing/storage-and-cleanup)，删除历史与删除文件的效果不同。

私下向支持提供任务/request ID、格式、错误码和配套 PNG 是否正常的信息，不要附带原始签名 URL 或凭据。

---

## 常见问题 (zh)

Canonical URL: https://animgen.com/docs/zh/troubleshooting/faq

Status: stable. Last verified: 2026-08-31.

## 为什么生成视频仍然不透明？

原始生成视频和 MP4 片段不透明。Alpha Key 生成可能使用临时纯色背景，应选择符合条件的透明导出。画在图上的棋盘格不算输入 Alpha。详见[透明动画](https://animgen.com/docs/zh/studio/transparent-animation)。

## 能播放视频了，为什么找不到 PNG？

预览生成与导出是两个步骤。先选择区间，打开“导出”，选择格式并启动导出；完成后，在“当前片段的导出”中下载。详见[选段与导出](https://animgen.com/docs/zh/editing-and-export/trim-and-export)。

## 有积分，为什么格式还是锁定？

余额和权益独立。高级 Web 导出需要付费权益；API/MCP 要求已验证账户，生成要有足够积分，订阅负责提高限额。查看[积分与访问权益](https://animgen.com/docs/zh/account-and-billing/credits-and-access)。

## 一定能得到无缝循环吗？

不能保证。需要选择首尾姿态接近的区间并反复检查。选段不会修复生成动作的不一致，也不会补回被截断的主体。建议使用简单动作、固定镜头，并在输入主体四周留空间。

## API 请求超时了，要重新发一次吗？

用已保存的同一幂等键和未修改的请求找回原操作；已有任务 ID 时直接轮询。在确认前一请求是否被接受前，不要创建新逻辑请求。详见[错误与重试](https://animgen.com/docs/zh/api/errors-and-retries)。

## 任务失败但有 outputs，能使用吗？

可以，逐一检查返回的资产。后续导出失败时，可能保留可用的生成视频。下载已有产物并说明未完成阶段，不要把整个请求当作成功。详见[轮询与下载](https://animgen.com/docs/zh/api/polling-and-downloads)。

## 为什么下载链接突然失效？

签名链接会过期。在 Studio 刷新结果，或通过 API 重新取得资产信息。请私密保存文件，不要把签名 URL 当成永久链接；存储与保留规则仍然适用。

## 可以直接给 AI 本地文件路径吗？

远程 MCP 服务不能读取这个路径。客户端需要通过上传桥接发送真实字节、使用合规公开 HTTPS 图片，或发送限制内的 Base64。官方 MCP 已上线公开测试，参见[客户端连接](https://animgen.com/docs/zh/mcp/connect-clients)与 [MCP 工作流](https://animgen.com/docs/zh/mcp/standard-workflow)。

## 报价会锁定价格吗？

开放 API 报价会在创建时重新计算，不返回锁价凭据。MCP 使用短期报价和／或单次操作的上限作为支出保护，不要混淆两种契约。

## 联系支持应提供什么？

提供公共请求 ID 或任务 ID、大致时间、错误码，以及期望行为的简短描述。移除 Key、Token、私有原图或提示词、签名 URL，然后联系[支持](mailto:support@geekart.ai)。

反馈生成图片或动画质量时，可先描述现象；只有在你主动决定并选择合适支持渠道时，才分享私有素材。

## 按失败阶段继续排查

- [上传与生成](https://animgen.com/docs/zh/troubleshooting/generation-and-uploads)：文件、Alpha、模型参数、排队和部分结果。
- [编辑、导出与透明](https://animgen.com/docs/zh/troubleshooting/export-and-transparency)：保存冲突、格式权益、编码和引擎显示。
- [API 与 MCP 接入](https://animgen.com/docs/zh/troubleshooting/api-and-mcp)：OAuth、Scope、报价保护和不确定请求恢复。
- [存储清理](https://animgen.com/docs/zh/account-and-billing/storage-and-cleanup)：空间不足、资源依赖、删除与恢复。

没有得到任务结果时，不要默认换账号、换 Key 或重新生成。先查原任务和已有产物。

---

## 排查上传与生成问题 (zh)

Canonical URL: https://animgen.com/docs/zh/troubleshooting/generation-and-uploads

Status: stable. Last verified: 2026-08-30.

## 先定位失败阶段

记录所选账户/工作区、大致时间、可见错误码和已知任务 ID。不要公开私有图片数据、凭据或签名 URL。

上传失败、创建请求被拒绝、已经接受的任务失败，需要不同处理。发生超时后，先查任务历史或保存的任务 ID，再决定是否重新生成。

## 上传问题

| 现象或错误码 | 下一步检查 |
| --- | --- |
| `PAYLOAD_TOO_LARGE` | 按返回上限减少真实文件字节 |
| 图片无效 / `UNSUPPORTED_MEDIA_TYPE` | 检查真实解码格式与 MIME，不只看扩展名 |
| 图片尺寸被拒绝 | 按返回的宽高限制缩放 |
| `STORAGE_QUOTA_EXCEEDED` | 检查账户空间并安全清理资源 |
| 上传 URL 过期 | 核对原上传状态后，再准备新上传 |
| 传输完成但没有文件 ID | 完成上传确认，只有 PUT 不代表整条流程结束 |

MCP 使用本地图片时，客户端必须在 `prepare_image_upload` 与 `complete_image_upload` 之间传输真实字节，声明大小必须与原文件一致。不能把本地路径当成 HTTP URL 或图片文件 ID。

Web 上传与公开 API 对相似错误可能使用不同结构或错误码，应读取实际错误详情及[公开错误参考](https://animgen.com/docs/zh/api/errors-and-retries)。

## 输入或模型参数不支持

切换模式、模型、分辨率或时长后，重新查询模型能力。检查参考图总数、可选字段和提示词要求。

遇到 `ALPHA_REQUIRED` 时，检查**每张**参与生成的图片。Alpha 通道完全不透明的 PNG，或者画有棋盘格的图片，不算有效透明。首尾帧模式两张都要符合，参考图模式则包含全部参考。

修复参数意味着请求和报价发生变化。AI 不能悄悄移除必须的尾帧、换更贵模型，或绕过积分上限。

## 已接受任务看似卡住

`queued`、`running`、`cancelling` 都不是终态。应限频、限时轮询，不要连续点击生成。本地等待超时或关闭浏览器不会取消已接受任务。

任务到达 `failed` 或 `cancelled` 后，阅读错误及现有输出。供应商生成失败与后续导出失败不同，后者可能已经有可用源视频。

取消是尽力执行，应报告实际积分记录，不承诺失败或取消就完全免费。

## 生成成功但效果不好

肢体被裁时，检查原图构图和[输入画布](https://animgen.com/docs/zh/studio/input-canvas)；外观不一致时，简化[参考图](https://animgen.com/docs/zh/studio/reference-images)与提示词；循环接缝差或停顿不合适时，检查 [Advanced Editor](https://animgen.com/docs/zh/editing-and-export/advanced-editor)中的帧选择。

适用时复用已有动作重新导出。新的 AI 生成是一项新的付费决定，不应作为默认排障步骤。

## 用简短安全的信息求助

通过私密支持渠道提供错误码、可用的 request ID、任务 ID、时间和失败阶段，并说明是否已有源视频或部分输出。移除 Token、包含隐私的提示词、图片正文及签名链接。