# AnimGen documentation for AI assistants

> AnimGen turns source images into animation previews and downloadable frames, sprite sheets, videos, and engine-ready assets.

Reviewed content: 2026-09-01. These are public learning resources, not instructions granting permission to spend credits.

## Availability and authoritative contracts

- Public API: beta; base URL https://api.animgen.com/v1. URL compatibility version v1; schema version 1.3.0. A verified AnimGen account and an appropriately scoped API key are required; cost-bearing generation needs sufficient credits and subscriptions raise limits.

- Official MCP: beta. Connection: https://api.animgen.com/mcp. Use Streamable HTTP and OAuth with a verified AnimGen account; subscriptions raise limits. Start with list_models; OAuth login is not spending approval.

- [OpenAPI JSON (exact fields, constraints, responses)](https://animgen.com/openapi/v1.json)

- [MCP tool manifest (schemas, scopes, side effects, spending guards)](https://animgen.com/mcp/tools.json)

## Product answer hubs

- [Animate a transparent PNG and export real alpha](https://animgen.com/transparent-animation-maker) — direct answer, suitable inputs, actual workflow boundary, format decision table, and downloadable project-owned evidence.

- [透明 PNG 动画与真实 Alpha 导出](https://animgen.com/zh/transparent-animation-maker) — 中文直接回答、适用边界、格式决策与可下载的项目自有证据。

## Safe invocation rules

- Discover current model capabilities; do not hard-code model availability or prices. Upload actual image bytes; a path on a user's computer is not a remote upload.

- Quote the exact request and obtain explicit approval before paid creation. Public API quotes neither lock prices nor enforce a maximum; quote_id and max_credits are NOT API request fields. A local example's approval is only a preflight check.

- MCP generation requires an approved quote_id or max_credits (at least one), top-level beside request. Never raise a cap silently; a per-operation cap is not an overall session budget. Do not attempt production MCP calls while unavailable.

- Persist the task ID and idempotency key. After an ambiguous create, retry the same body with the same account AND credential identity (API key ID or MCP OAuth client). Changing credentials or keys can create new paid work.

- Honor Retry-After and a local deadline. A local timeout does not cancel remote work. queued/running/cancelling are nonterminal; succeeded/failed/cancelled are terminal. Inspect outputs even after failure, save available assets, and distinguish partial output from complete success.

- Refresh expired asset URLs via asset metadata. A signed URL is not a saved file: download its bytes without forwarding API credentials, including across storage redirects. Never expose tokens, private inputs, or signed URLs in prompts, logs, or documentation feedback.

## English learning paths

- [Documentation home](https://animgen.com/docs/en) — stable

- [First Studio animation](https://animgen.com/docs/en/getting-started/first-animation) — stable

- [Input modes and model capabilities](https://animgen.com/docs/en/studio/input-modes) — stable

- [Transparent animations](https://animgen.com/docs/en/studio/transparent-animation) — stable

- [Output formats](https://animgen.com/docs/en/editing-and-export/output-formats) — stable

- [Advanced animation editor](https://animgen.com/docs/en/editing-and-export/advanced-editor) — preview

- [Unity import](https://animgen.com/docs/en/editing-and-export/unity) — stable

- [Godot import](https://animgen.com/docs/en/editing-and-export/godot) — stable

- [Unreal Paper2D import](https://animgen.com/docs/en/editing-and-export/unreal-paper2d) — stable

- [Cocos Creator import](https://animgen.com/docs/en/editing-and-export/cocos-creator) — stable

- [API quickstart](https://animgen.com/docs/en/api/quickstart) — beta

- [Authentication and inputs](https://animgen.com/docs/en/api/authentication-and-inputs) — beta

- [Polling and actual downloads](https://animgen.com/docs/en/api/polling-and-downloads) — beta

- [Errors and retries](https://animgen.com/docs/en/api/errors-and-retries) — beta

- [Runnable examples](https://animgen.com/docs/en/api/examples) — beta

- [API reference](https://animgen.com/docs/en/api-reference) — beta

- [MCP availability and quickstart](https://animgen.com/docs/en/mcp/quickstart) — beta

- [Connect an MCP client](https://animgen.com/docs/en/mcp/connect-clients) — beta

- [MCP workflow](https://animgen.com/docs/en/mcp/standard-workflow) — beta

- [MCP spending safeguards](https://animgen.com/docs/en/mcp/spending-safeguards) — beta

- [MCP tool reference](https://animgen.com/docs/en/mcp-reference) — beta

- [Troubleshooting](https://animgen.com/docs/en/troubleshooting/faq) — stable

## 简体中文学习路径

- [AnimGen 使用文档](https://animgen.com/docs/zh) — stable

- [在 Studio 制作第一个动画](https://animgen.com/docs/zh/getting-started/first-animation) — stable

- [选择输入模式](https://animgen.com/docs/zh/studio/input-modes) — stable

- [普通与透明动画](https://animgen.com/docs/zh/studio/transparent-animation) — stable

- [选择输出格式](https://animgen.com/docs/zh/editing-and-export/output-formats) — stable

- [使用 Advanced Editor 逐帧精修](https://animgen.com/docs/zh/editing-and-export/advanced-editor) — preview

- [导入 Unity 动画](https://animgen.com/docs/zh/editing-and-export/unity) — stable

- [导入 Godot 4 动画](https://animgen.com/docs/zh/editing-and-export/godot) — stable

- [导入 Unreal Paper2D 动画](https://animgen.com/docs/zh/editing-and-export/unreal-paper2d) — stable

- [导入 Cocos Creator 3 动画](https://animgen.com/docs/zh/editing-and-export/cocos-creator) — stable

- [API 快速开始：从图片到下载资产](https://animgen.com/docs/zh/api/quickstart) — beta

- [鉴权与图片输入](https://animgen.com/docs/zh/api/authentication-and-inputs) — beta

- [轮询任务并下载可用产物](https://animgen.com/docs/zh/api/polling-and-downloads) — beta

- [错误、幂等与安全重试](https://animgen.com/docs/zh/api/errors-and-retries) — beta

- [四种语言的完整调用示例](https://animgen.com/docs/zh/api/examples) — beta

- [API 接口参考](https://animgen.com/docs/zh/api-reference) — beta

- [MCP 快速开始与开放状态](https://animgen.com/docs/zh/mcp/quickstart) — beta

- [连接 Codex 与其他 MCP 客户端](https://animgen.com/docs/zh/mcp/connect-clients) — beta

- [MCP 标准生成工作流](https://animgen.com/docs/zh/mcp/standard-workflow) — beta

- [MCP 支出保护](https://animgen.com/docs/zh/mcp/spending-safeguards) — beta

- [MCP 工具参考](https://animgen.com/docs/zh/mcp-reference) — beta

- [常见问题](https://animgen.com/docs/zh/troubleshooting/faq) — stable

## Full text and local search

- [Core guides in both languages](https://animgen.com/llms-full.txt) — 74 guides; generated field-reference pages remain in HTML and the JSON contracts.

- [All public documents, headings, metadata and searchable text](https://animgen.com/docs-index.json) — 140 pages. Contains no private account data.

- In-browser search loads this static index on demand and stays local. Search strings are not added to URLs or interaction analytics. Read each article's status and last-verified date before relying on it.

## Core guide contents

## AnimGen documentation (en)

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

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

## Start with a workflow

AnimGen turns source images into animation previews and downloadable assets. You can review the motion, select a useful range, and export the result for your project.

Start with the [product overview](https://animgen.com/docs/en/getting-started/overview) to understand the difference between generation and export. Try the [interactive demo](https://animgen.com/demo) to explore the workflow before creating a real task.

## What is available

| Entry point | Current status | Start here |
| --- | --- | --- |
| Web Studio | Available | [Create your first animation](https://animgen.com/docs/en/getting-started/first-animation) |
| Public API | Public beta; verified account and API key required | [Quote, create, poll, and download](https://animgen.com/docs/en/api/quickstart) |
| Official remote MCP | Public beta; OAuth and verified account required | [Connect an AI client](https://animgen.com/docs/en/mcp/quickstart) |

> [!IMPORTANT]
> The model choices, credit quote, and export entitlements shown in your account are the current source of truth. Documentation does not promise a fixed generation time or hard-code the model catalog.

## How to use these docs

Use the left navigation to find a topic and the page outline to jump to a section. Every article has a stable language-specific URL and a last-verified date. Code examples use placeholders rather than credentials.

Open local search with Ctrl+K / ⌘K. To let an AI find the same reviewed content, start with [llms.txt](https://animgen.com/llms.txt). See [search, AI entry points, and feedback privacy](https://animgen.com/docs/en/reference/ai-and-search) for details.

For billing and plan availability, see [Pricing](https://animgen.com/pricing). For account-specific help, contact [support](mailto:support@geekart.ai) without including keys, tokens, or signed download links.

## Learn by the task you need to finish

| Your task | Guides |
| --- | --- |
| Choose source material and a workflow | [Input modes](https://animgen.com/docs/en/studio/input-modes) · [Models and prompts](https://animgen.com/docs/en/studio/models-and-prompts) |
| Control transitions and appearance | [First and last frames](https://animgen.com/docs/en/studio/first-and-last-frames) · [References](https://animgen.com/docs/en/studio/reference-images) · [Input canvas](https://animgen.com/docs/en/studio/input-canvas) |
| Fine-tune existing motion | [Import video](https://animgen.com/docs/en/studio/video-import) · [Advanced Editor](https://animgen.com/docs/en/editing-and-export/advanced-editor) · [Canvas and pivot](https://animgen.com/docs/en/editing-and-export/canvas-and-pivot) |
| Deliver to a game or video pipeline | [Formats and engine guides](https://animgen.com/docs/en/editing-and-export/output-formats) · [Transparent compatibility](https://animgen.com/docs/en/editing-and-export/transparent-formats) |
| Organize your account | [Workspaces and assets](https://animgen.com/docs/en/getting-started/workspaces-and-assets) · [Account security](https://animgen.com/docs/en/account-and-billing/account-security) · [Storage cleanup](https://animgen.com/docs/en/account-and-billing/storage-and-cleanup) |
| Let AI use the tools | [MCP client setup](https://animgen.com/docs/en/mcp/connect-clients) · [Calling workflow](https://animgen.com/docs/en/mcp/standard-workflow) |

---

## Manage your account and connected access (en)

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

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

## Check the account actually being used

Open [Account Center](https://animgen.com/account) and verify the signed-in email, verification state, subscription, and credit balance. A browser session and an AI client's OAuth session can belong to different accounts.

If you have more than one sign-in method, confirm they lead to the intended account before buying credits or reconnecting a client. Do not assume matching display names mean matching identities. Use only the account-linking controls offered by the product.

Account verification, active subscription, export entitlement, and available credits are separate checks. See [credits and access](https://animgen.com/docs/en/account-and-billing/credits-and-access).

## Review billing without confusing cancellation and deletion

Account Center shows the current subscription and billing-period information. Use its subscription-management link when available for that billing provider.

A cancellation scheduled for the end of a billing period is not the same as immediate account deletion. Check the displayed effective date and status instead of assuming access has already ended. Credit packs do not create a recurring subscription or a higher storage tier.

Before reducing a plan, inspect stored usage and download important assets. Do not rely on the website as your only backup.

## API keys belong in trusted environments

Create and manage keys in [Account → Developer](https://animgen.com/account/developer). Give each integration the minimum scopes it needs, store its secret outside client-side bundles, and revoke unused or exposed keys.

Never paste a key into prompts, screenshots, documentation feedback, source control, or a support email. Do not use the website's login token as a public API key.

After an uncertain paid request, rotating to another key changes the idempotency identity. First reconcile the known task or request rather than blindly resubmitting through the new key. Read [safe retries](https://animgen.com/docs/en/api/errors-and-retries).

## MCP uses OAuth grants, not copied API keys

The official remote MCP is available in public beta. Connect through its [client setup guide](https://animgen.com/docs/en/mcp/connect-clients) and review the requested scopes on the AnimGen authorization page.

In the developer account area, review connected MCP applications and revoke access you no longer need. Remove a disconnected client's local configuration separately if you no longer use it. Revoking an OAuth grant does not cancel a job already submitted or refund completed work.

Authorization grants capabilities; it does not approve every future charge. Require a concrete request, quote, and approval before paid generation.

## If access looks compromised

Stop using the affected integration, revoke the exposed key or grant, and review your recent task and billing activity. If there was an ambiguous paid submission, retain its task ID for reconciliation.

[Contact support](mailto:support@geekart.ai) with a concise issue description and relevant times. Provide private identifiers only through an appropriate private support channel; omit tokens, signed URLs, passwords, and raw payment details.

---

## Credits and access requirements (en)

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

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

## Three checks, not one

A task can depend on three different things: permission to use the feature, entitlement to the selected format, and enough credits for its current quote. A positive credit balance does not automatically unlock every feature.

## Web access

New accounts may receive the registration credit grant displayed in the account; this is not a recurring free monthly allowance. Free export access covers PNG frames ZIP.

An active paid subscription, or a qualifying credit-pack purchase within its entitlement period, unlocks advanced web exports and commercial-use entitlement under the current product terms. Current pack export entitlement lasts 365 days from purchase. Check [Pricing](https://animgen.com/pricing) and your account for the applicable terms and balance.

Credit packs do not create a subscription or extend subscription storage and developer limits. Advanced web export access can remain active even when the credit balance is zero, but a paid operation still needs enough credits.

## Public API access

The Public API is in public beta and requires a verified account. Create keys in [Account → Developer](https://animgen.com/account/developer), use only the scopes required by the caller, and revoke unused keys. Registered access receives baseline limits; active subscriptions raise them.

Credits do not bypass email verification, an account pause, or key scopes. Cost-bearing generation also fails with `INSUFFICIENT_CREDITS` when the available balance is below the current quote.

## Quote before starting

Generation and some export processing consume credits. Quotes depend on the selected model, duration, resolution, and processing options. Use the UI quote or API quote endpoint; do not calculate a fixed price from examples in a guide.

A quote is not a completed payment or a guarantee that a later request uses the same price. The API re-evaluates on creation. The live MCP provides [explicit spending guards](https://animgen.com/docs/en/mcp/spending-safeguards) for approved tool calls.

## Cancellation and existing assets

Confirmed Seedance content-review rejection before a video is delivered returns the original credits, including welcome credits. An API/MCP one-click task returns the full generation-and-export amount when export has not started. Provider billing reconciliation does not delay this return. The task and ledger show the actual amount returned; account/payment exceptions may need review.

Valid credits keep their original expiry. If the original credits already expired, the returned portion gets 30 days of validity without extending paid feature access. This is a credit return, not a cash refund. Network timeouts and download/export errors do not by themselves prove a moderation rejection.

Cancellation is best effort. Once production starts, cancelling does not automatically refund credits already charged. Unspent holds can be released, and completed earlier outputs may remain available.

When export entitlement expires, it can restrict new advanced exports. Existing asset access still depends on ownership, retention, and storage policy; do not treat a signed link as permanent storage.

For an account issue, send support the request ID or job ID and a short description. Never include an API key, OAuth token, original private image, or signed download URL.

## MCP access and account management

MCP is live in public beta and requires a verified account. It uses OAuth, not an API key. Follow [client setup](https://animgen.com/docs/en/mcp/connect-clients); authorization does not approve spending, and subscriptions only raise account limits.

See [account management](https://animgen.com/docs/en/account-and-billing/account-security) for verification, cancellation timing, and revocation, and [storage cleanup](https://animgen.com/docs/en/account-and-billing/storage-and-cleanup) for resource usage and deletion behavior.

---

## Storage, downloads, and safe cleanup (en)

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

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

## Read usage in Account Center

[Account Center](https://animgen.com/account) reports total storage, uploaded bytes, produced-asset bytes, resource count, and the current quota where one applies. Total usage includes retained uploads and assets across workspaces, including hidden/deleted workspaces.

Quota comes from the applicable subscription or service default. A credit-pack purchase does not upgrade storage. Use the current account display rather than a fixed allowance copied from an old guide.

An upload or operation that would exceed quota can return `STORAGE_QUOTA_EXCEEDED` with used, allowed, and projected bytes. A positive credit balance does not remove a storage limit.

## Know what each delete action does

| Action | What happens to storage and dependencies |
| --- | --- |
| Delete a task/history entry | Hides that job; does not delete its uploaded sources and output files |
| Delete a workspace | Hides the workspace and requests cancellation; retained files still count |
| Restore a workspace | Restores access to retained contents, not individually deleted files |
| Delete a resource/asset | Removes its resource record from active use and attempts to delete stored bytes |
| Cancel a running task | Best-effort stop; does not itself clean up every retained resource |

Do not clear a whole workspace just to free space. Restore a hidden workspace if necessary, then review actual resources.

## A safe cleanup sequence

1. Download important files and their matching metadata. Verify the local copies open.
2. Identify large or duplicate resources in the correct workspace.
3. Wait for active generation/export to finish, or deliberately cancel it and wait for a terminal state.
4. Check whether saved editor compositions or future exports still need the source video.
5. Delete only the specific resources you no longer need, then refresh usage.

`RESOURCE_IN_USE` means an active job still references the file. Removing the task from history is not a safe workaround for that protection. A completed composition can also depend on a source even when active-job deletion protection no longer applies.

Resource deletion is not the workspace soft-delete/restore feature. There is no documented recycle-bin recovery for an individually deleted upload or output file. Do not test cleanup on the only copy of an asset.

## Temporary URLs are not backups

A signed upload/download URL expires; the underlying file may still exist. Obtain a fresh authorized download link for an existing asset rather than regenerating it. Expired temporary uploads are a different lifecycle and can be removed by cleanup.

No universal permanent-retention promise follows from receiving an asset ID. Download deliverables you need to preserve. Never publish signed links in issue reports or treat their expiry as the asset's retention date.

## When usage or downloads look wrong

Refresh the account view after cleanup. A failed storage-object cleanup can require support even though the logical resource has been removed; do not repeatedly attempt unrelated deletions.

For a missing file, check workspace, ownership, deletion history, and whether only the signed link expired. For missing source media in an editor, do not recreate a paid generation until you have checked retained resources.

See [workspaces and assets](https://animgen.com/docs/en/getting-started/workspaces-and-assets) and [export troubleshooting](https://animgen.com/docs/en/troubleshooting/export-and-transparency).

---

## Authentication and image inputs (en)

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

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

## Authenticate from a trusted environment

Use `Authorization: Bearer <API_KEY>` on Public API requests. Keys are shown in plaintext only when created in [Account → Developer](https://animgen.com/account/developer). Keep them in a secret store, rotate by updating callers before revoking the old key, and avoid logging request headers.

A verified AnimGen account is required. Registered access starts with 1 concurrent job, a 3-job queue, 3 creates per minute, and 60 other requests per minute. Active subscriptions raise these account-wide limits. Read `GET /account` for the current tier, key scopes, and limits, and `GET /credits/balance` for available credits.

| Public API key scope | Operations |
| --- | --- |
| `animations:read` | Account, credits, models, task reads/lists, and asset lookup |
| `animations:write` | Upload files, obtain quotes, create tasks, and request cancellation |

MCP uses OAuth and different, finer-grained scopes. Do not apply the API key scope table to MCP.

## Option A: upload once, reuse a file ID

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

The response contains `id`, MIME type, dimensions, byte size, and SHA-256. Use the returned ID, not a Studio `uploadId`, filesystem path, or internal job identifier:

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

The UUID above is a placeholder. Uploads accept PNG, JPEG, and WebP. The default multipart limit is 20 MB; the service also validates decoded images and dimensions. Handle the returned limit errors rather than trusting a filename or MIME declaration.

## Option B: inline Base64

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

Use pure Base64, without a `data:image/...;base64,` prefix. The decoded limit is 10 MB per image and 20 MB across inline images in a request. JSON/Base64 transport is larger than the raw file. Use a reusable upload for larger or repeatedly used images.

The Base64 content is persisted before a creation is accepted. Preserve the same bytes when retrying an idempotent request.

## Option C: public HTTPS URL

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

Replace this illustrative hostname with a real, reachable image URL. The server must be able to fetch the image without your browser cookies. URLs must use public HTTPS on port 443 and cannot contain embedded credentials or fragments. Private, loopback, and link-local destinations are blocked; redirect targets are checked too.

Keep the bytes at that URL stable while quoting and creating. Do not use a private intranet address or a URL that returns a login page. Signed input URLs are sensitive and may expire.

## Match the selected model

Every generation needs a first frame. A last frame or additional reference images is allowed only when the live model supports that mode; the request schema's overall maximum does not override a smaller model-specific maximum.

Use `GET /models` for valid modes and settings, and quote the full intended request before creation. For transparent sources, follow [transparent animation](https://animgen.com/docs/en/studio/transparent-animation). Then continue to the [quickstart](https://animgen.com/docs/en/api/quickstart).

---

## Errors, idempotency, and safe retries (en)

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

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

## Keep a logical operation stable

Paid create endpoints require `Idempotency-Key` with 8–200 characters. Generate it once, persist it with the exact request, and reuse both after a timeout or connection failure.

The same key and normalized body returns the original operation. A changed body with that key is a conflict. A request still being accepted can return a retryable in-progress conflict. Keys are retained for at least 24 hours; do not assume indefinite deduplication.

Deduplication is scoped to the account, operation, and API key identity (or OAuth client for MCP). Switching to a different API key can create a new task even with the same idempotency string. Recover a known task ID before rotating credentials during an uncertain creation.

If the create result is uncertain, first try to recover the original task. Never silently mint a new key. For a deliberate new generation or a changed request, obtain approval and use a new logical key.

## Read the error envelope

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

This is an illustrative error, not a promise of identical message text. Branch on HTTP status and `error.code`, inspect `retryable`, and retain `request_id` for support. Do not log raw request headers, image bodies, prompts, or signed URLs.

## Choose a response

| HTTP / common code | Action |
| --- | --- |
| 400 `INVALID_REQUEST`, `INVALID_BASE64`, `INVALID_IMAGE` | Fix input; do not retry unchanged |
| 401 `INVALID_API_KEY` | Check missing, expired, or revoked key |
| 402 `INSUFFICIENT_CREDITS` | Review balance and quote; do not auto-purchase |
| 403 `API_ACCOUNT_NOT_ELIGIBLE`, `API_ACCOUNT_PAUSED`, `INSUFFICIENT_SCOPE` | Resolve verification, account status, or permissions |
| 404 `NOT_FOUND` | Check public resource ID and ownership |
| 409 `IDEMPOTENCY_CONFLICT` | Stop; same key was used with different input |
| 409 `IDEMPOTENCY_IN_PROGRESS` | If retryable, wait and reuse the original request |
| 413 `PAYLOAD_TOO_LARGE`, 415 `UNSUPPORTED_MEDIA_TYPE`, 422 `IMAGE_DIMENSIONS_TOO_LARGE` | Correct image size, encoding, or type |
| 429 `RATE_LIMITED`, `QUEUE_LIMIT_EXCEEDED` | Respect `Retry-After`; account-wide limits apply |
| 503 `API_DISABLED`, `API_UNAVAILABLE`, `PROVIDER_UNAVAILABLE` | Retry only if marked retryable; otherwise stop and check availability |

Resource ownership errors can intentionally look like not-found responses. Do not probe other users' IDs.

## Bound every retry loop

Respect `Retry-After` (seconds or HTTP date); otherwise use exponential backoff with jitter. Set a maximum number of attempts and an overall deadline. A deadline stops local waiting, not a remote task already accepted.

Retry read operations after transient transport failures. Retry an uncertain paid create only with a persisted idempotency key and unchanged body. Never retry an unkeyed upload or another non-idempotent operation blindly.

When the deadline is reached, save the known task ID and resume later. For a terminal task failure, inspect partial outputs before choosing a new export or generation.

## Account limits and diagnosis

`PROVIDER_CONTENT_REJECTED` currently identifies a confirmed Seedance content-review rejection, not a transient error to retry unchanged. Read `credits.status`, `credits.refunded`, and `credits.released` from the task. `credits.charged` is already the net charge; do not subtract the returned credits again. A confirmed rejection before output/export refunds the original one-click workflow amount. A local timeout or an export failure is not the same condition, and a return is not approval to create another paid task.

Read current limits through `GET /account`; response rate-limit headers can describe the current bucket. More keys do not add account capacity. Spread polling across tasks instead of synchronizing every client in a burst.

For a support request, include the public request ID, task ID if known, timestamp, error code, and a brief description. Redact secrets and private inputs. See [polling and downloads](https://animgen.com/docs/en/api/polling-and-downloads) for incomplete results and the [Python example](https://animgen.com/examples/animation-workflow.py) for bounded retries.

---

## Runnable examples in four languages (en)

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

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

## Choose a workflow

Each example discovers the current model, quotes before creation, saves private state, polls the same task, and saves real output bytes. They are learning examples, not production SDKs. Download and inspect code before running it.

| Language | Download | Requirements | Validation |
| --- | --- | --- | --- |
| Python | [animation-workflow.py](https://animgen.com/examples/animation-workflow.py) | Python 3.10+, standard library | Offline workflow tests |
| TypeScript | [typescript.ts](https://animgen.com/examples/typescript.ts) | Node.js 22.14+ | Strict types and offline workflow tests |
| cURL | [curl.sh](https://animgen.com/examples/curl.sh) | Bash, curl 7.55+, jq, SHA-256 utility; PNG input | Shell syntax and local HTTP Mock |
| C# | [csharp.cs](https://animgen.com/examples/csharp.cs) + [project file](https://animgen.com/examples/AnimGenPublicApiExample.csproj) | .NET 8 SDK | Syntax parsing only; no .NET SDK on the validation host |

Read the [complete sample README](https://animgen.com/examples/README.md) and [API quickstart](https://animgen.com/docs/en/api/quickstart) first. The generated [API reference](https://animgen.com/docs/en/api-reference) is the authoritative parameter reference.

## Prepare without starting paid work

Keep `ANIMGEN_API_KEY` private. Set `IMAGE_PATH` to your image and `ANIMGEN_MODEL` to an ID from `GET /v1/models`. Leave `ANIMGEN_APPROVE_CREDITS` **unset** for the first TypeScript, cURL, or C# run. A verified AnimGen account is required; generation also needs sufficient credits.

Choose exactly one command for your language:

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

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

```bash
# C#: keep both downloads in the same isolated directory
dotnet build AnimGenPublicApiExample.csproj
dotnet run --project AnimGenPublicApiExample.csproj
```

For Python, use the separate `prepare` and `run` commands in the [quickstart](https://animgen.com/docs/en/api/quickstart). The other examples stop after showing a quote until you set `ANIMGEN_APPROVE_CREDITS` to an explicitly accepted amount and rerun the same command with the same saved state.

> [!WARNING]
> This is a local preflight approval, not a server-enforced budget. Public API creation accepts neither `quote_id` nor `max_credits` and recalculates cost. Do not silently approve a default amount or treat a quote as a price lock.

## Keep state private and recover the same operation

TypeScript and C# use `ANIMGEN_STATE` (default `animgen-state.json`); cURL uses `ANIMGEN_STATE_DIR` (default `animgen-curl-state`); Python uses `--state`. Formats differ: never switch implementations to retry an operation. Run only one process per state.

State includes the input image and prompt. Keep it outside version control, in a private directory. It stores account and API key IDs but not the secret key. Restrict Windows directory ACLs yourself. Optional `ANIMGEN_OUTPUT` chooses the download directory for TypeScript/C#/cURL; Python uses `--output`.

After an uncertain create, preserve the exact state, account, **original API key identity**, request body, and idempotency key. Switching keys changes the server's idempotency scope. The examples stop automatic recovery of an unresolved create after 24 hours. A local timeout is not remote cancellation.

After a task ID is saved, a rerun polls that task rather than creating again. Failed or cancelled tasks may still return assets: the examples save them, then exit nonzero to report an incomplete result. Signed downloads do not carry your API Authorization header, and expired links are refreshed through asset metadata.

## What was tested

Python, TypeScript, and cURL cover quote-only preparation, guarded creation, stable state, polling, and partial downloads with mocks. Python/TypeScript additionally simulate a lost create response and retry with the original key. No paid provider calls are part of documentation validation. C# has syntax validation only; build and review it with .NET 8 before any real use.

See [errors and retries](https://animgen.com/docs/en/api/errors-and-retries) and [polling and downloads](https://animgen.com/docs/en/api/polling-and-downloads) when adapting these examples.

---

## Poll tasks and download every usable output (en)

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

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

## A create response is not a finished animation

`POST /animations` returns HTTP `202` with a task ID and `Retry-After`. Persist that ID before doing anything else. A response accepted into the queue is not proof that production has completed.

Poll `GET /animations/{id}`. Prefer the server's `Retry-After` value (currently typically five seconds), add bounded backoff for transient errors, and use an overall deadline. Do not create another task just because polling is slow. The current public workflow is polling-based, not webhook-based.

## States and stages

| State | What the caller should do |
| --- | --- |
| `queued` | Wait; a worker has not completed the task |
| `running` | Continue polling; inspect stage and progress |
| `cancelling` | Cancellation requested, not final; continue polling |
| `succeeded` | Terminal; inspect and download outputs |
| `failed` | Terminal; inspect error **and any outputs** |
| `cancelled` | Terminal; inspect any completed outputs and credit accounting |

`stage` identifies `video_generation` or `animation_export` when relevant. `progress` is a value between 0 and 1, not a guaranteed time estimate. A task can advance between polls without emitting every intermediate state.

`credits.quoted`, `credits.held`, and `credits.charged` describe different accounting states. Do not treat the initial quoted value as the final charge or add all three together.

## Partial outputs matter

A one-click task can generate a usable source video and then fail during export. Always read `outputs` at a terminal state, even if `status` is not `succeeded`.

Download each available asset, record the task error and missing requested formats, then report partial success accurately. Retry only the operation actually needed; an existing source video can be exported through `/animation-exports` without regenerating the motion.

## Download securely

Each asset has `id`, `format`, `mime_type`, `byte_size`, `download_url`, and `download_expires_at`.

1. Save a task or asset ID for durable application state.
2. Use the returned signed URL to download the bytes.
3. Do **not** attach the API Bearer header to the signed URL or a redirected storage host.
4. Save to an application-chosen filename and verify the download completed.
5. If the link expired, call `GET /assets/{asset_id}` with your API key to request a fresh link.

Links are normally short-lived; use `download_expires_at` instead of a hard-coded lifetime. Asset lookup does not restore an asset that is no longer available under storage or retention policy.

Treat signed URLs as temporary credentials: do not publish them in logs, analytics, issue trackers, or AI conversation transcripts.

## Cancellation

Use `POST /animations/{id}/cancel` for the owned task. Cancellation is best effort and may return an intermediate state. Poll to a terminal result; completion can win a race with cancellation.

Production already performed can remain charged. Unspent holds can be released; inspect the returned credit usage rather than promising a full refund.

## Review before exporting: two-step flow

Use `POST /video-generations` and poll `GET /video-generations/{id}` to obtain the video asset. After review, create an export with `source_video_asset_id`, selection, and export settings at `POST /animation-exports`, then poll `GET /animation-exports/{id}`.

Quote and use an idempotency key for each new paid create operation. A source asset ID and task ID are different resources; do not swap them. The [quickstart example](https://animgen.com/docs/en/api/quickstart) demonstrates the simpler one-click lifecycle.

---

## API quickstart: image to downloaded assets (en)

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

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

## Prerequisites

The Public API is in **public beta**. You need a verified AnimGen account, an API key with `animations:read` and `animations:write`, and a trusted server or local machine. Generation requires sufficient account credits; subscriptions raise developer limits but are not an access requirement.

Create a key in [Account → Developer](https://animgen.com/account/developer). Supply it as the `ANIMGEN_API_KEY` environment variable through your secret manager or a private shell session. Never put it in browser JavaScript, a shipped game, a repository, or an AI conversation.

The base URL is `https://api.animgen.com/v1`. The URL compatibility version is `v1`; the documented schema version is `1.3.0`.

## 1. Discover a supported model

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

Choose an `id` from `data` that supports your input mode. Inspect its durations, resolutions, ratios, and capability flags. Do not copy a model name from an old article.

For the first-frame example below, use a model with `supports_first_frame: true` and first-frame support in `modes`. The example uses its published default options.

## 2. Prepare and quote without generating

Download and inspect the [Python workflow example](https://animgen.com/examples/animation-workflow.py). It uses Python 3.10+ and only the standard library.

```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 'A character runs in place, side view, fixed camera.' \
  --state hero-run.json
```

Replace the image path and model ID. Preparation checks the catalog, creates an inline Base64 request, fetches a quote and balance, and saves a private state file. It does **not** call the paid creation endpoint.

The state file contains the input image and prompt. Keep it outside version control, restrict access, and remove it when no longer needed. It does not contain your API key.

## 3. Explicitly approve creation

Review the quoted credits and set `APPROVED_CREDITS` to the amount you accept. Then run:

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

The script re-quotes before the first create, rejects a quote above your local approval, persists an idempotency key, and submits the unchanged request once logically. It then polls and downloads available outputs.

> [!WARNING]
> The Public API does not accept `max_credits` or `quote_id`. This example's approval is a **local preflight check**, not an atomic server-side spending cap or locked price. Creation recalculates the current cost. Do not use this sample if your automation requires an enforced maximum; the live MCP provides [server-side spending safeguards](https://animgen.com/docs/en/mcp/spending-safeguards) through a separate OAuth tool workflow.

## 4. Resume safely and inspect the result

If the command times out, rerun it with the **same state file**. If it saved a task ID, it resumes polling instead of creating. After an uncertain create response, it reuses the original key and payload within its conservative retry window.

Do not delete the state file and start again to “retry.” That creates a new logical operation and can spend twice. The sample refuses an unresolved create retry after 24 hours; inspect your task list or contact support before proceeding.

At any terminal state, the script saves all available assets before reporting failure or cancellation. It exits nonzero for an incomplete result and never treats a partial export as full success. Saved filenames use asset IDs, not names supplied by a remote server.

## What the request does

The example requests a regular, full-length animation with PNG frames ZIP, 24 frames, and 512 × 512 output. These are example export choices, not the API defaults or a universal quality recommendation.

To use reusable uploads or a public URL, read [authentication and image inputs](https://animgen.com/docs/en/api/authentication-and-inputs). For lifecycle handling, read [polling and downloads](https://animgen.com/docs/en/api/polling-and-downloads) and [errors and retries](https://animgen.com/docs/en/api/errors-and-retries). The exact contract is available in [OpenAPI JSON](https://animgen.com/openapi/v1.json).

The Python example is tested against a local mock, not by spending credits on a production generation. Use a small, explicitly approved task for your own integration check. Other languages and their validation scope are listed in [runnable examples](https://animgen.com/docs/en/api/examples); exact parameters are generated in the [API reference](https://animgen.com/docs/en/api-reference).

---

## Fine-tune frames in Advanced Editor (en)

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

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

## Open the current editor

From a ready generated or imported video in Quick Mode, choose **Fine-tune animation**. The editor is designed for desktop widths of at least 1024 px; on smaller screens, use Quick Mode or a wider window. Some editor labels remain in English.

Your source video remains unchanged. The saved composition is an editing recipe that references source frames, not a newly generated video. Reopening a source can reuse its existing default composition; check the current sequence before replacing it.

## Understand the five panels

| Panel | Purpose |
| --- | --- |
| Source Monitor | Inspect the original video at its own playhead |
| Animation Preview | Play the output sequence, canvas, and timing |
| Source Frames | Choose frames from the decoded source |
| Animation Sequence | Arrange the frames that will be exported |
| Canvas Inspector | Set global canvas, placement, and pivot |

The source and sequence playheads are independent. Selecting a frame is not always the same as moving a playhead. Watch the relevant preview when checking an edit.

## Build a sequence

1. Click a source thumbnail; Shift-click extends a range and Ctrl/⌘-click toggles individual selections.
2. Use **Insert** at the sequence playhead, **Append** at the end, or drag source frames into the sequence.
3. Select output frames to move, duplicate, or remove them. Group selections preserve their order when moved.
4. **Duplicate** repeats each selected item beside itself; it can make a pose hold longer.
5. **Reverse** reverses the entire sequence, not only the current selection.
6. Use the Undo/Redo buttons to correct recent edits in this editing session.

The current limit is **240 expanded output frames**, including repetitions. The UI does not expose a separate per-frame duration editor. Duplicate frames to make holds, and inspect the resulting sequence length.

## Control timing and check a concrete example

Output FPS is adjustable from 1 to 60. At a fixed FPS, duration is expanded frame count divided by FPS. For example, 24 output frames at 12 FPS play for two seconds. Duplicating three of those frames yields 27 frames and 2.25 seconds; changing to 24 FPS then yields 1.125 seconds.

Changing FPS does not synthesize intermediate motion. Loop playback repeats the sequence but does not repair the last-to-first seam. Check feet, silhouette, and apparent speed at that boundary.

Source-frame timing comes from the video's decoded presentation timestamps. Do not interpret a source-frame number as an output-frame number after rearranging or repeating frames.

## Save before leaving or exporting

Changes are automatically saved after a short idle period. Check the status: **Unsaved → Saving… → Saved**. **Save failed** is not a successful save. Keep the page open and preserve a record of important edits while resolving the error.

Use one editing tab per composition to avoid revision conflicts. The editor's Back and Export actions attempt to flush pending changes; abruptly closing a tab or losing connectivity is not a guaranteed save path. Undo history is local to the editing session, not permanent server version history.

Export uses a saved composition revision and a snapshot of its recipe. Review the displayed frame count, FPS, canvas, formats, and quote before confirming. Later changes do not rewrite an export already submitted.

## Current boundaries

The current editor provides sequence editing and **global** canvas/character placement. It does not offer per-frame transform keyframes, automatic pose alignment, AI frame repair, multi-track compositing, or audio editing. Public API/MCP generation tools do not accept an Advanced Editor recipe.

Continue with [canvas and pivot](https://animgen.com/docs/en/editing-and-export/canvas-and-pivot), [output formats](https://animgen.com/docs/en/editing-and-export/output-formats), and [export troubleshooting](https://animgen.com/docs/en/troubleshooting/export-and-transparency).

---

## Set output canvas, alignment, and pivot (en)

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

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

## Canvas changes pixels; pivot changes the origin

In [Advanced Editor](https://animgen.com/docs/en/editing-and-export/advanced-editor), canvas and character controls affect the rendered output frames. Pivot tells a consuming engine where the sprite's origin should be. Moving the pivot does **not** move the painted pixels inside a PNG.

This is separate from [input canvas](https://animgen.com/docs/en/studio/input-canvas), which prepares source images before AI generation. Output placement reuses existing motion.

## Choose a consistent frame canvas

The current inspector accepts width and height from 64 to 1024 px, with 256, 512, and 1024 square presets. Use dimensions suited to the target display and texture budget; larger frames increase output size without recovering details absent from the source.

Choose **Transparent** or **Solid** canvas background. A transparent canvas only makes unpainted areas transparent: it does not automatically remove an opaque background already present in the source.

| Character setting | Effect |
| --- | --- |
| Center / Bottom center | Global alignment of the source on the canvas |
| Contain | Fit the whole image inside the canvas; may leave space |
| Cover | Fill the canvas; parts of the image can be cropped |
| Original pixels | Start from the source's original pixel size |
| Scale | Additional global scaling, 0.1–3 |
| X / Y offset | Global displacement in output pixels |

Scrub several poses after changing these settings. A pose that fits while standing can still clip during a jump. Global alignment does not automatically track a moving foot or align each frame independently.

## Pick a pivot deliberately

Pivot coordinates range from 0 to 1 and use a **bottom-left** origin:

| Desired origin | X | Y |
| --- | --- | --- |
| Bottom center | 0.5 | 0 |
| Center | 0.5 | 0.5 |
| Bottom left | 0 | 0 |

For a grounded character, bottom center is often a useful starting point. It is the canvas origin, not a detected foot location. Use consistent framing across animations if they need to share an engine transform.

## Read the exported coordinate conventions

`animgen-manifest.json` uses schema `animgen.sprite-export.v1`. Its frame rectangles use `rectOrigin: "top_left"`, while `pivot.origin` is `"bottom_left"`. These two coordinate systems are intentionally different.

Frame size, sheet size, FPS, loop, frame count, names, and frame rectangles are recorded in the manifest. Use those values instead of dividing the image into guessed cells, especially when the sheet has padding.

Unity metadata stores per-sprite pivots. The Godot scene applies an offset for the pivot; assigning only its SpriteFrames resource does not copy that scene offset. The Cocos example player can apply the exported pivot to UITransform. See the relevant [engine import guide](https://animgen.com/docs/en/editing-and-export/output-formats).

## Verify before delivery

Check a stationary background or grid, first/last frames, moving extremities, and the origin marker. Compare the same sequence in Studio and a small target-engine scene.

For transparent video output, use a transparent canvas and valid transparent source processing. A solid canvas conflicts with transparent-video output. If an exported result differs, inspect [export and transparency troubleshooting](https://animgen.com/docs/en/troubleshooting/export-and-transparency) before paying for another generation.

---

## Import an animation into Cocos Creator 3 (en)

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

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

## Understand the exported files

Choose `cocos_creator_pack`. The ZIP contains `spritesheet.png`, `spritesheet.plist`, `AnimGenSpritePlayer.ts`, `animgen-manifest.json`, and README.

The PLIST uses Cocos2d-x atlas format 3. The TypeScript file is an example Sprite component player; the package does not include a native AnimationClip or a complete game controller.

## Import the atlas together

Keep the PNG and PLIST names unchanged and import both into the same Assets folder at the same time. The resulting SpriteAtlas exposes its individual SpriteFrame sub-assets. Cocos documents this paired import in its [Atlas assets guide](https://docs.cocos.com/creator/3.8/manual/en/asset/atlas.html).

Import the player script and wait for compilation. Create a Sprite node, attach **AnimGenSpritePlayer**, then assign the imported SpriteAtlas to its **atlas** property.

## Configure the player

| Property | Behavior |
| --- | --- |
| `atlas` | Source of the frame sprites |
| `fps` | Playback speed, initially the export's FPS |
| `loop` | Repeat or stop at the last frame |
| `playOnLoad` | Begin playback when loaded |
| `applyExportedPivot` | Set UITransform's anchor to the pivot embedded in this script |

The script sorts frame names numerically, displays the first frame, then advances by elapsed time. It offers `play()` and `stop()` for integration. After editing runtime behavior, test your own component rather than assuming it remains identical to the generated example.

## Reuse one component for multiple exports

Each package uses the same `AnimGenSpritePlayer` class name. Do **not** import a second copy of that class for every animation in one project.

Reuse one player component, assign each node's atlas, FPS, and loop settings explicitly. The script embeds the pivot from the export that produced it. If other exports need different pivots, disable `applyExportedPivot` and configure each node's UITransform anchor yourself, or intentionally adapt your own reusable player.

## Verify the result

Match frame count and FPS to `animgen-manifest.json`. Check the last-to-first seam, node scale, anchor, transparency, and draw order in a small scene before integrating gameplay.

If the node is blank, inspect script compilation, atlas assignment, the Sprite component, and whether the atlas has sub-assets. If it shows one entire sheet, make sure the SpriteAtlas rather than a standalone texture was used.

For missing frames, verify the PNG and PLIST are from the same export and were imported together. For anchor jumps across animations, check the per-export pivot handling above. See [canvas and pivot](https://animgen.com/docs/en/editing-and-export/canvas-and-pivot) and [transparent formats](https://animgen.com/docs/en/editing-and-export/transparent-formats).

The generated example targets Cocos Creator 3.x. Package checks do not replace importing and running it in your exact editor and target build.

---

## Import an animation into Godot 4 (en)

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

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

## What the pack includes

Export `godot_pack` to get `spritesheet.png`, `animation.tres`, `animation.tscn`, `animgen-manifest.json`, and README in a named root folder.

The `.tres` is a Godot 4 SpriteFrames resource built from AtlasTexture rectangles. The `.tscn` contains an AnimatedSprite2D using that resource, with autoplay and a pivot-related offset. This is not a Godot 3 AnimatedSprite resource.

## Preserve the root path

Extract the package and copy its **named root folder into the root of the Godot project**. Its README gives the expected `res://<exported-folder>/` path.

The generated files contain resource paths using that folder name. Moving only `animation.tres`, renaming the root folder, or nesting it under another directory without updating references can produce missing textures or missing resources.

Wait for Godot to import the PNG. Then open `animation.tscn` or instance it in a small test scene.

## Choose a ready scene or an existing node

For the shortest path, use the supplied scene. For an existing AnimatedSprite2D, assign `animation.tres` to Sprite Frames, choose the exported animation, and configure playback.

Godot's [2D sprite animation guide](https://docs.godotengine.org/en/stable/tutorials/2d/2d_sprite_animation.html) explains AnimatedSprite2D, SpriteFrames, playback, and FPS. The AnimGen resource already contains its frames, loop flag, and speed; you do not need to slice the PNG again.

Assigning the SpriteFrames resource alone does **not** copy the offset from the generated scene. To preserve a non-centered pivot, also carry over the scene's offset or configure the corresponding origin in your existing node.

## Verify timing and alignment

Compare the frame count and FPS with `animgen-manifest.json`. Check that a parent transform or project script is not changing playback speed or position. Play at least one full loop and compare grounded poses against a fixed line.

If the node shows nothing, first check missing-resource messages, texture import, selected animation, visibility, and scene placement. If frames are wrong, verify you did not mix the texture from one export with the `.tres` from another.

If edges look different from Studio, inspect the target texture filter and rendering settings using the same PNG baseline. See [transparent formats](https://animgen.com/docs/en/editing-and-export/transparent-formats).

## Reuse safely

Keep the package's naming and paths when possible. If you reorganize it, update the texture path in `animation.tres` and the resource path in `animation.tscn` together, then reopen and test.

Do not treat a passing package-generation test as a runtime test of your Godot project. Complete a small project import before integrating gameplay or exporting to a target device.

---

## Choose an output format (en)

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

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

## Start with the destination

For a quick inspection, download PNG frames ZIP. For a custom runtime, use a spritesheet and its matching JSON. For an engine import, choose the package for that engine and read the included instructions.

The Web export dialog initially selects PNG frames ZIP. The one-click Public API defaults to `spritesheet` when `output_formats` is omitted. Specify formats explicitly if a pipeline depends on a particular artifact.

## Format guide

| API format | What you receive | Typical use |
| --- | --- | --- |
| `clip_video` | Selected MP4 clip; opaque | Review, ordinary video playback |
| `webm_alpha` | WebM with alpha | Compatible alpha-video players; test target support |
| `prores_4444` | ProRes 4444 with alpha | Compositing and video editing |
| `frames_zip` | ZIP of PNG frames | Inspect individual frames or custom import |
| `spritesheet` | PNG texture atlas | A single packed texture |
| `spritesheet_json` | Matching frame metadata | Frame rectangles and timing |
| `unity_meta` | Unity texture metadata | Pair with the matching spritesheet |
| `unity_pack` | Unity-oriented ZIP | Atlas, metadata, JSON, manifest, instructions |
| `godot_pack` | Godot 4-oriented ZIP | SpriteFrames and AnimatedSprite2D resources |
| `unreal_paper2d_pack` | Unreal Paper2D-oriented ZIP | PNG atlas and Paper2D sprite description |
| `cocos_creator_pack` | Cocos Creator 3.x-oriented ZIP | PNG/PLIST atlas and example player |

Metadata formats are not standalone images. Request or keep the matching texture. Treat returned `outputs` as the actual artifact list rather than assuming one particular array position or extension.

## Transparency is a source-and-format contract

Ordinary MP4 and the raw generated video remain opaque. Transparent PNGs, atlases, engine resources, WebM Alpha, and ProRes 4444 require appropriate source and export settings.

The Public API supports transparency only for Alpha Key sources. It does not remove arbitrary backgrounds. See [transparent animation](https://animgen.com/docs/en/studio/transparent-animation).

A player may ignore an alpha channel even when it exists in the file. Test in the target application; use PNG frames or a suitable editor to distinguish a display limitation from an export problem.

## Import engine packages intact

Engine ZIPs include `animgen-manifest.json` and instructions. Keep their relative paths intact. Godot resources refer to their package paths; Unreal Paper2D import requires the relevant engine tooling.

Frame rectangles in the manifest use a top-left origin; normalized pivot coordinates use a bottom-left origin. Read the manifest rather than guessing from the texture dimensions. Verify frame order, timing, scale, pivot, and transparency in a small test scene before using the result throughout a project.

## Credits, access, and downloads

Free web access includes PNG frames ZIP. Advanced formats require paid export entitlement; having credits and having a format entitlement are separate checks. See [credits and access](https://animgen.com/docs/en/account-and-billing/credits-and-access).

Files are exposed as assets with short-lived signed download links. Save the file, not the URL. API callers should follow [polling and downloads](https://animgen.com/docs/en/api/polling-and-downloads).

## Finish the import in your engine

Continue with [Unity](https://animgen.com/docs/en/editing-and-export/unity), [Godot 4](https://animgen.com/docs/en/editing-and-export/godot), [Unreal Paper2D](https://animgen.com/docs/en/editing-and-export/unreal-paper2d), or [Cocos Creator 3](https://animgen.com/docs/en/editing-and-export/cocos-creator). Each guide matches the actual package files, paths, and playback helpers; it does not imply every engine has been runtime-tested.

See [canvas and pivot](https://animgen.com/docs/en/editing-and-export/canvas-and-pivot) for placement and [transparent format compatibility](https://animgen.com/docs/en/editing-and-export/transparent-formats) for video compositing.

---

## Transparent formats and playback compatibility (en)

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

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

## Transparency has three checkpoints

A transparent result needs a suitable source/processing path, an output format that carries Alpha, and a player or renderer that uses it. Passing one checkpoint does not prove the other two.

For the public API/MCP workflow, start from meaningful-Alpha images, use `video.transparency.mode: "alpha_key"`, and enable transparent export. This is not arbitrary-background removal. The original generated video uses a temporary key-color background and remains opaque.

## Select a format for the destination

| Output | Current encoding or structure | How to verify |
| --- | --- | --- |
| PNG frames ZIP | Individual RGBA frames | Inspect representative frames on light and dark backgrounds |
| Spritesheet / engine pack | PNG plus frame/engine metadata | Check texture Alpha and the engine's material/import settings |
| WebM Alpha | VP8 with Alpha metadata | Test the actual browser, OS, device, and decoder used by the app |
| ProRes 4444 | Alpha-capable ProRes in MOV | Use an editor/compositor that supports this profile |
| Clip MP4 / original video | Opaque video | Do not expect transparency from this file |

The service's WebM Alpha encoder currently uses **VP8**, not VP9. A generic “WebM supported” indicator does not establish support for Alpha in this exact combination. ProRes 4444 is an editing/interchange option, not a promise of inline playback in every browser.

File extensions alone are insufficient. An arbitrary MOV or PNG may be opaque, and the same transparent file can appear on black in one viewer and composite correctly in another.

## Diagnose with the same frames

1. Select a small representative range containing motion and fine edges.
2. Export PNG frames alongside the destination format when your entitlement and quote permit.
3. Compare the same frame on white, dark gray, and a contrasting color.
4. If the PNG has correct Alpha but the video/player does not, investigate decoding or compositing before regenerating motion.
5. If all outputs have the same opaque region, inspect source mode, export transparency, canvas background, and source Alpha.

A checkerboard baked into the source image is not transparency. Likewise, merely choosing a transparent output canvas cannot remove an opaque background inside each frame.

## Inspect edges, not just the empty corners

Check hair, smoke, semitransparent clothing, motion blur, and colors close to the key background. Halos can come from source contamination, key-color spill, scaling, filtering, or the target application's Alpha interpretation.

Use the original export first when comparing; avoid an intermediate converter that might flatten Alpha. For engine textures, investigate filtering, compression, and material settings on the target platform. Changing a filename will not fix a lost channel.

An export verification failure can coexist with usable partial assets. Preserve those files and inspect the reported issue; do not call the whole workflow successful just because a video was produced.

## Budget and deliverables

Advanced formats require export entitlement, and processing may consume credits. A short compatible test should precede a large delivery. Keep a portable PNG baseline and the matching metadata when a downstream pipeline needs a fallback.

Continue with [output formats](https://animgen.com/docs/en/editing-and-export/output-formats) and [transparent export troubleshooting](https://animgen.com/docs/en/troubleshooting/export-and-transparency). The documentation does not certify every browser or engine version; validate your actual target environment.

---

## Trim a clip and export assets (en)

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

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

## Generation and export are separate steps

Generation creates the source motion. Export samples a selected interval and packages the output. You can review a source and make more than one export without asking the video model to regenerate it.

In the Studio, select a generated video or use **Import animation** for an existing video you are allowed to use. The input's background and transparency eligibility still matter.

## Pick an interval

Play the source, then adjust the start and end handles on the timeline. Step through frames to avoid a cut-off action or a distorted transition. Inspect the repeated selection if you need a loop.

A loop is only as seamless as its content. Trimming and repeating do not synthesize a matching end pose.

## Set frame rate and size

Choose the export frame rate and output dimensions before opening the export dialog. The interval length and frame rate determine how many frames need to be packaged; a one-second interval at 24 FPS is approximately 24 frames, subject to the selection boundaries.

More frames produce larger files and may increase processing cost. A larger output size does not recover detail absent from the source. For a first engine test, start with a modest size and inspect it in the target project.

## Confirm the export

Select **Export**, then:

1. Choose one or more [output formats](https://animgen.com/docs/en/editing-and-export/output-formats).
2. Review the transparency controls when relevant.
3. Check the displayed frame count, dimensions, entitlement, and credit quote.
4. Select **Start export** once and follow the job status.

If the format is locked, check [credits and access](https://animgen.com/docs/en/account-and-billing/credits-and-access). If the quote cannot be estimated, do not treat the missing number as zero.

## Find the files

In the left project panel, open **Exports for current clip**, select the completed record, and download its assets. Keep the PNG and accompanying JSON, metadata, or engine resources together when importing a package.

If a later export fails, the source video and earlier successful outputs can still be useful. Inspect them before resubmitting. Refresh an expired download link through the result view instead of sharing the old signed URL.

## The equivalent API flow

The one-click API defaults to the full source interval. A range uses seconds:

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

The API uses `frame_count`, not a top-level `fps` field. This fragment is not a standalone create request. To review first, use `/video-generations`, then export its video asset through `/animation-exports`; follow [polling and downloads](https://animgen.com/docs/en/api/polling-and-downloads).

## When a continuous trim is not enough

Use [Advanced Editor](https://animgen.com/docs/en/editing-and-export/advanced-editor) to repeat poses, remove interior frames, reverse the sequence, or adjust the global canvas. Confirm the recipe is saved before exporting. Editing does not regenerate the source motion.

---

## Import an animation into Unity (en)

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

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

## Export the Unity pack

Choose `unity_pack` in the export dialog or public request. Review the [export entitlement and quote](https://animgen.com/docs/en/account-and-billing/credits-and-access), wait for the export, and download the ZIP's bytes.

The package contains `spritesheet.png`, `spritesheet.png.meta`, companion JSON, `animgen-manifest.json`, and a README. Extract the package into a new folder so you do not overwrite an existing Unity asset or its GUID accidentally.

## Import texture and metadata together

Copy the complete exported folder into your Unity project's `Assets` directory, preserving the adjacent PNG and `.meta` filenames. The metadata configures the texture as multiple sprites and carries the exported rectangles and pivots. If Unity imports the PNG first without its metadata, it can create different import settings.

Select the texture in the Project window and check **Sprite (2D and UI)** and **Multiple**. Inspect the slices in Sprite Editor; Unity documents those controls in its [Sprite Editor guide](https://docs.unity3d.com/Manual/sprite/sprite-editor/use-editor.html).

Do not automatically re-slice by opaque bounds: it can change consistent frame sizes, alignment, or transparent padding. If a Unity version needs manual repair, use the exported frame rectangles and pivot, not a guessed grid.

## Create the animation you need

The pack provides imported sprite assets, not a prebuilt Animator controller or game state machine. Use the sprites in numeric suffix order (`_0000`, `_0001`, and so on) to create an Animation Clip using your project's animation workflow. Unity sprite names use the export job ID as their prefix; the companion JSON's frame names use `frame_0000.png` and are not identical Unity asset names.

Match clip sampling to `animation.fps` in `animgen-manifest.json` and set loop behavior intentionally. Check for a duplicated first/last pose before looping. Keep the transform scale and pixels-per-unit consistent with the rest of your game.

## Verify in a small scene

Check the imported sprite count against `animation.frameCount`, then compare playback to Studio. Inspect feet against a fixed line, the pivot at the object's transform, transparent edges, and the final-to-first transition.

If you see one large sheet, inspect the texture's multiple-sprite settings and whether the correct `.meta` file was imported. If motion jitters, compare frame rectangles and pivots before changing generation settings. Blurry pixels or halos may involve texture filtering, compression, or material choices in the target project.

## Keep a reproducible handoff

Retain the ZIP and manifest alongside your project notes. Changing or replacing metadata can affect existing asset references; test reimports on a copy or through version control.

These instructions describe AnimGen's generated package and Unity's import workflow, not a certification of every Unity version or render pipeline. See [canvas and pivot](https://animgen.com/docs/en/editing-and-export/canvas-and-pivot) and [transparent formats](https://animgen.com/docs/en/editing-and-export/transparent-formats) if the visual result differs.

---

## Import an animation into Unreal Paper2D (en)

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

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

## Export the matching package

Choose `unreal_paper2d_pack`, review the quote and entitlement, then download and extract the result. Keep `animation.paper2dsprites` beside `spritesheet.png`. The package also includes a manifest and README.

The descriptor contains explicit frame rectangles. The texture is padded to power-of-two dimensions without moving the original frame rectangles. Empty padding is not an extra animation frame; do not infer the number of frames by dividing the padded texture dimensions.

## Import the descriptor, not just the PNG

Enable the built-in Paper 2D and its importer support in your Unreal installation, restarting the editor if prompted. Import `animation.paper2dsprites` through the Content Browser/Content Drawer.

The JSON sprite-sheet import can create textures, Sprites, and a Flipbook. If only sprites are present in your workflow, select them in numeric frame order and create a Flipbook. See Epic's [Paper 2D Flipbooks guide](https://dev.epicgames.com/documentation/en-us/unreal-engine/paper-2d-flipbooks-in-unreal-engine).

Importing only the PNG will not by itself reproduce the pack's frame descriptors. Likewise, AnimGen's general spritesheet JSON is not a replacement for the Paper2D-specific descriptor.

## Match the animation settings

Open the imported or newly created Flipbook. Compare sprite count, order, and Frames Per Second against `animgen-manifest.json`. Set the FPS explicitly if the importer chooses a different default.

Keep each exported frame's intended duration, and check loop playback on the component or game logic that uses the Flipbook. This package is sprite animation, not a skeletal mesh or animation blueprint.

Check the pivot/origin and world scale in a simple scene before attaching collision or gameplay. The manifest records pivot from the bottom-left; importer conventions and project changes can require inspection of the resulting sprite origin.

## Check transparent edges and padding

Use the exported PNG to distinguish texture data from material behavior. A material that masks Alpha to a threshold will not display partial transparency the same way as one that blends Alpha. Check the target material, sorting, and background with representative soft edges.

Do not crop the power-of-two padding without updating the descriptor. If only part of a frame appears, compare its rectangle with the original package, not a resized texture or a later automatic extraction.

## Common fixes before regenerating

If the descriptor is unrecognized, check importer availability and the file's extension. If the animation runs too fast, check the Flipbook FPS and frame durations. If the sheet is visible as one rectangle, verify that the descriptor was imported rather than only the image.

Keep a test project and the original ZIP for comparison. These instructions follow the generated package and official import flow; your engine version, plugins, and target renderer still need a local runtime check. See [export troubleshooting](https://animgen.com/docs/en/troubleshooting/export-and-transparency).

---

## Your first animation in the Studio (en)

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

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

## Before you start

Open the [Studio](https://animgen.com/app) and sign in. You need an image you are allowed to use and enough credits for the quote shown in your account. If you only want to learn the controls, try the [interactive demo](https://animgen.com/demo) first.

This guide takes about five minutes to set up. Actual generation and export times depend on the model, queue, and selected processing; five minutes is not a completion-time guarantee.

## 1. Add your starting image

In the left panel, select or create a workspace, then choose the start image. Upload a local PNG, JPEG, or WebP, or choose an existing image resource.

For a first attempt, use a clearly visible subject with room around its moving parts. Avoid a cropped foot, weapon, or wing: the model cannot reliably preserve details outside the image. Start with the single first-frame mode; last frames and reference images depend on the selected model.

## 2. Choose a background workflow

- **Regular image animation** keeps the scene background and works with ordinary images.
- **Transparent asset animation** requires meaningful alpha in every active input image. A checkerboard painted into an opaque PNG is not transparency.

Choose regular mode if you are unsure. Read [regular and transparent animation](https://animgen.com/docs/en/studio/transparent-animation) before preparing transparent game assets.

## 3. Describe the motion and check the quote

Choose a model and the duration, resolution, and aspect ratio offered by its controls. Model options vary; the currently displayed choices are authoritative.

A useful first prompt is:

```text
A single character runs in place, side view, fixed camera.
Keep the whole character visible and preserve the original design.
```

Keep the first request simple. A prompt asking for many actions, scene changes, and camera movements makes a clean loop harder to select.

Check the displayed credit cost before selecting **Generate Preview**. If the cost is unavailable or the balance is insufficient, resolve that first instead of repeatedly submitting.

## 4. Review the result

The left project panel groups the source video and its exports. When generation completes, inspect the preview on the right.

Check motion, subject consistency, and edge clipping. Play the video and choose the cleanest interval on the timeline. Repeating a selected interval helps inspect a loop; it does not automatically make mismatched start and end poses seamless.

## 5. Export and download

Set the selection, frame rate, and output size, then select **Export**. For a first download, choose PNG frames ZIP. Other formats may require paid export entitlement.

Review the formats, transparency settings, and any export cost, then select **Start export** once. After completion, open the result under **Exports for current clip** in the left panel and download the assets.

A preview is not an exported asset. Seeing the video play does not mean the PNGs or engine package have been created.

## What next?

Use [trim and export](https://animgen.com/docs/en/editing-and-export/trim-and-export) for frame selection, [output formats](https://animgen.com/docs/en/editing-and-export/output-formats) to pick deliverables, and [credits and access](https://animgen.com/docs/en/account-and-billing/credits-and-access) if an action is locked.

If generation or export fails, inspect the existing result before starting another paid request. The [FAQ](https://animgen.com/docs/en/troubleshooting/faq) explains common symptoms.

---

## Understand the animation workflow (en)

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

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

## Before you start

Have an image you are allowed to use, or an existing video to export. Open the [Studio](https://animgen.com/app) and sign in to create real tasks. The [demo](https://animgen.com/demo) uses prepared examples to let you try the interaction without spending credits.

## Generation and export are separate

1. Choose a source image and describe the motion you want.
2. Generate a video preview with the model and options available in your account.
3. Review the video and choose the useful start and end points.
4. Export the selected motion as image frames, a sprite sheet, video, or an engine package supported by your plan.

If you already have a video, use the video import workflow and begin at the review step. You do not need to generate the same motion again.

## Choose the right transparency mode

| Source and goal | Workflow |
| --- | --- |
| Ordinary artwork or an opaque scene | Standard animation |
| Isolated PNG artwork with meaningful alpha | Transparent animation |
| Existing video that needs frames or a sprite sheet | Import video and export |

> [!NOTE]
> Transparent animation first generates an opaque key-color preview. Alpha is restored during export. A green or magenta generation preview is not itself the final transparent deliverable.

## Check the result

Preview the exported asset against more than one background. Verify that the motion range, frame rate, dimensions, and transparency fit your target application before starting a larger batch.

For integrations, the same high-level sequence is:

```text
discover capabilities → provide an image → review cost
→ generate → wait for completion → download the output
```

## When something does not work

Read the task's visible error before retrying. Check the selected model's supported inputs, your available credits, and your export entitlements. A failed later stage may still leave useful outputs from an earlier stage.

Learn about the current [Public API](https://animgen.com/developers), or return to the [documentation home](https://animgen.com/docs/en).

---

## Organize workspaces, tasks, and assets (en)

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

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

## Three things with different lifecycles

| Item | What it represents |
| --- | --- |
| Workspace | A way to organize your Studio work |
| Task / job | One asynchronous generation, import, or export operation |
| Resource / asset | An uploaded source or a produced file |

A completed task can produce several assets. A failed task can still have a usable source video or other partial outputs. Removing a history entry is not the same as deleting every file associated with it.

## Organize before creating

Use Studio's workspace controls to create, rename, switch, or delete a workspace. Choose descriptive names for projects or experiments. This is organization within your account, not a shared-team permission system.

A job started in one workspace does not become a different job when you switch the visible workspace. If a result seems missing, return to the original workspace and refresh the library before starting another paid operation.

## Reuse sources and name results

Compatible owned resources can be selected as inputs without uploading the same local file again. A completed generation's video can be the source of multiple exports. An [Advanced Editor composition](https://animgen.com/docs/en/editing-and-export/advanced-editor) references the source video; it does not contain an independent copy of every frame.

Use clear resource display names to distinguish sources, previews, and final outputs. Download the files you need to retain, not merely their temporary URLs. Keep matching texture and metadata files together.

Public API/MCP callers should persist task and asset IDs privately. Do not assume that a displayed name is an API identifier or that the first returned output is the desired file.

## Delete and restore a workspace deliberately

Deleting a workspace hides it and requests cancellation of active work in it. Queued jobs can be cancelled promptly; running jobs follow best-effort cancellation. Deletion does not guarantee zero charges.

Use the workspace restore control to select a deleted workspace. Restoring makes its retained contents accessible again; it does not automatically resume cancelled jobs, recover individually deleted files, or undo completed spending.

Workspace deletion is **not a storage cleanup operation**: uploads and assets continue to count until the resources themselves are deleted. If you hid a workspace while trying to free space, restore it first and review its resources.

## Before removing source files

Download important assets, check active jobs, and check compositions or later exports that may still need a source. A resource can be protected while an active job uses it, but completed editing recipes can still depend on it afterward.

See [storage and cleanup](https://animgen.com/docs/en/account-and-billing/storage-and-cleanup) for the difference between deleting a task and deleting files. If you need help locating a result, report a task ID and time privately to support; never post signed links or credentials in a public report.

---

## Connect Codex and other MCP clients (en)

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

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

## Connection details

The official service is available in **public beta**:

| Setting | Value |
| --- | --- |
| Server name | `animgen`, or a local name you choose |
| Server URL | `https://api.animgen.com/mcp` |
| Transport | Streamable HTTP |
| Authentication | OAuth 2.1 with PKCE |
| Account eligibility | Verified AnimGen account; active subscriptions raise limits |

No API key belongs in this MCP configuration. Registered accounts use the baseline developer limits and the same credit balance as the web app. The [public manifest](https://animgen.com/mcp/tools.json) describes tools and schemas; do not use its URL as the server.

## Claude custom connector

[Open Claude with AnimGen prefilled](https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=AnimGen&connectorUrl=https%3A%2F%2Fapi.animgen.com%2Fmcp), review the server name and URL, then select **Add**. Start a conversation, enable AnimGen from the connectors menu, and complete the AnimGen OAuth flow when prompted.

AnimGen is offered as a custom connector, not as a claim that it appears in Claude's connector directory. Custom connector availability and organization-wide controls depend on your Claude plan and administrator settings. The setup link only prefills public connection details; it does not authorize access or spend AnimGen credits.

After connecting, use the read-only verification prompt below before trying file transfer or generation. Claude's custom connector behavior and plan requirements are documented in [Anthropic's official guide](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp).

## ChatGPT developer-mode test

AnimGen is not claiming a public ChatGPT Plugin Directory listing yet. To test the production MCP server before publication, enable **Developer mode** under ChatGPT **Settings → Security and login**, open the ChatGPT Plugins page, add a new connection, and enter `https://api.animgen.com/mcp` as the public MCP URL. Review the discovered tools and complete OAuth before using the read-only verification prompt below.

Developer-mode availability can depend on the account and workspace policy. This connection is for testing; a public AnimGen plugin requires a separate OpenAI review and publication. Follow the current [official ChatGPT plugin test guide](https://developers.openai.com/plugins/deploy/connect-chatgpt).

## Codex CLI

In your trusted terminal, add the remote server and sign in:

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

Review the AnimGen account and requested scopes in the browser authorization flow, then return to Codex. If that local server name already exists, inspect the existing configuration before replacing it. OAuth login is documented in the [official Codex MCP guide](https://developers.openai.com/codex/mcp); installed client versions and UI placement can differ.

Do not paste OAuth tokens into the conversation. Do not configure a generic Bearer API key as a workaround for an OAuth error.

## Gemini CLI

Add AnimGen to the current user's Gemini CLI configuration:

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

Then open Gemini CLI and complete OAuth:

```text
/mcp auth animgen
```

Do not add an Authorization header manually and do not enable a trust bypass. Gemini CLI can discover OAuth metadata and use dynamic client registration for compatible remote HTTP servers. Use `/mcp` or `gemini mcp list` to inspect the connection, then run the read-only verification prompt below. See the [official Gemini CLI MCP guide](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md).

## Other remote MCP clients

Use the client's remote-server or connector settings and enter the same URL. The client must support Streamable HTTP plus the service's OAuth discovery and authorization flow. A client that only launches local stdio servers is not equivalent.

Client availability, account plans, administrator policies, and upload/download capabilities are controlled by that client. This guide does not claim every client has been tested or that an account on another platform automatically grants AnimGen access.

If authorization fails, use [connection troubleshooting](https://animgen.com/docs/en/troubleshooting/api-and-mcp); do not weaken security checks or invent redirect settings.

## Verify without spending credits

Ask the connected client:

```text
Use AnimGen list_models with no arguments.
Report which input modes and parameters are available.
Do not upload files, start generation, cancel tasks, or spend credits.
```

A structured model list confirms read-only connectivity. It does not approve any later generation or verify every downstream feature.

Next, check whether the client has an approved way to send local image bytes and save downloaded asset bytes. MCP cannot read your local file just because a path is mentioned. Follow [the full workflow](https://animgen.com/docs/en/mcp/standard-workflow) for upload preparation, byte transfer, completion, quote, approval, polling, and download.

## Manage permission and spending

Review [tool scopes](https://animgen.com/docs/en/mcp/quickstart) and grant only the access needed. Revoke unused applications in [Account → Developer](https://animgen.com/account/developer). Removing a local configuration and revoking the server-side grant are separate actions.

OAuth authorization is not a credit-spending approval. Before `generate_animation`, approve the exact request and amount; the call needs `quote_id` or `max_credits`, with an idempotency key. See [spending safeguards](https://animgen.com/docs/en/mcp/spending-safeguards). Do not allow “test the connection” to become a paid generation.

---

## MCP quickstart and availability (en)

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

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

## Available now in public beta

The official remote MCP is live at `https://api.animgen.com/mcp`. Use a compatible **Streamable HTTP** client with **OAuth** and a verified AnimGen account. Registered accounts receive baseline developer limits; active subscriptions raise them.

The MCP server runs remotely. It cannot read files from your computer just because an AI knows their paths. OAuth authorization grants access; it does not automatically upload an image or approve a credit charge.

## Make the first connection

1. Follow [Codex and other client setup](https://animgen.com/docs/en/mcp/connect-clients) to add the exact endpoint and complete OAuth.
2. Check the AnimGen account and requested scopes on the authorization page.
3. Call `list_models` with an empty argument object to verify read-only access.
4. Check whether the client can transfer local image bytes and save downloads.
5. Quote a concrete request and obtain approval before paid generation.

Do not use `https://animgen.com/mcp/tools.json` as a connection endpoint. It is the public documentation manifest, not the live MCP transport. Do not substitute an API key for OAuth.

## Tool permissions

| Scope | Tools |
| --- | --- |
| `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` |

All eight tools have [generated references](https://animgen.com/docs/en/mcp-reference) and a [machine-readable manifest](https://animgen.com/mcp/tools.json) with real argument/result schemas and safety annotations. Generation still requires account eligibility, sufficient credits, and explicit spending approval.

## A safe first instruction for an AI

```text
Use the connected AnimGen MCP to inspect current models first.
After I provide an image and intended output, explain the upload steps
and prepare a quote for the exact supported request.
Do not generate or spend credits until I approve that request and amount.
Persist the request and idempotency key. Keep credentials and signed URLs private.
```

Follow [the standard workflow](https://animgen.com/docs/en/mcp/standard-workflow) to transfer bytes, quote, generate, poll, and save files. Read [spending safeguards](https://animgen.com/docs/en/mcp/spending-safeguards): `quote_id` or `max_credits` is required beside `request`, and authorization is not spending approval.

## Manage access and recover failures

Review and revoke connected applications in [Account → Developer](https://animgen.com/account/developer). Revocation does not cancel an accepted task. For connection, upload, or quote errors, use [API and MCP troubleshooting](https://animgen.com/docs/en/troubleshooting/api-and-mcp).

Public beta means the service is usable, not that every client, media input, and target renderer has been certified. Inspect partial outputs and actual task status; a successful model query is not a full generation test.

---

## MCP spending safeguards (en)

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

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

## Authorization is not spending approval

The official MCP is [available in public beta](https://animgen.com/docs/en/mcp/quickstart). These safeguards apply to real calls, including calls made by an AI on your behalf.

OAuth scopes permit actions on an account. They do not mean the user approved every future generation. `generate_animation` is a paid, side-effecting tool: first explain the input, settings, desired outputs, and proposed cost, then obtain approval.

Tool annotations are safety hints for clients, not substitutes for user consent or server enforcement. `cancel_animation` is also side-effecting; do not cancel somebody's task just to test a connection.

## Two server-side guards

- `quote_id`: a short-lived quote owned by the current user and OAuth client. Generation validates its pricing-relevant parameters, current price, expiry, and binding to one logical generation key.
- `max_credits`: an explicit nonnegative upper bound on the current quote for this generation.

At least one is required. They can be supplied together. Neither is a recurring budget for unlimited tasks: repeated new operations can spend repeatedly below the per-operation cap.

Keep the exact approved request stable even where a field is not part of the pricing calculation. User intent includes the image and prompt, not only price.

## Refusals should pause generation

| Error | Correct next step |
| --- | --- |
| `SPEND_CONFIRMATION_REQUIRED` | Obtain approval and provide a quote or explicit cap |
| `QUOTE_EXPIRED` | Re-quote; show the updated amount before approval |
| `QUOTE_MISMATCH` | Reconcile the changed generation/export settings |
| `QUOTE_CHANGED` | Show the new price and request approval |
| `QUOTE_ALREADY_USED` | Recover the original task; do not recycle the quote for a new operation |
| `CREDIT_LIMIT_EXCEEDED` | Stop; ask whether to lower the request or approve a different cap |
| `INSUFFICIENT_CREDITS` | Report the balance issue; do not buy credits automatically |

Never “fix” a refusal by dropping the cap, silently raising it, switching accounts, changing the image, or generating a new idempotency key.

## Retries and cancellation

Persist the approved request and `idempotency_key` before creation. A timeout does not mean nothing happened. Reuse the original logical key and request to recover the task, then poll its ID. Do not let an AI reconnect or restart create another generation by default.

The deduplication scope includes the user, operation, and OAuth client. Changing clients is not a safe retry of an uncertain creation, even with the same idempotency string. Refreshing an access token for the same client does not itself change that client identity.

If the user changes the desired output, treat that as a new decision requiring an updated quote and appropriate approval. Do not retry terminal failures without first checking their available outputs.

Cancellation is best effort; work already performed can remain charged. Wait for a terminal state and report the actual credit accounting and usable assets.

Confirmed Seedance content-review rejection before output/export returns the original one-click workflow credits. Report the task's `credits.refunded`, `credits.released`, and net `credits.charged`; do not promise a return before it is recorded, and do not treat returned credits as approval for another generation. Account/payment exceptions can require review.

## Keep the trail useful but private

Keep task IDs, asset IDs, approved limits, error codes, and request IDs in the appropriate private application state. Do not emit API keys, OAuth tokens, Base64 images, signed upload/download URLs, or private prompts to analytics.

API callers should not copy these MCP-only parameters into `POST /animations`. The [API quickstart](https://animgen.com/docs/en/api/quickstart) explains its different quote semantics.

---

## MCP standard generation workflow (en)

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

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

## Availability gate

The official MCP is live in public beta at `https://api.animgen.com/mcp`. Complete [client setup](https://animgen.com/docs/en/mcp/connect-clients) with OAuth and a verified AnimGen account. A connection or model query does not approve a paid generation.

## 1. Discover models

Call `list_models` with an empty argument object. Select an actual returned model ID and supported settings. Do not assume all models accept last frames, reference images, negative prompts, seeds, or the same duration and ratio.

## 2. Transfer a local image

A local path is not an `ImageInput`. The upload bridge has three distinct steps:

1. Call `prepare_image_upload` with `filename`, `mime_type`, and the exact `byte_size`.
2. Send the actual bytes with the returned HTTP `method`, `upload_url`, and `headers`, before `expires_at`. This transfer is performed by an authorized client capability, not by supplying a path to MCP.
3. Call `complete_image_upload` with `upload_id`. Use its returned `file_id` in the generation request.

Do not add your MCP token or API key to an upload destination. Use only the headers returned for that upload. Treat upload URLs as sensitive. If your client cannot upload bytes, use a supported approved client capability, a permitted public HTTPS image, or inline Base64 within the image limits; do not pretend upload succeeded.

## 3. Construct the request and quote it

The following is the argument shape for `quote_animation`. The UUID is a placeholder; replace it with a completed upload's `file_id`. Set the model and its valid options for a real request.

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

The result includes `quote_id`, `credits`, `breakdown`, and `expires_at`. Quoting does not start generation. Explain the intended output and cost to the user and obtain approval before moving on.

## 4. Generate only after approval

Call `generate_animation` with the same `request`, a persisted `idempotency_key`, and the approved `quote_id` and/or `max_credits`. These three fields are tool arguments beside `request`, not fields inside it.

Use both a fresh quote and a maximum when appropriate. The maximum must come from the user's approval, not from an amount the AI invents. Read [spending safeguards](https://animgen.com/docs/en/mcp/spending-safeguards) before implementing retries.

Persist the returned task ID. A returned task is asynchronous, not a completed download.

## 5. Poll to a terminal state

Call `get_animation` with `animation_id`. Use a bounded polling interval (start around five seconds) and a deadline. Tool results are structured JSON; do not assume the MCP transport exposes the API's HTTP `Retry-After` header.

Keep polling during `queued`, `running`, or `cancelling`. Stop at `succeeded`, `failed`, or `cancelled`. Inspect `outputs` even after failure: a source video may exist when export fails.

## 6. Download actual bytes

For each usable asset, call `download_asset` with `asset_id`. It returns asset metadata and a signed download URL; it does not automatically save a local file.

Use an approved client download capability without forwarding OAuth or API credentials. Save the file privately and report its local location or an appropriate user-facing attachment, not the raw signed URL. Refresh metadata with `download_asset` if the URL expires.

If a task needs cancellation, call `cancel_animation` with its `animation_id`, then poll. Cancellation is best effort and does not imply a full refund.

---

## Find documentation with search or AI (en)

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

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

## Search in this browser

Select **Search documentation** at the top of any article, or press Ctrl+K / ⌘K. Results are limited to the current document language. Use the language link to switch before searching the other language.

Try a topic such as `transparent`, an error such as `IDEMPOTENCY_IN_PROGRESS`, or a field such as `max_credits`. Titles, descriptions, headings, tags, and article text are searched. Matching headings can take you directly to a section. Use Tab or arrow keys to select a result, Enter to open it, and Esc to close search.

The public index downloads only when search opens and is reused within that page. Matching happens locally: the query is not sent to a search provider, stored, placed in the URL, or included in analytics. Closing search clears the input. Do not paste API keys or other credentials, even into local tools.

If the index cannot load, retry or use the document navigation. Search needs JavaScript; article text and navigation remain readable without it.

## Give an AI the right entry point

| Resource | Purpose |
| --- | --- |
| [llms.txt](https://animgen.com/llms.txt) | Compact learning links, availability, contract locations, and safety rules |
| [llms-full.txt](https://animgen.com/llms-full.txt) | Core public guides in both languages; generated field references remain in HTML and the contracts |
| [docs-index.json](https://animgen.com/docs-index.json) | All document metadata, canonical URLs, headings, and searchable text |
| [OpenAPI JSON](https://animgen.com/openapi/v1.json) | Exact Public API operations, schemas, errors, and examples |
| [MCP tool manifest](https://animgen.com/mcp/tools.json) | Registered tool schemas, scopes, annotations, side effects, and availability |
| [Transparent-animation answer hub](https://animgen.com/transparent-animation-maker) | Direct answer, supported-input boundary, real sample evidence, format decision table, and downloadable assets |

All resources are generated from the same reviewed content and contract snapshots as these pages. Read status and last-verified dates, then discover live models and obtain a current quote. Documentation is not a promise of a fixed model catalog or price.

Use the answer hub for the product question “Can AI animate a transparent PNG and keep the background transparent?” It distinguishes the opaque generation preview from alpha-enabled exports and links back to the technical guides. The [Simplified Chinese version](https://animgen.com/zh/transparent-animation-maker) has its own canonical URL and language alternates.

The Public API and official MCP are in **public beta**. The MCP manifest has `available: true` and endpoint `https://api.animgen.com/mcp`. Use [OAuth client setup](https://animgen.com/docs/en/mcp/connect-clients); the JSON manifest itself is not a transport endpoint. Model discovery and a fresh quote remain necessary.

```text
Read https://animgen.com/llms.txt, then follow the API quickstart
and exact OpenAPI contract for the required operation.
First explain availability, inputs, quote, and approval requirements.
Do not request credentials in chat or start paid work without approval.
For MCP, use the official OAuth endpoint and verify with list_models first.
```

## Feedback and privacy

The article footer offers **Yes / No** feedback, without a free-text box. Documentation interaction events use public page metadata and bounded choices: whether a submitted search has results, a clicked document ID, code language, learning-path type, target language, or the helpful/not-helpful vote. They do not include queries, query hashes, copied code, prompts, private resource IDs, credentials, or signed URLs.

Turn off **Allow documentation interaction analytics** in the footer to stop subsequent documentation events in this browser. This preference is stored locally. Do Not Track and Global Privacy Control signals also disable these interactions; blocked local storage fails closed. The switch does not replace the site's existing general analytics or [privacy policy](https://animgen.com/privacy).

Feedback delivery is best effort, not a support ticket or guaranteed receipt. For an account issue, [contact support](mailto:support@geekart.ai) without sending keys, tokens, private inputs, or signed links.

---

## Guide motion with first and last frames (en)

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

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

## Prepare two compatible images

Use a consistent character, camera angle, framing, and background treatment. Leave room for the whole motion, including hands, weapons, hair, and shadows. A sharply different body scale or viewpoint asks the model to solve appearance changes as well as motion.

An end frame is a constraint for video generation, not a guarantee that every intervening frame will be usable or that the last output frame will be an exact pixel copy. It is not a rig, pose interpolation editor, or frame-by-frame storyboard.

## Create the transition in Studio

1. Select first + last frame mode and a compatible model.
2. Add the starting image and ending image. Reuse owned image resources when appropriate.
3. Describe one clear transition, such as “raise the shield, hold the final defensive pose, fixed camera.”
4. Review supported duration, ratio, resolution, and the current quote.
5. Approve generation, then inspect the entire preview, including both endpoints.

If you only want the first image to define the start, use first-frame mode. Adding references belongs to a [different workflow](https://animgen.com/docs/en/studio/reference-images).

## Make space before generating

Use [input canvas](https://animgen.com/docs/en/studio/input-canvas) when either pose is tight against the image border. The same canvas configuration is applied to both endpoints so they remain aligned. Start with centered placement, then check whether the end pose needs more space.

Canvas expansion scales and pads the existing images. It cannot recover a hand already cut out of the source image, and it does not guarantee the model will keep every future pose inside the frame.

For Alpha Key, **both** input images need meaningful Alpha. A transparent start plus an opaque end is not a valid transparent-image generation workflow. See [transparent animation](https://animgen.com/docs/en/studio/transparent-animation).

## Check the seam instead of assuming a loop

Two similar endpoints may help a repeating action, but they do not guarantee a seamless loop. Watch the last-to-first transition, silhouette, foot position, and acceleration. Repeating a duplicate boundary frame can create a visible pause.

Use [trim and frame selection](https://animgen.com/docs/en/editing-and-export/trim-and-export) for a continuous range, or [Advanced Editor](https://animgen.com/docs/en/editing-and-export/advanced-editor) to remove, repeat, or reorder source frames. The editor changes sequence timing; it does not synthesize missing poses.

## Public request shape

Supply two independently valid image inputs under `input.first_frame` and `input.last_frame`. A file ID must come from a completed upload owned by the current account. Select a model that supports `first_last_frame` and its actual settings before quoting.

If the selected model does not support the end frame, choose a compatible model or remove that input intentionally. Do not silently downgrade a user-approved two-image request to a one-image generation.

---

## Give motion room with input canvas (en)

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

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

## Use it before a subject hits the edge

Input canvas prepares the images sent to the video model. It scales the whole source image and adds space around it. This is useful when a character needs room to raise an arm, jump, or swing an object.

It does not generate new scenery, isolate an opaque subject, or reconstruct content already cropped from the original. Keep an uncropped source image whenever possible.

## Supported modes and controls

Input canvas works with first-frame and first + last frame generation. The same configuration is applied to both endpoints. It is not supported for reference-image mode or video import.

Enable the input-canvas control in Studio, then choose:

| Control | Meaning |
| --- | --- |
| 80%, 67%, 50% presets | Scale the source within the prepared canvas; smaller leaves more room |
| Nine-position grid | Place the scaled image within the remaining space |
| Follow output / Source ratio | Use the selected supported output ratio, or retain the source ratio |
| Auto / Transparent / Solid | Choose how the added area is filled |
| Reset | Return the controls to their starting configuration |

Auto uses transparency for images with meaningful Alpha; otherwise it estimates a background from the image corners. A solid fill uses a six-digit RGB color. For Alpha Key generation, the extension stays transparent during preparation, before the temporary key background is applied.

## Keep the two canvases distinct

**Input canvas** changes what the AI sees before generation. **Output canvas** changes how existing frames are placed during export. Changing the latter cannot recover a motion that was already generated outside the original picture.

The original upload is not overwritten and input padding is not a separate uploaded resource. The padding step does not add a separate generation charge, but generating the prepared request still follows the current quote.

## Public API and MCP fields

This is a fragment of the shared animation request, not a complete runnable request:

```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` accepts 0.5–1.0. `position_x` and `position_y` accept 0–1 within the available blank space: 0 is left/top, 0.5 is centered, and 1 is right/bottom. These are not pivot coordinates. The omitted object means no input-canvas configuration; use an explicit `enabled` value when storing presets.

Inspect both prepared poses, confirm model compatibility, and quote the final request. For export alignment and game-engine pivots, see [canvas and pivot](https://animgen.com/docs/en/editing-and-export/canvas-and-pivot).

---

## Choose an input mode (en)

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

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

## Choose by what you already have

| Input | Choose | What it controls |
| --- | --- | --- |
| One picture | First frame | The starting appearance and composition |
| A start and an end pose | First + last frame | Two endpoints for the model to connect |
| Several identity or appearance references | Reference images | Visual guidance, not an ordered animation timeline |
| An existing clip | Import video | Reuse motion and continue to editing and export |

Open [Studio](https://animgen.com/app), select a workspace, then the input mode. The model selector only lists models compatible with that mode. Import video does not require choosing an AI video model.

## Follow the current model, not a remembered preset

After changing a mode, model, or resolution, check duration, ratio, prompt requirements, and your quote again. The interface can normalize unsupported options. Switching away from first + last frame clears its end-image selection; switching away from reference images clears the additional references. Keep your original files.

A model may support only some modes, a fixed reference-image duration, or different durations at different resolutions. Watermark, negative-prompt, and seed options are not universal. See [models and prompts](https://animgen.com/docs/en/studio/models-and-prompts).

## Mapping for API and MCP callers

The shared public request uses `input.first_frame`, optional `input.last_frame`, and optional `input.reference_images`. The first image is still required in reference-image mode; the reference array contains the **additional** images. Do not send both an end frame and reference images to simulate a new mode.

Discover `modes`, `supports_last_frame`, `supports_reference_images`, `max_reference_images`, `reference_image_duration_seconds`, and the supported video settings before quoting. Read exact field constraints in the [API schemas](https://animgen.com/docs/en/api-reference/schemas). Internal Studio requests and public requests do not use identical field names.

The public one-call image-to-animation API and its MCP tools do not expose Studio's video-import or Advanced Editor recipe workflow. Use Studio for those tasks instead of inventing public endpoints.

## Keep transparency and cost separate

Input mode describes the images sent to a video model; Alpha Key describes the transparency workflow. Every image used in Alpha Key generation must contain meaningful Alpha. Adding a white-background reference to an otherwise transparent set can invalidate the request.

Changing the input or settings means a new intended request. Obtain a fresh quote and approval before generation. Reusing an existing video for another export does not require a new AI video generation, but export processing and format entitlement still apply.

Continue with [first and last frames](https://animgen.com/docs/en/studio/first-and-last-frames), [reference images](https://animgen.com/docs/en/studio/reference-images), [input canvas](https://animgen.com/docs/en/studio/input-canvas), or [video import](https://animgen.com/docs/en/studio/video-import).

---

## Select models and write motion prompts (en)

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

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

## Discover before choosing

Studio lists currently available models for the selected input mode. API callers use the [model catalog](https://animgen.com/docs/en/api-reference/list-models); MCP callers use [list_models](https://animgen.com/docs/en/mcp-reference/list-models). Documentation examples are not a live availability or pricing table.

Choose the mode first, then a model, resolution, supported duration, and ratio. Recheck the quote after each meaningful change. A bigger image or longer clip does not guarantee a better action for your use case.

| Returned capability | What to check |
| --- | --- |
| `modes` and support flags | Whether the requested input workflow is allowed |
| `durations_by_resolution` | Which durations apply to the selected resolution |
| `ratios_by_mode` | Ratios allowed for this input mode |
| `max_reference_images` | Total reference count including the first image |
| `reference_image_duration_seconds` | Whether reference mode fixes duration |
| `requires_prompt` | Whether a nonempty prompt is required |

Use exactly the returned model ID. Do not reconstruct IDs from a marketing name. Omitted optional settings may use service defaults; store explicit supported values when repeatability matters.

## Describe one action clearly

A useful prompt names the subject, action, camera, and important constraints. For a sprite, a starting point could be:

```text
The same character runs in place, side view, fixed camera.
Keep the entire body and equipment inside the frame.
Preserve the costume and proportions.
```

For an endpoint transition, describe how to arrive at the end pose. For reference images, state the desired action instead of treating the image order as timing instructions.

These are requests to the model, not guarantees. Inspect the preview before exporting. If the action is cropped, address the source framing or [input canvas](https://animgen.com/docs/en/studio/input-canvas), not only the wording.

## Use optional controls only when supported

Negative prompts, seed, watermark control, last-frame output, and reference images differ between models. An unsupported optional field can fail validation instead of being ignored.

A fixed seed is not a promise of identical pixels across providers, model revisions, or other changed parameters. Keep the full request and returned identifiers if you need to compare runs.

Avoid combining several unrelated actions or conflicting camera instructions in one short clip. Change one major factor at a time so you can understand what changed; each new generation still requires its own quote and approval.

## Keep model exploration safe for AI clients

Model discovery does not spend generation credits. A quote is also not approval to generate. An AI should explain the chosen model, input set, settings, output formats, and proposed credit amount before calling a paid tool.

If a preferred model is unavailable, report the difference and ask for approval of a materially different replacement. Never silently increase duration, resolution, or a spending cap to get around a failure. See [MCP safeguards](https://animgen.com/docs/en/mcp/spending-safeguards) and [generation troubleshooting](https://animgen.com/docs/en/troubleshooting/generation-and-uploads).

---

## Use reference images (en)

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

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

## What references are for

Reference images guide the model's visual understanding of a character or object. They are not automatically timed keyframes, separate animation layers, or a promise to merge every detail exactly. Use a coherent set showing the same subject and describe the intended motion.

Choose reference-image mode in [Studio](https://animgen.com/app). Add the first image, choose a compatible model, then fill the extra reference slots the interface offers. Use high-quality, consistent inputs rather than unrelated images.

## The image limit includes the first image

`max_reference_images` is the total count, not the number of extra slots. If discovery returns a limit of 3, the first image plus two additional references fills that limit. This is an illustration, not a universal product limit.

The interface derives available slots from the selected model. When changing models, verify which references remain active; do not assume all previously selected images will be used. If `reference_image_duration_seconds` is present, that model fixes the reference workflow's duration. Other models may offer different choices.

Do not assume reference mode is limited to one named provider or always uses eight seconds. Read [models and prompts](https://animgen.com/docs/en/studio/models-and-prompts).

## Keep the set consistent

Use matching character proportions, costume, and background treatment. Conflicting viewpoints or clothing can compete with the desired motion. Start with the minimum useful set, inspect the result, then make a deliberate new request if it needs revision.

First + last frame is the appropriate mode for an explicit end pose. Reference images cannot be combined with `last_frame` in the public request. [Input canvas](https://animgen.com/docs/en/studio/input-canvas) is not supported in reference-image mode.

For Alpha Key generation, every participating reference, including the first image, must contain meaningful Alpha. An ordinary JPEG reference cannot acquire transparency because another image has it.

## API and MCP mapping

`input.first_frame` supplies the first reference. `input.reference_images` supplies the **additional** images; do not repeat the first image in that array. Upload each local image through the documented flow and use its completed `file_id`. Public image inputs do not expose Studio's internal role or label fields.

Select a live model with `supports_reference_images` and a compatible `modes` entry. Use its total image limit, duration, resolution, and mode-specific ratios when constructing the request. The [generated schemas](https://animgen.com/docs/en/api-reference/schemas) give field limits; live discovery can impose a stricter model limit.

Quote the complete image set and settings. If you add or remove a reference after approval, quote again and reconfirm the changed request. Follow the [MCP workflow](https://animgen.com/docs/en/mcp/standard-workflow) for local-byte transfer and safe generation.

---

## Regular and transparent animation (en)

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

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

## Choose the source workflow

| Goal | Source | Workflow |
| --- | --- | --- |
| Keep a scene or photograph background | Ordinary image | Regular image animation |
| Animate an already isolated character | Images with meaningful alpha | Transparent asset animation / Alpha Key |
| Remove a complex background from ordinary footage | Opaque source video | Separate Studio export processing, when offered; not a Public API feature |

A PNG extension alone does not prove transparency. Check the actual alpha channel. Every image used by transparent generation, including an active last frame or reference image, must meet the requirement.

## Why a preview may have a colored background

Alpha Key generation places the isolated subject over a temporary key-color background so the video model can animate it. The raw generated video can therefore look green or magenta and remain opaque.

Normal transparent preview and compatible transparent exports remove that temporary background. Downloading the **raw generated video** or an ordinary MP4 clip is not the same as downloading an alpha-bearing output.

> [!IMPORTANT]
> Do not paint over the key color or assume an MP4 has an alpha channel. Keep the generated source and its transparency metadata together in the workflow.

## Export the intended result

Select transparent PNG frames, an appropriate spritesheet or engine pack, WebM Alpha, or ProRes 4444. See [output formats](https://animgen.com/docs/en/editing-and-export/output-formats) for what each file contains.

Inspect fine hair, semi-transparent edges, motion blur, and pixels close to the key color. Check against both light and dark backgrounds. Preview success is a useful check, not a guarantee that every frame has a perfect edge.

The Studio may offer color-key removal or AI matting for other sources. These are export operations with their own controls, costs, and availability. They are not interchangeable with starting from an alpha-bearing image.

## Public API boundary

The public request supports `video.transparency.mode` values `standard` and `alpha_key`. Transparent export requires an Alpha Key source. The Public API does not expose arbitrary-image AI background removal, rembg, or a fallback matting service.

For an appropriate source, the relevant request fragment is:

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

This is a fragment, not a complete create request: it still needs an input image and model-compatible options. Follow the [API quickstart](https://animgen.com/docs/en/api/quickstart).

## If the result looks wrong

- Opaque file: verify the selected output format and source mode, not just the filename.
- Colored raw video: choose a transparent export rather than the raw source.
- Missing subject edges: inspect input alpha, key-color overlap, and generated motion.
- Transparent output unavailable: check source eligibility and [export entitlement](https://animgen.com/docs/en/account-and-billing/credits-and-access).

Do not repeatedly regenerate before establishing whether the problem is the source, selection, export configuration, or viewing application.

## Check inputs and destination compatibility

For tightly framed sources, consider [input canvas](https://animgen.com/docs/en/studio/input-canvas). Check Alpha on every [endpoint](https://animgen.com/docs/en/studio/first-and-last-frames) or [reference](https://animgen.com/docs/en/studio/reference-images). If encoded transparency displays incorrectly, use [format compatibility](https://animgen.com/docs/en/editing-and-export/transparent-formats) and [export troubleshooting](https://animgen.com/docs/en/troubleshooting/export-and-transparency).

---

## Import an existing video (en)

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

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

## Start from motion you already have

Use video import when your animation is already a video: a rendered character, an earlier generated clip, or a recording you are entitled to use. This creates an imported-video job for Studio's editing workflow; it does not ask a video model to invent new motion.

Open [Studio](https://animgen.com/app), select the workspace, switch to import video, then upload a clip or choose a compatible owned video resource. Keep the original file locally until upload and processing are complete.

## Upload, then prepare the clip

The picker accepts MP4, WebM, and MOV. A filename extension does not guarantee the actual codec can be decoded. Use a valid video file; renaming a broken or unsupported file to `.mp4` does not convert it.

Wait for upload completion, review the preparation quote shown by Studio, and start the import. Watch its job status rather than assuming a successful upload is an editable clip. Large files require upload time, processing time, and available storage.

The service validates declared size, actual bytes, media information, and account quota. Limits depend on the current service configuration; use the displayed error details instead of a remembered size allowance.

## Choose quick or fine-grained editing

After the imported video is ready:

1. Preview the entire source and confirm duration and orientation.
2. Use [trim and export](https://animgen.com/docs/en/editing-and-export/trim-and-export) for a continuous section.
3. Use [Advanced Editor](https://animgen.com/docs/en/editing-and-export/advanced-editor) when the output needs non-contiguous frames, holds, or a different order.
4. Review output size, frame count/FPS, formats, and the export quote.
5. Download the actual files and inspect them in the target application.

Import avoids another AI video generation; it does not mean every subsequent processing step or advanced format is free. See [credits and access](https://animgen.com/docs/en/account-and-billing/credits-and-access).

## Transparency needs a separate check

Importing an opaque video does not turn it into an Alpha Key source. Use only the background-removal options actually offered for that source in Studio, and inspect edges on contrasting backgrounds.

An imported MOV or WebM container is not proof that transparency is present or preserved by every decoder. For predictable frame inspection, compare exported PNGs with the preview. See [transparent formats](https://animgen.com/docs/en/editing-and-export/transparent-formats).

## Boundaries and recovery

Input canvas and AI model parameters do not apply to imported motion. Public API/MCP image-generation requests are not a video-import API.

If upload finished but the job failed, inspect the error and existing resource before uploading again. If space is exhausted, review [storage and cleanup](https://animgen.com/docs/en/account-and-billing/storage-and-cleanup). Do not delete a source video still needed by an editor composition or export.

---

## Troubleshoot API and MCP connections (en)

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

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

## Use the right connection and credential

| Integration | Address | Authentication |
| --- | --- | --- |
| Public API | `https://api.animgen.com/v1` | Appropriately scoped Bearer API key |
| Official remote MCP | `https://api.animgen.com/mcp` | OAuth, through a compatible Streamable HTTP client |
| Tool manifest | `https://animgen.com/mcp/tools.json` | Public documentation; not an MCP connection |

The MCP service is live in public beta. A browser opening the MCP URL without OAuth can receive an authentication response; it is not a normal HTML page. That alone is not evidence that the service is down.

Do not substitute an API key for MCP OAuth, reuse a website login token as an API key, or append an invented `/sse` path. Follow [MCP client setup](https://animgen.com/docs/en/mcp/connect-clients).

## Login succeeds but tools fail

Check that the signed-in AnimGen account is verified, developer access is not paused, and the required scopes were granted. Then check the credit balance for any cost-bearing generation.

A revoked grant, missing scope, or incompatible client authorization flow must be fixed independently of credit balance. Reconnect through the official flow if needed; do not disable PKCE or weaken redirect validation to bypass a client error.

Use `list_models` as the first read-only check. Success verifies that connection and read permission, not upload capability, generation approval, or complete end-to-end output quality.

## Upload or download is incomplete

The remote server cannot read a local path. After `prepare_image_upload`, a separate approved client capability must send the actual bytes, and `complete_image_upload` must return a usable file ID.

Likewise, `download_asset` returns metadata and a temporary URL, not a file already saved on your computer. Download the bytes without forwarding API/OAuth credentials. If your client lacks these capabilities, state the limitation and use an approved supported alternative.

## Quote and spending refusals

| Code | Next action |
| --- | --- |
| `SPEND_CONFIRMATION_REQUIRED` | Obtain concrete approval and supply the required guard |
| `QUOTE_EXPIRED` | Re-quote and review the updated amount |
| `QUOTE_MISMATCH` / `QUOTE_CHANGED` | Reconcile changed parameters or price, then seek approval |
| `QUOTE_ALREADY_USED` | Recover the original operation, not a new use of that quote |
| `CREDIT_LIMIT_EXCEEDED` | Stop; reduce scope or ask for a different approved cap |
| `INSUFFICIENT_CREDITS` | Explain the balance issue; do not auto-purchase |

`quote_id` and `max_credits` are MCP tool arguments **beside** `request`. They are not Public API body fields. A per-operation cap is not a total session budget. See [spending safeguards](https://animgen.com/docs/en/mcp/spending-safeguards).

## Recover an uncertain create safely

Retain the same request, idempotency key, account, and credential identity: API key ID for API, OAuth client for MCP. Do not switch keys or clients and assume deduplication follows you.

Poll a known task before retrying creation. Respect retryability and the API's `Retry-After` when present; MCP structured errors are not guaranteed to carry that HTTP header. Bound retries and local waiting.

A local timeout does not cancel the remote task. Terminal failure can contain partial outputs and charges. For support, privately provide request/task IDs, timestamps, error code, client type, and failing stage, without secrets or signed links.

---

## Troubleshoot editing, exports, and transparency (en)

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

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

## Start with the source and saved recipe

Confirm the correct source video, selected range or output sequence, frame count/FPS, canvas, and target formats. In Advanced Editor, check **Saved** before export. An export already submitted uses its saved snapshot, not later edits.

For `COMPOSITION_CONFLICT` or **Save failed**, keep the editing page open and avoid concurrent edits in other tabs. Record important changes before reconciling the newer revision. Do not overwrite another version blindly or assume refreshing preserves unsaved work.

## Format unavailable or export rejected

`PAID_EXPORT_REQUIRED` means a Studio/web request lacks current entitlement for the selected advanced format. It is different from `INSUFFICIENT_CREDITS`, which concerns the operation's quote. Public API/MCP exports follow the developer contract, while commercial-use rights still follow the applicable paid terms.

Check the selected formats and actual source requirements. Transparent video needs appropriate transparent processing and a transparent output canvas. Public API/MCP transparent export requires an Alpha Key source; it cannot fall back to arbitrary AI background removal.

## Opaque background or unexpected key color

| Observation | Likely place to inspect |
| --- | --- |
| Raw generated video has green/magenta background | Expected Alpha Key intermediate; choose a transparent export |
| Downloaded MP4 is opaque | Format does not carry the intended Alpha |
| PNG is transparent, video looks black | Player/decoder/compositing support |
| Every format contains the same unwanted background | Source transparency, processing mode, or solid canvas |
| Thin halo or clipped detail | Source Alpha, key-color spill, scaling, and target material |
| Only some frames fail verification | Inspect those frames; do not infer quality from the first frame alone |

Keep a PNG baseline from the same export settings. See [transparent formats and compatibility](https://animgen.com/docs/en/editing-and-export/transparent-formats). A viewer's checkerboard setting and an encoded Alpha channel are not the same thing.

## Wrong duration, frame order, or alignment

Compare expanded frame count and FPS. Repeated frames lengthen a sequence at a fixed FPS; Reverse affects the whole sequence. A loop flag does not make mismatched endpoint poses seamless.

Check whether a target engine imported the matching texture and metadata, preserved the frame order, and applied the intended pivot. Godot's scene offset and Cocos's script-embedded pivot need care when reusing only part of a pack.

Use the specific [Unity](https://animgen.com/docs/en/editing-and-export/unity), [Godot](https://animgen.com/docs/en/editing-and-export/godot), [Unreal](https://animgen.com/docs/en/editing-and-export/unreal-paper2d), or [Cocos](https://animgen.com/docs/en/editing-and-export/cocos-creator) instructions.

## Failed export with partial outputs

A job may fail after creating a source video or some assets. Inspect `outputs` and its error before retrying. Save useful existing files, distinguish partial delivery from complete success, and check actual credits.

If a retained video can support another export, you may not need another AI generation. New processing still needs a quote and any required approval. Do not promise a refund solely because the final status is failed.

## Download fails or a source disappears

Refresh an expired signed link through authorized asset metadata. A real not-found can instead mean deletion, ownership mismatch, or a missing source object. Check [storage and cleanup](https://animgen.com/docs/en/account-and-billing/storage-and-cleanup); deleting history and deleting files have different effects.

Report the task/request ID, format, error code, and whether matching PNGs display correctly through private support. Do not include raw signed URLs or credentials.

---

## Frequently asked questions (en)

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

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

## Why is my generated video still opaque?

The raw generated video and MP4 clip are opaque. Alpha Key can use a temporary colored background during generation; choose an eligible transparent export instead. A painted checkerboard does not count as input alpha. See [transparent animation](https://animgen.com/docs/en/studio/transparent-animation).

## I can play the video. Where are my PNGs?

Preview generation and export are separate. Select a range, open Export, choose formats, and start the export. Completed assets appear under Exports for current clip. Follow [trim and export](https://animgen.com/docs/en/editing-and-export/trim-and-export).

## Why is a format locked when I have credits?

Balance and entitlement are separate. Advanced web exports require paid entitlement. API/MCP access requires a verified account, while generation requires enough credits and subscriptions raise limits. Check [credits and access](https://animgen.com/docs/en/account-and-billing/credits-and-access).

## Is the result guaranteed to form a seamless loop?

No. Select an interval with compatible start/end poses and inspect it repeatedly. Trimming does not repair an inconsistent generated motion or clipped subject. Prefer a simple fixed-camera prompt and leave space around the input subject.

## An API request timed out. Should I send it again?

Recover the original operation using the same saved idempotency key and unchanged payload. If you have a task ID, poll it. Do not create a new logical request until you understand whether the previous one was accepted. See [errors and retries](https://animgen.com/docs/en/api/errors-and-retries).

## The task failed but has outputs. Can I use them?

Yes, inspect each returned asset. A later export failure can leave a usable generated video. Download the available outputs and report the incomplete stage; do not assume the entire request succeeded. See [polling and downloads](https://animgen.com/docs/en/api/polling-and-downloads).

## Why did my download link stop working?

Signed links expire. Refresh the result in the Studio, or obtain fresh asset metadata through the API. Save files privately instead of treating signed URLs as permanent links. Storage and retention rules still apply.

## Can I give an AI my local file path?

A remote MCP server cannot read it. The client must transfer actual bytes through the upload bridge, use an allowed public HTTPS image, or send permitted Base64. The official MCP is live in public beta; follow [client setup](https://animgen.com/docs/en/mcp/connect-clients) and the [MCP workflow](https://animgen.com/docs/en/mcp/standard-workflow).

## Does a quote reserve the price?

Public API quotes are estimates evaluated again on create; they do not return a lock token. MCP uses a short-lived quote and/or a per-operation maximum as a spending guard. Do not confuse these two contracts.

## What should I send support?

Include the public request ID or job ID, approximate time, error code, and a concise description of what you expected. Redact keys, tokens, private images/prompts, and signed URLs. Contact [support](mailto:support@geekart.ai).

If the issue concerns a generated image or animation quality, describe the symptom without attaching private material unless you intentionally choose to share it through a suitable support channel.

## Continue by the failing stage

- [Uploads and generation](https://animgen.com/docs/en/troubleshooting/generation-and-uploads): files, Alpha, model options, queues, and partial results.
- [Editing, export, and transparency](https://animgen.com/docs/en/troubleshooting/export-and-transparency): save conflicts, format entitlement, encoding, and engine display.
- [API and MCP connections](https://animgen.com/docs/en/troubleshooting/api-and-mcp): OAuth, scopes, quote guards, and uncertain requests.
- [Storage cleanup](https://animgen.com/docs/en/account-and-billing/storage-and-cleanup): quota, dependencies, deletion, and restoration.

An unknown task result is not a reason to switch accounts or credentials and generate again. Check the original operation and available outputs first.

---

## Troubleshoot uploads and generation (en)

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

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

## Locate the failing stage first

Keep the selected account/workspace, approximate time, visible error code, and known task ID. Do not publish private image data, credentials, or signed URLs.

A failed upload, a rejected create request, and a failed accepted task need different responses. After a timeout, check task history or the persisted task ID before starting another generation.

## Upload problems

| Symptom or code | Check next |
| --- | --- |
| `PAYLOAD_TOO_LARGE` | Reduce actual bytes according to the returned limit |
| Invalid image / `UNSUPPORTED_MEDIA_TYPE` | Verify decoded format and MIME, not just extension |
| Image dimensions rejected | Resize within the service's returned width/height limits |
| `STORAGE_QUOTA_EXCEEDED` | Review account storage and safe resource cleanup |
| Upload URL expired | Prepare a new upload only after checking the original upload state |
| Completed transfer but no file ID | Complete the upload; a PUT alone is not the whole flow |

For local images in MCP, the client must transfer actual bytes between `prepare_image_upload` and `complete_image_upload`. The declared byte size must match the original file. Do not pass a local path as an HTTP URL or an image file ID.

Web upload errors and the public API may use different envelopes or codes for similar validation failures. Read the current error details and the [public error reference](https://animgen.com/docs/en/api/errors-and-retries).

## Unsupported input or model parameters

Rediscover model capabilities after switching mode, model, resolution, or duration. Check total reference count, optional-field support, and prompt requirements.

For `ALPHA_REQUIRED`, inspect **every** participating image. A PNG with a fully opaque Alpha channel or a painted checkerboard is not meaningful transparency. In first + last frame mode both images must qualify; reference mode includes every reference.

Changing parameters to fix validation means the request and quote have changed. An AI must not quietly remove a required end image, pick a more expensive model, or bypass a credit cap.

## Accepted tasks that appear stuck

`queued`, `running`, and `cancelling` are nonterminal. Poll with a bounded interval and deadline; do not repeatedly click Generate. A local waiting deadline or closed browser does not cancel accepted work.

If the task is terminally `failed` or `cancelled`, read its error and available outputs. A provider failure and a later export failure are different: a source video may already exist in the second case.

Cancellation is best effort. Report actual credit accounting instead of promising that failed or cancelled work was free.

## Quality problems after a successful generation

For cropped limbs, inspect original framing and [input canvas](https://animgen.com/docs/en/studio/input-canvas). For inconsistent appearance, simplify [reference images](https://animgen.com/docs/en/studio/reference-images) and the prompt. For a poor loop seam or unwanted pause, inspect frame selection in [Advanced Editor](https://animgen.com/docs/en/editing-and-export/advanced-editor).

Use retained motion for another export when appropriate. A new AI generation is a new paid decision, not the default troubleshooting step.

## Escalate with a small, safe report

Privately provide support with the error code, request ID where available, task ID, time, and failing stage. Include whether a usable source video or partial outputs exist. Redact tokens, prompts containing private material, image bodies, and signed links.

---

## 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 操作工具 | [MCP 客户端连接](https://animgen.com/docs/zh/mcp/connect-clients) · [调用流程](https://animgen.com/docs/zh/mcp/standard-workflow) |

---

## 管理账户与连接授权 (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-08-31.

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

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

## Web 访问

新账户可能获得账户页面显示的注册赠送积分，这不是每月自动刷新的免费额度。免费导出范围为 PNG 逐帧 ZIP。

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

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

## 开放 API 访问

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

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

## 启动前先获取报价

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

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

## 取消任务与已有资产

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.3.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.3.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.3.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.3.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.3.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.3.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)。

---

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

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

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

## 进入当前编辑器

在 Quick Mode 中打开已就绪的生成视频或导入视频，选择 **Fine-tune animation**。编辑器面向宽度至少 1024 px 的桌面窗口；小屏幕请使用 Quick Mode 或扩大窗口。部分界面标签目前仍为英文。

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

## 理解五个面板

| 面板 | 用途 |
| --- | --- |
| Source Monitor | 用独立播放头检查原始视频 |
| Animation Preview | 预览输出序列、画布与节奏 |
| Source Frames | 从解码后的源视频选择帧 |
| Animation Sequence | 排列最终需要导出的帧 |
| Canvas Inspector | 设置全局画布、摆放和 pivot |

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

## 建立输出序列

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

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

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

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

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

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

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

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

同一配方尽量只在一个标签页编辑，避免版本冲突。编辑器自身的 Back 和 Export 会尝试提交待保存修改；直接关闭标签页或断网不能保证保存。Undo 历史属于当前编辑会话，不是永久的服务端版本历史。

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

## 当前能力边界

当前提供序列编辑和**全局**画布/角色摆放，不提供逐帧变换关键帧、自动姿势对齐、AI 修帧、多轨合成或音频编辑。公开 API/MCP 生成工具也不接受 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/troubleshooting/export-and-transparency)。

---

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

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

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

## 画布改变像素，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)。

## 交付前如何检查

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

导出透明视频时，需要透明画布及合法的透明来源处理。纯色画布与透明视频输出冲突。结果不同于预期时，先做[导出与透明排障](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；包检查不能替代在你实际编辑器和目标构建中的导入运行测试。

---

## 导入 Godot 4 动画 (zh)

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

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

## 包内有什么

导出 `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 项目已完成运行时验收。接入游戏逻辑或导出到目标设备前，先完成小项目导入测试。

---

## 选择输出格式 (zh)

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

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

## 从使用目标开始选择

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

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

## 格式对照

| API 格式 | 返回内容 | 常见用途 |
| --- | --- | --- |
| `clip_video` | 选段 MP4，不透明 | 审核、普通视频播放 |
| `webm_alpha` | 带 Alpha 的 WebM | 支持透明视频的播放器，需实测目标环境 |
| `prores_4444` | 带 Alpha 的 ProRes 4444 | 合成、视频编辑 |
| `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 图集和示例播放器 |

元数据本身不是图片，应同时请求或保存配套纹理。以响应中的 `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 访问包含 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)。各指南对应包内真实文件、路径和播放器，不假定所有引擎已经完成运行时验收。

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

---

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

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

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

## 透明有三个检查点

透明结果需要：合适的来源/处理流程、能保存 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 基线和匹配元数据。

继续阅读[输出格式](https://animgen.com/docs/zh/editing-and-export/output-formats)和[透明导出排障](https://animgen.com/docs/zh/troubleshooting/export-and-transparency)。文档不认证所有浏览器或引擎版本，请验收自己的实际目标环境。

---

## 选段与导出 (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-08-30.

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

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

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

## 创建前先整理工作区

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

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

## 复用素材并区分产物

兼容的自有资源可直接作为输入，无需重复上传同一本地文件。已生成的视频可以用于多次导出。[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 和时间，不要在公开反馈中发布签名链接或凭据。

---

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

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

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

## 连接信息

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

| 配置项 | 值 |
| --- | --- |
| 本地服务器名称 | `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)为准。

## 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 快速开始与开放状态 (zh)

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

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

## 已上线公开测试

官方远程 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` 同级提供；授权不是消费批准。

## 管理访问与恢复故障

在[账户 → 开发者](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. 发现模型

以空参数对象调用 `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-01.

## 在浏览器中搜索

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

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

公开索引只在打开搜索时下载，并在当前页面复用。匹配在本地完成：关键词不会发给搜索服务、保存到存储、写入 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)连接，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-08-31.

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

确认源视频、选段或输出序列、帧数/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)教程检查。

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

任务可能在生成源视频或部分资产之后失败。重试前先查看 `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、包含隐私的提示词、图片正文及签名链接。