{"schemaVersion":1,"revision":"d5312f07668c3089","origin":"https://animgen.com","contentLastVerified":"2026-09-01","contracts":{"api":{"status":"beta","available":true,"baseUrl":"https://api.animgen.com/v1","pathVersion":"v1","contractVersion":"1.3.0","openapiUrl":"https://animgen.com/openapi/v1.json"},"mcp":{"status":"beta","available":true,"endpoint":"https://api.animgen.com/mcp","manifestUrl":"https://animgen.com/mcp/tools.json"}},"fullText":{"url":"https://animgen.com/llms-full.txt","maxBytes":393216,"includedPaths":["/docs/en","/docs/en/account-and-billing/account-security","/docs/en/account-and-billing/credits-and-access","/docs/en/account-and-billing/storage-and-cleanup","/docs/en/api/authentication-and-inputs","/docs/en/api/errors-and-retries","/docs/en/api/examples","/docs/en/api/polling-and-downloads","/docs/en/api/quickstart","/docs/en/editing-and-export/advanced-editor","/docs/en/editing-and-export/canvas-and-pivot","/docs/en/editing-and-export/cocos-creator","/docs/en/editing-and-export/godot","/docs/en/editing-and-export/output-formats","/docs/en/editing-and-export/transparent-formats","/docs/en/editing-and-export/trim-and-export","/docs/en/editing-and-export/unity","/docs/en/editing-and-export/unreal-paper2d","/docs/en/getting-started/first-animation","/docs/en/getting-started/overview","/docs/en/getting-started/workspaces-and-assets","/docs/en/mcp/connect-clients","/docs/en/mcp/quickstart","/docs/en/mcp/spending-safeguards","/docs/en/mcp/standard-workflow","/docs/en/reference/ai-and-search","/docs/en/studio/first-and-last-frames","/docs/en/studio/input-canvas","/docs/en/studio/input-modes","/docs/en/studio/models-and-prompts","/docs/en/studio/reference-images","/docs/en/studio/transparent-animation","/docs/en/studio/video-import","/docs/en/troubleshooting/api-and-mcp","/docs/en/troubleshooting/export-and-transparency","/docs/en/troubleshooting/faq","/docs/en/troubleshooting/generation-and-uploads","/docs/zh","/docs/zh/account-and-billing/account-security","/docs/zh/account-and-billing/credits-and-access","/docs/zh/account-and-billing/storage-and-cleanup","/docs/zh/api/authentication-and-inputs","/docs/zh/api/errors-and-retries","/docs/zh/api/examples","/docs/zh/api/polling-and-downloads","/docs/zh/api/quickstart","/docs/zh/editing-and-export/advanced-editor","/docs/zh/editing-and-export/canvas-and-pivot","/docs/zh/editing-and-export/cocos-creator","/docs/zh/editing-and-export/godot","/docs/zh/editing-and-export/output-formats","/docs/zh/editing-and-export/transparent-formats","/docs/zh/editing-and-export/trim-and-export","/docs/zh/editing-and-export/unity","/docs/zh/editing-and-export/unreal-paper2d","/docs/zh/getting-started/first-animation","/docs/zh/getting-started/overview","/docs/zh/getting-started/workspaces-and-assets","/docs/zh/mcp/connect-clients","/docs/zh/mcp/quickstart","/docs/zh/mcp/spending-safeguards","/docs/zh/mcp/standard-workflow","/docs/zh/reference/ai-and-search","/docs/zh/studio/first-and-last-frames","/docs/zh/studio/input-canvas","/docs/zh/studio/input-modes","/docs/zh/studio/models-and-prompts","/docs/zh/studio/reference-images","/docs/zh/studio/transparent-animation","/docs/zh/studio/video-import","/docs/zh/troubleshooting/api-and-mcp","/docs/zh/troubleshooting/export-and-transparency","/docs/zh/troubleshooting/faq","/docs/zh/troubleshooting/generation-and-uploads"]},"documents":[{"id":"docs.home","locale":"en","title":"AnimGen documentation","description":"Learn to create, export, and integrate animation assets with the Studio, Public API, and live MCP tools.","section":"getting-started","path":"/docs/en","url":"https://animgen.com/docs/en","status":"stable","lastVerified":"2026-08-31","audience":["user","api-developer","ai-agent"],"productAreas":["documentation"],"tags":["start","animation","documentation"],"translations":{"en":"https://animgen.com/docs/en","zh":"https://animgen.com/docs/zh"},"headings":[{"id":"start-with-a-workflow","title":"Start with a workflow","level":2},{"id":"what-is-available","title":"What is available","level":2},{"id":"how-to-use-these-docs","title":"How to use these docs","level":2},{"id":"learn-by-the-task-you-need-to-finish","title":"Learn by the task you need to finish","level":2}],"text":"Start with a workflow\nAnimGen 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.\nStart with the product overview to understand the difference between generation and export. Try the interactive demo to explore the workflow before creating a real task.\nWhat is available\nEntry point\nCurrent status\nStart here\nWeb Studio\nAvailable\nCreate your first animation\nPublic API\nPublic beta; verified account and API key required\nQuote, create, poll, and download\nOfficial remote MCP\nPublic beta; OAuth and verified account required\nConnect an AI client\nThe 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.\nHow to use these docs\nUse 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.\nOpen local search with Ctrl+K / ⌘K. To let an AI find the same reviewed content, start with llms.txt. See search, AI entry points, and feedback privacy for details.\nFor billing and plan availability, see Pricing. For account-specific help, contact support without including keys, tokens, or signed download links.\nLearn by the task you need to finish\nYour task\nGuides\nChoose source material and a workflow\nInput modes · Models and prompts\nControl transitions and appearance\nFirst and last frames · References · Input canvas\nFine-tune existing motion\nImport video · Advanced Editor · Canvas and pivot\nDeliver to a game or video pipeline\nFormats and engine guides · Transparent compatibility\nOrganize your account\nWorkspaces and assets · Account security · Storage cleanup\nLet AI use the tools\nMCP client setup · Calling workflow"},{"id":"account-and-billing.account-security","locale":"en","title":"Manage your account and connected access","description":"Review verification, subscription, credits, API keys, and MCP grants separately, and revoke unused access without exposing secrets.","section":"account-and-billing","path":"/docs/en/account-and-billing/account-security","url":"https://animgen.com/docs/en/account-and-billing/account-security","status":"stable","lastVerified":"2026-08-30","audience":["user","api-developer","ai-agent"],"productAreas":["account"],"tags":["account","OAuth","API key","revoke","账户","授权","订阅"],"translations":{"en":"https://animgen.com/docs/en/account-and-billing/account-security","zh":"https://animgen.com/docs/zh/account-and-billing/account-security"},"headings":[{"id":"check-the-account-actually-being-used","title":"Check the account actually being used","level":2},{"id":"review-billing-without-confusing-cancellation-and-deletion","title":"Review billing without confusing cancellation and deletion","level":2},{"id":"api-keys-belong-in-trusted-environments","title":"API keys belong in trusted environments","level":2},{"id":"mcp-uses-oauth-grants-not-copied-api-keys","title":"MCP uses OAuth grants, not copied API keys","level":2},{"id":"if-access-looks-compromised","title":"If access looks compromised","level":2}],"text":"Check the account actually being used\nOpen Account Center 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.\nIf 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.\nAccount verification, active subscription, export entitlement, and available credits are separate checks. See credits and access.\nReview billing without confusing cancellation and deletion\nAccount Center shows the current subscription and billing-period information. Use its subscription-management link when available for that billing provider.\nA 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.\nBefore reducing a plan, inspect stored usage and download important assets. Do not rely on the website as your only backup.\nAPI keys belong in trusted environments\nCreate and manage keys in Account → Developer. Give each integration the minimum scopes it needs, store its secret outside client-side bundles, and revoke unused or exposed keys.\nNever 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.\nAfter 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.\nMCP uses OAuth grants, not copied API keys\nThe official remote MCP is available in public beta. Connect through its client setup guide and review the requested scopes on the AnimGen authorization page.\nIn 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.\nAuthorization grants capabilities; it does not approve every future charge. Require a concrete request, quote, and approval before paid generation.\nIf access looks compromised\nStop 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.\nContact support 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."},{"id":"account-and-billing.credits-and-access","locale":"en","title":"Credits and access requirements","description":"Understand quotes, credit balance, web export entitlement, and verified-account requirements for developer access.","section":"account-and-billing","path":"/docs/en/account-and-billing/credits-and-access","url":"https://animgen.com/docs/en/account-and-billing/credits-and-access","status":"stable","lastVerified":"2026-08-31","audience":["user","api-developer"],"productAreas":["account","billing"],"tags":["credits","subscription","API key","entitlement"],"translations":{"en":"https://animgen.com/docs/en/account-and-billing/credits-and-access","zh":"https://animgen.com/docs/zh/account-and-billing/credits-and-access"},"headings":[{"id":"three-checks-not-one","title":"Three checks, not one","level":2},{"id":"web-access","title":"Web access","level":2},{"id":"public-api-access","title":"Public API access","level":2},{"id":"quote-before-starting","title":"Quote before starting","level":2},{"id":"cancellation-and-existing-assets","title":"Cancellation and existing assets","level":2},{"id":"mcp-access-and-account-management","title":"MCP access and account management","level":2}],"text":"Three checks, not one\nA 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.\nWeb access\nNew 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.\nAn 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 and your account for the applicable terms and balance.\nCredit 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.\nPublic API access\nThe Public API is in public beta and requires a verified account. Create keys in Account → Developer, use only the scopes required by the caller, and revoke unused keys. Registered access receives baseline limits; active subscriptions raise them.\nCredits 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.\nQuote before starting\nGeneration 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.\nA 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 for approved tool calls.\nCancellation and existing assets\nConfirmed 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.\nValid 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.\nCancellation 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.\nWhen 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.\nFor 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.\nMCP access and account management\nMCP is live in public beta and requires a verified account. It uses OAuth, not an API key. Follow client setup; authorization does not approve spending, and subscriptions only raise account limits.\nSee account management for verification, cancellation timing, and revocation, and storage cleanup for resource usage and deletion behavior."},{"id":"account-and-billing.storage-and-cleanup","locale":"en","title":"Storage, downloads, and safe cleanup","description":"Understand what counts toward storage, why deleting history does not free files, and how to remove resources without breaking active work or saved edits.","section":"account-and-billing","path":"/docs/en/account-and-billing/storage-and-cleanup","url":"https://animgen.com/docs/en/account-and-billing/storage-and-cleanup","status":"stable","lastVerified":"2026-08-30","audience":["user","api-developer","ai-agent"],"productAreas":["account","resources"],"tags":["storage","quota","STORAGE_QUOTA_EXCEEDED","RESOURCE_IN_USE","存储","删除","清理"],"translations":{"en":"https://animgen.com/docs/en/account-and-billing/storage-and-cleanup","zh":"https://animgen.com/docs/zh/account-and-billing/storage-and-cleanup"},"headings":[{"id":"read-usage-in-account-center","title":"Read usage in Account Center","level":2},{"id":"know-what-each-delete-action-does","title":"Know what each delete action does","level":2},{"id":"a-safe-cleanup-sequence","title":"A safe cleanup sequence","level":2},{"id":"temporary-urls-are-not-backups","title":"Temporary URLs are not backups","level":2},{"id":"when-usage-or-downloads-look-wrong","title":"When usage or downloads look wrong","level":2}],"text":"Read usage in Account Center\nAccount Center 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.\nQuota 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.\nAn 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.\nKnow what each delete action does\nAction\nWhat happens to storage and dependencies\nDelete a task/history entry\nHides that job; does not delete its uploaded sources and output files\nDelete a workspace\nHides the workspace and requests cancellation; retained files still count\nRestore a workspace\nRestores access to retained contents, not individually deleted files\nDelete a resource/asset\nRemoves its resource record from active use and attempts to delete stored bytes\nCancel a running task\nBest-effort stop; does not itself clean up every retained resource\nDo not clear a whole workspace just to free space. Restore a hidden workspace if necessary, then review actual resources.\nA safe cleanup sequence\nDownload important files and their matching metadata. Verify the local copies open.\nIdentify large or duplicate resources in the correct workspace.\nWait for active generation/export to finish, or deliberately cancel it and wait for a terminal state.\nCheck whether saved editor compositions or future exports still need the source video.\nDelete only the specific resources you no longer need, then refresh usage.\nRESOURCE_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.\nResource 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.\nTemporary URLs are not backups\nA 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.\nNo 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.\nWhen usage or downloads look wrong\nRefresh 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.\nFor 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.\nSee workspaces and assets and export troubleshooting."},{"id":"api-reference.index","locale":"en","title":"API reference","description":"Generated reference for every public API operation, with scopes, idempotency, asynchronous responses, errors, and schemas.","section":"api-reference","path":"/docs/en/api-reference","url":"https://animgen.com/docs/en/api-reference","status":"beta","lastVerified":"2026-08-30","apiVersion":"1.3.0","audience":["api-developer","ai-agent"],"productAreas":["public-api"],"tags":["reference","API","index"],"translations":{"en":"https://animgen.com/docs/en/api-reference","zh":"https://animgen.com/docs/zh/api-reference"},"headings":[{"id":"public-api-contract","title":"Public API contract","level":2},{"id":"operations","title":"Operations","level":2}],"text":"Generated from the backend contract. Field names, required flags, constraints, and defaults come from source models. Download the machine-readable source. Examples use placeholder IDs and illustrative values, not live prices, limits, or model availability.\nPublic API contract\nBase URL: https://api.animgen.com/v1. Public beta; a verified AnimGen account is required and subscriptions raise limits. Start with the quickstart.\nOperations\nMethod\nPath\nReference\nGET\n/account\nGet account and limits\nGET\n/animation-exports\nList animation export tasks\nPOST\n/animation-exports\nCreate animation export\nPOST\n/animation-exports/quote\nQuote animation export\nGET\n/animation-exports/{job_id}\nGet animation export\nPOST\n/animation-exports/{job_id}/cancel\nCancel animation export\nGET\n/animations\nList animation tasks\nPOST\n/animations\nCreate animation\nPOST\n/animations/quote\nQuote animation\nGET\n/animations/{animation_id}\nGet animation\nPOST\n/animations/{animation_id}/cancel\nCancel animation\nGET\n/assets/{asset_id}\nGet asset download metadata\nGET\n/assets/{asset_id}/content\nDownload signed asset\nGET\n/credits/balance\nGet credit balance\nPOST\n/files\nUpload image\nGET\n/models\nList model capabilities\nGET\n/video-generations\nList video generation tasks\nPOST\n/video-generations\nCreate video generation\nPOST\n/video-generations/quote\nQuote video generation\nGET\n/video-generations/{job_id}\nGet video generation\nPOST\n/video-generations/{job_id}/cancel\nCancel video generation\nShared schemas"},{"id":"api-reference.cancel-animation-exports","locale":"en","title":"Cancel animation export","description":"Source-generated POST /animation-exports/{job_id}/cancel reference: authentication, fields, responses, errors, and operational safeguards.","section":"api-reference","path":"/docs/en/api-reference/cancel-animation-exports","url":"https://animgen.com/docs/en/api-reference/cancel-animation-exports","status":"beta","lastVerified":"2026-08-30","apiVersion":"1.3.0","audience":["api-developer","ai-agent"],"productAreas":["public-api"],"tags":["reference","API","cancel-animation-exports"],"translations":{"en":"https://animgen.com/docs/en/api-reference/cancel-animation-exports","zh":"https://animgen.com/docs/zh/api-reference/cancel-animation-exports"},"headings":[{"id":"operation","title":"Operation","level":2},{"id":"authentication-and-side-effects","title":"Authentication and side effects","level":2},{"id":"parameters","title":"Parameters","level":2},{"id":"responses","title":"Responses","level":2},{"id":"response-headers","title":"Response headers","level":3},{"id":"response-example","title":"Response example","level":3},{"id":"related-guides","title":"Related guides","level":2}],"text":"Generated from the backend contract. Field names, required flags, constraints, and defaults come from source models. Download the machine-readable source. Examples use placeholder IDs and illustrative values, not live prices, limits, or model availability.\nOperation\nPOST /animation-exports/{job_id}/cancel\noperationId: cancel_animation_export_v1_animation_exports__job_id__cancel_post\nRequest best-effort cancellation of an owned task. The result may still be nonterminal; continue polling. Completed work can remain charged, unspent holds may be released, and earlier outputs may survive. Do not promise a full refund.\nAuthentication and side effects\nUse a server-side Bearer API key. Required scope: animations:write\nThis operation does not start paid generation. Other state changes are described above.\nParameters\nParameter\nLocation\nType\nRequired\nConstraints / default\nMeaning\njob_id\npath\nstring\nYes\nformat: uuid\nOwned public resource UUID; task, asset, and file IDs are not interchangeable.\nResponses\nHTTP\nBody\nMeaning\n200\nTaskResponse\nSuccessful public response. Example values are illustrative.\n400\nAPIErrorEnvelope\nInvalid input; correct the request before retrying.\n401\nAPIErrorEnvelope\nMissing, expired, or revoked API key.\n403\nAPIErrorEnvelope\nAccount eligibility, account status, or key scope does not allow this operation.\n404\nAPIErrorEnvelope\nResource is unavailable, not owned, or its signature is invalid/expired.\n429\nAPIErrorEnvelope\nAccount-wide rate or queue limit; wait for Retry-After.\n500\nAPIErrorEnvelope\nInternal failure; preserve the task/key and retry only when marked retryable.\n503\nAPIErrorEnvelope\nService/provider unavailable; retry only when error.retryable is true.\nResponse headers\nHTTP\nHeader\nType\nMeaning\n429\nRetry-After\ninteger\nSuggested wait in seconds; respect the server value and an overall deadline.\n503\nRetry-After\ninteger\nSuggested wait in seconds; respect the server value and an overall deadline.\nResponse example\nRelated guides\nPolling and downloads · Errors and safe retries"},{"id":"api-reference.cancel-animations","locale":"en","title":"Cancel animation","description":"Source-generated POST /animations/{animation_id}/cancel reference: authentication, fields, responses, errors, and operational safeguards.","section":"api-reference","path":"/docs/en/api-reference/cancel-animations","url":"https://animgen.com/docs/en/api-reference/cancel-animations","status":"beta","lastVerified":"2026-08-30","apiVersion":"1.3.0","audience":["api-developer","ai-agent"],"productAreas":["public-api"],"tags":["reference","API","cancel-animations"],"translations":{"en":"https://animgen.com/docs/en/api-reference/cancel-animations","zh":"https://animgen.com/docs/zh/api-reference/cancel-animations"},"headings":[{"id":"operation","title":"Operation","level":2},{"id":"authentication-and-side-effects","title":"Authentication and side effects","level":2},{"id":"parameters","title":"Parameters","level":2},{"id":"responses","title":"Responses","level":2},{"id":"response-headers","title":"Response headers","level":3},{"id":"response-example","title":"Response example","level":3},{"id":"related-guides","title":"Related guides","level":2}],"text":"Generated from the backend contract. Field names, required flags, constraints, and defaults come from source models. Download the machine-readable source. Examples use placeholder IDs and illustrative values, not live prices, limits, or model availability.\nOperation\nPOST /animations/{animation_id}/cancel\noperationId: cancel_one_click_animation_v1_animations__animation_id__cancel_post\nRequest best-effort cancellation of an owned task. The result may still be nonterminal; continue polling. Completed work can remain charged, unspent holds may be released, and earlier outputs may survive. Do not promise a full refund.\nAuthentication and side effects\nUse a server-side Bearer API key. Required scope: animations:write\nThis operation does not start paid generation. Other state changes are described above.\nParameters\nParameter\nLocation\nType\nRequired\nConstraints / default\nMeaning\nanimation_id\npath\nstring\nYes\nformat: uuid\nOwned public resource UUID; task, asset, and file IDs are not interchangeable.\nResponses\nHTTP\nBody\nMeaning\n200\nTaskResponse\nSuccessful public response. Example values are illustrative.\n400\nAPIErrorEnvelope\nInvalid input; correct the request before retrying.\n401\nAPIErrorEnvelope\nMissing, expired, or revoked API key.\n403\nAPIErrorEnvelope\nAccount eligibility, account status, or key scope does not allow this operation.\n404\nAPIErrorEnvelope\nResource is unavailable, not owned, or its signature is invalid/expired.\n429\nAPIErrorEnvelope\nAccount-wide rate or queue limit; wait for Retry-After.\n500\nAPIErrorEnvelope\nInternal failure; preserve the task/key and retry only when marked retryable.\n503\nAPIErrorEnvelope\nService/provider unavailable; retry only when error.retryable is true.\nResponse headers\nHTTP\nHeader\nType\nMeaning\n429\nRetry-After\ninteger\nSuggested wait in seconds; respect the server value and an overall deadline.\n503\nRetry-After\ninteger\nSuggested wait in seconds; respect the server value and an overall deadline.\nResponse example\nRelated guides\nPolling and downloads · Errors and safe retries"},{"id":"api-reference.cancel-video-generations","locale":"en","title":"Cancel video generation","description":"Source-generated POST /video-generations/{job_id}/cancel reference: authentication, fields, responses, errors, and operational safeguards.","section":"api-reference","path":"/docs/en/api-reference/cancel-video-generations","url":"https://animgen.com/docs/en/api-reference/cancel-video-generations","status":"beta","lastVerified":"2026-08-30","apiVersion":"1.3.0","audience":["api-developer","ai-agent"],"productAreas":["public-api"],"tags":["reference","API","cancel-video-generations"],"translations":{"en":"https://animgen.com/docs/en/api-reference/cancel-video-generations","zh":"https://animgen.com/docs/zh/api-reference/cancel-video-generations"},"headings":[{"id":"operation","title":"Operation","level":2},{"id":"authentication-and-side-effects","title":"Authentication and side effects","level":2},{"id":"parameters","title":"Parameters","level":2},{"id":"responses","title":"Responses","level":2},{"id":"response-headers","title":"Response headers","level":3},{"id":"response-example","title":"Response example","level":3},{"id":"related-guides","title":"Related guides","level":2}],"text":"Generated from the backend contract. Field names, required flags, constraints, and defaults come from source models. Download the machine-readable source. Examples use placeholder IDs and illustrative values, not live prices, limits, or model availability.\nOperation\nPOST /video-generations/{job_id}/cancel\noperationId: cancel_video_generation_v1_video_generations__job_id__cancel_post\nRequest best-effort cancellation of an owned task. The result may still be nonterminal; continue polling. Completed work can remain charged, unspent holds may be released, and earlier outputs may survive. Do not promise a full refund.\nAuthentication and side effects\nUse a server-side Bearer API key. Required scope: animations:write\nThis operation does not start paid generation. Other state changes are described above.\nParameters\nParameter\nLocation\nType\nRequired\nConstraints / default\nMeaning\njob_id\npath\nstring\nYes\nformat: uuid\nOwned public resource UUID; task, asset, and file IDs are not interchangeable.\nResponses\nHTTP\nBody\nMeaning\n200\nTaskResponse\nSuccessful public response. Example values are illustrative.\n400\nAPIErrorEnvelope\nInvalid input; correct the request before retrying.\n401\nAPIErrorEnvelope\nMissing, expired, or revoked API key.\n403\nAPIErrorEnvelope\nAccount eligibility, account status, or key scope does not allow this operation.\n404\nAPIErrorEnvelope\nResource is unavailable, not owned, or its signature is invalid/expired.\n429\nAPIErrorEnvelope\nAccount-wide rate or queue limit; wait for Retry-After.\n500\nAPIErrorEnvelope\nInternal failure; preserve the task/key and retry only when marked retryable.\n503\nAPIErrorEnvelope\nService/provider unavailable; retry only when error.retryable is true.\nResponse headers\nHTTP\nHeader\nType\nMeaning\n429\nRetry-After\ninteger\nSuggested wait in seconds; respect the server value and an overall deadline.\n503\nRetry-After\ninteger\nSuggested wait in seconds; respect the server value and an overall deadline.\nResponse example\nRelated guides\nPolling and downloads · Errors and safe retries"},{"id":"api-reference.create-animation-exports","locale":"en","title":"Create animation export","description":"Source-generated POST /animation-exports reference: authentication, fields, responses, errors, and operational safeguards.","section":"api-reference","path":"/docs/en/api-reference/create-animation-exports","url":"https://animgen.com/docs/en/api-reference/create-animation-exports","status":"beta","lastVerified":"2026-08-30","apiVersion":"1.3.0","audience":["api-developer","ai-agent"],"productAreas":["public-api"],"tags":["reference","API","create-animation-exports"],"translations":{"en":"https://animgen.com/docs/en/api-reference/create-animation-exports","zh":"https://animgen.com/docs/zh/api-reference/create-animation-exports"},"headings":[{"id":"operation","title":"Operation","level":2},{"id":"authentication-and-side-effects","title":"Authentication and side effects","level":2},{"id":"parameters","title":"Parameters","level":2},{"id":"request-body-application-json","title":"Request body (application/json)","level":2},{"id":"request-example","title":"Request example","level":3},{"id":"responses","title":"Responses","level":2},{"id":"response-headers","title":"Response headers","level":3},{"id":"response-example","title":"Response example","level":3},{"id":"related-guides","title":"Related guides","level":2}],"text":"Generated from the backend contract. Field names, required flags, constraints, and defaults come from source models. Download the machine-readable source. Examples use placeholder IDs and illustrative values, not live prices, limits, or model availability.\nOperation\nPOST /animation-exports\noperationId: create_animation_export_v1_animation_exports_post\nStart a paid asynchronous task. Quote first and obtain user approval. Persist the returned ID; 202 means accepted, not complete. Reuse the same Idempotency-Key, credential identity, and unchanged request after an uncertain response. Creation recalculates price; Public API quotes do not lock it and max_credits/quote_id are not API request fields. Poll using Retry-After and inspect outputs at every terminal state, including failure.\nAuthentication and side effects\nUse a server-side Bearer API key. Required scope: animations:write\nThis creates paid work. Obtain approval before submission. API quotes do not lock a price or enforce a maximum budget.\nParameters\nParameter\nLocation\nType\nRequired\nConstraints / default\nMeaning\nIdempotency-Key\nheader\nstring\nYes\nminLength: 8; maxLength: 200\nPersist once per logical operation; reuse with the same credential and unchanged body. Changing credentials changes the deduplication scope.\nRequest body (application/json)\nBody required: true\nField\nType\nRequired\nDefault\nConstraints\nMeaning\nexport\nExportOptions\nNo\n{\"frame_count\":24,\"output_formats\":[\"spritesheet\"],\"output_height\":512,\"output_width\":512,\"transparent\":{\"enabled\":false},\"unity\":{\"pivot\":\"bottom_center\",\"pixels_per_unit\":100}}\n—\nOutput formats and processing settings.\nmetadata\nobject\nNo\n{}\n—\nSimple scalar/null metadata; at most 4 KiB JSON, no credentials.\nselection\nSelection\nNo\n{\"duration_seconds\":null,\"mode\":\"full\",\"start_seconds\":0}\n—\nSource interval to export.\nsource_video_asset_id\nstring\nYes\n—\nformat: uuid\nOwned source video asset ID, not a task ID. Reuse an existing video to avoid generating motion again.\nFull nested schema: AnimationExportCreateRequest\nRequest example\nResponses\nHTTP\nBody\nMeaning\n202\nTaskResponse\nAccepted asynchronously; poll the task ID.\n400\nAPIErrorEnvelope\nInvalid input; correct the request before retrying.\n401\nAPIErrorEnvelope\nMissing, expired, or revoked API key.\n402\nAPIErrorEnvelope\nInsufficient credits; do not automatically purchase.\n403\nAPIErrorEnvelope\nAccount eligibility, account status, or key scope does not allow this operation.\n404\nAPIErrorEnvelope\nResource is unavailable, not owned, or its signature is invalid/expired.\n409\nAPIErrorEnvelope\nIdempotency conflict; only IDEMPOTENCY_IN_PROGRESS is retryable with the original request.\n413\nAPIErrorEnvelope\nRequest or decoded image exceeds the configured limit.\n415\nAPIErrorEnvelope\nUse supported image media types.\n422\nAPIErrorEnvelope\nDecoded image dimensions exceed the allowed size.\n429\nAPIErrorEnvelope\nAccount-wide rate or queue limit; wait for Retry-After.\n500\nAPIErrorEnvelope\nInternal failure; preserve the task/key and retry only when marked retryable.\n503\nAPIErrorEnvelope\nService/provider unavailable; retry only when error.retryable is true.\nResponse headers\nHTTP\nHeader\nType\nMeaning\n202\nRetry-After\ninteger\nSuggested wait in seconds; respect the server value and an overall deadline.\n429\nRetry-After\ninteger\nSuggested wait in seconds; respect the server value and an overall deadline.\n503\nRetry-After\ninteger\nSuggested wait in seconds; respect the server value and an overall deadline.\nResponse example\nRelated guides\nPolling and downloads · Errors and safe retries"},{"id":"api-reference.create-animations","locale":"en","title":"Create animation","description":"Source-generated POST /animations reference: authentication, fields, responses, errors, and operational safeguards.","section":"api-reference","path":"/docs/en/api-reference/create-animations","url":"https://animgen.com/docs/en/api-reference/create-animations","status":"beta","lastVerified":"2026-08-30","apiVersion":"1.3.0","audience":["api-developer","ai-agent"],"productAreas":["public-api"],"tags":["reference","API","create-animations"],"translations":{"en":"https://animgen.com/docs/en/api-reference/create-animations","zh":"https://animgen.com/docs/zh/api-reference/create-animations"},"headings":[{"id":"operation","title":"Operation","level":2},{"id":"authentication-and-side-effects","title":"Authentication and side effects","level":2},{"id":"parameters","title":"Parameters","level":2},{"id":"request-body-application-json","title":"Request body (application/json)","level":2},{"id":"request-example","title":"Request example","level":3},{"id":"responses","title":"Responses","level":2},{"id":"response-headers","title":"Response headers","level":3},{"id":"response-example","title":"Response example","level":3},{"id":"related-guides","title":"Related guides","level":2}],"text":"Generated from the backend contract. Field names, required flags, constraints, and defaults come from source models. Download the machine-readable source. Examples use placeholder IDs and illustrative values, not live prices, limits, or model availability.\nOperation\nPOST /animations\noperationId: create_one_click_animation_v1_animations_post\nStart a paid asynchronous task. Quote first and obtain user approval. Persist the returned ID; 202 means accepted, not complete. Reuse the same Idempotency-Key, credential identity, and unchanged request after an uncertain response. Creation recalculates price; Public API quotes do not lock it and max_credits/quote_id are not API request fields. Poll using Retry-After and inspect outputs at every terminal state, including failure.\nAuthentication and side effects\nUse a server-side Bearer API key. Required scope: animations:write\nThis creates paid work. Obtain approval before submission. API quotes do not lock a price or enforce a maximum budget.\nParameters\nParameter\nLocation\nType\nRequired\nConstraints / default\nMeaning\nIdempotency-Key\nheader\nstring\nYes\nminLength: 8; maxLength: 200\nPersist once per logical operation; reuse with the same credential and unchanged body. Changing credentials changes the deduplication scope.\nRequest body (application/json)\nBody required: true\nField\nType\nRequired\nDefault\nConstraints\nMeaning\nexport\nExportOptions\nNo\n{\"frame_count\":24,\"output_formats\":[\"spritesheet\"],\"output_height\":512,\"output_width\":512,\"transparent\":{\"enabled\":false},\"unity\":{\"pivot\":\"bottom_center\",\"pixels_per_unit\":100}}\n—\nExport after video generation. Alpha-bearing formats require an alpha_key source; compatible formats automatically enable its transparent export.\ninput\nGenerationInput\nYes\n—\n—\nImages owned by the caller or supplied for this generation.\nmetadata\nobject\nNo\n{}\n—\nCaller metadata: simple string/number/boolean/null values, at most 4 KiB JSON. Do not store secrets.\nnegative_prompt\nstring\nNo\n\"\"\nmaxLength: 4000\nOptional exclusions, only when the model supports negative prompts.\nprompt\nstring\nNo\n\"\"\nmaxLength: 8000\nMotion instruction; nonempty when the model requires a prompt. Keep private prompts out of logs.\nselection\nSelection\nNo\n{\"duration_seconds\":null,\"mode\":\"full\",\"start_seconds\":0}\n—\nInterval selected after generation; full by default.\nvideo\nVideoOptions\nNo\n{\"duration_seconds\":null,\"input_canvas\":null,\"model\":null,\"ratio\":null,\"resolution\":null,\"seed\":null,\"style_preset\":null,\"transparency\":{\"key_color\":null,\"key_selection\":\"auto\",\"mode\":\"standard\"},\"watermark\":null}\n—\nModel-compatible generation settings.\nFull nested schema: AnimationCreateRequest\nRequest example\nResponses\nHTTP\nBody\nMeaning\n202\nTaskResponse\nAccepted asynchronously; poll the task ID.\n400\nAPIErrorEnvelope\nInvalid input; correct the request before retrying.\n401\nAPIErrorEnvelope\nMissing, expired, or revoked API key.\n402\nAPIErrorEnvelope\nInsufficient credits; do not automatically purchase.\n403\nAPIErrorEnvelope\nAccount eligibility, account status, or key scope does not allow this operation.\n404\nAPIErrorEnvelope\nResource is unavailable, not owned, or its signature is invalid/expired.\n409\nAPIErrorEnvelope\nIdempotency conflict; only IDEMPOTENCY_IN_PROGRESS is retryable with the original request.\n413\nAPIErrorEnvelope\nRequest or decoded image exceeds the configured limit.\n415\nAPIErrorEnvelope\nUse supported image media types.\n422\nAPIErrorEnvelope\nDecoded image dimensions exceed the allowed size.\n429\nAPIErrorEnvelope\nAccount-wide rate or queue limit; wait for Retry-After.\n500\nAPIErrorEnvelope\nInternal failure; preserve the task/key and retry only when marked retryable.\n503\nAPIErrorEnvelope\nService/provider unavailable; retry only when error.retryable is true.\nResponse headers\nHTTP\nHeader\nType\nMeaning\n202\nRetry-After\ninteger\nSuggested wait in seconds; respect the server value and an overall deadline.\n429\nRetry-After\ninteger\nSuggested wait in seconds; respect the server value and an overall deadline.\n503\nRetry-After\ninteger\nSuggested wait in seconds; respect the server value and an overall deadline.\nResponse example\nRelated guides\nPolling and downloads · Errors and safe retries"},{"id":"api-reference.create-video-generations","locale":"en","title":"Create video generation","description":"Source-generated POST /video-generations reference: authentication, fields, responses, errors, and operational safeguards.","section":"api-reference","path":"/docs/en/api-reference/create-video-generations","url":"https://animgen.com/docs/en/api-reference/create-video-generations","status":"beta","lastVerified":"2026-08-30","apiVersion":"1.3.0","audience":["api-developer","ai-agent"],"productAreas":["public-api"],"tags":["reference","API","create-video-generations"],"translations":{"en":"https://animgen.com/docs/en/api-reference/create-video-generations","zh":"https://animgen.com/docs/zh/api-reference/create-video-generations"},"headings":[{"id":"operation","title":"Operation","level":2},{"id":"authentication-and-side-effects","title":"Authentication and side effects","level":2},{"id":"parameters","title":"Parameters","level":2},{"id":"request-body-application-json","title":"Request body (application/json)","level":2},{"id":"request-example","title":"Request example","level":3},{"id":"responses","title":"Responses","level":2},{"id":"response-headers","title":"Response headers","level":3},{"id":"response-example","title":"Response example","level":3},{"id":"related-guides","title":"Related guides","level":2}],"text":"Generated from the backend contract. Field names, required flags, constraints, and defaults come from source models. Download the machine-readable source. Examples use placeholder IDs and illustrative values, not live prices, limits, or model availability.\nOperation\nPOST /video-generations\noperationId: create_video_generation_v1_video_generations_post\nStart a paid asynchronous task. Quote first and obtain user approval. Persist the returned ID; 202 means accepted, not complete. Reuse the same Idempotency-Key, credential identity, and unchanged request after an uncertain response. Creation recalculates price; Public API quotes do not lock it and max_credits/quote_id are not API request fields. Poll using Retry-After and inspect outputs at every terminal state, including failure.\nAuthentication and side effects\nUse a server-side Bearer API key. Required scope: animations:write\nThis creates paid work. Obtain approval before submission. API quotes do not lock a price or enforce a maximum budget.\nParameters\nParameter\nLocation\nType\nRequired\nConstraints / default\nMeaning\nIdempotency-Key\nheader\nstring\nYes\nminLength: 8; maxLength: 200\nPersist once per logical operation; reuse with the same credential and unchanged body. Changing credentials changes the deduplication scope.\nRequest body (application/json)\nBody required: true\nField\nType\nRequired\nDefault\nConstraints\nMeaning\ninput\nGenerationInput\nYes\n—\n—\nImages owned by the caller or supplied for this generation.\nmetadata\nobject\nNo\n{}\n—\nCaller metadata: simple string/number/boolean/null values, at most 4 KiB JSON. Do not store secrets.\nnegative_prompt\nstring\nNo\n\"\"\nmaxLength: 4000\nOptional exclusions, only when the model supports negative prompts.\nprompt\nstring\nNo\n\"\"\nmaxLength: 8000\nMotion instruction; nonempty when the model requires a prompt. Keep private prompts out of logs.\nvideo\nVideoOptions\nNo\n{\"duration_seconds\":null,\"input_canvas\":null,\"model\":null,\"ratio\":null,\"resolution\":null,\"seed\":null,\"style_preset\":null,\"transparency\":{\"key_color\":null,\"key_selection\":\"auto\",\"mode\":\"standard\"},\"watermark\":null}\n—\nModel-compatible generation settings.\nFull nested schema: VideoGenerationCreateRequest\nRequest example\nResponses\nHTTP\nBody\nMeaning\n202\nTaskResponse\nAccepted asynchronously; poll the task ID.\n400\nAPIErrorEnvelope\nInvalid input; correct the request before retrying.\n401\nAPIErrorEnvelope\nMissing, expired, or revoked API key.\n402\nAPIErrorEnvelope\nInsufficient credits; do not automatically purchase.\n403\nAPIErrorEnvelope\nAccount eligibility, account status, or key scope does not allow this operation.\n404\nAPIErrorEnvelope\nResource is unavailable, not owned, or its signature is invalid/expired.\n409\nAPIErrorEnvelope\nIdempotency conflict; only IDEMPOTENCY_IN_PROGRESS is retryable with the original request.\n413\nAPIErrorEnvelope\nRequest or decoded image exceeds the configured limit.\n415\nAPIErrorEnvelope\nUse supported image media types.\n422\nAPIErrorEnvelope\nDecoded image dimensions exceed the allowed size.\n429\nAPIErrorEnvelope\nAccount-wide rate or queue limit; wait for Retry-After.\n500\nAPIErrorEnvelope\nInternal failure; preserve the task/key and retry only when marked retryable.\n503\nAPIErrorEnvelope\nService/provider unavailable; retry only when error.retryable is true.\nResponse headers\nHTTP\nHeader\nType\nMeaning\n202\nRetry-After\ninteger\nSuggested wait in seconds; respect the server value and an overall deadline.\n429\nRetry-After\ninteger\nSuggested wait in seconds; respect the server value and an overall deadline.\n503\nRetry-After\ninteger\nSuggested wait in seconds; respect the server value and an overall deadline.\nResponse example\nRelated guides\nPolling and downloads · Errors and safe retries"},{"id":"api-reference.download-asset","locale":"en","title":"Download signed asset","description":"Source-generated GET /assets/{asset_id}/content reference: authentication, fields, responses, errors, and operational safeguards.","section":"api-reference","path":"/docs/en/api-reference/download-asset","url":"https://animgen.com/docs/en/api-reference/download-asset","status":"beta","lastVerified":"2026-08-30","apiVersion":"1.3.0","audience":["api-developer","ai-agent"],"productAreas":["public-api"],"tags":["reference","API","download-asset"],"translations":{"en":"https://animgen.com/docs/en/api-reference/download-asset","zh":"https://animgen.com/docs/zh/api-reference/download-asset"},"headings":[{"id":"operation","title":"Operation","level":2},{"id":"authentication-and-side-effects","title":"Authentication and side effects","level":2},{"id":"parameters","title":"Parameters","level":2},{"id":"responses","title":"Responses","level":2},{"id":"response-headers","title":"Response headers","level":3},{"id":"related-guides","title":"Related guides","level":2}],"text":"Generated from the backend contract. Field names, required flags, constraints, and defaults come from source models. Download the machine-readable source. Examples use placeholder IDs and illustrative values, not live prices, limits, or model availability.\nOperation\nGET /assets/{asset_id}/content\noperationId: download_asset_v1_assets__asset_id__content_get\nDownload bytes using the complete signed URL returned in an Asset response. No Bearer header is required or recommended. Do not construct signatures or forward credentials to storage. Depending on delivery mode this returns bytes or a 302 redirect. Expired or invalid signatures appear as NOT_FOUND; refresh metadata through GET /assets/{asset_id}.\nAuthentication and side effects\nUse the complete returned signed URL. Do not attach a Bearer key.\nThis operation does not start paid generation. Other state changes are described above.\nParameters\nParameter\nLocation\nType\nRequired\nConstraints / default\nMeaning\nasset_id\npath\nstring\nYes\nformat: uuid\nOwned public resource UUID; task, asset, and file IDs are not interchangeable.\nexpires\nquery\ninteger\nYes\nexclusiveMinimum: 0\nUse the value in the returned signed URL; never invent or log it.\nsignature\nquery\nstring\nYes\nminLength: 64; maxLength: 64\nUse the value in the returned signed URL; never invent or log it.\nResponses\nHTTP\nBody\nMeaning\n200\nstring\nAsset bytes; Content-Type depends on the asset.\n302\n—\nRedirect to short-lived storage URL; do not forward credentials.\n400\nAPIErrorEnvelope\nInvalid input; correct the request before retrying.\n404\nAPIErrorEnvelope\nResource is unavailable, not owned, or its signature is invalid/expired.\n500\nAPIErrorEnvelope\nInternal failure; preserve the task/key and retry only when marked retryable.\n503\nAPIErrorEnvelope\nService/provider unavailable; retry only when error.retryable is true.\nResponse headers\nHTTP\nHeader\nType\nMeaning\n302\nLocation\nstring\nShort-lived storage download URL.\nRelated guides\nPolling and downloads · Errors and safe retries"},{"id":"api-reference.get-account","locale":"en","title":"Get account and limits","description":"Source-generated GET /account reference: authentication, fields, responses, errors, and operational safeguards.","section":"api-reference","path":"/docs/en/api-reference/get-account","url":"https://animgen.com/docs/en/api-reference/get-account","status":"beta","lastVerified":"2026-08-30","apiVersion":"1.3.0","audience":["api-developer","ai-agent"],"productAreas":["public-api"],"tags":["reference","API","get-account"],"translations":{"en":"https://animgen.com/docs/en/api-reference/get-account","zh":"https://animgen.com/docs/zh/api-reference/get-account"},"headings":[{"id":"operation","title":"Operation","level":2},{"id":"authentication-and-side-effects","title":"Authentication and side effects","level":2},{"id":"parameters","title":"Parameters","level":2},{"id":"responses","title":"Responses","level":2},{"id":"response-headers","title":"Response headers","level":3},{"id":"response-example","title":"Response example","level":3},{"id":"related-guides","title":"Related guides","level":2}],"text":"Generated from the backend contract. Field names, required flags, constraints, and defaults come from source models. Download the machine-readable source. Examples use placeholder IDs and illustrative values, not live prices, limits, or model availability.\nOperation\nGET /account\noperationId: account_v1_account_get\nRead the authenticated account, developer access tier, optional subscription period, key identity/scopes, and account-wide limits. Key secrets are never returned. Subscriptions raise limits but are not required for access. Keep the same key identity when recovering an uncertain idempotent create.\nAuthentication and side effects\nUse a server-side Bearer API key. Required scope: animations:read\nThis operation does not start paid generation. Other state changes are described above.\nParameters\nNo path, query, or operation-specific header parameters.\nResponses\nHTTP\nBody\nMeaning\n200\nAccountResponse\nSuccessful public response. Example values are illustrative.\n400\nAPIErrorEnvelope\nInvalid input; correct the request before retrying.\n401\nAPIErrorEnvelope\nMissing, expired, or revoked API key.\n403\nAPIErrorEnvelope\nAccount eligibility, account status, or key scope does not allow this operation.\n404\nAPIErrorEnvelope\nResource is unavailable, not owned, or its signature is invalid/expired.\n429\nAPIErrorEnvelope\nAccount-wide rate or queue limit; wait for Retry-After.\n500\nAPIErrorEnvelope\nInternal failure; preserve the task/key and retry only when marked retryable.\n503\nAPIErrorEnvelope\nService/provider unavailable; retry only when error.retryable is true.\nResponse headers\nHTTP\nHeader\nType\nMeaning\n429\nRetry-After\ninteger\nSuggested wait in seconds; respect the server value and an overall deadline.\n503\nRetry-After\ninteger\nSuggested wait in seconds; respect the server value and an overall deadline.\nResponse example\nRelated guides\nPolling and downloads · Errors and safe retries"},{"id":"api-reference.get-animation-exports","locale":"en","title":"Get animation export","description":"Source-generated GET /animation-exports/{job_id} reference: authentication, fields, responses, errors, and operational safeguards.","section":"api-reference","path":"/docs/en/api-reference/get-animation-exports","url":"https://animgen.com/docs/en/api-reference/get-animation-exports","status":"beta","lastVerified":"2026-08-30","apiVersion":"1.3.0","audience":["api-developer","ai-agent"],"productAreas":["public-api"],"tags":["reference","API","get-animation-exports"],"translations":{"en":"https://animgen.com/docs/en/api-reference/get-animation-exports","zh":"https://animgen.com/docs/zh/api-reference/get-animation-exports"},"headings":[{"id":"operation","title":"Operation","level":2},{"id":"authentication-and-side-effects","title":"Authentication and side effects","level":2},{"id":"parameters","title":"Parameters","level":2},{"id":"responses","title":"Responses","level":2},{"id":"response-headers","title":"Response headers","level":3},{"id":"response-example","title":"Response example","level":3},{"id":"related-guides","title":"Related guides","level":2}],"text":"Generated from the backend contract. Field names, required flags, constraints, and defaults come from source models. Download the machine-readable source. Examples use placeholder IDs and illustrative values, not live prices, limits, or model availability.\nOperation\nGET /animation-exports/{job_id}\noperationId: get_animation_export_v1_animation_exports__job_id__get\nRead an owned task. Respect Retry-After and use a bounded polling deadline. queued, running, and cancelling are nonterminal; succeeded, failed, and cancelled are terminal. A later-stage failure can leave usable outputs. Progress is not a time estimate.\nAuthentication and side effects\nUse a server-side Bearer API key. Required scope: animations:read\nThis operation does not start paid generation. Other state changes are described above.\nParameters\nParameter\nLocation\nType\nRequired\nConstraints / default\nMeaning\njob_id\npath\nstring\nYes\nformat: uuid\nOwned public resource UUID; task, asset, and file IDs are not interchangeable.\nResponses\nHTTP\nBody\nMeaning\n200\nTaskResponse\nSuccessful public response. Example values are illustrative.\n400\nAPIErrorEnvelope\nInvalid input; correct the request before retrying.\n401\nAPIErrorEnvelope\nMissing, expired, or revoked API key.\n403\nAPIErrorEnvelope\nAccount eligibility, account status, or key scope does not allow this operation.\n404\nAPIErrorEnvelope\nResource is unavailable, not owned, or its signature is invalid/expired.\n429\nAPIErrorEnvelope\nAccount-wide rate or queue limit; wait for Retry-After.\n500\nAPIErrorEnvelope\nInternal failure; preserve the task/key and retry only when marked retryable.\n503\nAPIErrorEnvelope\nService/provider unavailable; retry only when error.retryable is true.\nResponse headers\nHTTP\nHeader\nType\nMeaning\n200\nRetry-After\ninteger\nSuggested wait in seconds; respect the server value and an overall deadline.\n429\nRetry-After\ninteger\nSuggested wait in seconds; respect the server value and an overall deadline.\n503\nRetry-After\ninteger\nSuggested wait in seconds; respect the server value and an overall deadline.\nResponse example\nRelated guides\nPolling and downloads · Errors and safe retries"},{"id":"api-reference.get-animations","locale":"en","title":"Get animation","description":"Source-generated GET /animations/{animation_id} reference: authentication, fields, responses, errors, and operational safeguards.","section":"api-reference","path":"/docs/en/api-reference/get-animations","url":"https://animgen.com/docs/en/api-reference/get-animations","status":"beta","lastVerified":"2026-08-30","apiVersion":"1.3.0","audience":["api-developer","ai-agent"],"productAreas":["public-api"],"tags":["reference","API","get-animations"],"translations":{"en":"https://animgen.com/docs/en/api-reference/get-animations","zh":"https://animgen.com/docs/zh/api-reference/get-animations"},"headings":[{"id":"operation","title":"Operation","level":2},{"id":"authentication-and-side-effects","title":"Authentication and side effects","level":2},{"id":"parameters","title":"Parameters","level":2},{"id":"responses","title":"Responses","level":2},{"id":"response-headers","title":"Response headers","level":3},{"id":"response-example","title":"Response example","level":3},{"id":"related-guides","title":"Related guides","level":2}],"text":"Generated from the backend contract. Field names, required flags, constraints, and defaults come from source models. Download the machine-readable source. Examples use placeholder IDs and illustrative values, not live prices, limits, or model availability.\nOperation\nGET /animations/{animation_id}\noperationId: get_one_click_animation_v1_animations__animation_id__get\nRead an owned task. Respect Retry-After and use a bounded polling deadline. queued, running, and cancelling are nonterminal; succeeded, failed, and cancelled are terminal. A later-stage failure can leave usable outputs. Progress is not a time estimate.\nAuthentication and side effects\nUse a server-side Bearer API key. Required scope: animations:read\nThis operation does not start paid generation. Other state changes are described above.\nParameters\nParameter\nLocation\nType\nRequired\nConstraints / default\nMeaning\nanimation_id\npath\nstring\nYes\nformat: uuid\nOwned public resource UUID; task, asset, and file IDs are not interchangeable.\nResponses\nHTTP\nBody\nMeaning\n200\nTaskResponse\nSuccessful public response. Example values are illustrative.\n400\nAPIErrorEnvelope\nInvalid input; correct the request before retrying.\n401\nAPIErrorEnvelope\nMissing, expired, or revoked API key.\n403\nAPIErrorEnvelope\nAccount eligibility, account status, or key scope does not allow this operation.\n404\nAPIErrorEnvelope\nResource is unavailable, not owned, or its signature is invalid/expired.\n429\nAPIErrorEnvelope\nAccount-wide rate or queue limit; wait for Retry-After.\n500\nAPIErrorEnvelope\nInternal failure; preserve the task/key and retry only when marked retryable.\n503\nAPIErrorEnvelope\nService/provider unavailable; retry only when error.retryable is true.\nResponse headers\nHTTP\nHeader\nType\nMeaning\n200\nRetry-After\ninteger\nSuggested wait in seconds; respect the server value and an overall deadline.\n429\nRetry-After\ninteger\nSuggested wait in seconds; respect the server value and an overall deadline.\n503\nRetry-After\ninteger\nSuggested wait in seconds; respect the server value and an overall deadline.\nResponse example\nRelated guides\nPolling and downloads · Errors and safe retries"},{"id":"api-reference.get-asset","locale":"en","title":"Get asset download metadata","description":"Source-generated GET /assets/{asset_id} reference: authentication, fields, responses, errors, and operational safeguards.","section":"api-reference","path":"/docs/en/api-reference/get-asset","url":"https://animgen.com/docs/en/api-reference/get-asset","status":"beta","lastVerified":"2026-08-30","apiVersion":"1.3.0","audience":["api-developer","ai-agent"],"productAreas":["public-api"],"tags":["reference","API","get-asset"],"translations":{"en":"https://animgen.com/docs/en/api-reference/get-asset","zh":"https://animgen.com/docs/zh/api-reference/get-asset"},"headings":[{"id":"operation","title":"Operation","level":2},{"id":"authentication-and-side-effects","title":"Authentication and side effects","level":2},{"id":"parameters","title":"Parameters","level":2},{"id":"responses","title":"Responses","level":2},{"id":"response-headers","title":"Response headers","level":3},{"id":"response-example","title":"Response example","level":3},{"id":"related-guides","title":"Related guides","level":2}],"text":"Generated from the backend contract. Field names, required flags, constraints, and defaults come from source models. Download the machine-readable source. Examples use placeholder IDs and illustrative values, not live prices, limits, or model availability.\nOperation\nGET /assets/{asset_id}\noperationId: get_asset_v1_assets__asset_id__get\nRead an owned asset and issue a fresh short-lived signed download URL. Save the asset ID, not its expiring URL. The download itself must not include API credentials, including after storage redirects. Ownership and retention still apply.\nAuthentication and side effects\nUse a server-side Bearer API key. Required scope: animations:read\nThis operation does not start paid generation. Other state changes are described above.\nParameters\nParameter\nLocation\nType\nRequired\nConstraints / default\nMeaning\nasset_id\npath\nstring\nYes\nformat: uuid\nOwned public resource UUID; task, asset, and file IDs are not interchangeable.\nResponses\nHTTP\nBody\nMeaning\n200\nAssetResponse\nSuccessful public response. Example values are illustrative.\n400\nAPIErrorEnvelope\nInvalid input; correct the request before retrying.\n401\nAPIErrorEnvelope\nMissing, expired, or revoked API key.\n403\nAPIErrorEnvelope\nAccount eligibility, account status, or key scope does not allow this operation.\n404\nAPIErrorEnvelope\nResource is unavailable, not owned, or its signature is invalid/expired.\n429\nAPIErrorEnvelope\nAccount-wide rate or queue limit; wait for Retry-After.\n500\nAPIErrorEnvelope\nInternal failure; preserve the task/key and retry only when marked retryable.\n503\nAPIErrorEnvelope\nService/provider unavailable; retry only when error.retryable is true.\nResponse headers\nHTTP\nHeader\nType\nMeaning\n429\nRetry-After\ninteger\nSuggested wait in seconds; respect the server value and an overall deadline.\n503\nRetry-After\ninteger\nSuggested wait in seconds; respect the server value and an overall deadline.\nResponse example\nRelated guides\nPolling and downloads · Errors and safe retries"},{"id":"api-reference.get-credit-balance","locale":"en","title":"Get credit balance","description":"Source-generated GET /credits/balance reference: authentication, fields, responses, errors, and operational safeguards.","section":"api-reference","path":"/docs/en/api-reference/get-credit-balance","url":"https://animgen.com/docs/en/api-reference/get-credit-balance","status":"beta","lastVerified":"2026-08-30","apiVersion":"1.3.0","audience":["api-developer","ai-agent"],"productAreas":["public-api"],"tags":["reference","API","get-credit-balance"],"translations":{"en":"https://animgen.com/docs/en/api-reference/get-credit-balance","zh":"https://animgen.com/docs/zh/api-reference/get-credit-balance"},"headings":[{"id":"operation","title":"Operation","level":2},{"id":"authentication-and-side-effects","title":"Authentication and side effects","level":2},{"id":"parameters","title":"Parameters","level":2},{"id":"responses","title":"Responses","level":2},{"id":"response-headers","title":"Response headers","level":3},{"id":"response-example","title":"Response example","level":3},{"id":"related-guides","title":"Related guides","level":2}],"text":"Generated from the backend contract. Field names, required flags, constraints, and defaults come from source models. Download the machine-readable source. Examples use placeholder IDs and illustrative values, not live prices, limits, or model availability.\nOperation\nGET /credits/balance\noperationId: credits_balance_v1_credits_balance_get\nRead currently available credits shared by web and API use. Verified accounts may access the API, while cost-bearing generation still requires enough credits. Quote the intended operation before spending.\nAuthentication and side effects\nUse a server-side Bearer API key. Required scope: animations:read\nThis operation does not start paid generation. Other state changes are described above.\nParameters\nNo path, query, or operation-specific header parameters.\nResponses\nHTTP\nBody\nMeaning\n200\nCreditsBalanceResponse\nSuccessful public response. Example values are illustrative.\n400\nAPIErrorEnvelope\nInvalid input; correct the request before retrying.\n401\nAPIErrorEnvelope\nMissing, expired, or revoked API key.\n403\nAPIErrorEnvelope\nAccount eligibility, account status, or key scope does not allow this operation.\n404\nAPIErrorEnvelope\nResource is unavailable, not owned, or its signature is invalid/expired.\n429\nAPIErrorEnvelope\nAccount-wide rate or queue limit; wait for Retry-After.\n500\nAPIErrorEnvelope\nInternal failure; preserve the task/key and retry only when marked retryable.\n503\nAPIErrorEnvelope\nService/provider unavailable; retry only when error.retryable is true.\nResponse headers\nHTTP\nHeader\nType\nMeaning\n429\nRetry-After\ninteger\nSuggested wait in seconds; respect the server value and an overall deadline.\n503\nRetry-After\ninteger\nSuggested wait in seconds; respect the server value and an overall deadline.\nResponse example\nRelated guides\nPolling and downloads · Errors and safe retries"},{"id":"api-reference.get-video-generations","locale":"en","title":"Get video generation","description":"Source-generated GET /video-generations/{job_id} reference: authentication, fields, responses, errors, and operational safeguards.","section":"api-reference","path":"/docs/en/api-reference/get-video-generations","url":"https://animgen.com/docs/en/api-reference/get-video-generations","status":"beta","lastVerified":"2026-08-30","apiVersion":"1.3.0","audience":["api-developer","ai-agent"],"productAreas":["public-api"],"tags":["reference","API","get-video-generations"],"translations":{"en":"https://animgen.com/docs/en/api-reference/get-video-generations","zh":"https://animgen.com/docs/zh/api-reference/get-video-generations"},"headings":[{"id":"operation","title":"Operation","level":2},{"id":"authentication-and-side-effects","title":"Authentication and side effects","level":2},{"id":"parameters","title":"Parameters","level":2},{"id":"responses","title":"Responses","level":2},{"id":"response-headers","title":"Response headers","level":3},{"id":"response-example","title":"Response example","level":3},{"id":"related-guides","title":"Related guides","level":2}],"text":"Generated from the backend contract. Field names, required flags, constraints, and defaults come from source models. Download the machine-readable source. Examples use placeholder IDs and illustrative values, not live prices, limits, or model availability.\nOperation\nGET /video-generations/{job_id}\noperationId: get_video_generation_v1_video_generations__job_id__get\nRead an owned task. Respect Retry-After and use a bounded polling deadline. queued, running, and cancelling are nonterminal; succeeded, failed, and cancelled are terminal. A later-stage failure can leave usable outputs. Progress is not a time estimate.\nAuthentication and side effects\nUse a server-side Bearer API key. Required scope: animations:read\nThis operation does not start paid generation. Other state changes are described above.\nParameters\nParameter\nLocation\nType\nRequired\nConstraints / default\nMeaning\njob_id\npath\nstring\nYes\nformat: uuid\nOwned public resource UUID; task, asset, and file IDs are not interchangeable.\nResponses\nHTTP\nBody\nMeaning\n200\nTaskResponse\nSuccessful public response. Example values are illustrative.\n400\nAPIErrorEnvelope\nInvalid input; correct the request before retrying.\n401\nAPIErrorEnvelope\nMissing, expired, or revoked API key.\n403\nAPIErrorEnvelope\nAccount eligibility, account status, or key scope does not allow this operation.\n404\nAPIErrorEnvelope\nResource is unavailable, not owned, or its signature is invalid/expired.\n429\nAPIErrorEnvelope\nAccount-wide rate or queue limit; wait for Retry-After.\n500\nAPIErrorEnvelope\nInternal failure; preserve the task/key and retry only when marked retryable.\n503\nAPIErrorEnvelope\nService/provider unavailable; retry only when error.retryable is true.\nResponse headers\nHTTP\nHeader\nType\nMeaning\n200\nRetry-After\ninteger\nSuggested wait in seconds; respect the server value and an overall deadline.\n429\nRetry-After\ninteger\nSuggested wait in seconds; respect the server value and an overall deadline.\n503\nRetry-After\ninteger\nSuggested wait in seconds; respect the server value and an overall deadline.\nResponse example\nRelated guides\nPolling and downloads · Errors and safe retries"},{"id":"api-reference.list-animation-exports","locale":"en","title":"List animation export tasks","description":"Source-generated GET /animation-exports reference: authentication, fields, responses, errors, and operational safeguards.","section":"api-reference","path":"/docs/en/api-reference/list-animation-exports","url":"https://animgen.com/docs/en/api-reference/list-animation-exports","status":"beta","lastVerified":"2026-08-30","apiVersion":"1.3.0","audience":["api-developer","ai-agent"],"productAreas":["public-api"],"tags":["reference","API","list-animation-exports"],"translations":{"en":"https://animgen.com/docs/en/api-reference/list-animation-exports","zh":"https://animgen.com/docs/zh/api-reference/list-animation-exports"},"headings":[{"id":"operation","title":"Operation","level":2},{"id":"authentication-and-side-effects","title":"Authentication and side effects","level":2},{"id":"parameters","title":"Parameters","level":2},{"id":"responses","title":"Responses","level":2},{"id":"response-headers","title":"Response headers","level":3},{"id":"response-example","title":"Response example","level":3},{"id":"related-guides","title":"Related guides","level":2}],"text":"Generated from the backend contract. Field names, required flags, constraints, and defaults come from source models. Download the machine-readable source. Examples use placeholder IDs and illustrative values, not live prices, limits, or model availability.\nOperation\nGET /animation-exports\noperationId: list_animation_exports_v1_animation_exports_get\nList tasks owned by the authenticated account. Pass next_cursor unchanged to retrieve the next page; null ends pagination. Limits and rate budgets are account-wide, not per key.\nAuthentication and side effects\nUse a server-side Bearer API key. Required scope: animations:read\nThis operation does not start paid generation. Other state changes are described above.\nParameters\nParameter\nLocation\nType\nRequired\nConstraints / default\nMeaning\nlimit\nquery\ninteger\nNo\nminimum: 1; maximum: 100; default: 20\nMaximum records in this page, not an account concurrency limit.\ncursor\nquery\nstring / null\nNo\n—\nOpaque next_cursor from the prior page; pass unchanged.\nResponses\nHTTP\nBody\nMeaning\n200\nTaskListResponse\nSuccessful public response. Example values are illustrative.\n400\nAPIErrorEnvelope\nInvalid input; correct the request before retrying.\n401\nAPIErrorEnvelope\nMissing, expired, or revoked API key.\n403\nAPIErrorEnvelope\nAccount eligibility, account status, or key scope does not allow this operation.\n404\nAPIErrorEnvelope\nResource is unavailable, not owned, or its signature is invalid/expired.\n429\nAPIErrorEnvelope\nAccount-wide rate or queue limit; wait for Retry-After.\n500\nAPIErrorEnvelope\nInternal failure; preserve the task/key and retry only when marked retryable.\n503\nAPIErrorEnvelope\nService/provider unavailable; retry only when error.retryable is true.\nResponse headers\nHTTP\nHeader\nType\nMeaning\n429\nRetry-After\ninteger\nSuggested wait in seconds; respect the server value and an overall deadline.\n503\nRetry-After\ninteger\nSuggested wait in seconds; respect the server value and an overall deadline.\nResponse example\nRelated guides\nPolling and downloads · Errors and safe retries"},{"id":"api-reference.list-animations","locale":"en","title":"List animation tasks","description":"Source-generated GET /animations reference: authentication, fields, responses, errors, and operational safeguards.","section":"api-reference","path":"/docs/en/api-reference/list-animations","url":"https://animgen.com/docs/en/api-reference/list-animations","status":"beta","lastVerified":"2026-08-30","apiVersion":"1.3.0","audience":["api-developer","ai-agent"],"productAreas":["public-api"],"tags":["reference","API","list-animations"],"translations":{"en":"https://animgen.com/docs/en/api-reference/list-animations","zh":"https://animgen.com/docs/zh/api-reference/list-animations"},"headings":[{"id":"operation","title":"Operation","level":2},{"id":"authentication-and-side-effects","title":"Authentication and side effects","level":2},{"id":"parameters","title":"Parameters","level":2},{"id":"responses","title":"Responses","level":2},{"id":"response-headers","title":"Response headers","level":3},{"id":"response-example","title":"Response example","level":3},{"id":"related-guides","title":"Related guides","level":2}],"text":"Generated from the backend contract. Field names, required flags, constraints, and defaults come from source models. Download the machine-readable source. Examples use placeholder IDs and illustrative values, not live prices, limits, or model availability.\nOperation\nGET /animations\noperationId: list_one_click_animations_v1_animations_get\nList tasks owned by the authenticated account. Pass next_cursor unchanged to retrieve the next page; null ends pagination. Limits and rate budgets are account-wide, not per key.\nAuthentication and side effects\nUse a server-side Bearer API key. Required scope: animations:read\nThis operation does not start paid generation. Other state changes are described above.\nParameters\nParameter\nLocation\nType\nRequired\nConstraints / default\nMeaning\nlimit\nquery\ninteger\nNo\nminimum: 1; maximum: 100; default: 20\nMaximum records in this page, not an account concurrency limit.\ncursor\nquery\nstring / null\nNo\n—\nOpaque next_cursor from the prior page; pass unchanged.\nResponses\nHTTP\nBody\nMeaning\n200\nTaskListResponse\nSuccessful public response. Example values are illustrative.\n400\nAPIErrorEnvelope\nInvalid input; correct the request before retrying.\n401\nAPIErrorEnvelope\nMissing, expired, or revoked API key.\n403\nAPIErrorEnvelope\nAccount eligibility, account status, or key scope does not allow this operation.\n404\nAPIErrorEnvelope\nResource is unavailable, not owned, or its signature is invalid/expired.\n429\nAPIErrorEnvelope\nAccount-wide rate or queue limit; wait for Retry-After.\n500\nAPIErrorEnvelope\nInternal failure; preserve the task/key and retry only when marked retryable.\n503\nAPIErrorEnvelope\nService/provider unavailable; retry only when error.retryable is true.\nResponse headers\nHTTP\nHeader\nType\nMeaning\n429\nRetry-After\ninteger\nSuggested wait in seconds; respect the server value and an overall deadline.\n503\nRetry-After\ninteger\nSuggested wait in seconds; respect the server value and an overall deadline.\nResponse example\nRelated guides\nPolling and downloads · Errors and safe retries"},{"id":"api-reference.list-models","locale":"en","title":"List model capabilities","description":"Source-generated GET /models reference: authentication, fields, responses, errors, and operational safeguards.","section":"api-reference","path":"/docs/en/api-reference/list-models","url":"https://animgen.com/docs/en/api-reference/list-models","status":"beta","lastVerified":"2026-08-30","apiVersion":"1.3.0","audience":["api-developer","ai-agent"],"productAreas":["public-api"],"tags":["reference","API","list-models"],"translations":{"en":"https://animgen.com/docs/en/api-reference/list-models","zh":"https://animgen.com/docs/zh/api-reference/list-models"},"headings":[{"id":"operation","title":"Operation","level":2},{"id":"authentication-and-side-effects","title":"Authentication and side effects","level":2},{"id":"parameters","title":"Parameters","level":2},{"id":"responses","title":"Responses","level":2},{"id":"response-headers","title":"Response headers","level":3},{"id":"response-example","title":"Response example","level":3},{"id":"related-guides","title":"Related guides","level":2}],"text":"Generated from the backend contract. Field names, required flags, constraints, and defaults come from source models. Download the machine-readable source. Examples use placeholder IDs and illustrative values, not live prices, limits, or model availability.\nOperation\nGET /models\noperationId: list_models_v1_models_get\nDiscover currently enabled model IDs, defaults, and input capabilities. Check modes, per-mode ratios, per-resolution durations, and feature flags before quoting. Do not hard-code model IDs, supported combinations, or prices from documentation examples.\nAuthentication and side effects\nUse a server-side Bearer API key. Required scope: animations:read\nThis operation does not start paid generation. Other state changes are described above.\nParameters\nNo path, query, or operation-specific header parameters.\nResponses\nHTTP\nBody\nMeaning\n200\nModelsResponse\nSuccessful public response. Example values are illustrative.\n400\nAPIErrorEnvelope\nInvalid input; correct the request before retrying.\n401\nAPIErrorEnvelope\nMissing, expired, or revoked API key.\n403\nAPIErrorEnvelope\nAccount eligibility, account status, or key scope does not allow this operation.\n404\nAPIErrorEnvelope\nResource is unavailable, not owned, or its signature is invalid/expired.\n429\nAPIErrorEnvelope\nAccount-wide rate or queue limit; wait for Retry-After.\n500\nAPIErrorEnvelope\nInternal failure; preserve the task/key and retry only when marked retryable.\n503\nAPIErrorEnvelope\nService/provider unavailable; retry only when error.retryable is true.\nResponse headers\nHTTP\nHeader\nType\nMeaning\n429\nRetry-After\ninteger\nSuggested wait in seconds; respect the server value and an overall deadline.\n503\nRetry-After\ninteger\nSuggested wait in seconds; respect the server value and an overall deadline.\nResponse example\nRelated guides\nPolling and downloads · Errors and safe retries"},{"id":"api-reference.list-video-generations","locale":"en","title":"List video generation tasks","description":"Source-generated GET /video-generations reference: authentication, fields, responses, errors, and operational safeguards.","section":"api-reference","path":"/docs/en/api-reference/list-video-generations","url":"https://animgen.com/docs/en/api-reference/list-video-generations","status":"beta","lastVerified":"2026-08-30","apiVersion":"1.3.0","audience":["api-developer","ai-agent"],"productAreas":["public-api"],"tags":["reference","API","list-video-generations"],"translations":{"en":"https://animgen.com/docs/en/api-reference/list-video-generations","zh":"https://animgen.com/docs/zh/api-reference/list-video-generations"},"headings":[{"id":"operation","title":"Operation","level":2},{"id":"authentication-and-side-effects","title":"Authentication and side effects","level":2},{"id":"parameters","title":"Parameters","level":2},{"id":"responses","title":"Responses","level":2},{"id":"response-headers","title":"Response headers","level":3},{"id":"response-example","title":"Response example","level":3},{"id":"related-guides","title":"Related guides","level":2}],"text":"Generated from the backend contract. Field names, required flags, constraints, and defaults come from source models. Download the machine-readable source. Examples use placeholder IDs and illustrative values, not live prices, limits, or model availability.\nOperation\nGET /video-generations\noperationId: list_video_generations_v1_video_generations_get\nList tasks owned by the authenticated account. Pass next_cursor unchanged to retrieve the next page; null ends pagination. Limits and rate budgets are account-wide, not per key.\nAuthentication and side effects\nUse a server-side Bearer API key. Required scope: animations:read\nThis operation does not start paid generation. Other state changes are described above.\nParameters\nParameter\nLocation\nType\nRequired\nConstraints / default\nMeaning\nlimit\nquery\ninteger\nNo\nminimum: 1; maximum: 100; default: 20\nMaximum records in this page, not an account concurrency limit.\ncursor\nquery\nstring / null\nNo\n—\nOpaque next_cursor from the prior page; pass unchanged.\nResponses\nHTTP\nBody\nMeaning\n200\nTaskListResponse\nSuccessful public response. Example values are illustrative.\n400\nAPIErrorEnvelope\nInvalid input; correct the request before retrying.\n401\nAPIErrorEnvelope\nMissing, expired, or revoked API key.\n403\nAPIErrorEnvelope\nAccount eligibility, account status, or key scope does not allow this operation.\n404\nAPIErrorEnvelope\nResource is unavailable, not owned, or its signature is invalid/expired.\n429\nAPIErrorEnvelope\nAccount-wide rate or queue limit; wait for Retry-After.\n500\nAPIErrorEnvelope\nInternal failure; preserve the task/key and retry only when marked retryable.\n503\nAPIErrorEnvelope\nService/provider unavailable; retry only when error.retryable is true.\nResponse headers\nHTTP\nHeader\nType\nMeaning\n429\nRetry-After\ninteger\nSuggested wait in seconds; respect the server value and an overall deadline.\n503\nRetry-After\ninteger\nSuggested wait in seconds; respect the server value and an overall deadline.\nResponse example\nRelated guides\nPolling and downloads · Errors and safe retries"},{"id":"api-reference.quote-animation-exports","locale":"en","title":"Quote animation export","description":"Source-generated POST /animation-exports/quote reference: authentication, fields, responses, errors, and operational safeguards.","section":"api-reference","path":"/docs/en/api-reference/quote-animation-exports","url":"https://animgen.com/docs/en/api-reference/quote-animation-exports","status":"beta","lastVerified":"2026-08-30","apiVersion":"1.3.0","audience":["api-developer","ai-agent"],"productAreas":["public-api"],"tags":["reference","API","quote-animation-exports"],"translations":{"en":"https://animgen.com/docs/en/api-reference/quote-animation-exports","zh":"https://animgen.com/docs/zh/api-reference/quote-animation-exports"},"headings":[{"id":"operation","title":"Operation","level":2},{"id":"authentication-and-side-effects","title":"Authentication and side effects","level":2},{"id":"parameters","title":"Parameters","level":2},{"id":"request-body-application-json","title":"Request body (application/json)","level":2},{"id":"request-example","title":"Request example","level":3},{"id":"responses","title":"Responses","level":2},{"id":"response-headers","title":"Response headers","level":3},{"id":"response-example","title":"Response example","level":3},{"id":"related-guides","title":"Related guides","level":2}],"text":"Generated from the backend contract. Field names, required flags, constraints, and defaults come from source models. Download the machine-readable source. Examples use placeholder IDs and illustrative values, not live prices, limits, or model availability.\nOperation\nPOST /animation-exports/quote\noperationId: quote_animation_export_v1_animation_exports_quote_post\nEstimate credits for the intended operation without starting production or charging credits. This is not a price lock or spend authorization. Creation recalculates the current quote; review it before creating. Match the pricing-relevant options to the later request.\nAuthentication and side effects\nUse a server-side Bearer API key. Required scope: animations:write\nThis operation does not start paid generation. Other state changes are described above.\nParameters\nNo path, query, or operation-specific header parameters.\nRequest body (application/json)\nBody required: true\nField\nType\nRequired\nDefault\nConstraints\nMeaning\nexport\nExportOptions\nNo\n{\"frame_count\":24,\"output_formats\":[\"spritesheet\"],\"output_height\":512,\"output_width\":512,\"transparent\":{\"enabled\":false},\"unity\":{\"pivot\":\"bottom_center\",\"pixels_per_unit\":100}}\n—\nOutput formats and processing settings.\nmetadata\nobject\nNo\n{}\n—\nSimple scalar/null metadata; at most 4 KiB JSON, no credentials.\nselection\nSelection\nNo\n{\"duration_seconds\":null,\"mode\":\"full\",\"start_seconds\":0}\n—\nSource interval to export.\nsource_video_asset_id\nstring\nYes\n—\nformat: uuid\nOwned source video asset ID, not a task ID. Reuse an existing video to avoid generating motion again.\nFull nested schema: AnimationExportCreateRequest\nRequest example\nResponses\nHTTP\nBody\nMeaning\n200\nQuoteResponse\nSuccessful public response. Example values are illustrative.\n400\nAPIErrorEnvelope\nInvalid input; correct the request before retrying.\n401\nAPIErrorEnvelope\nMissing, expired, or revoked API key.\n402\nAPIErrorEnvelope\nInsufficient credits; do not automatically purchase.\n403\nAPIErrorEnvelope\nAccount eligibility, account status, or key scope does not allow this operation.\n404\nAPIErrorEnvelope\nResource is unavailable, not owned, or its signature is invalid/expired.\n413\nAPIErrorEnvelope\nRequest or decoded image exceeds the configured limit.\n415\nAPIErrorEnvelope\nUse supported image media types.\n422\nAPIErrorEnvelope\nDecoded image dimensions exceed the allowed size.\n429\nAPIErrorEnvelope\nAccount-wide rate or queue limit; wait for Retry-After.\n500\nAPIErrorEnvelope\nInternal failure; preserve the task/key and retry only when marked retryable.\n503\nAPIErrorEnvelope\nService/provider unavailable; retry only when error.retryable is true.\nResponse headers\nHTTP\nHeader\nType\nMeaning\n429\nRetry-After\ninteger\nSuggested wait in seconds; respect the server value and an overall deadline.\n503\nRetry-After\ninteger\nSuggested wait in seconds; respect the server value and an overall deadline.\nResponse example\nRelated guides\nPolling and downloads · Errors and safe retries"},{"id":"api-reference.quote-animations","locale":"en","title":"Quote animation","description":"Source-generated POST /animations/quote reference: authentication, fields, responses, errors, and operational safeguards.","section":"api-reference","path":"/docs/en/api-reference/quote-animations","url":"https://animgen.com/docs/en/api-reference/quote-animations","status":"beta","lastVerified":"2026-08-30","apiVersion":"1.3.0","audience":["api-developer","ai-agent"],"productAreas":["public-api"],"tags":["reference","API","quote-animations"],"translations":{"en":"https://animgen.com/docs/en/api-reference/quote-animations","zh":"https://animgen.com/docs/zh/api-reference/quote-animations"},"headings":[{"id":"operation","title":"Operation","level":2},{"id":"authentication-and-side-effects","title":"Authentication and side effects","level":2},{"id":"parameters","title":"Parameters","level":2},{"id":"request-body-application-json","title":"Request body (application/json)","level":2},{"id":"request-example","title":"Request example","level":3},{"id":"responses","title":"Responses","level":2},{"id":"response-headers","title":"Response headers","level":3},{"id":"response-example","title":"Response example","level":3},{"id":"related-guides","title":"Related guides","level":2}],"text":"Generated from the backend contract. Field names, required flags, constraints, and defaults come from source models. Download the machine-readable source. Examples use placeholder IDs and illustrative values, not live prices, limits, or model availability.\nOperation\nPOST /animations/quote\noperationId: quote_one_click_animation_v1_animations_quote_post\nEstimate credits for the intended operation without starting production or charging credits. This is not a price lock or spend authorization. Creation recalculates the current quote; review it before creating. Match the pricing-relevant options to the later request.\nAuthentication and side effects\nUse a server-side Bearer API key. Required scope: animations:write\nThis operation does not start paid generation. Other state changes are described above.\nParameters\nNo path, query, or operation-specific header parameters.\nRequest body (application/json)\nBody required: true\nField\nType\nRequired\nDefault\nConstraints\nMeaning\nexport\nExportOptions\nNo\n{\"frame_count\":24,\"output_formats\":[\"spritesheet\"],\"output_height\":512,\"output_width\":512,\"transparent\":{\"enabled\":false},\"unity\":{\"pivot\":\"bottom_center\",\"pixels_per_unit\":100}}\n—\nExport after video generation. Alpha-bearing formats require an alpha_key source; compatible formats automatically enable its transparent export.\ninput\nGenerationInput\nYes\n—\n—\nImages owned by the caller or supplied for this generation.\nmetadata\nobject\nNo\n{}\n—\nCaller metadata: simple string/number/boolean/null values, at most 4 KiB JSON. Do not store secrets.\nnegative_prompt\nstring\nNo\n\"\"\nmaxLength: 4000\nOptional exclusions, only when the model supports negative prompts.\nprompt\nstring\nNo\n\"\"\nmaxLength: 8000\nMotion instruction; nonempty when the model requires a prompt. Keep private prompts out of logs.\nselection\nSelection\nNo\n{\"duration_seconds\":null,\"mode\":\"full\",\"start_seconds\":0}\n—\nInterval selected after generation; full by default.\nvideo\nVideoOptions\nNo\n{\"duration_seconds\":null,\"input_canvas\":null,\"model\":null,\"ratio\":null,\"resolution\":null,\"seed\":null,\"style_preset\":null,\"transparency\":{\"key_color\":null,\"key_selection\":\"auto\",\"mode\":\"standard\"},\"watermark\":null}\n—\nModel-compatible generation settings.\nFull nested schema: AnimationCreateRequest\nRequest example\nResponses\nHTTP\nBody\nMeaning\n200\nQuoteResponse\nSuccessful public response. Example values are illustrative.\n400\nAPIErrorEnvelope\nInvalid input; correct the request before retrying.\n401\nAPIErrorEnvelope\nMissing, expired, or revoked API key.\n402\nAPIErrorEnvelope\nInsufficient credits; do not automatically purchase.\n403\nAPIErrorEnvelope\nAccount eligibility, account status, or key scope does not allow this operation.\n404\nAPIErrorEnvelope\nResource is unavailable, not owned, or its signature is invalid/expired.\n413\nAPIErrorEnvelope\nRequest or decoded image exceeds the configured limit.\n415\nAPIErrorEnvelope\nUse supported image media types.\n422\nAPIErrorEnvelope\nDecoded image dimensions exceed the allowed size.\n429\nAPIErrorEnvelope\nAccount-wide rate or queue limit; wait for Retry-After.\n500\nAPIErrorEnvelope\nInternal failure; preserve the task/key and retry only when marked retryable.\n503\nAPIErrorEnvelope\nService/provider unavailable; retry only when error.retryable is true.\nResponse headers\nHTTP\nHeader\nType\nMeaning\n429\nRetry-After\ninteger\nSuggested wait in seconds; respect the server value and an overall deadline.\n503\nRetry-After\ninteger\nSuggested wait in seconds; respect the server value and an overall deadline.\nResponse example\nRelated guides\nPolling and downloads · Errors and safe retries"},{"id":"api-reference.quote-video-generations","locale":"en","title":"Quote video generation","description":"Source-generated POST /video-generations/quote reference: authentication, fields, responses, errors, and operational safeguards.","section":"api-reference","path":"/docs/en/api-reference/quote-video-generations","url":"https://animgen.com/docs/en/api-reference/quote-video-generations","status":"beta","lastVerified":"2026-08-30","apiVersion":"1.3.0","audience":["api-developer","ai-agent"],"productAreas":["public-api"],"tags":["reference","API","quote-video-generations"],"translations":{"en":"https://animgen.com/docs/en/api-reference/quote-video-generations","zh":"https://animgen.com/docs/zh/api-reference/quote-video-generations"},"headings":[{"id":"operation","title":"Operation","level":2},{"id":"authentication-and-side-effects","title":"Authentication and side effects","level":2},{"id":"parameters","title":"Parameters","level":2},{"id":"request-body-application-json","title":"Request body (application/json)","level":2},{"id":"request-example","title":"Request example","level":3},{"id":"responses","title":"Responses","level":2},{"id":"response-headers","title":"Response headers","level":3},{"id":"response-example","title":"Response example","level":3},{"id":"related-guides","title":"Related guides","level":2}],"text":"Generated from the backend contract. Field names, required flags, constraints, and defaults come from source models. Download the machine-readable source. Examples use placeholder IDs and illustrative values, not live prices, limits, or model availability.\nOperation\nPOST /video-generations/quote\noperationId: quote_video_generation_v1_video_generations_quote_post\nEstimate credits for the intended operation without starting production or charging credits. This is not a price lock or spend authorization. Creation recalculates the current quote; review it before creating. Match the pricing-relevant options to the later request.\nAuthentication and side effects\nUse a server-side Bearer API key. Required scope: animations:write\nThis operation does not start paid generation. Other state changes are described above.\nParameters\nNo path, query, or operation-specific header parameters.\nRequest body (application/json)\nBody required: true\nField\nType\nRequired\nDefault\nConstraints\nMeaning\nhas_last_frame\nboolean\nNo\nfalse\n—\nWhether the planned request includes a last frame.\nreference_image_count\ninteger\nNo\n0\nminimum: 0; maximum: 8\nNumber of additional references, excluding the first frame.\nvideo\nVideoOptions\nNo\n{\"duration_seconds\":null,\"input_canvas\":null,\"model\":null,\"ratio\":null,\"resolution\":null,\"seed\":null,\"style_preset\":null,\"transparency\":{\"key_color\":null,\"key_selection\":\"auto\",\"mode\":\"standard\"},\"watermark\":null}\n—\nGeneration options to estimate; must match the later create.\nFull nested schema: VideoGenerationQuoteRequest\nRequest example\nResponses\nHTTP\nBody\nMeaning\n200\nQuoteResponse\nSuccessful public response. Example values are illustrative.\n400\nAPIErrorEnvelope\nInvalid input; correct the request before retrying.\n401\nAPIErrorEnvelope\nMissing, expired, or revoked API key.\n402\nAPIErrorEnvelope\nInsufficient credits; do not automatically purchase.\n403\nAPIErrorEnvelope\nAccount eligibility, account status, or key scope does not allow this operation.\n404\nAPIErrorEnvelope\nResource is unavailable, not owned, or its signature is invalid/expired.\n413\nAPIErrorEnvelope\nRequest or decoded image exceeds the configured limit.\n415\nAPIErrorEnvelope\nUse supported image media types.\n422\nAPIErrorEnvelope\nDecoded image dimensions exceed the allowed size.\n429\nAPIErrorEnvelope\nAccount-wide rate or queue limit; wait for Retry-After.\n500\nAPIErrorEnvelope\nInternal failure; preserve the task/key and retry only when marked retryable.\n503\nAPIErrorEnvelope\nService/provider unavailable; retry only when error.retryable is true.\nResponse headers\nHTTP\nHeader\nType\nMeaning\n429\nRetry-After\ninteger\nSuggested wait in seconds; respect the server value and an overall deadline.\n503\nRetry-After\ninteger\nSuggested wait in seconds; respect the server value and an overall deadline.\nResponse example\nRelated guides\nPolling and downloads · Errors and safe retries"},{"id":"api-reference.schemas","locale":"en","title":"Shared schema definitions","description":"Source-generated field definitions, nested types, defaults, required flags, and constraints for this contract.","section":"api-reference","path":"/docs/en/api-reference/schemas","url":"https://animgen.com/docs/en/api-reference/schemas","status":"beta","lastVerified":"2026-08-30","apiVersion":"1.3.0","audience":["api-developer","ai-agent"],"productAreas":["public-api"],"tags":["reference","API","schemas"],"translations":{"en":"https://animgen.com/docs/en/api-reference/schemas","zh":"https://animgen.com/docs/zh/api-reference/schemas"},"headings":[{"id":"accountapikey","title":"AccountAPIKey","level":2},{"id":"accountlimits","title":"AccountLimits","level":2},{"id":"accountplan","title":"AccountPlan","level":2},{"id":"accountresponse","title":"AccountResponse","level":2},{"id":"animationcreaterequest","title":"AnimationCreateRequest","level":2},{"id":"animationexportcreaterequest","title":"AnimationExportCreateRequest","level":2},{"id":"apierror","title":"APIError","level":2},{"id":"apierrorenvelope","title":"APIErrorEnvelope","level":2},{"id":"assetresponse","title":"AssetResponse","level":2},{"id":"base64imageinput","title":"Base64ImageInput","level":2},{"id":"body-create-file-v1-files-post","title":"Body_create_file_v1_files_post","level":2},{"id":"creditsbalanceresponse","title":"CreditsBalanceResponse","level":2},{"id":"creditusage","title":"CreditUsage","level":2},{"id":"exportoptions","title":"ExportOptions","level":2},{"id":"exporttransparency","title":"ExportTransparency","level":2},{"id":"fileimageinput","title":"FileImageInput","level":2},{"id":"fileresponse","title":"FileResponse","level":2},{"id":"generationinput","title":"GenerationInput","level":2},{"id":"generationtransparency","title":"GenerationTransparency","level":2},{"id":"inputcanvasoptions","title":"InputCanvasOptions","level":2},{"id":"modelcapabilities","title":"ModelCapabilities","level":2},{"id":"modelsresponse","title":"ModelsResponse","level":2},{"id":"quoteresponse","title":"QuoteResponse","level":2},{"id":"selection","title":"Selection","level":2},{"id":"taskerror","title":"TaskError","level":2},{"id":"tasklistresponse","title":"TaskListResponse","level":2},{"id":"taskresponse","title":"TaskResponse","level":2},{"id":"unityoptions","title":"UnityOptions","level":2},{"id":"urlimageinput","title":"UrlImageInput","level":2},{"id":"videogenerationcreaterequest","title":"VideoGenerationCreateRequest","level":2},{"id":"videogenerationquoterequest","title":"VideoGenerationQuoteRequest","level":2},{"id":"videooptions","title":"VideoOptions","level":2}],"text":"Generated from the backend contract. Field names, required flags, constraints, and defaults come from source models. Download the machine-readable source. Examples use placeholder IDs and illustrative values, not live prices, limits, or model availability.\nA dash means no default is declared, not a null value. A field can be optional in JSON Schema but conditionally required by the documented workflow. Model-specific options still require live capability discovery.\nAccountAPIKey\nUnknown fields are rejected.\nField\nType\nRequired\nDefault\nConstraints\nMeaning\nid\nstring\nYes\n—\nformat: uuid\nIdentity of the authenticated key, not its secret. Idempotency is scoped to this identity.\nscopes\narray<string>\nYes\n—\n—\nPermissions granted to this key.\nAccountLimits\nUnknown fields are rejected.\nField\nType\nRequired\nDefault\nConstraints\nMeaning\nconcurrency\ninteger\nYes\n—\n—\nMaximum concurrent jobs across this account.\ncreate_per_minute\ninteger\nYes\n—\n—\nAccount-wide create requests per minute.\nother_per_minute\ninteger\nYes\n—\n—\nAccount-wide other requests per minute.\nqueue\ninteger\nYes\n—\n—\nMaximum queued jobs across this account.\nAccountPlan\nUnknown fields are rejected.\nField\nType\nRequired\nDefault\nConstraints\nMeaning\ncancel_at_period_end\nboolean\nYes\n—\n—\nWhether the current paid subscription will stop renewing; false for registered access.\ncode\nstring\nYes\n—\n—\nCurrent developer access tier: registered, basic, expert, or ultra.\ncurrent_period_end\nstring / null\nYes\n—\nformat: date-time\nPaid subscription period end in UTC, or null for registered access.\nAccountResponse\nUnknown fields are rejected.\nField\nType\nRequired\nDefault\nConstraints\nMeaning\napi_key\nAccountAPIKey\nYes\n—\n—\nCurrent key identity and scopes; never the key secret.\nid\nstring\nYes\n—\nformat: uuid\nAuthenticated account ID.\nlimits\nAccountLimits\nYes\n—\n—\nLimits are shared by every key on this account.\nobject\nstring\nNo\n\"account\"\nconst: \"account\"\n—\nplan\nAccountPlan\nYes\n—\n—\nCurrent developer access tier and optional subscription period.\nAnimationCreateRequest\nUnknown fields are rejected.\nField\nType\nRequired\nDefault\nConstraints\nMeaning\nexport\nExportOptions\nNo\n{\"frame_count\":24,\"output_formats\":[\"spritesheet\"],\"output_height\":512,\"output_width\":512,\"transparent\":{\"enabled\":false},\"unity\":{\"pivot\":\"bottom_center\",\"pixels_per_unit\":100}}\n—\nExport after video generation. Alpha-bearing formats require an alpha_key source; compatible formats automatically enable its transparent export.\ninput\nGenerationInput\nYes\n—\n—\nImages owned by the caller or supplied for this generation.\nmetadata\nobject\nNo\n{}\n—\nCaller metadata: simple string/number/boolean/null values, at most 4 KiB JSON. Do not store secrets.\nnegative_prompt\nstring\nNo\n\"\"\nmaxLength: 4000\nOptional exclusions, only when the model supports negative prompts.\nprompt\nstring\nNo\n\"\"\nmaxLength: 8000\nMotion instruction; nonempty when the model requires a prompt. Keep private prompts out of logs.\nselection\nSelection\nNo\n{\"duration_seconds\":null,\"mode\":\"full\",\"start_seconds\":0}\n—\nInterval selected after generation; full by default.\nvideo\nVideoOptions\nNo\n{\"duration_seconds\":null,\"input_canvas\":null,\"model\":null,\"ratio\":null,\"resolution\":null,\"seed\":null,\"style_preset\":null,\"transparency\":{\"key_color\":null,\"key_selection\":\"auto\",\"mode\":\"standard\"},\"watermark\":null}\n—\nModel-compatible generation settings.\nAnimationExportCreateRequest\nUnknown fields are rejected.\nField\nType\nRequired\nDefault\nConstraints\nMeaning\nexport\nExportOptions\nNo\n{\"frame_count\":24,\"output_formats\":[\"spritesheet\"],\"output_height\":512,\"output_width\":512,\"transparent\":{\"enabled\":false},\"unity\":{\"pivot\":\"bottom_center\",\"pixels_per_unit\":100}}\n—\nOutput formats and processing settings.\nmetadata\nobject\nNo\n{}\n—\nSimple scalar/null metadata; at most 4 KiB JSON, no credentials.\nselection\nSelection\nNo\n{\"duration_seconds\":null,\"mode\":\"full\",\"start_seconds\":0}\n—\nSource interval to export.\nsource_video_asset_id\nstring\nYes\n—\nformat: uuid\nOwned source video asset ID, not a task ID. Reuse an existing video to avoid generating motion again.\nAPIError\nField\nType\nRequired\nDefault\nConstraints\nMeaning\ncode\nstring\nYes\n—\n—\nStable machine-readable error code.\ndetails\nobject\nYes\n—\n—\nPublic error-specific fields; inspect without logging private inputs.\nmessage\nstring\nYes\n—\n—\nHuman-readable explanation; do not branch on exact text.\nparam\nstring / null\nNo\n—\n—\nRelated public parameter, if known.\nrequest_id\nstring / null\nYes\n—\n—\nPublic support correlation ID, not a credential.\nretryable\nboolean\nYes\n—\n—\nRetry may help; still preserve idempotency and respect Retry-After.\nAPIErrorEnvelope\nField\nType\nRequired\nDefault\nConstraints\nMeaning\nerror\nAPIError\nYes\n—\n—\n—\nAssetResponse\nUnknown fields are rejected.\nField\nType\nRequired\nDefault\nConstraints\nMeaning\nbyte_size\ninteger\nYes\n—\n—\nExpected file size in bytes.\ncreated_at\nstring\nYes\n—\nformat: date-time\nCreation timestamp in UTC.\ndownload_expires_at\nstring\nYes\n—\nformat: date-time\nSigned URL expiry in UTC; refresh via asset lookup when expired.\ndownload_url\nstring\nYes\n—\n—\nSensitive short-lived signed URL. Download without a Bearer header, including after redirects; never log the URL.\nformat\nstring\nYes\n—\n—\nArtifact format; inspect actual outputs rather than assuming an array order.\nid\nstring\nYes\n—\nformat: uuid\nStable public asset ID; use it to refresh download metadata.\nmime_type\nstring\nYes\n—\n—\nAsset media type.\nobject\nstring\nNo\n\"asset\"\nconst: \"asset\"\n—\nBase64ImageInput\nUnknown fields are rejected.\nField\nType\nRequired\nDefault\nConstraints\nMeaning\ndata\nstring\nYes\n—\nminLength: 4\nPure Base64 without a data URL prefix; decoded limits: 10 MiB per image, 20 MiB total.\nmedia_type\nstring\nYes\n—\nenum: \"image/png\", \"image/jpeg\", \"image/webp\"\nActual image MIME type.\ntype\nstring\nYes\n—\nconst: \"base64\"\n—\nBody_create_file_v1_files_post\nField\nType\nRequired\nDefault\nConstraints\nMeaning\nfile\nstring\nYes\n—\nformat: binary\nPNG, JPEG, or WebP image bytes; validated before returning a public file ID.\nCreditsBalanceResponse\nUnknown fields are rejected.\nField\nType\nRequired\nDefault\nConstraints\nMeaning\navailable\ninteger\nYes\n—\n—\nCurrently available account credits; not a feature-entitlement flag.\nobject\nstring\nNo\n\"credit_balance\"\nconst: \"credit_balance\"\n—\nCreditUsage\nUnknown fields are rejected.\nField\nType\nRequired\nDefault\nConstraints\nMeaning\ncharged\ninteger\nYes\n—\n—\nNet charged credits. Confirmed provider moderation rejection is refunded; cancellation alone is not a refund.\nheld\ninteger\nYes\n—\n—\nCredits currently reserved, not an additional charge to sum with charged.\nquoted\ninteger\nYes\n—\n—\nQuoted total, not necessarily the final charge.\nrefunded\ninteger\nNo\n0\n—\nCredits returned after a charge; already excluded from charged. Not a cash refund.\nreleased\ninteger\nNo\n0\n—\nCredits returned from an uncommitted hold.\nstatus\nstring / null\nNo\nnull\n—\nBilling state: held, charged, released, refunded, or managed for internal child tasks.\nExportOptions\nUnknown fields are rejected.\nField\nType\nRequired\nDefault\nConstraints\nMeaning\nframe_count\ninteger\nNo\n24\nminimum: 1; maximum: 240\nNumber of frames sampled over the selected interval, not an FPS field.\noutput_formats\narray<string>\nNo\n[\"spritesheet\"]\nminItems: 1; items: enum: \"clip_video\", \"webm_alpha\", \"prores_4444\", \"frames_zip\", \"spritesheet\", \"spritesheet_json\", \"unity_meta\", \"unity_pack\", \"godot_pack\", \"unreal_paper2d_pack\", \"cocos_creator_pack\"\nRequested asset formats; defaults to spritesheet. Duplicates are removed. Metadata needs its matching texture.\noutput_height\ninteger\nNo\n512\nminimum: 64; maximum: 1024\nOutput frame height in pixels.\noutput_width\ninteger\nNo\n512\nminimum: 64; maximum: 1024\nOutput frame width in pixels.\ntransparent\nExportTransparency\nNo\n{\"enabled\":false}\n—\nUse the enabled object form. Legacy booleans are accepted but normalized to this object.\nunity\nUnityOptions\nNo\n{\"pivot\":\"bottom_center\",\"pixels_per_unit\":100}\n—\nSettings for Unity-specific metadata and packs.\nExportTransparency\nUnknown fields are rejected.\nField\nType\nRequired\nDefault\nConstraints\nMeaning\nenabled\nboolean\nNo\nfalse\n—\nTransparent processing for compatible outputs; requires an alpha_key source and does not make MP4 transparent.\nFileImageInput\nUnknown fields are rejected.\nField\nType\nRequired\nDefault\nConstraints\nMeaning\nfile_id\nstring\nYes\n—\nformat: uuid\nOwned public file ID from POST /files or complete_image_upload; not a Studio upload ID.\ntype\nstring\nYes\n—\nconst: \"file\"\n—\nFileResponse\nUnknown fields are rejected.\nField\nType\nRequired\nDefault\nConstraints\nMeaning\nbyte_size\ninteger\nYes\n—\n—\nStored image byte count.\ncreated_at\nstring\nYes\n—\nformat: date-time\nUTC upload creation time.\nheight\ninteger\nYes\n—\n—\nDecoded image height in pixels.\nid\nstring\nYes\n—\nformat: uuid\nReusable public file ID for type=file inputs.\nmime_type\nstring\nYes\n—\n—\nValidated image media type.\nobject\nstring\nNo\n\"file\"\nconst: \"file\"\n—\nsha256\nstring\nYes\n—\n—\nSHA-256 of the image bytes.\nwidth\ninteger\nYes\n—\n—\nDecoded image width in pixels.\nGenerationInput\nUnknown fields are rejected.\nField\nType\nRequired\nDefault\nConstraints\nMeaning\nfirst_frame\nFileImageInput / Base64ImageInput / UrlImageInput\nYes\n—\ndiscriminator: type\nRequired starting image; use the type discriminator to select an input representation.\nlast_frame\nFileImageInput / Base64ImageInput / UrlImageInput / null\nNo\nnull\ndiscriminator: type\nOptional end image; the selected model must support first/last-frame mode.\nreference_images\narray<FileImageInput / Base64ImageInput / UrlImageInput>\nNo\n[]\nmaxItems: 8; items: discriminator: type\nAdditional references, excluding the first frame. The live model can impose a smaller limit.\nGenerationTransparency\nUnknown fields are rejected.\nField\nType\nRequired\nDefault\nConstraints\nMeaning\nkey_color\nstring / null\nNo\nnull\n—\nTemporary key color when using manual selection; normally leave automatic selection enabled.\nkey_selection\nstring\nNo\n\"auto\"\nenum: \"auto\", \"manual\"\nHow the temporary key color is selected.\nmode\nstring\nNo\n\"standard\"\nenum: \"standard\", \"alpha_key\"\nstandard keeps the scene; alpha_key requires meaningful alpha in all active input images. Raw videos remain opaque.\nInputCanvasOptions\nUnknown fields are rejected.\nField\nType\nRequired\nDefault\nConstraints\nMeaning\naspect_ratio\nstring\nNo\n\"follow_output\"\nenum: \"follow_output\", \"source\"\nFollow the output ratio or preserve the source ratio.\nbackground\nstring\nNo\n\"auto\"\nenum: \"auto\", \"transparent\", \"solid\"\nCanvas extension background strategy.\nbackground_color\nstring / null\nNo\nnull\npattern: ^#[0-9A-Fa-f]{6}$\nSix-digit RGB color for a solid extension.\nenabled\nboolean\nNo\ntrue\n—\nWhether to prepare an expanded input canvas.\nposition_x\nnumber\nNo\n0.5\nminimum: 0; maximum: 1\nNormalized horizontal source position.\nposition_y\nnumber\nNo\n0.5\nminimum: 0; maximum: 1\nNormalized vertical source position.\nsource_scale\nnumber\nNo\n0.8\nminimum: 0.5; maximum: 1\nSource subject scale within the canvas.\nModelCapabilities\nUnknown fields are rejected.\nField\nType\nRequired\nDefault\nConstraints\nMeaning\naspect_ratio_mode\nstring\nYes\n—\n—\nProvider's aspect-ratio handling mode.\ndefault_duration_seconds\ninteger\nYes\n—\n—\nDefault generation duration in seconds.\ndefault_ratio\nstring / null\nYes\n—\n—\nDefault ratio, or null when not applicable.\ndefault_resolution\nstring / null\nYes\n—\n—\nDefault resolution, or null when not applicable.\ndurations\narray<integer>\nYes\n—\n—\nSupported generation durations in seconds; also inspect resolution-specific constraints.\ndurations_by_resolution\nobject\nNo\n{}\n—\nResolution-specific supported durations in seconds.\nid\nstring\nYes\n—\n—\nStable provider:model selector for requests; use the live catalog.\nlabel\nstring\nYes\n—\n—\nHuman-readable model label.\nmax_reference_images\ninteger\nYes\n—\n—\nModel reference-image capacity; the first frame occupies the first reference slot in reference mode.\nmodel\nstring\nYes\n—\n—\nModel identifier within the provider.\nmodes\narray<string>\nYes\n—\n—\nSupported input modes, such as first_frame, first_last_frame, or reference_images.\nprovider\nstring\nYes\n—\n—\nPublic provider identifier.\nratios\narray<string>\nYes\n—\n—\nSupported aspect ratio values; check ratios_by_mode where present.\nratios_by_mode\nobject\nNo\n{}\n—\nInput-mode-specific supported ratios.\nreference_image_duration_seconds\ninteger / null\nYes\n—\n—\nRequired duration for reference mode, when constrained.\nrequires_prompt\nboolean\nYes\n—\n—\nWhether prompt must be nonempty.\nresolutions\narray<string>\nYes\n—\n—\nSupported resolution values.\nreturns_last_frame\nboolean\nYes\n—\n—\nWhether the model can return a last-frame asset.\nsupports_first_frame\nboolean\nYes\n—\n—\nWhether a first-frame input is supported.\nsupports_last_frame\nboolean\nYes\n—\n—\nWhether a last-frame input is supported.\nsupports_negative_prompt\nboolean\nYes\n—\n—\nWhether negative_prompt is supported.\nsupports_reference_images\nboolean\nYes\n—\n—\nWhether reference-image mode is supported.\nsupports_seed\nboolean\nYes\n—\n—\nWhether seed is supported.\nsupports_watermark\nboolean\nYes\n—\n—\nWhether the watermark setting is supported.\nModelsResponse\nUnknown fields are rejected.\nField\nType\nRequired\nDefault\nConstraints\nMeaning\ndata\narray<ModelCapabilities>\nYes\n—\n—\nCurrently enabled models; do not hard-code this list in a client.\nobject\nstring\nNo\n\"list\"\nconst: \"list\"\n—\nQuoteResponse\nUnknown fields are rejected.\nField\nType\nRequired\nDefault\nConstraints\nMeaning\nbreakdown\nobject\nNo\n{}\n—\nPublic cost components; use credits as the quoted total.\ncredits\ninteger\nYes\n—\n—\nCurrent estimated credits. No price lock or spend authorization; creation recalculates the quote.\nobject\nstring\nNo\n\"quote\"\nconst: \"quote\"\n—\nSelection\nUnknown fields are rejected.\nField\nType\nRequired\nDefault\nConstraints\nMeaning\nduration_seconds\nnumber / null\nNo\nnull\nexclusiveMinimum: 0\nRequired when mode=range; positive interval length in seconds.\nmode\nstring\nNo\n\"full\"\nenum: \"full\", \"range\"\nfull uses the complete source; range requires duration_seconds.\nstart_seconds\nnumber\nNo\n0\nminimum: 0\nRange start in seconds from the source beginning.\nTaskError\nUnknown fields are rejected.\nField\nType\nRequired\nDefault\nConstraints\nMeaning\ncode\nstring\nYes\n—\n—\nMachine-readable task error code.\nmessage\nstring\nYes\n—\n—\nHuman-readable summary, not a stable branching key.\nretryable\nboolean\nNo\nfalse\n—\nWhether retry may help; inspect partial outputs before creating a new paid task.\nTaskListResponse\nUnknown fields are rejected.\nField\nType\nRequired\nDefault\nConstraints\nMeaning\ndata\narray<TaskResponse>\nYes\n—\n—\nOwned tasks in this page.\nnext_cursor\nstring / null\nNo\nnull\n—\nOpaque next-page cursor; null means no next page. Pass it unchanged.\nobject\nstring\nNo\n\"list\"\nconst: \"list\"\n—\nTaskResponse\nUnknown fields are rejected.\nField\nType\nRequired\nDefault\nConstraints\nMeaning\ncreated_at\nstring\nYes\n—\nformat: date-time\nUTC acceptance timestamp.\ncredits\nCreditUsage\nYes\n—\n—\nQuoted, reserved, and charged credit states.\nerror\nTaskError / null\nNo\nnull\n—\nTask failure details, independently of any usable outputs.\nfinished_at\nstring / null\nNo\nnull\nformat: date-time\nUTC terminal timestamp when known.\nid\nstring\nYes\n—\nformat: uuid\nPersist this task ID immediately after create; poll it instead of creating again.\nmetadata\nobject\nNo\n{}\n—\nCaller-provided metadata.\nnormalized_input\nobject\nNo\n{}\n—\nNormalized public input; may contain private prompts or image references. Do not log wholesale.\nobject\nstring\nYes\n—\nenum: \"video_generation\", \"animation_export\", \"animation\"\nPublic task resource type.\noutputs\narray<AssetResponse>\nNo\n[]\n—\nAvailable assets, including partial outputs on failed/cancelled tasks. Always inspect them at a terminal state.\nprogress\nnumber\nYes\n—\nminimum: 0; maximum: 1\nFraction from 0 to 1, not a completion-time estimate.\nstage\nstring / null\nNo\nnull\nenum: \"queued\", \"video_generation\", \"animation_export\", \"completed\"\nCurrent pipeline stage when available.\nstarted_at\nstring / null\nNo\nnull\nformat: date-time\nUTC production start when known.\nstatus\nstring\nYes\n—\nenum: \"queued\", \"running\", \"cancelling\", \"succeeded\", \"failed\", \"cancelled\"\nsucceeded, failed, and cancelled are terminal; cancelling is not terminal.\nUnityOptions\nUnknown fields are rejected.\nField\nType\nRequired\nDefault\nConstraints\nMeaning\npivot\nstring\nNo\n\"bottom_center\"\nconst: \"bottom_center\"\nSupported Unity sprite pivot.\npixels_per_unit\ninteger\nNo\n100\nminimum: 1; maximum: 1000\nUnity texture pixels per world unit.\nUrlImageInput\nUnknown fields are rejected.\nField\nType\nRequired\nDefault\nConstraints\nMeaning\ntype\nstring\nYes\n—\nconst: \"url\"\n—\nurl\nstring\nYes\n—\nminLength: 9; maxLength: 2048\nPublic HTTPS image on port 443, without credentials or fragments. Private networks and unsafe redirects are rejected. Keep bytes stable across retries.\nVideoGenerationCreateRequest\nUnknown fields are rejected.\nField\nType\nRequired\nDefault\nConstraints\nMeaning\ninput\nGenerationInput\nYes\n—\n—\nImages owned by the caller or supplied for this generation.\nmetadata\nobject\nNo\n{}\n—\nCaller metadata: simple string/number/boolean/null values, at most 4 KiB JSON. Do not store secrets.\nnegative_prompt\nstring\nNo\n\"\"\nmaxLength: 4000\nOptional exclusions, only when the model supports negative prompts.\nprompt\nstring\nNo\n\"\"\nmaxLength: 8000\nMotion instruction; nonempty when the model requires a prompt. Keep private prompts out of logs.\nvideo\nVideoOptions\nNo\n{\"duration_seconds\":null,\"input_canvas\":null,\"model\":null,\"ratio\":null,\"resolution\":null,\"seed\":null,\"style_preset\":null,\"transparency\":{\"key_color\":null,\"key_selection\":\"auto\",\"mode\":\"standard\"},\"watermark\":null}\n—\nModel-compatible generation settings.\nVideoGenerationQuoteRequest\nUnknown fields are rejected.\nField\nType\nRequired\nDefault\nConstraints\nMeaning\nhas_last_frame\nboolean\nNo\nfalse\n—\nWhether the planned request includes a last frame.\nreference_image_count\ninteger\nNo\n0\nminimum: 0; maximum: 8\nNumber of additional references, excluding the first frame.\nvideo\nVideoOptions\nNo\n{\"duration_seconds\":null,\"input_canvas\":null,\"model\":null,\"ratio\":null,\"resolution\":null,\"seed\":null,\"style_preset\":null,\"transparency\":{\"key_color\":null,\"key_selection\":\"auto\",\"mode\":\"standard\"},\"watermark\":null}\n—\nGeneration options to estimate; must match the later create.\nVideoOptions\nUnknown fields are rejected.\nField\nType\nRequired\nDefault\nConstraints\nMeaning\nduration_seconds\nnumber / null\nNo\nnull\nexclusiveMinimum: 0\nSeconds; choose a supported duration for the model and resolution. Omission uses its default.\ninput_canvas\nInputCanvasOptions / null\nNo\nnull\n—\nOptional input framing; omit to keep the source framing.\nmodel\nstring / null\nNo\nnull\n—\nprovider:model ID from GET /models; omission uses the configured default model.\nratio\nstring / null\nNo\nnull\n—\nAspect ratio supported by the current model and input mode.\nresolution\nstring / null\nNo\nnull\n—\nResolution value from the live model catalog.\nseed\ninteger / null\nNo\nnull\nminimum: 0; maximum: 2147483647\nOptional seed only for models advertising seed support; not a universal determinism guarantee.\nstyle_preset\nstring / null\nNo\nnull\n—\nOptional style preset supported by the selected provider/model.\ntransparency\nGenerationTransparency\nNo\n{\"key_color\":null,\"key_selection\":\"auto\",\"mode\":\"standard\"}\n—\nSource transparency workflow; transparent exports require alpha_key.\nwatermark\nboolean / null\nNo\nnull\n—\nOptional watermark setting; check the model capability."},{"id":"api-reference.upload-file","locale":"en","title":"Upload image","description":"Source-generated POST /files reference: authentication, fields, responses, errors, and operational safeguards.","section":"api-reference","path":"/docs/en/api-reference/upload-file","url":"https://animgen.com/docs/en/api-reference/upload-file","status":"beta","lastVerified":"2026-08-30","apiVersion":"1.3.0","audience":["api-developer","ai-agent"],"productAreas":["public-api"],"tags":["reference","API","upload-file"],"translations":{"en":"https://animgen.com/docs/en/api-reference/upload-file","zh":"https://animgen.com/docs/zh/api-reference/upload-file"},"headings":[{"id":"operation","title":"Operation","level":2},{"id":"authentication-and-side-effects","title":"Authentication and side effects","level":2},{"id":"parameters","title":"Parameters","level":2},{"id":"request-body-multipart-form-data","title":"Request body (multipart/form-data)","level":2},{"id":"responses","title":"Responses","level":2},{"id":"response-headers","title":"Response headers","level":3},{"id":"response-example","title":"Response example","level":3},{"id":"related-guides","title":"Related guides","level":2}],"text":"Generated from the backend contract. Field names, required flags, constraints, and defaults come from source models. Download the machine-readable source. Examples use placeholder IDs and illustrative values, not live prices, limits, or model availability.\nOperation\nPOST /files\noperationId: create_file_v1_files_post\nUpload PNG, JPEG, or WebP as multipart field file and receive a reusable public file ID. The service validates actual image bytes and dimensions. No generation starts. An upload is not an idempotent paid create; avoid blindly replaying it after a transport error.\nAuthentication and side effects\nUse a server-side Bearer API key. Required scope: animations:write\nThis operation does not start paid generation. Other state changes are described above.\nParameters\nNo path, query, or operation-specific header parameters.\nRequest body (multipart/form-data)\nBody required: true\nField\nType\nRequired\nDefault\nConstraints\nMeaning\nfile\nstring\nYes\n—\nformat: binary\nPNG, JPEG, or WebP image bytes; validated before returning a public file ID.\nFull nested schema: Body_create_file_v1_files_post\nResponses\nHTTP\nBody\nMeaning\n201\nFileResponse\nSuccessful public response. Example values are illustrative.\n400\nAPIErrorEnvelope\nInvalid input; correct the request before retrying.\n401\nAPIErrorEnvelope\nMissing, expired, or revoked API key.\n403\nAPIErrorEnvelope\nAccount eligibility, account status, or key scope does not allow this operation.\n404\nAPIErrorEnvelope\nResource is unavailable, not owned, or its signature is invalid/expired.\n413\nAPIErrorEnvelope\nRequest or decoded image exceeds the configured limit.\n415\nAPIErrorEnvelope\nUse supported image media types.\n422\nAPIErrorEnvelope\nDecoded image dimensions exceed the allowed size.\n429\nAPIErrorEnvelope\nAccount-wide rate or queue limit; wait for Retry-After.\n500\nAPIErrorEnvelope\nInternal failure; preserve the task/key and retry only when marked retryable.\n503\nAPIErrorEnvelope\nService/provider unavailable; retry only when error.retryable is true.\nResponse headers\nHTTP\nHeader\nType\nMeaning\n429\nRetry-After\ninteger\nSuggested wait in seconds; respect the server value and an overall deadline.\n503\nRetry-After\ninteger\nSuggested wait in seconds; respect the server value and an overall deadline.\nResponse example\nRelated guides\nPolling and downloads · Errors and safe retries"},{"id":"api.authentication-and-inputs","locale":"en","title":"Authentication and image inputs","description":"Keep API credentials server-side, choose the correct key scopes, and send images as reusable files, Base64, or safe public HTTPS URLs.","section":"api","path":"/docs/en/api/authentication-and-inputs","url":"https://animgen.com/docs/en/api/authentication-and-inputs","status":"beta","lastVerified":"2026-08-31","apiVersion":"1.3.0","audience":["api-developer","ai-agent"],"productAreas":["public-api"],"tags":["authentication","API key","upload","Base64","URL","file_id"],"translations":{"en":"https://animgen.com/docs/en/api/authentication-and-inputs","zh":"https://animgen.com/docs/zh/api/authentication-and-inputs"},"headings":[{"id":"authenticate-from-a-trusted-environment","title":"Authenticate from a trusted environment","level":2},{"id":"option-a-upload-once-reuse-a-file-id","title":"Option A: upload once, reuse a file ID","level":2},{"id":"option-b-inline-base64","title":"Option B: inline Base64","level":2},{"id":"option-c-public-https-url","title":"Option C: public HTTPS URL","level":2},{"id":"match-the-selected-model","title":"Match the selected model","level":2}],"text":"Authenticate from a trusted environment\nUse Authorization: Bearer <API_KEY> on Public API requests. Keys are shown in plaintext only when created in Account → Developer. Keep them in a secret store, rotate by updating callers before revoking the old key, and avoid logging request headers.\nA 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.\nPublic API key scope\nOperations\nanimations:read\nAccount, credits, models, task reads/lists, and asset lookup\nanimations:write\nUpload files, obtain quotes, create tasks, and request cancellation\nMCP uses OAuth and different, finer-grained scopes. Do not apply the API key scope table to MCP.\nOption A: upload once, reuse a file ID\nThe 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:\nThe 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.\nOption B: inline Base64\nUse 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.\nThe Base64 content is persisted before a creation is accepted. Preserve the same bytes when retrying an idempotent request.\nOption C: public HTTPS URL\nReplace 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.\nKeep 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.\nMatch the selected model\nEvery 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.\nUse GET /models for valid modes and settings, and quote the full intended request before creation. For transparent sources, follow transparent animation. Then continue to the quickstart."},{"id":"api.errors-and-retries","locale":"en","title":"Errors, idempotency, and safe retries","description":"Distinguish correctable errors from temporary failures, preserve one logical request across retries, and troubleshoot without exposing secrets.","section":"api","path":"/docs/en/api/errors-and-retries","url":"https://animgen.com/docs/en/api/errors-and-retries","status":"beta","lastVerified":"2026-08-31","apiVersion":"1.3.0","audience":["api-developer","ai-agent"],"productAreas":["public-api"],"tags":["error","retry","429","idempotency","request_id"],"translations":{"en":"https://animgen.com/docs/en/api/errors-and-retries","zh":"https://animgen.com/docs/zh/api/errors-and-retries"},"headings":[{"id":"keep-a-logical-operation-stable","title":"Keep a logical operation stable","level":2},{"id":"read-the-error-envelope","title":"Read the error envelope","level":2},{"id":"choose-a-response","title":"Choose a response","level":2},{"id":"bound-every-retry-loop","title":"Bound every retry loop","level":2},{"id":"account-limits-and-diagnosis","title":"Account limits and diagnosis","level":2}],"text":"Keep a logical operation stable\nPaid 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.\nThe 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.\nDeduplication 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.\nIf 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.\nRead the error envelope\nThis 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.\nChoose a response\nHTTP / common code\nAction\n400 INVALID_REQUEST, INVALID_BASE64, INVALID_IMAGE\nFix input; do not retry unchanged\n401 INVALID_API_KEY\nCheck missing, expired, or revoked key\n402 INSUFFICIENT_CREDITS\nReview balance and quote; do not auto-purchase\n403 API_ACCOUNT_NOT_ELIGIBLE, API_ACCOUNT_PAUSED, INSUFFICIENT_SCOPE\nResolve verification, account status, or permissions\n404 NOT_FOUND\nCheck public resource ID and ownership\n409 IDEMPOTENCY_CONFLICT\nStop; same key was used with different input\n409 IDEMPOTENCY_IN_PROGRESS\nIf retryable, wait and reuse the original request\n413 PAYLOAD_TOO_LARGE, 415 UNSUPPORTED_MEDIA_TYPE, 422 IMAGE_DIMENSIONS_TOO_LARGE\nCorrect image size, encoding, or type\n429 RATE_LIMITED, QUEUE_LIMIT_EXCEEDED\nRespect Retry-After; account-wide limits apply\n503 API_DISABLED, API_UNAVAILABLE, PROVIDER_UNAVAILABLE\nRetry only if marked retryable; otherwise stop and check availability\nResource ownership errors can intentionally look like not-found responses. Do not probe other users' IDs.\nBound every retry loop\nRespect 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.\nRetry 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.\nWhen 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.\nAccount limits and diagnosis\nPROVIDER_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.\nRead 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.\nFor 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 for incomplete results and the Python example for bounded retries."},{"id":"api.examples","locale":"en","title":"Runnable examples in four languages","description":"Download safe Python, TypeScript, cURL, and C# workflows with quote-only preparation, persistent idempotency, resumable polling, and actual asset downloads.","section":"api","path":"/docs/en/api/examples","url":"https://animgen.com/docs/en/api/examples","status":"beta","lastVerified":"2026-08-31","apiVersion":"1.3.0","audience":["api-developer","ai-agent"],"productAreas":["public-api"],"tags":["Python","TypeScript","C#","curl","examples","idempotency"],"translations":{"en":"https://animgen.com/docs/en/api/examples","zh":"https://animgen.com/docs/zh/api/examples"},"headings":[{"id":"choose-a-workflow","title":"Choose a workflow","level":2},{"id":"prepare-without-starting-paid-work","title":"Prepare without starting paid work","level":2},{"id":"keep-state-private-and-recover-the-same-operation","title":"Keep state private and recover the same operation","level":2},{"id":"what-was-tested","title":"What was tested","level":2}],"text":"Choose a workflow\nEach 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.\nLanguage\nDownload\nRequirements\nValidation\nPython\nanimation-workflow.py\nPython 3.10+, standard library\nOffline workflow tests\nTypeScript\ntypescript.ts\nNode.js 22.14+\nStrict types and offline workflow tests\ncURL\ncurl.sh\nBash, curl 7.55+, jq, SHA-256 utility; PNG input\nShell syntax and local HTTP Mock\nC#\ncsharp.cs + project file\n.NET 8 SDK\nSyntax parsing only; no .NET SDK on the validation host\nRead the complete sample README and API quickstart first. The generated API reference is the authoritative parameter reference.\nPrepare without starting paid work\nKeep 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.\nChoose exactly one command for your language:\nFor Python, use the separate prepare and run commands in the 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.\nThis 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.\nKeep state private and recover the same operation\nTypeScript 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.\nState 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.\nAfter 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.\nAfter 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.\nWhat was tested\nPython, 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.\nSee errors and retries and polling and downloads when adapting these examples."},{"id":"api.polling-and-downloads","locale":"en","title":"Poll tasks and download every usable output","description":"Handle asynchronous states, credit accounting, partial outputs, cancellation, and expiring signed asset URLs without leaking credentials.","section":"api","path":"/docs/en/api/polling-and-downloads","url":"https://animgen.com/docs/en/api/polling-and-downloads","status":"beta","lastVerified":"2026-08-31","apiVersion":"1.3.0","audience":["api-developer","ai-agent"],"productAreas":["public-api"],"tags":["polling","Retry-After","outputs","asset","download","cancel"],"translations":{"en":"https://animgen.com/docs/en/api/polling-and-downloads","zh":"https://animgen.com/docs/zh/api/polling-and-downloads"},"headings":[{"id":"a-create-response-is-not-a-finished-animation","title":"A create response is not a finished animation","level":2},{"id":"states-and-stages","title":"States and stages","level":2},{"id":"partial-outputs-matter","title":"Partial outputs matter","level":2},{"id":"download-securely","title":"Download securely","level":2},{"id":"cancellation","title":"Cancellation","level":2},{"id":"review-before-exporting-two-step-flow","title":"Review before exporting: two-step flow","level":2}],"text":"A create response is not a finished animation\nPOST /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.\nPoll 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.\nStates and stages\nState\nWhat the caller should do\nqueued\nWait; a worker has not completed the task\nrunning\nContinue polling; inspect stage and progress\ncancelling\nCancellation requested, not final; continue polling\nsucceeded\nTerminal; inspect and download outputs\nfailed\nTerminal; inspect error and any outputs\ncancelled\nTerminal; inspect any completed outputs and credit accounting\nstage 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.\ncredits.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.\nPartial outputs matter\nA 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.\nDownload 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.\nDownload securely\nEach asset has id, format, mime_type, byte_size, download_url, and download_expires_at.\nSave a task or asset ID for durable application state.\nUse the returned signed URL to download the bytes.\nDo not attach the API Bearer header to the signed URL or a redirected storage host.\nSave to an application-chosen filename and verify the download completed.\nIf the link expired, call GET /assets/{asset_id} with your API key to request a fresh link.\nLinks 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.\nTreat signed URLs as temporary credentials: do not publish them in logs, analytics, issue trackers, or AI conversation transcripts.\nCancellation\nUse 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.\nProduction already performed can remain charged. Unspent holds can be released; inspect the returned credit usage rather than promising a full refund.\nReview before exporting: two-step flow\nUse 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}.\nQuote 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 demonstrates the simpler one-click lifecycle."},{"id":"api.quickstart","locale":"en","title":"API quickstart: image to downloaded assets","description":"Create your first API animation safely: discover models, prepare an image, review a quote, submit once, poll, and save the resulting files.","section":"api","path":"/docs/en/api/quickstart","url":"https://animgen.com/docs/en/api/quickstart","status":"beta","lastVerified":"2026-08-31","apiVersion":"1.3.0","audience":["api-developer","ai-agent"],"productAreas":["public-api"],"tags":["quickstart","Python","curl","quote","idempotency"],"translations":{"en":"https://animgen.com/docs/en/api/quickstart","zh":"https://animgen.com/docs/zh/api/quickstart"},"headings":[{"id":"prerequisites","title":"Prerequisites","level":2},{"id":"1-discover-a-supported-model","title":"1. Discover a supported model","level":2},{"id":"2-prepare-and-quote-without-generating","title":"2. Prepare and quote without generating","level":2},{"id":"3-explicitly-approve-creation","title":"3. Explicitly approve creation","level":2},{"id":"4-resume-safely-and-inspect-the-result","title":"4. Resume safely and inspect the result","level":2},{"id":"what-the-request-does","title":"What the request does","level":2}],"text":"Prerequisites\nThe 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.\nCreate a key in 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.\nThe base URL is https://api.animgen.com/v1. The URL compatibility version is v1; the documented schema version is 1.3.0.\n1. Discover a supported model\nChoose 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.\nFor 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.\n2. Prepare and quote without generating\nDownload and inspect the Python workflow example. It uses Python 3.10+ and only the standard library.\nReplace 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.\nThe 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.\n3. Explicitly approve creation\nReview the quoted credits and set APPROVED_CREDITS to the amount you accept. Then run:\nThe 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.\nThe 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 through a separate OAuth tool workflow.\n4. Resume safely and inspect the result\nIf 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.\nDo 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.\nAt 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.\nWhat the request does\nThe 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.\nTo use reusable uploads or a public URL, read authentication and image inputs. For lifecycle handling, read polling and downloads and errors and retries. The exact contract is available in OpenAPI JSON.\nThe 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; exact parameters are generated in the API reference."},{"id":"editing-and-export.advanced-editor","locale":"en","title":"Fine-tune frames in Advanced Editor","description":"Build a non-destructive animation sequence from source frames, adjust playback, save the recipe, and export a revision you have checked.","section":"editing-and-export","path":"/docs/en/editing-and-export/advanced-editor","url":"https://animgen.com/docs/en/editing-and-export/advanced-editor","status":"preview","lastVerified":"2026-08-30","audience":["user","game-developer"],"productAreas":["editor","export"],"tags":["Advanced Editor","Fine-tune animation","精修","选帧","sequence","autosave"],"translations":{"en":"https://animgen.com/docs/en/editing-and-export/advanced-editor","zh":"https://animgen.com/docs/zh/editing-and-export/advanced-editor"},"headings":[{"id":"open-the-current-editor","title":"Open the current editor","level":2},{"id":"understand-the-five-panels","title":"Understand the five panels","level":2},{"id":"build-a-sequence","title":"Build a sequence","level":2},{"id":"control-timing-and-check-a-concrete-example","title":"Control timing and check a concrete example","level":2},{"id":"save-before-leaving-or-exporting","title":"Save before leaving or exporting","level":2},{"id":"current-boundaries","title":"Current boundaries","level":2}],"text":"Open the current editor\nFrom 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.\nYour 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.\nUnderstand the five panels\nPanel\nPurpose\nSource Monitor\nInspect the original video at its own playhead\nAnimation Preview\nPlay the output sequence, canvas, and timing\nSource Frames\nChoose frames from the decoded source\nAnimation Sequence\nArrange the frames that will be exported\nCanvas Inspector\nSet global canvas, placement, and pivot\nThe 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.\nBuild a sequence\nClick a source thumbnail; Shift-click extends a range and Ctrl/⌘-click toggles individual selections.\nUse Insert at the sequence playhead, Append at the end, or drag source frames into the sequence.\nSelect output frames to move, duplicate, or remove them. Group selections preserve their order when moved.\nDuplicate repeats each selected item beside itself; it can make a pose hold longer.\nReverse reverses the entire sequence, not only the current selection.\nUse the Undo/Redo buttons to correct recent edits in this editing session.\nThe 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.\nControl timing and check a concrete example\nOutput 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.\nChanging 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.\nSource-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.\nSave before leaving or exporting\nChanges 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.\nUse 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.\nExport 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.\nCurrent boundaries\nThe 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.\nContinue with canvas and pivot, output formats, and export troubleshooting."},{"id":"editing-and-export.canvas-and-pivot","locale":"en","title":"Set output canvas, alignment, and pivot","description":"Place the same source sequence on a consistent canvas and carry the intended origin into exported sprites and game-engine resources.","section":"editing-and-export","path":"/docs/en/editing-and-export/canvas-and-pivot","url":"https://animgen.com/docs/en/editing-and-export/canvas-and-pivot","status":"preview","lastVerified":"2026-08-30","audience":["user","game-developer"],"productAreas":["editor","export"],"tags":["canvas","pivot","anchor","画布","锚点","alignment","contain","cover"],"translations":{"en":"https://animgen.com/docs/en/editing-and-export/canvas-and-pivot","zh":"https://animgen.com/docs/zh/editing-and-export/canvas-and-pivot"},"headings":[{"id":"canvas-changes-pixels-pivot-changes-the-origin","title":"Canvas changes pixels; pivot changes the origin","level":2},{"id":"choose-a-consistent-frame-canvas","title":"Choose a consistent frame canvas","level":2},{"id":"pick-a-pivot-deliberately","title":"Pick a pivot deliberately","level":2},{"id":"read-the-exported-coordinate-conventions","title":"Read the exported coordinate conventions","level":2},{"id":"verify-before-delivery","title":"Verify before delivery","level":2}],"text":"Canvas changes pixels; pivot changes the origin\nIn 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.\nThis is separate from input canvas, which prepares source images before AI generation. Output placement reuses existing motion.\nChoose a consistent frame canvas\nThe 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.\nChoose 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.\nCharacter setting\nEffect\nCenter / Bottom center\nGlobal alignment of the source on the canvas\nContain\nFit the whole image inside the canvas; may leave space\nCover\nFill the canvas; parts of the image can be cropped\nOriginal pixels\nStart from the source's original pixel size\nScale\nAdditional global scaling, 0.1–3\nX / Y offset\nGlobal displacement in output pixels\nScrub 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.\nPick a pivot deliberately\nPivot coordinates range from 0 to 1 and use a bottom-left origin:\nDesired origin\nX\nY\nBottom center\n0.5\n0\nCenter\n0.5\n0.5\nBottom left\n0\n0\nFor 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.\nRead the exported coordinate conventions\nanimgen-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.\nFrame 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.\nUnity 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.\nVerify before delivery\nCheck 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.\nFor 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 before paying for another generation."},{"id":"editing-and-export.cocos-creator","locale":"en","title":"Import an animation into Cocos Creator 3","description":"Import the PNG and PLIST atlas together, attach the generated sprite player, and handle multiple animations without duplicating component classes.","section":"editing-and-export","path":"/docs/en/editing-and-export/cocos-creator","url":"https://animgen.com/docs/en/editing-and-export/cocos-creator","status":"stable","lastVerified":"2026-08-30","audience":["user","game-developer","api-developer","ai-agent"],"productAreas":["export"],"tags":["Cocos Creator","cocos_creator_pack","SpriteAtlas","plist","AnimGenSpritePlayer","UITransform"],"translations":{"en":"https://animgen.com/docs/en/editing-and-export/cocos-creator","zh":"https://animgen.com/docs/zh/editing-and-export/cocos-creator"},"headings":[{"id":"understand-the-exported-files","title":"Understand the exported files","level":2},{"id":"import-the-atlas-together","title":"Import the atlas together","level":2},{"id":"configure-the-player","title":"Configure the player","level":2},{"id":"reuse-one-component-for-multiple-exports","title":"Reuse one component for multiple exports","level":2},{"id":"verify-the-result","title":"Verify the result","level":2}],"text":"Understand the exported files\nChoose cocos_creator_pack. The ZIP contains spritesheet.png, spritesheet.plist, AnimGenSpritePlayer.ts, animgen-manifest.json, and README.\nThe 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.\nImport the atlas together\nKeep 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.\nImport the player script and wait for compilation. Create a Sprite node, attach AnimGenSpritePlayer, then assign the imported SpriteAtlas to its atlas property.\nConfigure the player\nProperty\nBehavior\natlas\nSource of the frame sprites\nfps\nPlayback speed, initially the export's FPS\nloop\nRepeat or stop at the last frame\nplayOnLoad\nBegin playback when loaded\napplyExportedPivot\nSet UITransform's anchor to the pivot embedded in this script\nThe 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.\nReuse one component for multiple exports\nEach package uses the same AnimGenSpritePlayer class name. Do not import a second copy of that class for every animation in one project.\nReuse 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.\nVerify the result\nMatch 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.\nIf 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.\nFor 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 and transparent formats.\nThe generated example targets Cocos Creator 3.x. Package checks do not replace importing and running it in your exact editor and target build."},{"id":"editing-and-export.godot","locale":"en","title":"Import an animation into Godot 4","description":"Keep the Godot pack's resource paths intact, use its SpriteFrames and ready-to-play scene, and preserve the intended FPS and pivot offset.","section":"editing-and-export","path":"/docs/en/editing-and-export/godot","url":"https://animgen.com/docs/en/editing-and-export/godot","status":"stable","lastVerified":"2026-08-30","audience":["user","game-developer","api-developer","ai-agent"],"productAreas":["export"],"tags":["Godot","Godot 4","godot_pack","SpriteFrames","AnimatedSprite2D","res://"],"translations":{"en":"https://animgen.com/docs/en/editing-and-export/godot","zh":"https://animgen.com/docs/zh/editing-and-export/godot"},"headings":[{"id":"what-the-pack-includes","title":"What the pack includes","level":2},{"id":"preserve-the-root-path","title":"Preserve the root path","level":2},{"id":"choose-a-ready-scene-or-an-existing-node","title":"Choose a ready scene or an existing node","level":2},{"id":"verify-timing-and-alignment","title":"Verify timing and alignment","level":2},{"id":"reuse-safely","title":"Reuse safely","level":2}],"text":"What the pack includes\nExport godot_pack to get spritesheet.png, animation.tres, animation.tscn, animgen-manifest.json, and README in a named root folder.\nThe .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.\nPreserve the root path\nExtract the package and copy its named root folder into the root of the Godot project. Its README gives the expected res://<exported-folder>/ path.\nThe 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.\nWait for Godot to import the PNG. Then open animation.tscn or instance it in a small test scene.\nChoose a ready scene or an existing node\nFor the shortest path, use the supplied scene. For an existing AnimatedSprite2D, assign animation.tres to Sprite Frames, choose the exported animation, and configure playback.\nGodot's 2D sprite animation guide 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.\nAssigning 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.\nVerify timing and alignment\nCompare 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.\nIf 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.\nIf edges look different from Studio, inspect the target texture filter and rendering settings using the same PNG baseline. See transparent formats.\nReuse safely\nKeep 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.\nDo 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."},{"id":"editing-and-export.output-formats","locale":"en","title":"Choose an output format","description":"Compare video, PNG frames, spritesheet metadata, and engine packages, including transparency and entitlement requirements.","section":"editing-and-export","path":"/docs/en/editing-and-export/output-formats","url":"https://animgen.com/docs/en/editing-and-export/output-formats","status":"stable","lastVerified":"2026-08-30","audience":["user","api-developer"],"productAreas":["export"],"tags":["formats","spritesheet","Unity","Godot","Unreal","Cocos","WebM","ProRes"],"translations":{"en":"https://animgen.com/docs/en/editing-and-export/output-formats","zh":"https://animgen.com/docs/zh/editing-and-export/output-formats"},"headings":[{"id":"start-with-the-destination","title":"Start with the destination","level":2},{"id":"format-guide","title":"Format guide","level":2},{"id":"transparency-is-a-source-and-format-contract","title":"Transparency is a source-and-format contract","level":2},{"id":"import-engine-packages-intact","title":"Import engine packages intact","level":2},{"id":"credits-access-and-downloads","title":"Credits, access, and downloads","level":2},{"id":"finish-the-import-in-your-engine","title":"Finish the import in your engine","level":2}],"text":"Start with the destination\nFor 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.\nThe 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.\nFormat guide\nAPI format\nWhat you receive\nTypical use\nclip_video\nSelected MP4 clip; opaque\nReview, ordinary video playback\nwebm_alpha\nWebM with alpha\nCompatible alpha-video players; test target support\nprores_4444\nProRes 4444 with alpha\nCompositing and video editing\nframes_zip\nZIP of PNG frames\nInspect individual frames or custom import\nspritesheet\nPNG texture atlas\nA single packed texture\nspritesheet_json\nMatching frame metadata\nFrame rectangles and timing\nunity_meta\nUnity texture metadata\nPair with the matching spritesheet\nunity_pack\nUnity-oriented ZIP\nAtlas, metadata, JSON, manifest, instructions\ngodot_pack\nGodot 4-oriented ZIP\nSpriteFrames and AnimatedSprite2D resources\nunreal_paper2d_pack\nUnreal Paper2D-oriented ZIP\nPNG atlas and Paper2D sprite description\ncocos_creator_pack\nCocos Creator 3.x-oriented ZIP\nPNG/PLIST atlas and example player\nMetadata 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.\nTransparency is a source-and-format contract\nOrdinary MP4 and the raw generated video remain opaque. Transparent PNGs, atlases, engine resources, WebM Alpha, and ProRes 4444 require appropriate source and export settings.\nThe Public API supports transparency only for Alpha Key sources. It does not remove arbitrary backgrounds. See transparent animation.\nA 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.\nImport engine packages intact\nEngine 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.\nFrame 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.\nCredits, access, and downloads\nFree 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.\nFiles are exposed as assets with short-lived signed download links. Save the file, not the URL. API callers should follow polling and downloads.\nFinish the import in your engine\nContinue with Unity, Godot 4, Unreal Paper2D, or Cocos Creator 3. Each guide matches the actual package files, paths, and playback helpers; it does not imply every engine has been runtime-tested.\nSee canvas and pivot for placement and transparent format compatibility for video compositing."},{"id":"editing-and-export.transparent-formats","locale":"en","title":"Transparent formats and playback compatibility","description":"Choose PNGs, sprites, WebM Alpha, or ProRes 4444, and distinguish source transparency, encoded Alpha, and actual playback support.","section":"editing-and-export","path":"/docs/en/editing-and-export/transparent-formats","url":"https://animgen.com/docs/en/editing-and-export/transparent-formats","status":"stable","lastVerified":"2026-08-30","audience":["user","game-developer"],"productAreas":["editor","export"],"tags":["Alpha","WebM","VP8","ProRes 4444","PNG","透明","兼容性"],"translations":{"en":"https://animgen.com/docs/en/editing-and-export/transparent-formats","zh":"https://animgen.com/docs/zh/editing-and-export/transparent-formats"},"headings":[{"id":"transparency-has-three-checkpoints","title":"Transparency has three checkpoints","level":2},{"id":"select-a-format-for-the-destination","title":"Select a format for the destination","level":2},{"id":"diagnose-with-the-same-frames","title":"Diagnose with the same frames","level":2},{"id":"inspect-edges-not-just-the-empty-corners","title":"Inspect edges, not just the empty corners","level":2},{"id":"budget-and-deliverables","title":"Budget and deliverables","level":2}],"text":"Transparency has three checkpoints\nA 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.\nFor 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.\nSelect a format for the destination\nOutput\nCurrent encoding or structure\nHow to verify\nPNG frames ZIP\nIndividual RGBA frames\nInspect representative frames on light and dark backgrounds\nSpritesheet / engine pack\nPNG plus frame/engine metadata\nCheck texture Alpha and the engine's material/import settings\nWebM Alpha\nVP8 with Alpha metadata\nTest the actual browser, OS, device, and decoder used by the app\nProRes 4444\nAlpha-capable ProRes in MOV\nUse an editor/compositor that supports this profile\nClip MP4 / original video\nOpaque video\nDo not expect transparency from this file\nThe 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.\nFile 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.\nDiagnose with the same frames\nSelect a small representative range containing motion and fine edges.\nExport PNG frames alongside the destination format when your entitlement and quote permit.\nCompare the same frame on white, dark gray, and a contrasting color.\nIf the PNG has correct Alpha but the video/player does not, investigate decoding or compositing before regenerating motion.\nIf all outputs have the same opaque region, inspect source mode, export transparency, canvas background, and source Alpha.\nA checkerboard baked into the source image is not transparency. Likewise, merely choosing a transparent output canvas cannot remove an opaque background inside each frame.\nInspect edges, not just the empty corners\nCheck 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.\nUse 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.\nAn 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.\nBudget and deliverables\nAdvanced 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.\nContinue with output formats and transparent export troubleshooting. The documentation does not certify every browser or engine version; validate your actual target environment."},{"id":"editing-and-export.trim-and-export","locale":"en","title":"Trim a clip and export assets","description":"Select the useful interval, balance frame count and resolution, review the export quote, and locate completed downloads.","section":"editing-and-export","path":"/docs/en/editing-and-export/trim-and-export","url":"https://animgen.com/docs/en/editing-and-export/trim-and-export","status":"stable","lastVerified":"2026-08-30","audience":["user","api-developer"],"productAreas":["studio","export"],"tags":["trim","loop","FPS","download"],"translations":{"en":"https://animgen.com/docs/en/editing-and-export/trim-and-export","zh":"https://animgen.com/docs/zh/editing-and-export/trim-and-export"},"headings":[{"id":"generation-and-export-are-separate-steps","title":"Generation and export are separate steps","level":2},{"id":"pick-an-interval","title":"Pick an interval","level":2},{"id":"set-frame-rate-and-size","title":"Set frame rate and size","level":2},{"id":"confirm-the-export","title":"Confirm the export","level":2},{"id":"find-the-files","title":"Find the files","level":2},{"id":"the-equivalent-api-flow","title":"The equivalent API flow","level":2},{"id":"when-a-continuous-trim-is-not-enough","title":"When a continuous trim is not enough","level":2}],"text":"Generation and export are separate steps\nGeneration 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.\nIn 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.\nPick an interval\nPlay 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.\nA loop is only as seamless as its content. Trimming and repeating do not synthesize a matching end pose.\nSet frame rate and size\nChoose 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.\nMore 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.\nConfirm the export\nSelect Export, then:\nChoose one or more output formats.\nReview the transparency controls when relevant.\nCheck the displayed frame count, dimensions, entitlement, and credit quote.\nSelect Start export once and follow the job status.\nIf the format is locked, check credits and access. If the quote cannot be estimated, do not treat the missing number as zero.\nFind the files\nIn 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.\nIf 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.\nThe equivalent API flow\nThe one-click API defaults to the full source interval. A range uses seconds:\nThe 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.\nWhen a continuous trim is not enough\nUse 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."},{"id":"editing-and-export.unity","locale":"en","title":"Import an animation into Unity","description":"Import the Unity pack with its texture metadata intact, build a sprite animation, and verify frame order, scale, pivot, and transparency.","section":"editing-and-export","path":"/docs/en/editing-and-export/unity","url":"https://animgen.com/docs/en/editing-and-export/unity","status":"stable","lastVerified":"2026-08-30","audience":["user","game-developer","api-developer","ai-agent"],"productAreas":["export"],"tags":["Unity","unity_pack","meta","Sprite Editor","Animator","导入"],"translations":{"en":"https://animgen.com/docs/en/editing-and-export/unity","zh":"https://animgen.com/docs/zh/editing-and-export/unity"},"headings":[{"id":"export-the-unity-pack","title":"Export the Unity pack","level":2},{"id":"import-texture-and-metadata-together","title":"Import texture and metadata together","level":2},{"id":"create-the-animation-you-need","title":"Create the animation you need","level":2},{"id":"verify-in-a-small-scene","title":"Verify in a small scene","level":2},{"id":"keep-a-reproducible-handoff","title":"Keep a reproducible handoff","level":2}],"text":"Export the Unity pack\nChoose unity_pack in the export dialog or public request. Review the export entitlement and quote, wait for the export, and download the ZIP's bytes.\nThe 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.\nImport texture and metadata together\nCopy 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.\nSelect 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.\nDo 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.\nCreate the animation you need\nThe 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.\nMatch 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.\nVerify in a small scene\nCheck 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.\nIf 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.\nKeep a reproducible handoff\nRetain 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.\nThese 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 and transparent formats if the visual result differs."},{"id":"editing-and-export.unreal-paper2d","locale":"en","title":"Import an animation into Unreal Paper2D","description":"Import the Paper2D sprite descriptor with its padded texture, create or inspect the Flipbook, and match frame rate, origin, and material behavior.","section":"editing-and-export","path":"/docs/en/editing-and-export/unreal-paper2d","url":"https://animgen.com/docs/en/editing-and-export/unreal-paper2d","status":"stable","lastVerified":"2026-08-30","audience":["user","game-developer","api-developer","ai-agent"],"productAreas":["export"],"tags":["Unreal","Paper2D","Flipbook","unreal_paper2d_pack","paper2dsprites","导入"],"translations":{"en":"https://animgen.com/docs/en/editing-and-export/unreal-paper2d","zh":"https://animgen.com/docs/zh/editing-and-export/unreal-paper2d"},"headings":[{"id":"export-the-matching-package","title":"Export the matching package","level":2},{"id":"import-the-descriptor-not-just-the-png","title":"Import the descriptor, not just the PNG","level":2},{"id":"match-the-animation-settings","title":"Match the animation settings","level":2},{"id":"check-transparent-edges-and-padding","title":"Check transparent edges and padding","level":2},{"id":"common-fixes-before-regenerating","title":"Common fixes before regenerating","level":2}],"text":"Export the matching package\nChoose 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.\nThe 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.\nImport the descriptor, not just the PNG\nEnable 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.\nThe 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.\nImporting 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.\nMatch the animation settings\nOpen 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.\nKeep 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.\nCheck 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.\nCheck transparent edges and padding\nUse 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.\nDo 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.\nCommon fixes before regenerating\nIf 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.\nKeep 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."},{"id":"getting-started.first-animation","locale":"en","title":"Your first animation in the Studio","description":"A five-minute setup guide: upload an image, generate a preview, select a useful range, and download your first animation assets.","section":"getting-started","path":"/docs/en/getting-started/first-animation","url":"https://animgen.com/docs/en/getting-started/first-animation","status":"stable","lastVerified":"2026-08-30","audience":["user","api-developer"],"productAreas":["studio"],"tags":["beginner","upload","preview","export"],"translations":{"en":"https://animgen.com/docs/en/getting-started/first-animation","zh":"https://animgen.com/docs/zh/getting-started/first-animation"},"headings":[{"id":"before-you-start","title":"Before you start","level":2},{"id":"1-add-your-starting-image","title":"1. Add your starting image","level":2},{"id":"2-choose-a-background-workflow","title":"2. Choose a background workflow","level":2},{"id":"3-describe-the-motion-and-check-the-quote","title":"3. Describe the motion and check the quote","level":2},{"id":"4-review-the-result","title":"4. Review the result","level":2},{"id":"5-export-and-download","title":"5. Export and download","level":2},{"id":"what-next","title":"What next?","level":2}],"text":"Before you start\nOpen the Studio 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 first.\nThis 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.\n1. Add your starting image\nIn 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.\nFor 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.\n2. Choose a background workflow\nRegular image animation keeps the scene background and works with ordinary images.\nTransparent asset animation requires meaningful alpha in every active input image. A checkerboard painted into an opaque PNG is not transparency.\nChoose regular mode if you are unsure. Read regular and transparent animation before preparing transparent game assets.\n3. Describe the motion and check the quote\nChoose a model and the duration, resolution, and aspect ratio offered by its controls. Model options vary; the currently displayed choices are authoritative.\nA useful first prompt is:\nKeep the first request simple. A prompt asking for many actions, scene changes, and camera movements makes a clean loop harder to select.\nCheck 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.\n4. Review the result\nThe left project panel groups the source video and its exports. When generation completes, inspect the preview on the right.\nCheck 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.\n5. Export and download\nSet 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.\nReview 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.\nA preview is not an exported asset. Seeing the video play does not mean the PNGs or engine package have been created.\nWhat next?\nUse trim and export for frame selection, output formats to pick deliverables, and credits and access if an action is locked.\nIf generation or export fails, inspect the existing result before starting another paid request. The FAQ explains common symptoms."},{"id":"getting-started.overview","locale":"en","title":"Understand the animation workflow","description":"Choose between generating motion and exporting existing video, and understand where transparent assets are created.","section":"getting-started","path":"/docs/en/getting-started/overview","url":"https://animgen.com/docs/en/getting-started/overview","status":"stable","lastVerified":"2026-08-30","audience":["user"],"productAreas":["studio"],"tags":["workflow","generation","export"],"translations":{"en":"https://animgen.com/docs/en/getting-started/overview","zh":"https://animgen.com/docs/zh/getting-started/overview"},"headings":[{"id":"before-you-start","title":"Before you start","level":2},{"id":"generation-and-export-are-separate","title":"Generation and export are separate","level":2},{"id":"choose-the-right-transparency-mode","title":"Choose the right transparency mode","level":2},{"id":"check-the-result","title":"Check the result","level":2},{"id":"when-something-does-not-work","title":"When something does not work","level":2}],"text":"Before you start\nHave an image you are allowed to use, or an existing video to export. Open the Studio and sign in to create real tasks. The demo uses prepared examples to let you try the interaction without spending credits.\nGeneration and export are separate\nChoose a source image and describe the motion you want.\nGenerate a video preview with the model and options available in your account.\nReview the video and choose the useful start and end points.\nExport the selected motion as image frames, a sprite sheet, video, or an engine package supported by your plan.\nIf 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.\nChoose the right transparency mode\nSource and goal\nWorkflow\nOrdinary artwork or an opaque scene\nStandard animation\nIsolated PNG artwork with meaningful alpha\nTransparent animation\nExisting video that needs frames or a sprite sheet\nImport video and export\nTransparent 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.\nCheck the result\nPreview 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.\nFor integrations, the same high-level sequence is:\nWhen something does not work\nRead 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.\nLearn about the current Public API, or return to the documentation home."},{"id":"getting-started.workspaces-and-assets","locale":"en","title":"Organize workspaces, tasks, and assets","description":"Separate project organization from task history and stored files, reuse owned sources, and understand what workspace deletion and restoration actually do.","section":"getting-started","path":"/docs/en/getting-started/workspaces-and-assets","url":"https://animgen.com/docs/en/getting-started/workspaces-and-assets","status":"stable","lastVerified":"2026-08-30","audience":["user","api-developer","ai-agent"],"productAreas":["studio","resources"],"tags":["workspace","asset","resource","job","工作区","资源","恢复"],"translations":{"en":"https://animgen.com/docs/en/getting-started/workspaces-and-assets","zh":"https://animgen.com/docs/zh/getting-started/workspaces-and-assets"},"headings":[{"id":"three-things-with-different-lifecycles","title":"Three things with different lifecycles","level":2},{"id":"organize-before-creating","title":"Organize before creating","level":2},{"id":"reuse-sources-and-name-results","title":"Reuse sources and name results","level":2},{"id":"delete-and-restore-a-workspace-deliberately","title":"Delete and restore a workspace deliberately","level":2},{"id":"before-removing-source-files","title":"Before removing source files","level":2}],"text":"Three things with different lifecycles\nItem\nWhat it represents\nWorkspace\nA way to organize your Studio work\nTask / job\nOne asynchronous generation, import, or export operation\nResource / asset\nAn uploaded source or a produced file\nA 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.\nOrganize before creating\nUse 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.\nA 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.\nReuse sources and name results\nCompatible 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 references the source video; it does not contain an independent copy of every frame.\nUse 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.\nPublic 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.\nDelete and restore a workspace deliberately\nDeleting 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.\nUse 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.\nWorkspace 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.\nBefore removing source files\nDownload 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.\nSee 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."},{"id":"mcp-reference.index","locale":"en","title":"MCP tool reference","description":"Generated contracts for all registered MCP tools: arguments, results, OAuth scopes, side effects, spending safeguards, and reviewed availability.","section":"mcp-reference","path":"/docs/en/mcp-reference","url":"https://animgen.com/docs/en/mcp-reference","status":"beta","lastVerified":"2026-08-30","audience":["api-developer","ai-agent"],"productAreas":["mcp"],"tags":["reference","MCP","index"],"translations":{"en":"https://animgen.com/docs/en/mcp-reference","zh":"https://animgen.com/docs/zh/mcp-reference"},"headings":[{"id":"availability-and-workflow","title":"Availability and workflow","level":2},{"id":"tools","title":"Tools","level":2}],"text":"Generated from the backend contract. Field names, required flags, constraints, and defaults come from source models. Download the machine-readable source. Examples use placeholder IDs and illustrative values, not live prices, limits, or model availability.\nAvailability and workflow\nOfficial MCP is in public beta at https://api.animgen.com/mcp. Use Streamable HTTP and OAuth with a verified AnimGen account; subscriptions raise limits and a connection does not approve spending.\nAvailability and quickstart · Standard workflow\nTools\nTool\nScope\nPurpose\nlist_models\nmodels:read\nList enabled animation models, supported parameters, and capabilities.\nprepare_image_upload\nfiles:write\nCreate a short-lived direct upload. PUT exactly byte_size bytes using the returned URL and headers, then call complete_image_upload.\ncomplete_image_upload\nfiles:write\nValidate a prepared image upload and return its reusable file_id.\nquote_animation\nanimations:write\nCalculate the current credit price and issue a short-lived quote_id. This does not start generation or spend credits.\ngenerate_animation\nanimations:write\nStart a paid asynchronous animation. Requires a prior quote_id or an explicit max_credits limit and an idempotency key. Credits may be charged once production begins.\nget_animation\nanimations:read\nGet animation status, progress, credit state, errors, and generated assets.\ndownload_asset\nassets:read\nReturn metadata and a short-lived signed download URL for an owned output asset.\ncancel_animation\nanimations:write\nBest-effort cancellation of an owned animation. Work already in production may not stop and credits already charged are not refunded.\nShared schemas"},{"id":"mcp-reference.cancel-animation","locale":"en","title":"Cancel animation","description":"Source-generated cancel_animation arguments, output schema, OAuth scope, and safety annotations for the reviewed MCP contract.","section":"mcp-reference","path":"/docs/en/mcp-reference/cancel-animation","url":"https://animgen.com/docs/en/mcp-reference/cancel-animation","status":"beta","lastVerified":"2026-08-30","audience":["api-developer","ai-agent"],"productAreas":["mcp"],"tags":["reference","MCP","cancel-animation","animation_id"],"translations":{"en":"https://animgen.com/docs/en/mcp-reference/cancel-animation","zh":"https://animgen.com/docs/zh/mcp-reference/cancel-animation"},"headings":[{"id":"tool","title":"Tool","level":2},{"id":"permissions-and-safety","title":"Permissions and safety","level":2},{"id":"input-arguments","title":"Input arguments","level":2},{"id":"argument-example","title":"Argument example","level":3},{"id":"structured-result","title":"Structured result","level":2},{"id":"errors-and-next-steps","title":"Errors and next steps","level":2}],"text":"Generated from the backend contract. Field names, required flags, constraints, and defaults come from source models. Download the machine-readable source. Examples use placeholder IDs and illustrative values, not live prices, limits, or model availability.\nTool\ncancel_animation\nBest-effort cancellation of an owned animation. Work already in production may not stop and credits already charged are not refunded.\nPermissions and safety\nOAuth scope: animations:write\nSignal\nValue\ndestructiveHint\ntrue\nidempotentHint\ntrue\nopenWorldHint\nfalse\nreadOnlyHint\nfalse\nspendsCredits\nfalse\nrequiresUserConfirmation\ntrue\nsideEffects\ncancellation_requested\nAnnotations describe safety properties; they do not replace consent, OAuth authorization, or server checks.\nInput arguments\nField\nType\nRequired\nDefault\nConstraints\nMeaning\nanimation_id\nstring\nYes\n—\nformat: uuid\nOwned task the user has asked to cancel.\nArgument example\nStructured result\nField\nType\nRequired\nDefault\nConstraints\nMeaning\ncreated_at\nstring\nYes\n—\nformat: date-time\nUTC acceptance timestamp.\ncredits\nCreditUsage\nYes\n—\n—\nQuoted, reserved, and charged credit states.\nerror\nTaskError / null\nNo\nnull\n—\nTask failure details, independently of any usable outputs.\nfinished_at\nstring / null\nNo\nnull\nformat: date-time\nUTC terminal timestamp when known.\nid\nstring\nYes\n—\nformat: uuid\nPersist this task ID immediately after create; poll it instead of creating again.\nmetadata\nobject\nNo\n{}\n—\nCaller-provided metadata.\nnormalized_input\nobject\nNo\n{}\n—\nNormalized public input; may contain private prompts or image references. Do not log wholesale.\nobject\nstring\nYes\n—\nenum: \"video_generation\", \"animation_export\", \"animation\"\nPublic task resource type.\noutputs\narray<AssetResponse>\nNo\n[]\n—\nAvailable assets, including partial outputs on failed/cancelled tasks. Always inspect them at a terminal state.\nprogress\nnumber\nYes\n—\nminimum: 0; maximum: 1\nFraction from 0 to 1, not a completion-time estimate.\nstage\nstring / null\nNo\nnull\nenum: \"queued\", \"video_generation\", \"animation_export\", \"completed\"\nCurrent pipeline stage when available.\nstarted_at\nstring / null\nNo\nnull\nformat: date-time\nUTC production start when known.\nstatus\nstring\nYes\n—\nenum: \"queued\", \"running\", \"cancelling\", \"succeeded\", \"failed\", \"cancelled\"\nsucceeded, failed, and cancelled are terminal; cancelling is not terminal.\nTaskResponse\nErrors and next steps\nTool errors contain an error object with code, message, retryable, request_id, and details. Do not parse message text or leak private inputs. Inspect partial outputs after a terminal failure; a signed URL is not a saved file.\nStandard workflow · Spending safeguards"},{"id":"mcp-reference.complete-image-upload","locale":"en","title":"Complete image upload","description":"Source-generated complete_image_upload arguments, output schema, OAuth scope, and safety annotations for the reviewed MCP contract.","section":"mcp-reference","path":"/docs/en/mcp-reference/complete-image-upload","url":"https://animgen.com/docs/en/mcp-reference/complete-image-upload","status":"beta","lastVerified":"2026-08-30","audience":["api-developer","ai-agent"],"productAreas":["mcp"],"tags":["reference","MCP","complete-image-upload","upload_id"],"translations":{"en":"https://animgen.com/docs/en/mcp-reference/complete-image-upload","zh":"https://animgen.com/docs/zh/mcp-reference/complete-image-upload"},"headings":[{"id":"tool","title":"Tool","level":2},{"id":"permissions-and-safety","title":"Permissions and safety","level":2},{"id":"input-arguments","title":"Input arguments","level":2},{"id":"argument-example","title":"Argument example","level":3},{"id":"structured-result","title":"Structured result","level":2},{"id":"errors-and-next-steps","title":"Errors and next steps","level":2}],"text":"Generated from the backend contract. Field names, required flags, constraints, and defaults come from source models. Download the machine-readable source. Examples use placeholder IDs and illustrative values, not live prices, limits, or model availability.\nTool\ncomplete_image_upload\nValidate a prepared image upload and return its reusable file_id.\nPermissions and safety\nOAuth scope: files:write\nSignal\nValue\ndestructiveHint\nfalse\nidempotentHint\ntrue\nopenWorldHint\nfalse\nreadOnlyHint\nfalse\nspendsCredits\nfalse\nrequiresUserConfirmation\nfalse\nsideEffects\nuploaded_image_persisted\nAnnotations describe safety properties; they do not replace consent, OAuth authorization, or server checks.\nInput arguments\nField\nType\nRequired\nDefault\nConstraints\nMeaning\nupload_id\nstring\nYes\n—\nformat: uuid\nSession from prepare_image_upload, after byte transfer completed.\nArgument example\nStructured result\nField\nType\nRequired\nDefault\nConstraints\nMeaning\nbyte_size\ninteger\nYes\n—\n—\nValidated image byte count.\nfile_id\nstring\nYes\n—\nformat: uuid\nReusable owned public file ID for request.input.first_frame.\nmime_type\nstring\nYes\n—\n—\nValidated image MIME type.\nsha256\nstring\nYes\n—\n—\nSHA-256 of the uploaded image bytes.\nMcpUploadCompleteOutput\nErrors and next steps\nTool errors contain an error object with code, message, retryable, request_id, and details. Do not parse message text or leak private inputs. Inspect partial outputs after a terminal failure; a signed URL is not a saved file.\nStandard workflow · Spending safeguards"},{"id":"mcp-reference.download-asset","locale":"en","title":"Download asset","description":"Source-generated download_asset arguments, output schema, OAuth scope, and safety annotations for the reviewed MCP contract.","section":"mcp-reference","path":"/docs/en/mcp-reference/download-asset","url":"https://animgen.com/docs/en/mcp-reference/download-asset","status":"beta","lastVerified":"2026-08-30","audience":["api-developer","ai-agent"],"productAreas":["mcp"],"tags":["reference","MCP","download-asset","asset_id"],"translations":{"en":"https://animgen.com/docs/en/mcp-reference/download-asset","zh":"https://animgen.com/docs/zh/mcp-reference/download-asset"},"headings":[{"id":"tool","title":"Tool","level":2},{"id":"permissions-and-safety","title":"Permissions and safety","level":2},{"id":"input-arguments","title":"Input arguments","level":2},{"id":"argument-example","title":"Argument example","level":3},{"id":"structured-result","title":"Structured result","level":2},{"id":"errors-and-next-steps","title":"Errors and next steps","level":2}],"text":"Generated from the backend contract. Field names, required flags, constraints, and defaults come from source models. Download the machine-readable source. Examples use placeholder IDs and illustrative values, not live prices, limits, or model availability.\nTool\ndownload_asset\nReturn metadata and a short-lived signed download URL for an owned output asset.\nPermissions and safety\nOAuth scope: assets:read\nSignal\nValue\ndestructiveHint\nfalse\nidempotentHint\ntrue\nopenWorldHint\nfalse\nreadOnlyHint\ntrue\nspendsCredits\nfalse\nrequiresUserConfirmation\nfalse\nsideEffects\nsigned_url_issued\nAnnotations describe safety properties; they do not replace consent, OAuth authorization, or server checks.\nInput arguments\nField\nType\nRequired\nDefault\nConstraints\nMeaning\nasset_id\nstring\nYes\n—\nformat: uuid\nOwned asset ID from task outputs, not a task ID.\nArgument example\nStructured result\nField\nType\nRequired\nDefault\nConstraints\nMeaning\nbyte_size\ninteger\nYes\n—\n—\nExpected file size in bytes.\ncreated_at\nstring\nYes\n—\nformat: date-time\nCreation timestamp in UTC.\ndownload_expires_at\nstring\nYes\n—\nformat: date-time\nSigned URL expiry in UTC; refresh via asset lookup when expired.\ndownload_url\nstring\nYes\n—\n—\nSensitive short-lived signed URL. Download without a Bearer header, including after redirects; never log the URL.\nformat\nstring\nYes\n—\n—\nArtifact format; inspect actual outputs rather than assuming an array order.\nid\nstring\nYes\n—\nformat: uuid\nStable public asset ID; use it to refresh download metadata.\nmime_type\nstring\nYes\n—\n—\nAsset media type.\nobject\nstring\nNo\n\"asset\"\nconst: \"asset\"\n—\nAssetResponse\nErrors and next steps\nTool errors contain an error object with code, message, retryable, request_id, and details. Do not parse message text or leak private inputs. Inspect partial outputs after a terminal failure; a signed URL is not a saved file.\nStandard workflow · Spending safeguards"},{"id":"mcp-reference.generate-animation","locale":"en","title":"Generate animation","description":"Source-generated generate_animation arguments, output schema, OAuth scope, and safety annotations for the reviewed MCP contract.","section":"mcp-reference","path":"/docs/en/mcp-reference/generate-animation","url":"https://animgen.com/docs/en/mcp-reference/generate-animation","status":"beta","lastVerified":"2026-08-30","audience":["api-developer","ai-agent"],"productAreas":["mcp"],"tags":["reference","MCP","generate-animation","idempotency_key","max_credits","quote_id","request"],"translations":{"en":"https://animgen.com/docs/en/mcp-reference/generate-animation","zh":"https://animgen.com/docs/zh/mcp-reference/generate-animation"},"headings":[{"id":"tool","title":"Tool","level":2},{"id":"permissions-and-safety","title":"Permissions and safety","level":2},{"id":"input-arguments","title":"Input arguments","level":2},{"id":"argument-example","title":"Argument example","level":3},{"id":"structured-result","title":"Structured result","level":2},{"id":"errors-and-next-steps","title":"Errors and next steps","level":2}],"text":"Generated from the backend contract. Field names, required flags, constraints, and defaults come from source models. Download the machine-readable source. Examples use placeholder IDs and illustrative values, not live prices, limits, or model availability.\nTool\ngenerate_animation\nStart a paid asynchronous animation. Requires a prior quote_id or an explicit max_credits limit and an idempotency key. Credits may be charged once production begins.\nPermissions and safety\nOAuth scope: animations:write\nSignal\nValue\ndestructiveHint\ntrue\nidempotentHint\ntrue\nopenWorldHint\ntrue\nreadOnlyHint\nfalse\nspendsCredits\ntrue\nrequiresUserConfirmation\ntrue\nsideEffects\ngeneration_started, credits_reserved_or_charged\nAnnotations describe safety properties; they do not replace consent, OAuth authorization, or server checks.\nAt least one of quote_id or max_credits is required. Both are top-level tool arguments beside request. Obtain explicit approval; never silently raise a cap. Keep the same user, OAuth client, idempotency key, and request on retries.\nInput arguments\nField\nType\nRequired\nDefault\nConstraints\nMeaning\nidempotency_key\nstring\nYes\n—\nminLength: 8; maxLength: 200\nPersist per logical generation; reuse with the same OAuth client and user after a timeout.\nmax_credits\ninteger / null\nNo\nnull\nminimum: 0\nUser-approved per-operation credit cap. Never silently increase it; this is not a multi-task budget.\nquote_id\nstring / null\nNo\nnull\nformat: uuid\nFresh approved quote. At least quote_id or max_credits is required; both are allowed.\nrequest\nAnimationCreateRequest\nYes\n—\n—\nExact user-approved request; keep unchanged across retries.\nArgument example\nStructured result\nField\nType\nRequired\nDefault\nConstraints\nMeaning\ncreated_at\nstring\nYes\n—\nformat: date-time\nUTC acceptance timestamp.\ncredits\nCreditUsage\nYes\n—\n—\nQuoted, reserved, and charged credit states.\nerror\nTaskError / null\nNo\nnull\n—\nTask failure details, independently of any usable outputs.\nfinished_at\nstring / null\nNo\nnull\nformat: date-time\nUTC terminal timestamp when known.\nid\nstring\nYes\n—\nformat: uuid\nPersist this task ID immediately after create; poll it instead of creating again.\nmetadata\nobject\nNo\n{}\n—\nCaller-provided metadata.\nnormalized_input\nobject\nNo\n{}\n—\nNormalized public input; may contain private prompts or image references. Do not log wholesale.\nobject\nstring\nYes\n—\nenum: \"video_generation\", \"animation_export\", \"animation\"\nPublic task resource type.\noutputs\narray<AssetResponse>\nNo\n[]\n—\nAvailable assets, including partial outputs on failed/cancelled tasks. Always inspect them at a terminal state.\nprogress\nnumber\nYes\n—\nminimum: 0; maximum: 1\nFraction from 0 to 1, not a completion-time estimate.\nstage\nstring / null\nNo\nnull\nenum: \"queued\", \"video_generation\", \"animation_export\", \"completed\"\nCurrent pipeline stage when available.\nstarted_at\nstring / null\nNo\nnull\nformat: date-time\nUTC production start when known.\nstatus\nstring\nYes\n—\nenum: \"queued\", \"running\", \"cancelling\", \"succeeded\", \"failed\", \"cancelled\"\nsucceeded, failed, and cancelled are terminal; cancelling is not terminal.\nTaskResponse\nErrors and next steps\nTool errors contain an error object with code, message, retryable, request_id, and details. Do not parse message text or leak private inputs. Inspect partial outputs after a terminal failure; a signed URL is not a saved file.\nStandard workflow · Spending safeguards"},{"id":"mcp-reference.get-animation","locale":"en","title":"Get animation","description":"Source-generated get_animation arguments, output schema, OAuth scope, and safety annotations for the reviewed MCP contract.","section":"mcp-reference","path":"/docs/en/mcp-reference/get-animation","url":"https://animgen.com/docs/en/mcp-reference/get-animation","status":"beta","lastVerified":"2026-08-30","audience":["api-developer","ai-agent"],"productAreas":["mcp"],"tags":["reference","MCP","get-animation","animation_id"],"translations":{"en":"https://animgen.com/docs/en/mcp-reference/get-animation","zh":"https://animgen.com/docs/zh/mcp-reference/get-animation"},"headings":[{"id":"tool","title":"Tool","level":2},{"id":"permissions-and-safety","title":"Permissions and safety","level":2},{"id":"input-arguments","title":"Input arguments","level":2},{"id":"argument-example","title":"Argument example","level":3},{"id":"structured-result","title":"Structured result","level":2},{"id":"errors-and-next-steps","title":"Errors and next steps","level":2}],"text":"Generated from the backend contract. Field names, required flags, constraints, and defaults come from source models. Download the machine-readable source. Examples use placeholder IDs and illustrative values, not live prices, limits, or model availability.\nTool\nget_animation\nGet animation status, progress, credit state, errors, and generated assets.\nPermissions and safety\nOAuth scope: animations:read\nSignal\nValue\ndestructiveHint\nfalse\nidempotentHint\ntrue\nopenWorldHint\nfalse\nreadOnlyHint\ntrue\nspendsCredits\nfalse\nrequiresUserConfirmation\nfalse\nsideEffects\n—\nAnnotations describe safety properties; they do not replace consent, OAuth authorization, or server checks.\nInput arguments\nField\nType\nRequired\nDefault\nConstraints\nMeaning\nanimation_id\nstring\nYes\n—\nformat: uuid\nOwned task ID returned by generate_animation.\nArgument example\nStructured result\nField\nType\nRequired\nDefault\nConstraints\nMeaning\ncreated_at\nstring\nYes\n—\nformat: date-time\nUTC acceptance timestamp.\ncredits\nCreditUsage\nYes\n—\n—\nQuoted, reserved, and charged credit states.\nerror\nTaskError / null\nNo\nnull\n—\nTask failure details, independently of any usable outputs.\nfinished_at\nstring / null\nNo\nnull\nformat: date-time\nUTC terminal timestamp when known.\nid\nstring\nYes\n—\nformat: uuid\nPersist this task ID immediately after create; poll it instead of creating again.\nmetadata\nobject\nNo\n{}\n—\nCaller-provided metadata.\nnormalized_input\nobject\nNo\n{}\n—\nNormalized public input; may contain private prompts or image references. Do not log wholesale.\nobject\nstring\nYes\n—\nenum: \"video_generation\", \"animation_export\", \"animation\"\nPublic task resource type.\noutputs\narray<AssetResponse>\nNo\n[]\n—\nAvailable assets, including partial outputs on failed/cancelled tasks. Always inspect them at a terminal state.\nprogress\nnumber\nYes\n—\nminimum: 0; maximum: 1\nFraction from 0 to 1, not a completion-time estimate.\nstage\nstring / null\nNo\nnull\nenum: \"queued\", \"video_generation\", \"animation_export\", \"completed\"\nCurrent pipeline stage when available.\nstarted_at\nstring / null\nNo\nnull\nformat: date-time\nUTC production start when known.\nstatus\nstring\nYes\n—\nenum: \"queued\", \"running\", \"cancelling\", \"succeeded\", \"failed\", \"cancelled\"\nsucceeded, failed, and cancelled are terminal; cancelling is not terminal.\nTaskResponse\nErrors and next steps\nTool errors contain an error object with code, message, retryable, request_id, and details. Do not parse message text or leak private inputs. Inspect partial outputs after a terminal failure; a signed URL is not a saved file.\nStandard workflow · Spending safeguards"},{"id":"mcp-reference.list-models","locale":"en","title":"List animation models","description":"Source-generated list_models arguments, output schema, OAuth scope, and safety annotations for the reviewed MCP contract.","section":"mcp-reference","path":"/docs/en/mcp-reference/list-models","url":"https://animgen.com/docs/en/mcp-reference/list-models","status":"beta","lastVerified":"2026-08-30","audience":["api-developer","ai-agent"],"productAreas":["mcp"],"tags":["reference","MCP","list-models"],"translations":{"en":"https://animgen.com/docs/en/mcp-reference/list-models","zh":"https://animgen.com/docs/zh/mcp-reference/list-models"},"headings":[{"id":"tool","title":"Tool","level":2},{"id":"permissions-and-safety","title":"Permissions and safety","level":2},{"id":"input-arguments","title":"Input arguments","level":2},{"id":"argument-example","title":"Argument example","level":3},{"id":"structured-result","title":"Structured result","level":2},{"id":"errors-and-next-steps","title":"Errors and next steps","level":2}],"text":"Generated from the backend contract. Field names, required flags, constraints, and defaults come from source models. Download the machine-readable source. Examples use placeholder IDs and illustrative values, not live prices, limits, or model availability.\nTool\nlist_models\nList enabled animation models, supported parameters, and capabilities.\nPermissions and safety\nOAuth scope: models:read\nSignal\nValue\ndestructiveHint\nfalse\nidempotentHint\ntrue\nopenWorldHint\nfalse\nreadOnlyHint\ntrue\nspendsCredits\nfalse\nrequiresUserConfirmation\nfalse\nsideEffects\n—\nAnnotations describe safety properties; they do not replace consent, OAuth authorization, or server checks.\nInput arguments\nNo arguments; send an empty object: {}.\nArgument example\nStructured result\nField\nType\nRequired\nDefault\nConstraints\nMeaning\ndata\narray<ModelCapabilities>\nYes\n—\n—\nCurrently enabled models; do not hard-code this list in a client.\nobject\nstring\nNo\n\"list\"\nconst: \"list\"\n—\nModelsResponse\nErrors and next steps\nTool errors contain an error object with code, message, retryable, request_id, and details. Do not parse message text or leak private inputs. Inspect partial outputs after a terminal failure; a signed URL is not a saved file.\nStandard workflow · Spending safeguards"},{"id":"mcp-reference.prepare-image-upload","locale":"en","title":"Prepare image upload","description":"Source-generated prepare_image_upload arguments, output schema, OAuth scope, and safety annotations for the reviewed MCP contract.","section":"mcp-reference","path":"/docs/en/mcp-reference/prepare-image-upload","url":"https://animgen.com/docs/en/mcp-reference/prepare-image-upload","status":"beta","lastVerified":"2026-08-30","audience":["api-developer","ai-agent"],"productAreas":["mcp"],"tags":["reference","MCP","prepare-image-upload","byte_size","filename","mime_type"],"translations":{"en":"https://animgen.com/docs/en/mcp-reference/prepare-image-upload","zh":"https://animgen.com/docs/zh/mcp-reference/prepare-image-upload"},"headings":[{"id":"tool","title":"Tool","level":2},{"id":"permissions-and-safety","title":"Permissions and safety","level":2},{"id":"input-arguments","title":"Input arguments","level":2},{"id":"argument-example","title":"Argument example","level":3},{"id":"structured-result","title":"Structured result","level":2},{"id":"errors-and-next-steps","title":"Errors and next steps","level":2}],"text":"Generated from the backend contract. Field names, required flags, constraints, and defaults come from source models. Download the machine-readable source. Examples use placeholder IDs and illustrative values, not live prices, limits, or model availability.\nTool\nprepare_image_upload\nCreate a short-lived direct upload. PUT exactly byte_size bytes using the returned URL and headers, then call complete_image_upload.\nPermissions and safety\nOAuth scope: files:write\nSignal\nValue\ndestructiveHint\nfalse\nidempotentHint\nfalse\nopenWorldHint\ntrue\nreadOnlyHint\nfalse\nspendsCredits\nfalse\nrequiresUserConfirmation\nfalse\nsideEffects\ntemporary_upload_created\nAnnotations describe safety properties; they do not replace consent, OAuth authorization, or server checks.\nInput arguments\nField\nType\nRequired\nDefault\nConstraints\nMeaning\nbyte_size\ninteger\nYes\n—\nexclusiveMinimum: 0\nExact number of bytes the client will PUT.\nfilename\nstring\nYes\n—\nminLength: 1; maxLength: 240\nClient filename, not a local path the server can read.\nmime_type\nstring\nYes\n—\npattern: ^image/(png|jpeg|webp)$\nActual image MIME type.\nArgument example\nStructured result\nField\nType\nRequired\nDefault\nConstraints\nMeaning\nexpires_at\nstring\nYes\n—\nformat: date-time\nUpload URL expiry.\nheaders\nobject\nYes\n—\n—\nExact transfer headers; do not add MCP tokens or API Bearer credentials.\nmax_bytes\ninteger\nYes\n—\n—\nMaximum accepted upload byte count.\nmethod\nstring\nNo\n\"PUT\"\nconst: \"PUT\"\nHTTP method the client must use for the byte transfer.\nupload_id\nstring\nYes\n—\nformat: uuid\nUpload session ID for complete_image_upload, not the final file_id.\nupload_url\nstring\nYes\n—\n—\nSensitive short-lived upload URL. Transfer actual bytes; do not publish this URL.\nMcpUploadPrepareOutput\nErrors and next steps\nTool errors contain an error object with code, message, retryable, request_id, and details. Do not parse message text or leak private inputs. Inspect partial outputs after a terminal failure; a signed URL is not a saved file.\nStandard workflow · Spending safeguards"},{"id":"mcp-reference.quote-animation","locale":"en","title":"Quote animation","description":"Source-generated quote_animation arguments, output schema, OAuth scope, and safety annotations for the reviewed MCP contract.","section":"mcp-reference","path":"/docs/en/mcp-reference/quote-animation","url":"https://animgen.com/docs/en/mcp-reference/quote-animation","status":"beta","lastVerified":"2026-08-30","audience":["api-developer","ai-agent"],"productAreas":["mcp"],"tags":["reference","MCP","quote-animation","request"],"translations":{"en":"https://animgen.com/docs/en/mcp-reference/quote-animation","zh":"https://animgen.com/docs/zh/mcp-reference/quote-animation"},"headings":[{"id":"tool","title":"Tool","level":2},{"id":"permissions-and-safety","title":"Permissions and safety","level":2},{"id":"input-arguments","title":"Input arguments","level":2},{"id":"argument-example","title":"Argument example","level":3},{"id":"structured-result","title":"Structured result","level":2},{"id":"errors-and-next-steps","title":"Errors and next steps","level":2}],"text":"Generated from the backend contract. Field names, required flags, constraints, and defaults come from source models. Download the machine-readable source. Examples use placeholder IDs and illustrative values, not live prices, limits, or model availability.\nTool\nquote_animation\nCalculate the current credit price and issue a short-lived quote_id. This does not start generation or spend credits.\nPermissions and safety\nOAuth scope: animations:write\nSignal\nValue\ndestructiveHint\nfalse\nidempotentHint\nfalse\nopenWorldHint\nfalse\nreadOnlyHint\ntrue\nspendsCredits\nfalse\nrequiresUserConfirmation\nfalse\nsideEffects\ntemporary_quote_created\nAnnotations describe safety properties; they do not replace consent, OAuth authorization, or server checks.\nInput arguments\nField\nType\nRequired\nDefault\nConstraints\nMeaning\nrequest\nAnimationCreateRequest\nYes\n—\n—\nComplete intended animation request; quoting starts no generation.\nArgument example\nStructured result\nField\nType\nRequired\nDefault\nConstraints\nMeaning\nbreakdown\nobject\nYes\n—\n—\nPublic cost components.\ncredits\ninteger\nYes\n—\n—\nQuoted credits; show the amount to the user before generation.\nexpires_at\nstring\nYes\n—\nformat: date-time\nQuote expiry; re-quote and confirm if it expires or price changes.\nquote_id\nstring\nYes\n—\nformat: uuid\nShort-lived quote owned by this user and OAuth client; can bind to one logical generation key.\nMcpQuoteOutput\nErrors and next steps\nTool errors contain an error object with code, message, retryable, request_id, and details. Do not parse message text or leak private inputs. Inspect partial outputs after a terminal failure; a signed URL is not a saved file.\nStandard workflow · Spending safeguards"},{"id":"mcp-reference.schemas","locale":"en","title":"Shared schema definitions","description":"Source-generated field definitions, nested types, defaults, required flags, and constraints for this contract.","section":"mcp-reference","path":"/docs/en/mcp-reference/schemas","url":"https://animgen.com/docs/en/mcp-reference/schemas","status":"beta","lastVerified":"2026-08-30","audience":["api-developer","ai-agent"],"productAreas":["mcp"],"tags":["reference","MCP","schemas"],"translations":{"en":"https://animgen.com/docs/en/mcp-reference/schemas","zh":"https://animgen.com/docs/zh/mcp-reference/schemas"},"headings":[{"id":"animationcreaterequest","title":"AnimationCreateRequest","level":2},{"id":"assetresponse","title":"AssetResponse","level":2},{"id":"base64imageinput","title":"Base64ImageInput","level":2},{"id":"creditusage","title":"CreditUsage","level":2},{"id":"exportoptions","title":"ExportOptions","level":2},{"id":"exporttransparency","title":"ExportTransparency","level":2},{"id":"fileimageinput","title":"FileImageInput","level":2},{"id":"generationinput","title":"GenerationInput","level":2},{"id":"generationtransparency","title":"GenerationTransparency","level":2},{"id":"inputcanvasoptions","title":"InputCanvasOptions","level":2},{"id":"mcpquoteoutput","title":"McpQuoteOutput","level":2},{"id":"mcpuploadcompleteoutput","title":"McpUploadCompleteOutput","level":2},{"id":"mcpuploadprepareoutput","title":"McpUploadPrepareOutput","level":2},{"id":"modelcapabilities","title":"ModelCapabilities","level":2},{"id":"modelsresponse","title":"ModelsResponse","level":2},{"id":"selection","title":"Selection","level":2},{"id":"taskerror","title":"TaskError","level":2},{"id":"taskresponse","title":"TaskResponse","level":2},{"id":"unityoptions","title":"UnityOptions","level":2},{"id":"urlimageinput","title":"UrlImageInput","level":2},{"id":"videooptions","title":"VideoOptions","level":2}],"text":"Generated from the backend contract. Field names, required flags, constraints, and defaults come from source models. Download the machine-readable source. Examples use placeholder IDs and illustrative values, not live prices, limits, or model availability.\nA dash means no default is declared, not a null value. A field can be optional in JSON Schema but conditionally required by the documented workflow. Model-specific options still require live capability discovery.\nAnimationCreateRequest\nUnknown fields are rejected.\nField\nType\nRequired\nDefault\nConstraints\nMeaning\nexport\nExportOptions\nNo\n{\"frame_count\":24,\"output_formats\":[\"spritesheet\"],\"output_height\":512,\"output_width\":512,\"transparent\":{\"enabled\":false},\"unity\":{\"pivot\":\"bottom_center\",\"pixels_per_unit\":100}}\n—\nExport after video generation. Alpha-bearing formats require an alpha_key source; compatible formats automatically enable its transparent export.\ninput\nGenerationInput\nYes\n—\n—\nImages owned by the caller or supplied for this generation.\nmetadata\nobject\nNo\n{}\n—\nCaller metadata: simple string/number/boolean/null values, at most 4 KiB JSON. Do not store secrets.\nnegative_prompt\nstring\nNo\n\"\"\nmaxLength: 4000\nOptional exclusions, only when the model supports negative prompts.\nprompt\nstring\nNo\n\"\"\nmaxLength: 8000\nMotion instruction; nonempty when the model requires a prompt. Keep private prompts out of logs.\nselection\nSelection\nNo\n{\"duration_seconds\":null,\"mode\":\"full\",\"start_seconds\":0}\n—\nInterval selected after generation; full by default.\nvideo\nVideoOptions\nNo\n{\"duration_seconds\":null,\"input_canvas\":null,\"model\":null,\"ratio\":null,\"resolution\":null,\"seed\":null,\"style_preset\":null,\"transparency\":{\"key_color\":null,\"key_selection\":\"auto\",\"mode\":\"standard\"},\"watermark\":null}\n—\nModel-compatible generation settings.\nAssetResponse\nUnknown fields are rejected.\nField\nType\nRequired\nDefault\nConstraints\nMeaning\nbyte_size\ninteger\nYes\n—\n—\nExpected file size in bytes.\ncreated_at\nstring\nYes\n—\nformat: date-time\nCreation timestamp in UTC.\ndownload_expires_at\nstring\nYes\n—\nformat: date-time\nSigned URL expiry in UTC; refresh via asset lookup when expired.\ndownload_url\nstring\nYes\n—\n—\nSensitive short-lived signed URL. Download without a Bearer header, including after redirects; never log the URL.\nformat\nstring\nYes\n—\n—\nArtifact format; inspect actual outputs rather than assuming an array order.\nid\nstring\nYes\n—\nformat: uuid\nStable public asset ID; use it to refresh download metadata.\nmime_type\nstring\nYes\n—\n—\nAsset media type.\nobject\nstring\nNo\n\"asset\"\nconst: \"asset\"\n—\nBase64ImageInput\nUnknown fields are rejected.\nField\nType\nRequired\nDefault\nConstraints\nMeaning\ndata\nstring\nYes\n—\nminLength: 4\nPure Base64 without a data URL prefix; decoded limits: 10 MiB per image, 20 MiB total.\nmedia_type\nstring\nYes\n—\nenum: \"image/png\", \"image/jpeg\", \"image/webp\"\nActual image MIME type.\ntype\nstring\nYes\n—\nconst: \"base64\"\n—\nCreditUsage\nUnknown fields are rejected.\nField\nType\nRequired\nDefault\nConstraints\nMeaning\ncharged\ninteger\nYes\n—\n—\nNet charged credits. Confirmed provider moderation rejection is refunded; cancellation alone is not a refund.\nheld\ninteger\nYes\n—\n—\nCredits currently reserved, not an additional charge to sum with charged.\nquoted\ninteger\nYes\n—\n—\nQuoted total, not necessarily the final charge.\nrefunded\ninteger\nNo\n0\n—\nCredits returned after a charge; already excluded from charged. Not a cash refund.\nreleased\ninteger\nNo\n0\n—\nCredits returned from an uncommitted hold.\nstatus\nstring / null\nNo\nnull\n—\nBilling state: held, charged, released, refunded, or managed for internal child tasks.\nExportOptions\nUnknown fields are rejected.\nField\nType\nRequired\nDefault\nConstraints\nMeaning\nframe_count\ninteger\nNo\n24\nminimum: 1; maximum: 240\nNumber of frames sampled over the selected interval, not an FPS field.\noutput_formats\narray<string>\nNo\n[\"spritesheet\"]\nminItems: 1; items: enum: \"clip_video\", \"webm_alpha\", \"prores_4444\", \"frames_zip\", \"spritesheet\", \"spritesheet_json\", \"unity_meta\", \"unity_pack\", \"godot_pack\", \"unreal_paper2d_pack\", \"cocos_creator_pack\"\nRequested asset formats; defaults to spritesheet. Duplicates are removed. Metadata needs its matching texture.\noutput_height\ninteger\nNo\n512\nminimum: 64; maximum: 1024\nOutput frame height in pixels.\noutput_width\ninteger\nNo\n512\nminimum: 64; maximum: 1024\nOutput frame width in pixels.\ntransparent\nExportTransparency\nNo\n{\"enabled\":false}\n—\nUse the enabled object form. Legacy booleans are accepted but normalized to this object.\nunity\nUnityOptions\nNo\n{\"pivot\":\"bottom_center\",\"pixels_per_unit\":100}\n—\nSettings for Unity-specific metadata and packs.\nExportTransparency\nUnknown fields are rejected.\nField\nType\nRequired\nDefault\nConstraints\nMeaning\nenabled\nboolean\nNo\nfalse\n—\nTransparent processing for compatible outputs; requires an alpha_key source and does not make MP4 transparent.\nFileImageInput\nUnknown fields are rejected.\nField\nType\nRequired\nDefault\nConstraints\nMeaning\nfile_id\nstring\nYes\n—\nformat: uuid\nOwned public file ID from POST /files or complete_image_upload; not a Studio upload ID.\ntype\nstring\nYes\n—\nconst: \"file\"\n—\nGenerationInput\nUnknown fields are rejected.\nField\nType\nRequired\nDefault\nConstraints\nMeaning\nfirst_frame\nFileImageInput / Base64ImageInput / UrlImageInput\nYes\n—\ndiscriminator: type\nRequired starting image; use the type discriminator to select an input representation.\nlast_frame\nFileImageInput / Base64ImageInput / UrlImageInput / null\nNo\nnull\ndiscriminator: type\nOptional end image; the selected model must support first/last-frame mode.\nreference_images\narray<FileImageInput / Base64ImageInput / UrlImageInput>\nNo\n[]\nmaxItems: 8; items: discriminator: type\nAdditional references, excluding the first frame. The live model can impose a smaller limit.\nGenerationTransparency\nUnknown fields are rejected.\nField\nType\nRequired\nDefault\nConstraints\nMeaning\nkey_color\nstring / null\nNo\nnull\n—\nTemporary key color when using manual selection; normally leave automatic selection enabled.\nkey_selection\nstring\nNo\n\"auto\"\nenum: \"auto\", \"manual\"\nHow the temporary key color is selected.\nmode\nstring\nNo\n\"standard\"\nenum: \"standard\", \"alpha_key\"\nstandard keeps the scene; alpha_key requires meaningful alpha in all active input images. Raw videos remain opaque.\nInputCanvasOptions\nUnknown fields are rejected.\nField\nType\nRequired\nDefault\nConstraints\nMeaning\naspect_ratio\nstring\nNo\n\"follow_output\"\nenum: \"follow_output\", \"source\"\nFollow the output ratio or preserve the source ratio.\nbackground\nstring\nNo\n\"auto\"\nenum: \"auto\", \"transparent\", \"solid\"\nCanvas extension background strategy.\nbackground_color\nstring / null\nNo\nnull\npattern: ^#[0-9A-Fa-f]{6}$\nSix-digit RGB color for a solid extension.\nenabled\nboolean\nNo\ntrue\n—\nWhether to prepare an expanded input canvas.\nposition_x\nnumber\nNo\n0.5\nminimum: 0; maximum: 1\nNormalized horizontal source position.\nposition_y\nnumber\nNo\n0.5\nminimum: 0; maximum: 1\nNormalized vertical source position.\nsource_scale\nnumber\nNo\n0.8\nminimum: 0.5; maximum: 1\nSource subject scale within the canvas.\nMcpQuoteOutput\nUnknown fields are rejected.\nField\nType\nRequired\nDefault\nConstraints\nMeaning\nbreakdown\nobject\nYes\n—\n—\nPublic cost components.\ncredits\ninteger\nYes\n—\n—\nQuoted credits; show the amount to the user before generation.\nexpires_at\nstring\nYes\n—\nformat: date-time\nQuote expiry; re-quote and confirm if it expires or price changes.\nquote_id\nstring\nYes\n—\nformat: uuid\nShort-lived quote owned by this user and OAuth client; can bind to one logical generation key.\nMcpUploadCompleteOutput\nUnknown fields are rejected.\nField\nType\nRequired\nDefault\nConstraints\nMeaning\nbyte_size\ninteger\nYes\n—\n—\nValidated image byte count.\nfile_id\nstring\nYes\n—\nformat: uuid\nReusable owned public file ID for request.input.first_frame.\nmime_type\nstring\nYes\n—\n—\nValidated image MIME type.\nsha256\nstring\nYes\n—\n—\nSHA-256 of the uploaded image bytes.\nMcpUploadPrepareOutput\nUnknown fields are rejected.\nField\nType\nRequired\nDefault\nConstraints\nMeaning\nexpires_at\nstring\nYes\n—\nformat: date-time\nUpload URL expiry.\nheaders\nobject\nYes\n—\n—\nExact transfer headers; do not add MCP tokens or API Bearer credentials.\nmax_bytes\ninteger\nYes\n—\n—\nMaximum accepted upload byte count.\nmethod\nstring\nNo\n\"PUT\"\nconst: \"PUT\"\nHTTP method the client must use for the byte transfer.\nupload_id\nstring\nYes\n—\nformat: uuid\nUpload session ID for complete_image_upload, not the final file_id.\nupload_url\nstring\nYes\n—\n—\nSensitive short-lived upload URL. Transfer actual bytes; do not publish this URL.\nModelCapabilities\nUnknown fields are rejected.\nField\nType\nRequired\nDefault\nConstraints\nMeaning\naspect_ratio_mode\nstring\nYes\n—\n—\nProvider's aspect-ratio handling mode.\ndefault_duration_seconds\ninteger\nYes\n—\n—\nDefault generation duration in seconds.\ndefault_ratio\nstring / null\nYes\n—\n—\nDefault ratio, or null when not applicable.\ndefault_resolution\nstring / null\nYes\n—\n—\nDefault resolution, or null when not applicable.\ndurations\narray<integer>\nYes\n—\n—\nSupported generation durations in seconds; also inspect resolution-specific constraints.\ndurations_by_resolution\nobject\nNo\n{}\n—\nResolution-specific supported durations in seconds.\nid\nstring\nYes\n—\n—\nStable provider:model selector for requests; use the live catalog.\nlabel\nstring\nYes\n—\n—\nHuman-readable model label.\nmax_reference_images\ninteger\nYes\n—\n—\nModel reference-image capacity; the first frame occupies the first reference slot in reference mode.\nmodel\nstring\nYes\n—\n—\nModel identifier within the provider.\nmodes\narray<string>\nYes\n—\n—\nSupported input modes, such as first_frame, first_last_frame, or reference_images.\nprovider\nstring\nYes\n—\n—\nPublic provider identifier.\nratios\narray<string>\nYes\n—\n—\nSupported aspect ratio values; check ratios_by_mode where present.\nratios_by_mode\nobject\nNo\n{}\n—\nInput-mode-specific supported ratios.\nreference_image_duration_seconds\ninteger / null\nYes\n—\n—\nRequired duration for reference mode, when constrained.\nrequires_prompt\nboolean\nYes\n—\n—\nWhether prompt must be nonempty.\nresolutions\narray<string>\nYes\n—\n—\nSupported resolution values.\nreturns_last_frame\nboolean\nYes\n—\n—\nWhether the model can return a last-frame asset.\nsupports_first_frame\nboolean\nYes\n—\n—\nWhether a first-frame input is supported.\nsupports_last_frame\nboolean\nYes\n—\n—\nWhether a last-frame input is supported.\nsupports_negative_prompt\nboolean\nYes\n—\n—\nWhether negative_prompt is supported.\nsupports_reference_images\nboolean\nYes\n—\n—\nWhether reference-image mode is supported.\nsupports_seed\nboolean\nYes\n—\n—\nWhether seed is supported.\nsupports_watermark\nboolean\nYes\n—\n—\nWhether the watermark setting is supported.\nModelsResponse\nUnknown fields are rejected.\nField\nType\nRequired\nDefault\nConstraints\nMeaning\ndata\narray<ModelCapabilities>\nYes\n—\n—\nCurrently enabled models; do not hard-code this list in a client.\nobject\nstring\nNo\n\"list\"\nconst: \"list\"\n—\nSelection\nUnknown fields are rejected.\nField\nType\nRequired\nDefault\nConstraints\nMeaning\nduration_seconds\nnumber / null\nNo\nnull\nexclusiveMinimum: 0\nRequired when mode=range; positive interval length in seconds.\nmode\nstring\nNo\n\"full\"\nenum: \"full\", \"range\"\nfull uses the complete source; range requires duration_seconds.\nstart_seconds\nnumber\nNo\n0\nminimum: 0\nRange start in seconds from the source beginning.\nTaskError\nUnknown fields are rejected.\nField\nType\nRequired\nDefault\nConstraints\nMeaning\ncode\nstring\nYes\n—\n—\nMachine-readable task error code.\nmessage\nstring\nYes\n—\n—\nHuman-readable summary, not a stable branching key.\nretryable\nboolean\nNo\nfalse\n—\nWhether retry may help; inspect partial outputs before creating a new paid task.\nTaskResponse\nUnknown fields are rejected.\nField\nType\nRequired\nDefault\nConstraints\nMeaning\ncreated_at\nstring\nYes\n—\nformat: date-time\nUTC acceptance timestamp.\ncredits\nCreditUsage\nYes\n—\n—\nQuoted, reserved, and charged credit states.\nerror\nTaskError / null\nNo\nnull\n—\nTask failure details, independently of any usable outputs.\nfinished_at\nstring / null\nNo\nnull\nformat: date-time\nUTC terminal timestamp when known.\nid\nstring\nYes\n—\nformat: uuid\nPersist this task ID immediately after create; poll it instead of creating again.\nmetadata\nobject\nNo\n{}\n—\nCaller-provided metadata.\nnormalized_input\nobject\nNo\n{}\n—\nNormalized public input; may contain private prompts or image references. Do not log wholesale.\nobject\nstring\nYes\n—\nenum: \"video_generation\", \"animation_export\", \"animation\"\nPublic task resource type.\noutputs\narray<AssetResponse>\nNo\n[]\n—\nAvailable assets, including partial outputs on failed/cancelled tasks. Always inspect them at a terminal state.\nprogress\nnumber\nYes\n—\nminimum: 0; maximum: 1\nFraction from 0 to 1, not a completion-time estimate.\nstage\nstring / null\nNo\nnull\nenum: \"queued\", \"video_generation\", \"animation_export\", \"completed\"\nCurrent pipeline stage when available.\nstarted_at\nstring / null\nNo\nnull\nformat: date-time\nUTC production start when known.\nstatus\nstring\nYes\n—\nenum: \"queued\", \"running\", \"cancelling\", \"succeeded\", \"failed\", \"cancelled\"\nsucceeded, failed, and cancelled are terminal; cancelling is not terminal.\nUnityOptions\nUnknown fields are rejected.\nField\nType\nRequired\nDefault\nConstraints\nMeaning\npivot\nstring\nNo\n\"bottom_center\"\nconst: \"bottom_center\"\nSupported Unity sprite pivot.\npixels_per_unit\ninteger\nNo\n100\nminimum: 1; maximum: 1000\nUnity texture pixels per world unit.\nUrlImageInput\nUnknown fields are rejected.\nField\nType\nRequired\nDefault\nConstraints\nMeaning\ntype\nstring\nYes\n—\nconst: \"url\"\n—\nurl\nstring\nYes\n—\nminLength: 9; maxLength: 2048\nPublic HTTPS image on port 443, without credentials or fragments. Private networks and unsafe redirects are rejected. Keep bytes stable across retries.\nVideoOptions\nUnknown fields are rejected.\nField\nType\nRequired\nDefault\nConstraints\nMeaning\nduration_seconds\nnumber / null\nNo\nnull\nexclusiveMinimum: 0\nSeconds; choose a supported duration for the model and resolution. Omission uses its default.\ninput_canvas\nInputCanvasOptions / null\nNo\nnull\n—\nOptional input framing; omit to keep the source framing.\nmodel\nstring / null\nNo\nnull\n—\nprovider:model ID from GET /models; omission uses the configured default model.\nratio\nstring / null\nNo\nnull\n—\nAspect ratio supported by the current model and input mode.\nresolution\nstring / null\nNo\nnull\n—\nResolution value from the live model catalog.\nseed\ninteger / null\nNo\nnull\nminimum: 0; maximum: 2147483647\nOptional seed only for models advertising seed support; not a universal determinism guarantee.\nstyle_preset\nstring / null\nNo\nnull\n—\nOptional style preset supported by the selected provider/model.\ntransparency\nGenerationTransparency\nNo\n{\"key_color\":null,\"key_selection\":\"auto\",\"mode\":\"standard\"}\n—\nSource transparency workflow; transparent exports require alpha_key.\nwatermark\nboolean / null\nNo\nnull\n—\nOptional watermark setting; check the model capability."},{"id":"mcp.connect-clients","locale":"en","title":"Connect Codex and other MCP clients","description":"Connect the live AnimGen MCP endpoint to Claude, Codex, and compatible clients using OAuth, then verify it without spending credits.","section":"mcp","path":"/docs/en/mcp/connect-clients","url":"https://animgen.com/docs/en/mcp/connect-clients","status":"beta","lastVerified":"2026-09-01","audience":["user","api-developer","ai-agent"],"productAreas":["mcp"],"tags":["MCP","Claude","ChatGPT","Codex","Gemini CLI","OAuth","Streamable HTTP","connector","client"],"translations":{"en":"https://animgen.com/docs/en/mcp/connect-clients","zh":"https://animgen.com/docs/zh/mcp/connect-clients"},"headings":[{"id":"connection-details","title":"Connection details","level":2},{"id":"claude-custom-connector","title":"Claude custom connector","level":2},{"id":"chatgpt-developer-mode-test","title":"ChatGPT developer-mode test","level":2},{"id":"codex-cli","title":"Codex CLI","level":2},{"id":"gemini-cli","title":"Gemini CLI","level":2},{"id":"other-remote-mcp-clients","title":"Other remote MCP clients","level":2},{"id":"verify-without-spending-credits","title":"Verify without spending credits","level":2},{"id":"manage-permission-and-spending","title":"Manage permission and spending","level":2}],"text":"Connection details\nThe official service is available in public beta:\nSetting\nValue\nServer name\nanimgen, or a local name you choose\nServer URL\nhttps://api.animgen.com/mcp\nTransport\nStreamable HTTP\nAuthentication\nOAuth 2.1 with PKCE\nAccount eligibility\nVerified AnimGen account; active subscriptions raise limits\nNo 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 describes tools and schemas; do not use its URL as the server.\nClaude custom connector\nOpen Claude with AnimGen prefilled, 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.\nAnimGen 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.\nAfter 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.\nChatGPT developer-mode test\nAnimGen 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.\nDeveloper-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.\nCodex CLI\nIn your trusted terminal, add the remote server and sign in:\nReview 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; installed client versions and UI placement can differ.\nDo not paste OAuth tokens into the conversation. Do not configure a generic Bearer API key as a workaround for an OAuth error.\nGemini CLI\nAdd AnimGen to the current user's Gemini CLI configuration:\nThen open Gemini CLI and complete OAuth:\nDo 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.\nOther remote MCP clients\nUse 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.\nClient 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.\nIf authorization fails, use connection troubleshooting; do not weaken security checks or invent redirect settings.\nVerify without spending credits\nAsk the connected client:\nA structured model list confirms read-only connectivity. It does not approve any later generation or verify every downstream feature.\nNext, 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 for upload preparation, byte transfer, completion, quote, approval, polling, and download.\nManage permission and spending\nReview tool scopes and grant only the access needed. Revoke unused applications in Account → Developer. Removing a local configuration and revoking the server-side grant are separate actions.\nOAuth 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. Do not allow “test the connection” to become a paid generation."},{"id":"mcp.quickstart","locale":"en","title":"MCP quickstart and availability","description":"Connect to the live AnimGen remote MCP, review OAuth permissions, and follow the safe path from local images and approved quotes to downloaded assets.","section":"mcp","path":"/docs/en/mcp/quickstart","url":"https://animgen.com/docs/en/mcp/quickstart","status":"beta","lastVerified":"2026-08-31","audience":["user","ai-agent","api-developer"],"productAreas":["mcp"],"tags":["MCP","OAuth","AI","beta","Streamable HTTP"],"translations":{"en":"https://animgen.com/docs/en/mcp/quickstart","zh":"https://animgen.com/docs/zh/mcp/quickstart"},"headings":[{"id":"available-now-in-public-beta","title":"Available now in public beta","level":2},{"id":"make-the-first-connection","title":"Make the first connection","level":2},{"id":"tool-permissions","title":"Tool permissions","level":2},{"id":"a-safe-first-instruction-for-an-ai","title":"A safe first instruction for an AI","level":2},{"id":"manage-access-and-recover-failures","title":"Manage access and recover failures","level":2}],"text":"Available now in public beta\nThe 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.\nThe 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.\nMake the first connection\nFollow Codex and other client setup to add the exact endpoint and complete OAuth.\nCheck the AnimGen account and requested scopes on the authorization page.\nCall list_models with an empty argument object to verify read-only access.\nCheck whether the client can transfer local image bytes and save downloads.\nQuote a concrete request and obtain approval before paid generation.\nDo 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.\nTool permissions\nScope\nTools\nmodels:read\nlist_models\nfiles:write\nprepare_image_upload, complete_image_upload\nanimations:read\nget_animation\nanimations:write\nquote_animation, generate_animation, cancel_animation\nassets:read\ndownload_asset\nAll eight tools have generated references and a machine-readable manifest with real argument/result schemas and safety annotations. Generation still requires account eligibility, sufficient credits, and explicit spending approval.\nA safe first instruction for an AI\nFollow the standard workflow to transfer bytes, quote, generate, poll, and save files. Read spending safeguards: quote_id or max_credits is required beside request, and authorization is not spending approval.\nManage access and recover failures\nReview and revoke connected applications in Account → Developer. Revocation does not cancel an accepted task. For connection, upload, or quote errors, use API and MCP troubleshooting.\nPublic 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."},{"id":"mcp.spending-safeguards","locale":"en","title":"MCP spending safeguards","description":"Require concrete user approval, handle quote expiry and price changes, and preserve idempotency without silently increasing the allowed spend.","section":"mcp","path":"/docs/en/mcp/spending-safeguards","url":"https://animgen.com/docs/en/mcp/spending-safeguards","status":"beta","lastVerified":"2026-08-31","audience":["user","ai-agent","api-developer"],"productAreas":["mcp"],"tags":["MCP","credits","safety","quote_id","max_credits","idempotency"],"translations":{"en":"https://animgen.com/docs/en/mcp/spending-safeguards","zh":"https://animgen.com/docs/zh/mcp/spending-safeguards"},"headings":[{"id":"authorization-is-not-spending-approval","title":"Authorization is not spending approval","level":2},{"id":"two-server-side-guards","title":"Two server-side guards","level":2},{"id":"refusals-should-pause-generation","title":"Refusals should pause generation","level":2},{"id":"retries-and-cancellation","title":"Retries and cancellation","level":2},{"id":"keep-the-trail-useful-but-private","title":"Keep the trail useful but private","level":2}],"text":"Authorization is not spending approval\nThe official MCP is available in public beta. These safeguards apply to real calls, including calls made by an AI on your behalf.\nOAuth 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.\nTool 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.\nTwo server-side guards\nquote_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.\nmax_credits: an explicit nonnegative upper bound on the current quote for this generation.\nAt 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.\nKeep 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.\nRefusals should pause generation\nError\nCorrect next step\nSPEND_CONFIRMATION_REQUIRED\nObtain approval and provide a quote or explicit cap\nQUOTE_EXPIRED\nRe-quote; show the updated amount before approval\nQUOTE_MISMATCH\nReconcile the changed generation/export settings\nQUOTE_CHANGED\nShow the new price and request approval\nQUOTE_ALREADY_USED\nRecover the original task; do not recycle the quote for a new operation\nCREDIT_LIMIT_EXCEEDED\nStop; ask whether to lower the request or approve a different cap\nINSUFFICIENT_CREDITS\nReport the balance issue; do not buy credits automatically\nNever “fix” a refusal by dropping the cap, silently raising it, switching accounts, changing the image, or generating a new idempotency key.\nRetries and cancellation\nPersist 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.\nThe 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.\nIf 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.\nCancellation is best effort; work already performed can remain charged. Wait for a terminal state and report the actual credit accounting and usable assets.\nConfirmed 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.\nKeep the trail useful but private\nKeep 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.\nAPI callers should not copy these MCP-only parameters into POST /animations. The API quickstart explains its different quote semantics."},{"id":"mcp.standard-workflow","locale":"en","title":"MCP standard generation workflow","description":"Follow the exact tool sequence for local image upload, model selection, a user-approved quote, idempotent generation, polling, and asset download.","section":"mcp","path":"/docs/en/mcp/standard-workflow","url":"https://animgen.com/docs/en/mcp/standard-workflow","status":"beta","lastVerified":"2026-08-31","audience":["user","ai-agent","api-developer"],"productAreas":["mcp"],"tags":["MCP","tools","upload","quote","generate","download"],"translations":{"en":"https://animgen.com/docs/en/mcp/standard-workflow","zh":"https://animgen.com/docs/zh/mcp/standard-workflow"},"headings":[{"id":"availability-gate","title":"Availability gate","level":2},{"id":"1-discover-models","title":"1. Discover models","level":2},{"id":"2-transfer-a-local-image","title":"2. Transfer a local image","level":2},{"id":"3-construct-the-request-and-quote-it","title":"3. Construct the request and quote it","level":2},{"id":"4-generate-only-after-approval","title":"4. Generate only after approval","level":2},{"id":"5-poll-to-a-terminal-state","title":"5. Poll to a terminal state","level":2},{"id":"6-download-actual-bytes","title":"6. Download actual bytes","level":2}],"text":"Availability gate\nThe official MCP is live in public beta at https://api.animgen.com/mcp. Complete client setup with OAuth and a verified AnimGen account. A connection or model query does not approve a paid generation.\n1. Discover models\nCall 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.\n2. Transfer a local image\nA local path is not an ImageInput. The upload bridge has three distinct steps:\nCall prepare_image_upload with filename, mime_type, and the exact byte_size.\nSend 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.\nCall complete_image_upload with upload_id. Use its returned file_id in the generation request.\nDo 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.\n3. Construct the request and quote it\nThe 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.\nThe 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.\n4. Generate only after approval\nCall 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.\nUse 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 before implementing retries.\nPersist the returned task ID. A returned task is asynchronous, not a completed download.\n5. Poll to a terminal state\nCall 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.\nKeep 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.\n6. Download actual bytes\nFor 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.\nUse 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.\nIf a task needs cancellation, call cancel_animation with its animation_id, then poll. Cancellation is best effort and does not imply a full refund."},{"id":"reference.ai-and-search","locale":"en","title":"Find documentation with search or AI","description":"Use local documentation search and stable machine-readable resources, while keeping queries, code, credentials, and spending approvals private.","section":"reference","path":"/docs/en/reference/ai-and-search","url":"https://animgen.com/docs/en/reference/ai-and-search","status":"stable","lastVerified":"2026-09-01","audience":["user","api-developer","ai-agent"],"productAreas":["documentation"],"tags":["search","AI","llms.txt","privacy","feedback"],"translations":{"en":"https://animgen.com/docs/en/reference/ai-and-search","zh":"https://animgen.com/docs/zh/reference/ai-and-search"},"headings":[{"id":"search-in-this-browser","title":"Search in this browser","level":2},{"id":"give-an-ai-the-right-entry-point","title":"Give an AI the right entry point","level":2},{"id":"feedback-and-privacy","title":"Feedback and privacy","level":2}],"text":"Search in this browser\nSelect 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.\nTry 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.\nThe 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.\nIf the index cannot load, retry or use the document navigation. Search needs JavaScript; article text and navigation remain readable without it.\nGive an AI the right entry point\nResource\nPurpose\nllms.txt\nCompact learning links, availability, contract locations, and safety rules\nllms-full.txt\nCore public guides in both languages; generated field references remain in HTML and the contracts\ndocs-index.json\nAll document metadata, canonical URLs, headings, and searchable text\nOpenAPI JSON\nExact Public API operations, schemas, errors, and examples\nMCP tool manifest\nRegistered tool schemas, scopes, annotations, side effects, and availability\nTransparent-animation answer hub\nDirect answer, supported-input boundary, real sample evidence, format decision table, and downloadable assets\nAll 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.\nUse 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 has its own canonical URL and language alternates.\nThe 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; the JSON manifest itself is not a transport endpoint. Model discovery and a fresh quote remain necessary.\nFeedback and privacy\nThe 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.\nTurn 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.\nFeedback delivery is best effort, not a support ticket or guaranteed receipt. For an account issue, contact support without sending keys, tokens, private inputs, or signed links."},{"id":"studio.first-and-last-frames","locale":"en","title":"Guide motion with first and last frames","description":"Prepare compatible start and end poses, select a supporting model, and check transitions, transparency, and loop seams before exporting.","section":"studio","path":"/docs/en/studio/first-and-last-frames","url":"https://animgen.com/docs/en/studio/first-and-last-frames","status":"stable","lastVerified":"2026-08-30","audience":["user","api-developer","ai-agent"],"productAreas":["studio"],"tags":["首尾帧","first_frame","last_frame","pose","loop"],"translations":{"en":"https://animgen.com/docs/en/studio/first-and-last-frames","zh":"https://animgen.com/docs/zh/studio/first-and-last-frames"},"headings":[{"id":"prepare-two-compatible-images","title":"Prepare two compatible images","level":2},{"id":"create-the-transition-in-studio","title":"Create the transition in Studio","level":2},{"id":"make-space-before-generating","title":"Make space before generating","level":2},{"id":"check-the-seam-instead-of-assuming-a-loop","title":"Check the seam instead of assuming a loop","level":2},{"id":"public-request-shape","title":"Public request shape","level":2}],"text":"Prepare two compatible images\nUse 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.\nAn 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.\nCreate the transition in Studio\nSelect first + last frame mode and a compatible model.\nAdd the starting image and ending image. Reuse owned image resources when appropriate.\nDescribe one clear transition, such as “raise the shield, hold the final defensive pose, fixed camera.”\nReview supported duration, ratio, resolution, and the current quote.\nApprove generation, then inspect the entire preview, including both endpoints.\nIf you only want the first image to define the start, use first-frame mode. Adding references belongs to a different workflow.\nMake space before generating\nUse 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.\nCanvas 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.\nFor 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.\nCheck the seam instead of assuming a loop\nTwo 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.\nUse trim and frame selection for a continuous range, or Advanced Editor to remove, repeat, or reorder source frames. The editor changes sequence timing; it does not synthesize missing poses.\nPublic request shape\nSupply 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.\nIf 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."},{"id":"studio.input-canvas","locale":"en","title":"Give motion room with input canvas","description":"Scale and position input images before generation, choose padding backgrounds, and distinguish input preparation from output canvas editing.","section":"studio","path":"/docs/en/studio/input-canvas","url":"https://animgen.com/docs/en/studio/input-canvas","status":"stable","lastVerified":"2026-08-30","audience":["user","api-developer","ai-agent"],"productAreas":["studio"],"tags":["input_canvas","source_scale","输入画布","留白","cropping"],"translations":{"en":"https://animgen.com/docs/en/studio/input-canvas","zh":"https://animgen.com/docs/zh/studio/input-canvas"},"headings":[{"id":"use-it-before-a-subject-hits-the-edge","title":"Use it before a subject hits the edge","level":2},{"id":"supported-modes-and-controls","title":"Supported modes and controls","level":2},{"id":"keep-the-two-canvases-distinct","title":"Keep the two canvases distinct","level":2},{"id":"public-api-and-mcp-fields","title":"Public API and MCP fields","level":2}],"text":"Use it before a subject hits the edge\nInput 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.\nIt does not generate new scenery, isolate an opaque subject, or reconstruct content already cropped from the original. Keep an uncropped source image whenever possible.\nSupported modes and controls\nInput 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.\nEnable the input-canvas control in Studio, then choose:\nControl\nMeaning\n80%, 67%, 50% presets\nScale the source within the prepared canvas; smaller leaves more room\nNine-position grid\nPlace the scaled image within the remaining space\nFollow output / Source ratio\nUse the selected supported output ratio, or retain the source ratio\nAuto / Transparent / Solid\nChoose how the added area is filled\nReset\nReturn the controls to their starting configuration\nAuto 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.\nKeep the two canvases distinct\nInput 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.\nThe 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.\nPublic API and MCP fields\nThis is a fragment of the shared animation request, not a complete runnable request:\nsource_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.\nInspect both prepared poses, confirm model compatibility, and quote the final request. For export alignment and game-engine pivots, see canvas and pivot."},{"id":"studio.input-modes","locale":"en","title":"Choose an input mode","description":"Choose first frame, first and last frames, reference images, or an existing video, and match the request to live model capabilities.","section":"studio","path":"/docs/en/studio/input-modes","url":"https://animgen.com/docs/en/studio/input-modes","status":"stable","lastVerified":"2026-08-30","audience":["user","api-developer","ai-agent"],"productAreas":["studio"],"tags":["first_frame","first_last_frame","reference_images","video_import","模型","输入模式"],"translations":{"en":"https://animgen.com/docs/en/studio/input-modes","zh":"https://animgen.com/docs/zh/studio/input-modes"},"headings":[{"id":"choose-by-what-you-already-have","title":"Choose by what you already have","level":2},{"id":"follow-the-current-model-not-a-remembered-preset","title":"Follow the current model, not a remembered preset","level":2},{"id":"mapping-for-api-and-mcp-callers","title":"Mapping for API and MCP callers","level":2},{"id":"keep-transparency-and-cost-separate","title":"Keep transparency and cost separate","level":2}],"text":"Choose by what you already have\nInput\nChoose\nWhat it controls\nOne picture\nFirst frame\nThe starting appearance and composition\nA start and an end pose\nFirst + last frame\nTwo endpoints for the model to connect\nSeveral identity or appearance references\nReference images\nVisual guidance, not an ordered animation timeline\nAn existing clip\nImport video\nReuse motion and continue to editing and export\nOpen Studio, 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.\nFollow the current model, not a remembered preset\nAfter 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.\nA 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.\nMapping for API and MCP callers\nThe 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.\nDiscover 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. Internal Studio requests and public requests do not use identical field names.\nThe 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.\nKeep transparency and cost separate\nInput 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.\nChanging 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.\nContinue with first and last frames, reference images, input canvas, or video import."},{"id":"studio.models-and-prompts","locale":"en","title":"Select models and write motion prompts","description":"Use current capability discovery to choose a model and supported settings, then write focused motion instructions and approve the resulting quote.","section":"studio","path":"/docs/en/studio/models-and-prompts","url":"https://animgen.com/docs/en/studio/models-and-prompts","status":"stable","lastVerified":"2026-08-30","audience":["user","api-developer","ai-agent"],"productAreas":["studio"],"tags":["models","capabilities","prompt","提示词","resolution","duration","seed"],"translations":{"en":"https://animgen.com/docs/en/studio/models-and-prompts","zh":"https://animgen.com/docs/zh/studio/models-and-prompts"},"headings":[{"id":"discover-before-choosing","title":"Discover before choosing","level":2},{"id":"describe-one-action-clearly","title":"Describe one action clearly","level":2},{"id":"use-optional-controls-only-when-supported","title":"Use optional controls only when supported","level":2},{"id":"keep-model-exploration-safe-for-ai-clients","title":"Keep model exploration safe for AI clients","level":2}],"text":"Discover before choosing\nStudio lists currently available models for the selected input mode. API callers use the model catalog; MCP callers use list_models. Documentation examples are not a live availability or pricing table.\nChoose 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.\nReturned capability\nWhat to check\nmodes and support flags\nWhether the requested input workflow is allowed\ndurations_by_resolution\nWhich durations apply to the selected resolution\nratios_by_mode\nRatios allowed for this input mode\nmax_reference_images\nTotal reference count including the first image\nreference_image_duration_seconds\nWhether reference mode fixes duration\nrequires_prompt\nWhether a nonempty prompt is required\nUse 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.\nDescribe one action clearly\nA useful prompt names the subject, action, camera, and important constraints. For a sprite, a starting point could be:\nFor 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.\nThese are requests to the model, not guarantees. Inspect the preview before exporting. If the action is cropped, address the source framing or input canvas, not only the wording.\nUse optional controls only when supported\nNegative prompts, seed, watermark control, last-frame output, and reference images differ between models. An unsupported optional field can fail validation instead of being ignored.\nA 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.\nAvoid 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.\nKeep model exploration safe for AI clients\nModel 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.\nIf 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 and generation troubleshooting."},{"id":"studio.reference-images","locale":"en","title":"Use reference images","description":"Keep a character's appearance consistent with a model-supported reference set, count images correctly, and avoid mixing references with endpoint control.","section":"studio","path":"/docs/en/studio/reference-images","url":"https://animgen.com/docs/en/studio/reference-images","status":"stable","lastVerified":"2026-08-30","audience":["user","api-developer","ai-agent"],"productAreas":["studio"],"tags":["reference_images","max_reference_images","参考图","identity","模型能力"],"translations":{"en":"https://animgen.com/docs/en/studio/reference-images","zh":"https://animgen.com/docs/zh/studio/reference-images"},"headings":[{"id":"what-references-are-for","title":"What references are for","level":2},{"id":"the-image-limit-includes-the-first-image","title":"The image limit includes the first image","level":2},{"id":"keep-the-set-consistent","title":"Keep the set consistent","level":2},{"id":"api-and-mcp-mapping","title":"API and MCP mapping","level":2}],"text":"What references are for\nReference 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.\nChoose reference-image mode in Studio. 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.\nThe image limit includes the first image\nmax_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.\nThe 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.\nDo not assume reference mode is limited to one named provider or always uses eight seconds. Read models and prompts.\nKeep the set consistent\nUse 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.\nFirst + 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 is not supported in reference-image mode.\nFor 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.\nAPI and MCP mapping\ninput.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.\nSelect 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 give field limits; live discovery can impose a stricter model limit.\nQuote 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 for local-byte transfer and safe generation."},{"id":"studio.transparent-animation","locale":"en","title":"Regular and transparent animation","description":"Choose the right input workflow, understand Alpha Key previews, and export transparency without confusing it with background removal.","section":"studio","path":"/docs/en/studio/transparent-animation","url":"https://animgen.com/docs/en/studio/transparent-animation","status":"stable","lastVerified":"2026-08-30","audience":["user","api-developer"],"productAreas":["studio","export"],"tags":["alpha","transparent","PNG","alpha_key","background"],"translations":{"en":"https://animgen.com/docs/en/studio/transparent-animation","zh":"https://animgen.com/docs/zh/studio/transparent-animation"},"headings":[{"id":"choose-the-source-workflow","title":"Choose the source workflow","level":2},{"id":"why-a-preview-may-have-a-colored-background","title":"Why a preview may have a colored background","level":2},{"id":"export-the-intended-result","title":"Export the intended result","level":2},{"id":"public-api-boundary","title":"Public API boundary","level":2},{"id":"if-the-result-looks-wrong","title":"If the result looks wrong","level":2},{"id":"check-inputs-and-destination-compatibility","title":"Check inputs and destination compatibility","level":2}],"text":"Choose the source workflow\nGoal\nSource\nWorkflow\nKeep a scene or photograph background\nOrdinary image\nRegular image animation\nAnimate an already isolated character\nImages with meaningful alpha\nTransparent asset animation / Alpha Key\nRemove a complex background from ordinary footage\nOpaque source video\nSeparate Studio export processing, when offered; not a Public API feature\nA 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.\nWhy a preview may have a colored background\nAlpha 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.\nNormal 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.\nDo 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.\nExport the intended result\nSelect transparent PNG frames, an appropriate spritesheet or engine pack, WebM Alpha, or ProRes 4444. See output formats for what each file contains.\nInspect 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.\nThe 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.\nPublic API boundary\nThe 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.\nFor an appropriate source, the relevant request fragment is:\nThis is a fragment, not a complete create request: it still needs an input image and model-compatible options. Follow the API quickstart.\nIf the result looks wrong\nOpaque file: verify the selected output format and source mode, not just the filename.\nColored raw video: choose a transparent export rather than the raw source.\nMissing subject edges: inspect input alpha, key-color overlap, and generated motion.\nTransparent output unavailable: check source eligibility and export entitlement.\nDo not repeatedly regenerate before establishing whether the problem is the source, selection, export configuration, or viewing application.\nCheck inputs and destination compatibility\nFor tightly framed sources, consider input canvas. Check Alpha on every endpoint or reference. If encoded transparency displays incorrectly, use format compatibility and export troubleshooting."},{"id":"studio.video-import","locale":"en","title":"Import an existing video","description":"Bring an MP4, WebM, or MOV clip into Studio, reuse its motion, and continue through frame editing and export without another AI video generation.","section":"studio","path":"/docs/en/studio/video-import","url":"https://animgen.com/docs/en/studio/video-import","status":"stable","lastVerified":"2026-08-30","audience":["user","api-developer","ai-agent"],"productAreas":["studio"],"tags":["video_import","MP4","WebM","MOV","视频导入","existing video"],"translations":{"en":"https://animgen.com/docs/en/studio/video-import","zh":"https://animgen.com/docs/zh/studio/video-import"},"headings":[{"id":"start-from-motion-you-already-have","title":"Start from motion you already have","level":2},{"id":"upload-then-prepare-the-clip","title":"Upload, then prepare the clip","level":2},{"id":"choose-quick-or-fine-grained-editing","title":"Choose quick or fine-grained editing","level":2},{"id":"transparency-needs-a-separate-check","title":"Transparency needs a separate check","level":2},{"id":"boundaries-and-recovery","title":"Boundaries and recovery","level":2}],"text":"Start from motion you already have\nUse 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.\nOpen Studio, 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.\nUpload, then prepare the clip\nThe 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.\nWait 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.\nThe 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.\nChoose quick or fine-grained editing\nAfter the imported video is ready:\nPreview the entire source and confirm duration and orientation.\nUse trim and export for a continuous section.\nUse Advanced Editor when the output needs non-contiguous frames, holds, or a different order.\nReview output size, frame count/FPS, formats, and the export quote.\nDownload the actual files and inspect them in the target application.\nImport avoids another AI video generation; it does not mean every subsequent processing step or advanced format is free. See credits and access.\nTransparency needs a separate check\nImporting 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.\nAn 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.\nBoundaries and recovery\nInput canvas and AI model parameters do not apply to imported motion. Public API/MCP image-generation requests are not a video-import API.\nIf upload finished but the job failed, inspect the error and existing resource before uploading again. If space is exhausted, review storage and cleanup. Do not delete a source video still needed by an editor composition or export."},{"id":"troubleshooting.api-and-mcp","locale":"en","title":"Troubleshoot API and MCP connections","description":"Distinguish API keys from OAuth, resolve permissions and upload issues, and recover quotes or uncertain paid requests without bypassing safeguards.","section":"troubleshooting","path":"/docs/en/troubleshooting/api-and-mcp","url":"https://animgen.com/docs/en/troubleshooting/api-and-mcp","status":"stable","lastVerified":"2026-08-31","audience":["user","api-developer","ai-agent"],"productAreas":["documentation"],"tags":["MCP","OAuth","API","QUOTE_EXPIRED","CREDIT_LIMIT_EXCEEDED","连接失败","幂等"],"translations":{"en":"https://animgen.com/docs/en/troubleshooting/api-and-mcp","zh":"https://animgen.com/docs/zh/troubleshooting/api-and-mcp"},"headings":[{"id":"use-the-right-connection-and-credential","title":"Use the right connection and credential","level":2},{"id":"login-succeeds-but-tools-fail","title":"Login succeeds but tools fail","level":2},{"id":"upload-or-download-is-incomplete","title":"Upload or download is incomplete","level":2},{"id":"quote-and-spending-refusals","title":"Quote and spending refusals","level":2},{"id":"recover-an-uncertain-create-safely","title":"Recover an uncertain create safely","level":2}],"text":"Use the right connection and credential\nIntegration\nAddress\nAuthentication\nPublic API\nhttps://api.animgen.com/v1\nAppropriately scoped Bearer API key\nOfficial remote MCP\nhttps://api.animgen.com/mcp\nOAuth, through a compatible Streamable HTTP client\nTool manifest\nhttps://animgen.com/mcp/tools.json\nPublic documentation; not an MCP connection\nThe 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.\nDo 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.\nLogin succeeds but tools fail\nCheck 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.\nA 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.\nUse 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.\nUpload or download is incomplete\nThe 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.\nLikewise, 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.\nQuote and spending refusals\nCode\nNext action\nSPEND_CONFIRMATION_REQUIRED\nObtain concrete approval and supply the required guard\nQUOTE_EXPIRED\nRe-quote and review the updated amount\nQUOTE_MISMATCH / QUOTE_CHANGED\nReconcile changed parameters or price, then seek approval\nQUOTE_ALREADY_USED\nRecover the original operation, not a new use of that quote\nCREDIT_LIMIT_EXCEEDED\nStop; reduce scope or ask for a different approved cap\nINSUFFICIENT_CREDITS\nExplain the balance issue; do not auto-purchase\nquote_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.\nRecover an uncertain create safely\nRetain 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.\nPoll 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.\nA 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."},{"id":"troubleshooting.export-and-transparency","locale":"en","title":"Troubleshoot editing, exports, and transparency","description":"Separate editor-save issues, frame selection, export entitlement, transparent encoding, and target-engine rendering before deciding to regenerate.","section":"troubleshooting","path":"/docs/en/troubleshooting/export-and-transparency","url":"https://animgen.com/docs/en/troubleshooting/export-and-transparency","status":"stable","lastVerified":"2026-08-31","audience":["user","api-developer","ai-agent"],"productAreas":["documentation"],"tags":["export","Alpha","PAID_EXPORT_REQUIRED","COMPOSITION_CONFLICT","透明失败","导出失败"],"translations":{"en":"https://animgen.com/docs/en/troubleshooting/export-and-transparency","zh":"https://animgen.com/docs/zh/troubleshooting/export-and-transparency"},"headings":[{"id":"start-with-the-source-and-saved-recipe","title":"Start with the source and saved recipe","level":2},{"id":"format-unavailable-or-export-rejected","title":"Format unavailable or export rejected","level":2},{"id":"opaque-background-or-unexpected-key-color","title":"Opaque background or unexpected key color","level":2},{"id":"wrong-duration-frame-order-or-alignment","title":"Wrong duration, frame order, or alignment","level":2},{"id":"failed-export-with-partial-outputs","title":"Failed export with partial outputs","level":2},{"id":"download-fails-or-a-source-disappears","title":"Download fails or a source disappears","level":2}],"text":"Start with the source and saved recipe\nConfirm 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.\nFor 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.\nFormat unavailable or export rejected\nPAID_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.\nCheck 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.\nOpaque background or unexpected key color\nObservation\nLikely place to inspect\nRaw generated video has green/magenta background\nExpected Alpha Key intermediate; choose a transparent export\nDownloaded MP4 is opaque\nFormat does not carry the intended Alpha\nPNG is transparent, video looks black\nPlayer/decoder/compositing support\nEvery format contains the same unwanted background\nSource transparency, processing mode, or solid canvas\nThin halo or clipped detail\nSource Alpha, key-color spill, scaling, and target material\nOnly some frames fail verification\nInspect those frames; do not infer quality from the first frame alone\nKeep a PNG baseline from the same export settings. See transparent formats and compatibility. A viewer's checkerboard setting and an encoded Alpha channel are not the same thing.\nWrong duration, frame order, or alignment\nCompare 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.\nCheck 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.\nUse the specific Unity, Godot, Unreal, or Cocos instructions.\nFailed export with partial outputs\nA 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.\nIf 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.\nDownload fails or a source disappears\nRefresh 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; deleting history and deleting files have different effects.\nReport the task/request ID, format, error code, and whether matching PNGs display correctly through private support. Do not include raw signed URLs or credentials."},{"id":"troubleshooting.faq","locale":"en","title":"Frequently asked questions","description":"Resolve common first-run problems with previews, transparent outputs, locked formats, API retries, downloads, and the live MCP connection.","section":"troubleshooting","path":"/docs/en/troubleshooting/faq","url":"https://animgen.com/docs/en/troubleshooting/faq","status":"stable","lastVerified":"2026-08-31","audience":["user","ai-agent","api-developer"],"productAreas":["documentation"],"tags":["FAQ","troubleshooting","errors","download","transparent"],"translations":{"en":"https://animgen.com/docs/en/troubleshooting/faq","zh":"https://animgen.com/docs/zh/troubleshooting/faq"},"headings":[{"id":"why-is-my-generated-video-still-opaque","title":"Why is my generated video still opaque?","level":2},{"id":"i-can-play-the-video-where-are-my-pngs","title":"I can play the video. Where are my PNGs?","level":2},{"id":"why-is-a-format-locked-when-i-have-credits","title":"Why is a format locked when I have credits?","level":2},{"id":"is-the-result-guaranteed-to-form-a-seamless-loop","title":"Is the result guaranteed to form a seamless loop?","level":2},{"id":"an-api-request-timed-out-should-i-send-it-again","title":"An API request timed out. Should I send it again?","level":2},{"id":"the-task-failed-but-has-outputs-can-i-use-them","title":"The task failed but has outputs. Can I use them?","level":2},{"id":"why-did-my-download-link-stop-working","title":"Why did my download link stop working?","level":2},{"id":"can-i-give-an-ai-my-local-file-path","title":"Can I give an AI my local file path?","level":2},{"id":"does-a-quote-reserve-the-price","title":"Does a quote reserve the price?","level":2},{"id":"what-should-i-send-support","title":"What should I send support?","level":2},{"id":"continue-by-the-failing-stage","title":"Continue by the failing stage","level":2}],"text":"Why is my generated video still opaque?\nThe 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.\nI can play the video. Where are my PNGs?\nPreview 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.\nWhy is a format locked when I have credits?\nBalance 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.\nIs the result guaranteed to form a seamless loop?\nNo. 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.\nAn API request timed out. Should I send it again?\nRecover 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.\nThe task failed but has outputs. Can I use them?\nYes, 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.\nWhy did my download link stop working?\nSigned 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.\nCan I give an AI my local file path?\nA 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 and the MCP workflow.\nDoes a quote reserve the price?\nPublic 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.\nWhat should I send support?\nInclude 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.\nIf 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.\nContinue by the failing stage\nUploads and generation: files, Alpha, model options, queues, and partial results.\nEditing, export, and transparency: save conflicts, format entitlement, encoding, and engine display.\nAPI and MCP connections: OAuth, scopes, quote guards, and uncertain requests.\nStorage cleanup: quota, dependencies, deletion, and restoration.\nAn unknown task result is not a reason to switch accounts or credentials and generate again. Check the original operation and available outputs first."},{"id":"troubleshooting.generation-and-uploads","locale":"en","title":"Troubleshoot uploads and generation","description":"Identify whether a problem happened before upload, during request validation, or after job acceptance, and recover without duplicate paid work.","section":"troubleshooting","path":"/docs/en/troubleshooting/generation-and-uploads","url":"https://animgen.com/docs/en/troubleshooting/generation-and-uploads","status":"stable","lastVerified":"2026-08-30","audience":["user","api-developer","ai-agent"],"productAreas":["documentation"],"tags":["upload","generation","ALPHA_REQUIRED","PAYLOAD_TOO_LARGE","上传失败","生成失败"],"translations":{"en":"https://animgen.com/docs/en/troubleshooting/generation-and-uploads","zh":"https://animgen.com/docs/zh/troubleshooting/generation-and-uploads"},"headings":[{"id":"locate-the-failing-stage-first","title":"Locate the failing stage first","level":2},{"id":"upload-problems","title":"Upload problems","level":2},{"id":"unsupported-input-or-model-parameters","title":"Unsupported input or model parameters","level":2},{"id":"accepted-tasks-that-appear-stuck","title":"Accepted tasks that appear stuck","level":2},{"id":"quality-problems-after-a-successful-generation","title":"Quality problems after a successful generation","level":2},{"id":"escalate-with-a-small-safe-report","title":"Escalate with a small, safe report","level":2}],"text":"Locate the failing stage first\nKeep the selected account/workspace, approximate time, visible error code, and known task ID. Do not publish private image data, credentials, or signed URLs.\nA 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.\nUpload problems\nSymptom or code\nCheck next\nPAYLOAD_TOO_LARGE\nReduce actual bytes according to the returned limit\nInvalid image / UNSUPPORTED_MEDIA_TYPE\nVerify decoded format and MIME, not just extension\nImage dimensions rejected\nResize within the service's returned width/height limits\nSTORAGE_QUOTA_EXCEEDED\nReview account storage and safe resource cleanup\nUpload URL expired\nPrepare a new upload only after checking the original upload state\nCompleted transfer but no file ID\nComplete the upload; a PUT alone is not the whole flow\nFor 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.\nWeb 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.\nUnsupported input or model parameters\nRediscover model capabilities after switching mode, model, resolution, or duration. Check total reference count, optional-field support, and prompt requirements.\nFor 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.\nChanging 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.\nAccepted tasks that appear stuck\nqueued, 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.\nIf 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.\nCancellation is best effort. Report actual credit accounting instead of promising that failed or cancelled work was free.\nQuality problems after a successful generation\nFor cropped limbs, inspect original framing and input canvas. For inconsistent appearance, simplify reference images and the prompt. For a poor loop seam or unwanted pause, inspect frame selection in Advanced Editor.\nUse retained motion for another export when appropriate. A new AI generation is a new paid decision, not the default troubleshooting step.\nEscalate with a small, safe report\nPrivately 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."},{"id":"docs.home","locale":"zh","title":"AnimGen 使用文档","description":"从 Studio 制作与导出动画，到通过开放 API 和已上线的 MCP 接入自己的应用，找到适合你的学习路径。","section":"getting-started","path":"/docs/zh","url":"https://animgen.com/docs/zh","status":"stable","lastVerified":"2026-08-31","audience":["user","api-developer","ai-agent"],"productAreas":["documentation"],"tags":["入门","动画","文档"],"translations":{"en":"https://animgen.com/docs/en","zh":"https://animgen.com/docs/zh"},"headings":[{"id":"从一条工作流开始","title":"从一条工作流开始","level":2},{"id":"当前可以使用什么","title":"当前可以使用什么","level":2},{"id":"如何使用文档","title":"如何使用文档","level":2},{"id":"按任务深入学习","title":"按任务深入学习","level":2}],"text":"从一条工作流开始\nAnimGen 把源图片变成动画预览，再导出为可以使用的资产。你可以先检查动作，选择有用的片段，再为项目导出所需格式。\n先阅读产品概览，理解“生成”和“导出”的区别。也可以打开交互式 Demo，在创建真实任务前体验整个流程。\n当前可以使用什么\n使用入口\n当前状态\n从哪里开始\nWeb Studio\n已开放\n制作第一个动画\n开放 API\n公开测试；需要已验证账户与 API Key\n报价、创建、轮询与下载\n官方远程 MCP\n公开测试；OAuth 与已验证账户\n连接 AI 客户端\n账户中显示的模型选项、积分报价和导出权益是当前事实来源。文档不会承诺固定生成时长，也不会硬编码整份模型清单。\n如何使用文档\n通过左侧目录查找主题，通过本页目录跳转到具体章节。每篇文章都有固定的语言 URL 和最后核实日期。所有代码示例只使用占位符，不包含真实凭据。\n按 Ctrl+K / ⌘K 打开本地搜索。让 AI 查找相同的核实内容，可从 llms.txt 开始。详见搜索、AI 入口与反馈隐私。\n套餐与购买方式请查看定价页。账户问题可联系支持，请勿附带 API Key、Token 或签名下载链接。\n按任务深入学习\n你要完成什么\n教程\n选择素材和生成模式\n输入模式 · 模型与提示词\n制作角色过渡与一致外观\n首尾帧 · 参考图 · 输入画布\n精修已有动作\n导入视频 · Advanced Editor · 画布与 pivot\n接入游戏或透明视频\n格式与引擎指南 · 透明兼容性\n整理账户内容\n工作区与资源 · 账户安全 · 存储清理\n让 AI 操作工具\nMCP 客户端连接 · 调用流程"},{"id":"account-and-billing.account-security","locale":"zh","title":"管理账户与连接授权","description":"分别检查邮箱验证、订阅、积分、API Key 和 MCP 授权，并在不泄露凭据的前提下撤销不再使用的访问。","section":"account-and-billing","path":"/docs/zh/account-and-billing/account-security","url":"https://animgen.com/docs/zh/account-and-billing/account-security","status":"stable","lastVerified":"2026-08-30","audience":["user","api-developer","ai-agent"],"productAreas":["account"],"tags":["account","OAuth","API key","revoke","账户","授权","订阅"],"translations":{"en":"https://animgen.com/docs/en/account-and-billing/account-security","zh":"https://animgen.com/docs/zh/account-and-billing/account-security"},"headings":[{"id":"先确认实际使用的账户","title":"先确认实际使用的账户","level":2},{"id":"区分订阅取消与账户删除","title":"区分订阅取消与账户删除","level":2},{"id":"api-key-应保存在可信环境","title":"API Key 应保存在可信环境","level":2},{"id":"mcp-使用-oauth-不复制-api-key","title":"MCP 使用 OAuth，不复制 API Key","level":2},{"id":"怀疑访问泄露时","title":"怀疑访问泄露时","level":2}],"text":"先确认实际使用的账户\n打开账户中心，检查登录邮箱、验证状态、订阅和积分。浏览器登录与 AI 客户端 OAuth 登录可能属于不同账户。\n使用多个登录方式时，购买积分或重新连接客户端前，应确认它们进入的是目标账户。显示名相同不等于身份相同，只使用产品提供的账户关联入口。\n账户验证、有效订阅、导出权益和可用积分分别检查，详见积分与访问权益。\n区分订阅取消与账户删除\n账户中心显示当前订阅和计费周期信息。对应支付渠道提供管理入口时，可以通过该链接管理订阅。\n安排在周期结束时取消，不等于立即删除账户。应读取显示的生效时间和状态，不要假定权限已经结束。积分包不产生循环订阅，也不自动提高存储等级。\n降低套餐前先检查空间用量，下载重要资产，不把网站当作唯一备份。\nAPI Key 应保存在可信环境\n在账户 → 开发者创建和管理 Key。按集成分配最小必要权限，密钥不要进入浏览器前端包；不再使用或已经暴露的 Key 应撤销。\n不要把 Key 粘贴到提示词、截图、文档反馈、源代码仓库或支持邮件中，也不要把网页登录 Token 当作公开 API Key。\n付费请求结果不确定时，换 Key 会改变幂等身份。应先核对已有任务或请求，再决定后续操作，不要换 Key 后盲目重发。详见安全重试。\nMCP 使用 OAuth，不复制 API Key\n官方远程 MCP 已开放公开测试。按客户端接入指南连接，并在 AnimGen 授权页面核对请求权限。\n可在开发者账户区域查看已连接的 MCP 应用，撤销不再使用的授权。客户端不再使用时，还应单独移除其本地配置。撤销 OAuth 授权不会取消已提交任务，也不会退回已经发生的消费。\n授权只赋予能力，不代表批准所有后续收费。每次付费生成前，仍要确认具体请求、报价和用户批准。\n怀疑访问泄露时\n先停止使用受影响集成，撤销暴露的 Key 或授权，再检查近期任务和消费记录。如果存在结果不明的付费请求，保留任务 ID 便于核对。\n联系支持时提供简明问题描述和相关时间。私有标识仅通过适当的私密支持渠道提供；不要附带 Token、签名 URL、密码或完整支付资料。"},{"id":"account-and-billing.credits-and-access","locale":"zh","title":"积分与访问权益","description":"区分报价、积分余额、Web 格式权益与开发者访问条件，避免把有积分误认为所有功能都已解锁。","section":"account-and-billing","path":"/docs/zh/account-and-billing/credits-and-access","url":"https://animgen.com/docs/zh/account-and-billing/credits-and-access","status":"stable","lastVerified":"2026-08-31","audience":["user","api-developer"],"productAreas":["account","billing"],"tags":["credits","subscription","API key","entitlement"],"translations":{"en":"https://animgen.com/docs/en/account-and-billing/credits-and-access","zh":"https://animgen.com/docs/zh/account-and-billing/credits-and-access"},"headings":[{"id":"这是三项检查-不是一项","title":"这是三项检查，不是一项","level":2},{"id":"web-访问","title":"Web 访问","level":2},{"id":"开放-api-访问","title":"开放 API 访问","level":2},{"id":"启动前先获取报价","title":"启动前先获取报价","level":2},{"id":"取消任务与已有资产","title":"取消任务与已有资产","level":2},{"id":"mcp-访问与账户管理","title":"MCP 访问与账户管理","level":2}],"text":"这是三项检查，不是一项\n一个任务可能同时受功能访问权限、输出格式权益和积分余额限制。有积分不代表所有功能都可用。\nWeb 访问\n新账户可能获得账户页面显示的注册赠送积分，这不是每月自动刷新的免费额度。免费导出范围为 PNG 逐帧 ZIP。\n有效付费订阅，或仍在权益有效期内的合资格积分包购买，可以按照当前产品条款解锁高级 Web 导出与商业使用权益。目前积分包导出权益自购买起持续 365 天。具体条款与余额以价格页及账户显示为准。\n积分包不等于订阅，不会增加订阅存储或开发者限额。余额为零时，高级 Web 导出权益可能仍有效，但有费用的操作仍需足够积分。\n开放 API 访问\n开放 API 处于公开测试阶段，需要已验证账户。在账户 → 开发者创建 Key，按调用需要授予最小权限，并撤销不再使用的 Key。注册基础档使用基础限额，有效订阅会提高限额。\n积分不能绕过邮箱验证、账户暂停或 Key 权限。产生费用的生成在余额低于当前报价时仍会返回 INSUFFICIENT_CREDITS。\n启动前先获取报价\n生成及部分导出处理会消耗积分。费用受模型、时长、分辨率和处理设置影响，应使用界面报价或 API 报价接口，不要依据文档示例写死价格。\n报价不是已经扣款，也不保证后续创建时价格不变。API 创建任务时会重新计算。已上线的 MCP 为经过批准的工具调用提供明确支出保护。\n取消任务与已有资产\nSeedance 明确因内容审核拒绝、未交付视频时，退回本次原积分，包括注册赠送积分。API/MCP 一键任务在导出尚未开始时退回生成与导出的整笔积分，不等待供应商账单对账。任务和账单展示实际退回金额；账户或支付异常可能需要核验。\n有效积分保留原到期时间；原积分已过期时，仅退回部分获得 30 天有效期，不延长付费权益。这是积分返还，不是现金退款。网络超时、下载或导出失败本身不能证明审核拒绝。\n取消属于尽力而为。一旦生产开始，取消不代表已扣积分自动退回；未消耗的预占可以释放，前面阶段已完成的产物可能仍可下载。\n导出权益到期可能限制新建高级导出。已有资产的访问仍受归属、保留和存储政策影响，不要把签名 URL 当作永久存储。\n处理账户问题时，可向支持提供请求 ID 或任务 ID，以及简短描述。不要附上 API Key、OAuth Token、私有原图或带签名的下载链接。\nMCP 访问与账户管理\nMCP 已开放公开测试，同样要求已验证账户，使用 OAuth 而不是 API Key。按连接指南接入；授权不等于批准消费，订阅只负责提高账户限额。\n账户验证、取消时间与撤销授权见账户管理，资源用量和删除语义见存储清理。"},{"id":"account-and-billing.storage-and-cleanup","locale":"zh","title":"存储、下载与安全清理","description":"了解哪些文件计入空间、为什么删除历史不等于释放文件，并在不破坏任务和编辑配方的前提下清理资源。","section":"account-and-billing","path":"/docs/zh/account-and-billing/storage-and-cleanup","url":"https://animgen.com/docs/zh/account-and-billing/storage-and-cleanup","status":"stable","lastVerified":"2026-08-30","audience":["user","api-developer","ai-agent"],"productAreas":["account","resources"],"tags":["storage","quota","STORAGE_QUOTA_EXCEEDED","RESOURCE_IN_USE","存储","删除","清理"],"translations":{"en":"https://animgen.com/docs/en/account-and-billing/storage-and-cleanup","zh":"https://animgen.com/docs/zh/account-and-billing/storage-and-cleanup"},"headings":[{"id":"在账户中心查看用量","title":"在账户中心查看用量","level":2},{"id":"先弄清每种删除的作用","title":"先弄清每种删除的作用","level":2},{"id":"安全清理顺序","title":"安全清理顺序","level":2},{"id":"临时链接不是备份","title":"临时链接不是备份","level":2},{"id":"用量或下载不正常时","title":"用量或下载不正常时","level":2}],"text":"在账户中心查看用量\n账户中心显示总空间、上传文件大小、产出资产大小、资源数量，以及适用的当前配额。所有工作区保留的上传和资产都计入总量，包括已经隐藏或删除的工作区。\n配额取决于适用订阅或服务默认值；购买积分包不会升级存储。以当前账户显示为准，不照搬旧指南中的固定额度。\n上传或操作预计超过配额时，可能返回 STORAGE_QUOTA_EXCEEDED，包含已用、允许和预计用量。积分余额充足不能解除存储限制。\n先弄清每种删除的作用\n操作\n对空间和依赖的影响\n删除任务/历史条目\n隐藏该任务，不删除关联上传源文件和输出文件\n删除工作区\n隐藏工作区并请求取消任务，保留文件仍占空间\n恢复工作区\n恢复访问保留内容，不恢复单独删除的文件\n删除资源/资产\n将该资源从有效资源中移除，并尝试删除存储字节\n取消运行任务\n尽力停止，不会自动清理所有保留资源\n不要为了腾空间直接清空整个工作区。必要时先恢复隐藏工作区，再检查真实资源。\n安全清理顺序\n下载重要文件及配套元数据，确认本地副本能打开。\n在正确工作区识别大文件或重复资源。\n等待活跃生成/导出完成，或明确取消后等待终态。\n检查保存的编辑配方和后续导出是否仍需要源视频。\n仅删除确定不再需要的具体资源，再刷新用量。\nRESOURCE_IN_USE 表示活跃任务仍引用文件。删除任务历史不是绕过该保护的安全办法。即使活跃任务保护不再适用，已保存的 composition 也可能继续依赖来源。\n资源删除不属于工作区的软删除/恢复功能。单独删除的上传或输出文件，没有文档承诺的回收站恢复路径。不要用唯一副本测试清理。\n临时链接不是备份\n签名上传/下载 URL 会过期，但底层文件可能仍存在。资产存在时应重新获取授权下载链接，而不是重新生成。临时上传到期清理是另一种生命周期，文件可能真正被移除。\n拿到资产 ID 不代表永久保留承诺，需要长期保存的交付物应下载到本地。不要把签名链接公开到问题反馈，也不要把链接有效期当作文件保留期限。\n用量或下载不正常时\n清理后刷新账户视图。存储对象清理失败时，即使逻辑资源已移除，也可能需要支持处理；不要因此反复删除无关文件。\n文件找不到时，检查工作区、归属、删除历史，以及是否只是签名链接过期。编辑器缺少来源时，应先核对仍保留的资源，再考虑是否需要重新付费生成。\n详见工作区与资源及导出排障。"},{"id":"api-reference.index","locale":"zh","title":"API 接口参考","description":"自动生成全部公开 API 操作参考，包含权限、幂等、异步响应、错误和完整数据结构。","section":"api-reference","path":"/docs/zh/api-reference","url":"https://animgen.com/docs/zh/api-reference","status":"beta","lastVerified":"2026-08-30","apiVersion":"1.3.0","audience":["api-developer","ai-agent"],"productAreas":["public-api"],"tags":["reference","API","index"],"translations":{"en":"https://animgen.com/docs/en/api-reference","zh":"https://animgen.com/docs/zh/api-reference"},"headings":[{"id":"公开-api-契约","title":"公开 API 契约","level":2},{"id":"操作列表","title":"操作列表","level":2}],"text":"本页由后端契约生成。字段、必填项、约束和默认值来自源码模型。下载机器可读来源。示例 ID 与数值均为占位说明，不代表实时价格、限额或模型可用性。\n公开 API 契约\n基础地址：https://api.animgen.com/v1。公开测试，需要已验证的 AnimGen 账户，订阅会提高限额。先阅读快速开始。\n操作列表\n方法\n路径\n参考\nGET\n/account\n查询账户与限额\nGET\n/animation-exports\n列出动画导出任务\nPOST\n/animation-exports\n创建动画导出\nPOST\n/animation-exports/quote\n动画导出报价\nGET\n/animation-exports/{job_id}\n查询动画导出\nPOST\n/animation-exports/{job_id}/cancel\n取消动画导出\nGET\n/animations\n列出一键动画任务\nPOST\n/animations\n创建一键动画\nPOST\n/animations/quote\n一键动画报价\nGET\n/animations/{animation_id}\n查询一键动画\nPOST\n/animations/{animation_id}/cancel\n取消一键动画\nGET\n/assets/{asset_id}\n查询资产下载信息\nGET\n/assets/{asset_id}/content\n通过签名下载资产\nGET\n/credits/balance\n查询积分余额\nPOST\n/files\n上传图片\nGET\n/models\n查询模型能力\nGET\n/video-generations\n列出视频生成任务\nPOST\n/video-generations\n创建视频生成\nPOST\n/video-generations/quote\n视频生成报价\nGET\n/video-generations/{job_id}\n查询视频生成\nPOST\n/video-generations/{job_id}/cancel\n取消视频生成\n共享数据结构"},{"id":"api-reference.cancel-animation-exports","locale":"zh","title":"取消动画导出","description":"从源码生成 POST /animation-exports/{job_id}/cancel 的鉴权、字段、响应、错误与安全调用参考。","section":"api-reference","path":"/docs/zh/api-reference/cancel-animation-exports","url":"https://animgen.com/docs/zh/api-reference/cancel-animation-exports","status":"beta","lastVerified":"2026-08-30","apiVersion":"1.3.0","audience":["api-developer","ai-agent"],"productAreas":["public-api"],"tags":["reference","API","cancel-animation-exports"],"translations":{"en":"https://animgen.com/docs/en/api-reference/cancel-animation-exports","zh":"https://animgen.com/docs/zh/api-reference/cancel-animation-exports"},"headings":[{"id":"操作","title":"操作","level":2},{"id":"鉴权与副作用","title":"鉴权与副作用","level":2},{"id":"参数","title":"参数","level":2},{"id":"响应","title":"响应","level":2},{"id":"响应头","title":"响应头","level":3},{"id":"响应示例","title":"响应示例","level":3},{"id":"相关教程","title":"相关教程","level":2}],"text":"本页由后端契约生成。字段、必填项、约束和默认值来自源码模型。下载机器可读来源。示例 ID 与数值均为占位说明，不代表实时价格、限额或模型可用性。\n操作\nPOST /animation-exports/{job_id}/cancel\noperationId: cancel_animation_export_v1_animation_exports__job_id__cancel_post\n尽力取消所属任务，返回仍可能是非终态，应继续轮询。已完成工作可能保留扣费，未消耗预占可释放，先前产物可能保留；不保证全额退款。\n鉴权与副作用\n使用可信环境中的 Bearer API Key。所需权限：animations:write\n此操作不启动付费生成，其他状态变化见上文说明。\n参数\n参数\n位置\n类型\n必填\n约束 / 默认值\n含义\njob_id\npath\nstring\n是\nformat: uuid\n所属公共资源 UUID；任务、资产、文件 ID 不能互换。\n响应\nHTTP\n正文\n含义\n200\nTaskResponse\n成功的公开响应，示例数值仅用于说明。\n400\nAPIErrorEnvelope\n输入错误，修正请求后再尝试。\n401\nAPIErrorEnvelope\nAPI Key 缺失、到期或被撤销。\n403\nAPIErrorEnvelope\n账户资格、账户状态或 Key 权限不允许此操作。\n404\nAPIErrorEnvelope\n资源不可用、不属于当前用户，或签名无效/过期。\n429\nAPIErrorEnvelope\n触发账户级速率或队列限制，遵循 Retry-After 等待。\n500\nAPIErrorEnvelope\n内部错误，保留任务 ID 和幂等键，仅标记可重试时重试。\n503\nAPIErrorEnvelope\n服务或供应商不可用，仅 error.retryable 为 true 时重试。\n响应头\nHTTP\n响应头\n类型\n含义\n429\nRetry-After\ninteger\n建议等待秒数，遵循服务值并设置总体截止时间。\n503\nRetry-After\ninteger\n建议等待秒数，遵循服务值并设置总体截止时间。\n响应示例\n相关教程\n轮询与下载 · 错误与安全重试"},{"id":"api-reference.cancel-animations","locale":"zh","title":"取消一键动画","description":"从源码生成 POST /animations/{animation_id}/cancel 的鉴权、字段、响应、错误与安全调用参考。","section":"api-reference","path":"/docs/zh/api-reference/cancel-animations","url":"https://animgen.com/docs/zh/api-reference/cancel-animations","status":"beta","lastVerified":"2026-08-30","apiVersion":"1.3.0","audience":["api-developer","ai-agent"],"productAreas":["public-api"],"tags":["reference","API","cancel-animations"],"translations":{"en":"https://animgen.com/docs/en/api-reference/cancel-animations","zh":"https://animgen.com/docs/zh/api-reference/cancel-animations"},"headings":[{"id":"操作","title":"操作","level":2},{"id":"鉴权与副作用","title":"鉴权与副作用","level":2},{"id":"参数","title":"参数","level":2},{"id":"响应","title":"响应","level":2},{"id":"响应头","title":"响应头","level":3},{"id":"响应示例","title":"响应示例","level":3},{"id":"相关教程","title":"相关教程","level":2}],"text":"本页由后端契约生成。字段、必填项、约束和默认值来自源码模型。下载机器可读来源。示例 ID 与数值均为占位说明，不代表实时价格、限额或模型可用性。\n操作\nPOST /animations/{animation_id}/cancel\noperationId: cancel_one_click_animation_v1_animations__animation_id__cancel_post\n尽力取消所属任务，返回仍可能是非终态，应继续轮询。已完成工作可能保留扣费，未消耗预占可释放，先前产物可能保留；不保证全额退款。\n鉴权与副作用\n使用可信环境中的 Bearer API Key。所需权限：animations:write\n此操作不启动付费生成，其他状态变化见上文说明。\n参数\n参数\n位置\n类型\n必填\n约束 / 默认值\n含义\nanimation_id\npath\nstring\n是\nformat: uuid\n所属公共资源 UUID；任务、资产、文件 ID 不能互换。\n响应\nHTTP\n正文\n含义\n200\nTaskResponse\n成功的公开响应，示例数值仅用于说明。\n400\nAPIErrorEnvelope\n输入错误，修正请求后再尝试。\n401\nAPIErrorEnvelope\nAPI Key 缺失、到期或被撤销。\n403\nAPIErrorEnvelope\n账户资格、账户状态或 Key 权限不允许此操作。\n404\nAPIErrorEnvelope\n资源不可用、不属于当前用户，或签名无效/过期。\n429\nAPIErrorEnvelope\n触发账户级速率或队列限制，遵循 Retry-After 等待。\n500\nAPIErrorEnvelope\n内部错误，保留任务 ID 和幂等键，仅标记可重试时重试。\n503\nAPIErrorEnvelope\n服务或供应商不可用，仅 error.retryable 为 true 时重试。\n响应头\nHTTP\n响应头\n类型\n含义\n429\nRetry-After\ninteger\n建议等待秒数，遵循服务值并设置总体截止时间。\n503\nRetry-After\ninteger\n建议等待秒数，遵循服务值并设置总体截止时间。\n响应示例\n相关教程\n轮询与下载 · 错误与安全重试"},{"id":"api-reference.cancel-video-generations","locale":"zh","title":"取消视频生成","description":"从源码生成 POST /video-generations/{job_id}/cancel 的鉴权、字段、响应、错误与安全调用参考。","section":"api-reference","path":"/docs/zh/api-reference/cancel-video-generations","url":"https://animgen.com/docs/zh/api-reference/cancel-video-generations","status":"beta","lastVerified":"2026-08-30","apiVersion":"1.3.0","audience":["api-developer","ai-agent"],"productAreas":["public-api"],"tags":["reference","API","cancel-video-generations"],"translations":{"en":"https://animgen.com/docs/en/api-reference/cancel-video-generations","zh":"https://animgen.com/docs/zh/api-reference/cancel-video-generations"},"headings":[{"id":"操作","title":"操作","level":2},{"id":"鉴权与副作用","title":"鉴权与副作用","level":2},{"id":"参数","title":"参数","level":2},{"id":"响应","title":"响应","level":2},{"id":"响应头","title":"响应头","level":3},{"id":"响应示例","title":"响应示例","level":3},{"id":"相关教程","title":"相关教程","level":2}],"text":"本页由后端契约生成。字段、必填项、约束和默认值来自源码模型。下载机器可读来源。示例 ID 与数值均为占位说明，不代表实时价格、限额或模型可用性。\n操作\nPOST /video-generations/{job_id}/cancel\noperationId: cancel_video_generation_v1_video_generations__job_id__cancel_post\n尽力取消所属任务，返回仍可能是非终态，应继续轮询。已完成工作可能保留扣费，未消耗预占可释放，先前产物可能保留；不保证全额退款。\n鉴权与副作用\n使用可信环境中的 Bearer API Key。所需权限：animations:write\n此操作不启动付费生成，其他状态变化见上文说明。\n参数\n参数\n位置\n类型\n必填\n约束 / 默认值\n含义\njob_id\npath\nstring\n是\nformat: uuid\n所属公共资源 UUID；任务、资产、文件 ID 不能互换。\n响应\nHTTP\n正文\n含义\n200\nTaskResponse\n成功的公开响应，示例数值仅用于说明。\n400\nAPIErrorEnvelope\n输入错误，修正请求后再尝试。\n401\nAPIErrorEnvelope\nAPI Key 缺失、到期或被撤销。\n403\nAPIErrorEnvelope\n账户资格、账户状态或 Key 权限不允许此操作。\n404\nAPIErrorEnvelope\n资源不可用、不属于当前用户，或签名无效/过期。\n429\nAPIErrorEnvelope\n触发账户级速率或队列限制，遵循 Retry-After 等待。\n500\nAPIErrorEnvelope\n内部错误，保留任务 ID 和幂等键，仅标记可重试时重试。\n503\nAPIErrorEnvelope\n服务或供应商不可用，仅 error.retryable 为 true 时重试。\n响应头\nHTTP\n响应头\n类型\n含义\n429\nRetry-After\ninteger\n建议等待秒数，遵循服务值并设置总体截止时间。\n503\nRetry-After\ninteger\n建议等待秒数，遵循服务值并设置总体截止时间。\n响应示例\n相关教程\n轮询与下载 · 错误与安全重试"},{"id":"api-reference.create-animation-exports","locale":"zh","title":"创建动画导出","description":"从源码生成 POST /animation-exports 的鉴权、字段、响应、错误与安全调用参考。","section":"api-reference","path":"/docs/zh/api-reference/create-animation-exports","url":"https://animgen.com/docs/zh/api-reference/create-animation-exports","status":"beta","lastVerified":"2026-08-30","apiVersion":"1.3.0","audience":["api-developer","ai-agent"],"productAreas":["public-api"],"tags":["reference","API","create-animation-exports"],"translations":{"en":"https://animgen.com/docs/en/api-reference/create-animation-exports","zh":"https://animgen.com/docs/zh/api-reference/create-animation-exports"},"headings":[{"id":"操作","title":"操作","level":2},{"id":"鉴权与副作用","title":"鉴权与副作用","level":2},{"id":"参数","title":"参数","level":2},{"id":"请求体-application-json","title":"请求体 (application/json)","level":2},{"id":"请求示例","title":"请求示例","level":3},{"id":"响应","title":"响应","level":2},{"id":"响应头","title":"响应头","level":3},{"id":"响应示例","title":"响应示例","level":3},{"id":"相关教程","title":"相关教程","level":2}],"text":"本页由后端契约生成。字段、必填项、约束和默认值来自源码模型。下载机器可读来源。示例 ID 与数值均为占位说明，不代表实时价格、限额或模型可用性。\n操作\nPOST /animation-exports\noperationId: create_animation_export_v1_animation_exports_post\n启动付费异步任务。先报价并取得用户批准，立即保存任务 ID；202 仅代表已接受。响应不明时复用同一幂等键、凭据身份与未修改的请求。创建时重新计价；API 报价不锁价，max_credits/quote_id 不是 API 请求字段。遵循 Retry-After 轮询，所有终态（包括失败）都需检查 outputs。\n鉴权与副作用\n使用可信环境中的 Bearer API Key。所需权限：animations:write\n此操作创建付费任务，提交前取得批准。API 报价不锁价，也不强制执行最高预算。\n参数\n参数\n位置\n类型\n必填\n约束 / 默认值\n含义\nIdempotency-Key\nheader\nstring\n是\nminLength: 8; maxLength: 200\n每次逻辑操作生成并保存一次；同一凭据和未修改请求重试时复用，更换凭据会改变去重范围。\n请求体 (application/json)\n请求体必填：true\n字段\n类型\n必填\n默认值\n约束\n含义\nexport\nExportOptions\n否\n{\"frame_count\":24,\"output_formats\":[\"spritesheet\"],\"output_height\":512,\"output_width\":512,\"transparent\":{\"enabled\":false},\"unity\":{\"pivot\":\"bottom_center\",\"pixels_per_unit\":100}}\n—\n输出格式及处理设置。\nmetadata\nobject\n否\n{}\n—\n简单标量或 null 元数据，JSON 不超过 4 KiB，不包含凭据。\nselection\nSelection\n否\n{\"duration_seconds\":null,\"mode\":\"full\",\"start_seconds\":0}\n—\n需要导出的源视频区间。\nsource_video_asset_id\nstring\n是\n—\nformat: uuid\n所属源视频资产 ID，不是任务 ID；复用已有视频可避免重新生成动作。\n完整嵌套结构：AnimationExportCreateRequest\n请求示例\n响应\nHTTP\n正文\n含义\n202\nTaskResponse\n已接受异步任务，请保存任务 ID 并轮询。\n400\nAPIErrorEnvelope\n输入错误，修正请求后再尝试。\n401\nAPIErrorEnvelope\nAPI Key 缺失、到期或被撤销。\n402\nAPIErrorEnvelope\n积分不足，不自动购买。\n403\nAPIErrorEnvelope\n账户资格、账户状态或 Key 权限不允许此操作。\n404\nAPIErrorEnvelope\n资源不可用、不属于当前用户，或签名无效/过期。\n409\nAPIErrorEnvelope\n幂等冲突；仅 IDEMPOTENCY_IN_PROGRESS 可复用原请求重试。\n413\nAPIErrorEnvelope\n请求或解码后的图片超过配置限制。\n415\nAPIErrorEnvelope\n使用支持的图片媒体类型。\n422\nAPIErrorEnvelope\n图片解码后尺寸超过限制。\n429\nAPIErrorEnvelope\n触发账户级速率或队列限制，遵循 Retry-After 等待。\n500\nAPIErrorEnvelope\n内部错误，保留任务 ID 和幂等键，仅标记可重试时重试。\n503\nAPIErrorEnvelope\n服务或供应商不可用，仅 error.retryable 为 true 时重试。\n响应头\nHTTP\n响应头\n类型\n含义\n202\nRetry-After\ninteger\n建议等待秒数，遵循服务值并设置总体截止时间。\n429\nRetry-After\ninteger\n建议等待秒数，遵循服务值并设置总体截止时间。\n503\nRetry-After\ninteger\n建议等待秒数，遵循服务值并设置总体截止时间。\n响应示例\n相关教程\n轮询与下载 · 错误与安全重试"},{"id":"api-reference.create-animations","locale":"zh","title":"创建一键动画","description":"从源码生成 POST /animations 的鉴权、字段、响应、错误与安全调用参考。","section":"api-reference","path":"/docs/zh/api-reference/create-animations","url":"https://animgen.com/docs/zh/api-reference/create-animations","status":"beta","lastVerified":"2026-08-30","apiVersion":"1.3.0","audience":["api-developer","ai-agent"],"productAreas":["public-api"],"tags":["reference","API","create-animations"],"translations":{"en":"https://animgen.com/docs/en/api-reference/create-animations","zh":"https://animgen.com/docs/zh/api-reference/create-animations"},"headings":[{"id":"操作","title":"操作","level":2},{"id":"鉴权与副作用","title":"鉴权与副作用","level":2},{"id":"参数","title":"参数","level":2},{"id":"请求体-application-json","title":"请求体 (application/json)","level":2},{"id":"请求示例","title":"请求示例","level":3},{"id":"响应","title":"响应","level":2},{"id":"响应头","title":"响应头","level":3},{"id":"响应示例","title":"响应示例","level":3},{"id":"相关教程","title":"相关教程","level":2}],"text":"本页由后端契约生成。字段、必填项、约束和默认值来自源码模型。下载机器可读来源。示例 ID 与数值均为占位说明，不代表实时价格、限额或模型可用性。\n操作\nPOST /animations\noperationId: create_one_click_animation_v1_animations_post\n启动付费异步任务。先报价并取得用户批准，立即保存任务 ID；202 仅代表已接受。响应不明时复用同一幂等键、凭据身份与未修改的请求。创建时重新计价；API 报价不锁价，max_credits/quote_id 不是 API 请求字段。遵循 Retry-After 轮询，所有终态（包括失败）都需检查 outputs。\n鉴权与副作用\n使用可信环境中的 Bearer API Key。所需权限：animations:write\n此操作创建付费任务，提交前取得批准。API 报价不锁价，也不强制执行最高预算。\n参数\n参数\n位置\n类型\n必填\n约束 / 默认值\n含义\nIdempotency-Key\nheader\nstring\n是\nminLength: 8; maxLength: 200\n每次逻辑操作生成并保存一次；同一凭据和未修改请求重试时复用，更换凭据会改变去重范围。\n请求体 (application/json)\n请求体必填：true\n字段\n类型\n必填\n默认值\n约束\n含义\nexport\nExportOptions\n否\n{\"frame_count\":24,\"output_formats\":[\"spritesheet\"],\"output_height\":512,\"output_width\":512,\"transparent\":{\"enabled\":false},\"unity\":{\"pivot\":\"bottom_center\",\"pixels_per_unit\":100}}\n—\n视频生成后执行导出；带 Alpha 的格式要求 alpha_key 来源，适配格式会自动启用其透明处理。\ninput\nGenerationInput\n是\n—\n—\n调用方所属或本次提供的生成图片。\nmetadata\nobject\n否\n{}\n—\n调用方元数据，仅字符串、数字、布尔或 null；JSON 不超过 4 KiB，不存凭据。\nnegative_prompt\nstring\n否\n\"\"\nmaxLength: 4000\n可选负向提示词，仅适用于支持的模型。\nprompt\nstring\n否\n\"\"\nmaxLength: 8000\n动作提示词；模型要求时不能为空，私有提示词不得写入日志。\nselection\nSelection\n否\n{\"duration_seconds\":null,\"mode\":\"full\",\"start_seconds\":0}\n—\n生成后选取的区间，默认完整视频。\nvideo\nVideoOptions\n否\n{\"duration_seconds\":null,\"input_canvas\":null,\"model\":null,\"ratio\":null,\"resolution\":null,\"seed\":null,\"style_preset\":null,\"transparency\":{\"key_color\":null,\"key_selection\":\"auto\",\"mode\":\"standard\"},\"watermark\":null}\n—\n符合模型能力的生成设置。\n完整嵌套结构：AnimationCreateRequest\n请求示例\n响应\nHTTP\n正文\n含义\n202\nTaskResponse\n已接受异步任务，请保存任务 ID 并轮询。\n400\nAPIErrorEnvelope\n输入错误，修正请求后再尝试。\n401\nAPIErrorEnvelope\nAPI Key 缺失、到期或被撤销。\n402\nAPIErrorEnvelope\n积分不足，不自动购买。\n403\nAPIErrorEnvelope\n账户资格、账户状态或 Key 权限不允许此操作。\n404\nAPIErrorEnvelope\n资源不可用、不属于当前用户，或签名无效/过期。\n409\nAPIErrorEnvelope\n幂等冲突；仅 IDEMPOTENCY_IN_PROGRESS 可复用原请求重试。\n413\nAPIErrorEnvelope\n请求或解码后的图片超过配置限制。\n415\nAPIErrorEnvelope\n使用支持的图片媒体类型。\n422\nAPIErrorEnvelope\n图片解码后尺寸超过限制。\n429\nAPIErrorEnvelope\n触发账户级速率或队列限制，遵循 Retry-After 等待。\n500\nAPIErrorEnvelope\n内部错误，保留任务 ID 和幂等键，仅标记可重试时重试。\n503\nAPIErrorEnvelope\n服务或供应商不可用，仅 error.retryable 为 true 时重试。\n响应头\nHTTP\n响应头\n类型\n含义\n202\nRetry-After\ninteger\n建议等待秒数，遵循服务值并设置总体截止时间。\n429\nRetry-After\ninteger\n建议等待秒数，遵循服务值并设置总体截止时间。\n503\nRetry-After\ninteger\n建议等待秒数，遵循服务值并设置总体截止时间。\n响应示例\n相关教程\n轮询与下载 · 错误与安全重试"},{"id":"api-reference.create-video-generations","locale":"zh","title":"创建视频生成","description":"从源码生成 POST /video-generations 的鉴权、字段、响应、错误与安全调用参考。","section":"api-reference","path":"/docs/zh/api-reference/create-video-generations","url":"https://animgen.com/docs/zh/api-reference/create-video-generations","status":"beta","lastVerified":"2026-08-30","apiVersion":"1.3.0","audience":["api-developer","ai-agent"],"productAreas":["public-api"],"tags":["reference","API","create-video-generations"],"translations":{"en":"https://animgen.com/docs/en/api-reference/create-video-generations","zh":"https://animgen.com/docs/zh/api-reference/create-video-generations"},"headings":[{"id":"操作","title":"操作","level":2},{"id":"鉴权与副作用","title":"鉴权与副作用","level":2},{"id":"参数","title":"参数","level":2},{"id":"请求体-application-json","title":"请求体 (application/json)","level":2},{"id":"请求示例","title":"请求示例","level":3},{"id":"响应","title":"响应","level":2},{"id":"响应头","title":"响应头","level":3},{"id":"响应示例","title":"响应示例","level":3},{"id":"相关教程","title":"相关教程","level":2}],"text":"本页由后端契约生成。字段、必填项、约束和默认值来自源码模型。下载机器可读来源。示例 ID 与数值均为占位说明，不代表实时价格、限额或模型可用性。\n操作\nPOST /video-generations\noperationId: create_video_generation_v1_video_generations_post\n启动付费异步任务。先报价并取得用户批准，立即保存任务 ID；202 仅代表已接受。响应不明时复用同一幂等键、凭据身份与未修改的请求。创建时重新计价；API 报价不锁价，max_credits/quote_id 不是 API 请求字段。遵循 Retry-After 轮询，所有终态（包括失败）都需检查 outputs。\n鉴权与副作用\n使用可信环境中的 Bearer API Key。所需权限：animations:write\n此操作创建付费任务，提交前取得批准。API 报价不锁价，也不强制执行最高预算。\n参数\n参数\n位置\n类型\n必填\n约束 / 默认值\n含义\nIdempotency-Key\nheader\nstring\n是\nminLength: 8; maxLength: 200\n每次逻辑操作生成并保存一次；同一凭据和未修改请求重试时复用，更换凭据会改变去重范围。\n请求体 (application/json)\n请求体必填：true\n字段\n类型\n必填\n默认值\n约束\n含义\ninput\nGenerationInput\n是\n—\n—\n调用方所属或本次提供的生成图片。\nmetadata\nobject\n否\n{}\n—\n调用方元数据，仅字符串、数字、布尔或 null；JSON 不超过 4 KiB，不存凭据。\nnegative_prompt\nstring\n否\n\"\"\nmaxLength: 4000\n可选负向提示词，仅适用于支持的模型。\nprompt\nstring\n否\n\"\"\nmaxLength: 8000\n动作提示词；模型要求时不能为空，私有提示词不得写入日志。\nvideo\nVideoOptions\n否\n{\"duration_seconds\":null,\"input_canvas\":null,\"model\":null,\"ratio\":null,\"resolution\":null,\"seed\":null,\"style_preset\":null,\"transparency\":{\"key_color\":null,\"key_selection\":\"auto\",\"mode\":\"standard\"},\"watermark\":null}\n—\n符合模型能力的生成设置。\n完整嵌套结构：VideoGenerationCreateRequest\n请求示例\n响应\nHTTP\n正文\n含义\n202\nTaskResponse\n已接受异步任务，请保存任务 ID 并轮询。\n400\nAPIErrorEnvelope\n输入错误，修正请求后再尝试。\n401\nAPIErrorEnvelope\nAPI Key 缺失、到期或被撤销。\n402\nAPIErrorEnvelope\n积分不足，不自动购买。\n403\nAPIErrorEnvelope\n账户资格、账户状态或 Key 权限不允许此操作。\n404\nAPIErrorEnvelope\n资源不可用、不属于当前用户，或签名无效/过期。\n409\nAPIErrorEnvelope\n幂等冲突；仅 IDEMPOTENCY_IN_PROGRESS 可复用原请求重试。\n413\nAPIErrorEnvelope\n请求或解码后的图片超过配置限制。\n415\nAPIErrorEnvelope\n使用支持的图片媒体类型。\n422\nAPIErrorEnvelope\n图片解码后尺寸超过限制。\n429\nAPIErrorEnvelope\n触发账户级速率或队列限制，遵循 Retry-After 等待。\n500\nAPIErrorEnvelope\n内部错误，保留任务 ID 和幂等键，仅标记可重试时重试。\n503\nAPIErrorEnvelope\n服务或供应商不可用，仅 error.retryable 为 true 时重试。\n响应头\nHTTP\n响应头\n类型\n含义\n202\nRetry-After\ninteger\n建议等待秒数，遵循服务值并设置总体截止时间。\n429\nRetry-After\ninteger\n建议等待秒数，遵循服务值并设置总体截止时间。\n503\nRetry-After\ninteger\n建议等待秒数，遵循服务值并设置总体截止时间。\n响应示例\n相关教程\n轮询与下载 · 错误与安全重试"},{"id":"api-reference.download-asset","locale":"zh","title":"通过签名下载资产","description":"从源码生成 GET /assets/{asset_id}/content 的鉴权、字段、响应、错误与安全调用参考。","section":"api-reference","path":"/docs/zh/api-reference/download-asset","url":"https://animgen.com/docs/zh/api-reference/download-asset","status":"beta","lastVerified":"2026-08-30","apiVersion":"1.3.0","audience":["api-developer","ai-agent"],"productAreas":["public-api"],"tags":["reference","API","download-asset"],"translations":{"en":"https://animgen.com/docs/en/api-reference/download-asset","zh":"https://animgen.com/docs/zh/api-reference/download-asset"},"headings":[{"id":"操作","title":"操作","level":2},{"id":"鉴权与副作用","title":"鉴权与副作用","level":2},{"id":"参数","title":"参数","level":2},{"id":"响应","title":"响应","level":2},{"id":"响应头","title":"响应头","level":3},{"id":"相关教程","title":"相关教程","level":2}],"text":"本页由后端契约生成。字段、必填项、约束和默认值来自源码模型。下载机器可读来源。示例 ID 与数值均为占位说明，不代表实时价格、限额或模型可用性。\n操作\nGET /assets/{asset_id}/content\noperationId: download_asset_v1_assets__asset_id__content_get\n使用 Asset 响应给出的完整签名 URL 下载字节，无需也不建议携带 Bearer 头。不要自行构造签名，不转发凭据给存储。按交付模式返回文件或 302 跳转。过期或无效签名表现为 NOT_FOUND，应通过 GET /assets/{asset_id} 刷新信息。\n鉴权与副作用\n使用返回的完整签名 URL，不携带 Bearer Key。\n此操作不启动付费生成，其他状态变化见上文说明。\n参数\n参数\n位置\n类型\n必填\n约束 / 默认值\n含义\nasset_id\npath\nstring\n是\nformat: uuid\n所属公共资源 UUID；任务、资产、文件 ID 不能互换。\nexpires\nquery\ninteger\n是\nexclusiveMinimum: 0\n使用返回的签名 URL 中的值，不自行构造或记录。\nsignature\nquery\nstring\n是\nminLength: 64; maxLength: 64\n使用返回的签名 URL 中的值，不自行构造或记录。\n响应\nHTTP\n正文\n含义\n200\nstring\n资产字节，Content-Type 由具体资产决定。\n302\n—\n重定向到短期存储地址，不转发凭据。\n400\nAPIErrorEnvelope\n输入错误，修正请求后再尝试。\n404\nAPIErrorEnvelope\n资源不可用、不属于当前用户，或签名无效/过期。\n500\nAPIErrorEnvelope\n内部错误，保留任务 ID 和幂等键，仅标记可重试时重试。\n503\nAPIErrorEnvelope\n服务或供应商不可用，仅 error.retryable 为 true 时重试。\n响应头\nHTTP\n响应头\n类型\n含义\n302\nLocation\nstring\n短期有效的存储下载地址。\n相关教程\n轮询与下载 · 错误与安全重试"},{"id":"api-reference.get-account","locale":"zh","title":"查询账户与限额","description":"从源码生成 GET /account 的鉴权、字段、响应、错误与安全调用参考。","section":"api-reference","path":"/docs/zh/api-reference/get-account","url":"https://animgen.com/docs/zh/api-reference/get-account","status":"beta","lastVerified":"2026-08-30","apiVersion":"1.3.0","audience":["api-developer","ai-agent"],"productAreas":["public-api"],"tags":["reference","API","get-account"],"translations":{"en":"https://animgen.com/docs/en/api-reference/get-account","zh":"https://animgen.com/docs/zh/api-reference/get-account"},"headings":[{"id":"操作","title":"操作","level":2},{"id":"鉴权与副作用","title":"鉴权与副作用","level":2},{"id":"参数","title":"参数","level":2},{"id":"响应","title":"响应","level":2},{"id":"响应头","title":"响应头","level":3},{"id":"响应示例","title":"响应示例","level":3},{"id":"相关教程","title":"相关教程","level":2}],"text":"本页由后端契约生成。字段、必填项、约束和默认值来自源码模型。下载机器可读来源。示例 ID 与数值均为占位说明，不代表实时价格、限额或模型可用性。\n操作\nGET /account\noperationId: account_v1_account_get\n读取当前账户、开发者访问档位、可选订阅周期、Key 标识及权限和账户级限额，不返回密钥。订阅会提高限额，但不是访问前提。恢复结果不明的幂等创建时，应保持相同 Key 身份。\n鉴权与副作用\n使用可信环境中的 Bearer API Key。所需权限：animations:read\n此操作不启动付费生成，其他状态变化见上文说明。\n参数\n无路径、查询或操作专属请求头参数。\n响应\nHTTP\n正文\n含义\n200\nAccountResponse\n成功的公开响应，示例数值仅用于说明。\n400\nAPIErrorEnvelope\n输入错误，修正请求后再尝试。\n401\nAPIErrorEnvelope\nAPI Key 缺失、到期或被撤销。\n403\nAPIErrorEnvelope\n账户资格、账户状态或 Key 权限不允许此操作。\n404\nAPIErrorEnvelope\n资源不可用、不属于当前用户，或签名无效/过期。\n429\nAPIErrorEnvelope\n触发账户级速率或队列限制，遵循 Retry-After 等待。\n500\nAPIErrorEnvelope\n内部错误，保留任务 ID 和幂等键，仅标记可重试时重试。\n503\nAPIErrorEnvelope\n服务或供应商不可用，仅 error.retryable 为 true 时重试。\n响应头\nHTTP\n响应头\n类型\n含义\n429\nRetry-After\ninteger\n建议等待秒数，遵循服务值并设置总体截止时间。\n503\nRetry-After\ninteger\n建议等待秒数，遵循服务值并设置总体截止时间。\n响应示例\n相关教程\n轮询与下载 · 错误与安全重试"},{"id":"api-reference.get-animation-exports","locale":"zh","title":"查询动画导出","description":"从源码生成 GET /animation-exports/{job_id} 的鉴权、字段、响应、错误与安全调用参考。","section":"api-reference","path":"/docs/zh/api-reference/get-animation-exports","url":"https://animgen.com/docs/zh/api-reference/get-animation-exports","status":"beta","lastVerified":"2026-08-30","apiVersion":"1.3.0","audience":["api-developer","ai-agent"],"productAreas":["public-api"],"tags":["reference","API","get-animation-exports"],"translations":{"en":"https://animgen.com/docs/en/api-reference/get-animation-exports","zh":"https://animgen.com/docs/zh/api-reference/get-animation-exports"},"headings":[{"id":"操作","title":"操作","level":2},{"id":"鉴权与副作用","title":"鉴权与副作用","level":2},{"id":"参数","title":"参数","level":2},{"id":"响应","title":"响应","level":2},{"id":"响应头","title":"响应头","level":3},{"id":"响应示例","title":"响应示例","level":3},{"id":"相关教程","title":"相关教程","level":2}],"text":"本页由后端契约生成。字段、必填项、约束和默认值来自源码模型。下载机器可读来源。示例 ID 与数值均为占位说明，不代表实时价格、限额或模型可用性。\n操作\nGET /animation-exports/{job_id}\noperationId: get_animation_export_v1_animation_exports__job_id__get\n读取所属任务。遵循 Retry-After 并设置轮询截止时间。queued、running、cancelling 非终态；succeeded、failed、cancelled 为终态。后续阶段失败仍可能有可用产物，进度不代表精确时间。\n鉴权与副作用\n使用可信环境中的 Bearer API Key。所需权限：animations:read\n此操作不启动付费生成，其他状态变化见上文说明。\n参数\n参数\n位置\n类型\n必填\n约束 / 默认值\n含义\njob_id\npath\nstring\n是\nformat: uuid\n所属公共资源 UUID；任务、资产、文件 ID 不能互换。\n响应\nHTTP\n正文\n含义\n200\nTaskResponse\n成功的公开响应，示例数值仅用于说明。\n400\nAPIErrorEnvelope\n输入错误，修正请求后再尝试。\n401\nAPIErrorEnvelope\nAPI Key 缺失、到期或被撤销。\n403\nAPIErrorEnvelope\n账户资格、账户状态或 Key 权限不允许此操作。\n404\nAPIErrorEnvelope\n资源不可用、不属于当前用户，或签名无效/过期。\n429\nAPIErrorEnvelope\n触发账户级速率或队列限制，遵循 Retry-After 等待。\n500\nAPIErrorEnvelope\n内部错误，保留任务 ID 和幂等键，仅标记可重试时重试。\n503\nAPIErrorEnvelope\n服务或供应商不可用，仅 error.retryable 为 true 时重试。\n响应头\nHTTP\n响应头\n类型\n含义\n200\nRetry-After\ninteger\n建议等待秒数，遵循服务值并设置总体截止时间。\n429\nRetry-After\ninteger\n建议等待秒数，遵循服务值并设置总体截止时间。\n503\nRetry-After\ninteger\n建议等待秒数，遵循服务值并设置总体截止时间。\n响应示例\n相关教程\n轮询与下载 · 错误与安全重试"},{"id":"api-reference.get-animations","locale":"zh","title":"查询一键动画","description":"从源码生成 GET /animations/{animation_id} 的鉴权、字段、响应、错误与安全调用参考。","section":"api-reference","path":"/docs/zh/api-reference/get-animations","url":"https://animgen.com/docs/zh/api-reference/get-animations","status":"beta","lastVerified":"2026-08-30","apiVersion":"1.3.0","audience":["api-developer","ai-agent"],"productAreas":["public-api"],"tags":["reference","API","get-animations"],"translations":{"en":"https://animgen.com/docs/en/api-reference/get-animations","zh":"https://animgen.com/docs/zh/api-reference/get-animations"},"headings":[{"id":"操作","title":"操作","level":2},{"id":"鉴权与副作用","title":"鉴权与副作用","level":2},{"id":"参数","title":"参数","level":2},{"id":"响应","title":"响应","level":2},{"id":"响应头","title":"响应头","level":3},{"id":"响应示例","title":"响应示例","level":3},{"id":"相关教程","title":"相关教程","level":2}],"text":"本页由后端契约生成。字段、必填项、约束和默认值来自源码模型。下载机器可读来源。示例 ID 与数值均为占位说明，不代表实时价格、限额或模型可用性。\n操作\nGET /animations/{animation_id}\noperationId: get_one_click_animation_v1_animations__animation_id__get\n读取所属任务。遵循 Retry-After 并设置轮询截止时间。queued、running、cancelling 非终态；succeeded、failed、cancelled 为终态。后续阶段失败仍可能有可用产物，进度不代表精确时间。\n鉴权与副作用\n使用可信环境中的 Bearer API Key。所需权限：animations:read\n此操作不启动付费生成，其他状态变化见上文说明。\n参数\n参数\n位置\n类型\n必填\n约束 / 默认值\n含义\nanimation_id\npath\nstring\n是\nformat: uuid\n所属公共资源 UUID；任务、资产、文件 ID 不能互换。\n响应\nHTTP\n正文\n含义\n200\nTaskResponse\n成功的公开响应，示例数值仅用于说明。\n400\nAPIErrorEnvelope\n输入错误，修正请求后再尝试。\n401\nAPIErrorEnvelope\nAPI Key 缺失、到期或被撤销。\n403\nAPIErrorEnvelope\n账户资格、账户状态或 Key 权限不允许此操作。\n404\nAPIErrorEnvelope\n资源不可用、不属于当前用户，或签名无效/过期。\n429\nAPIErrorEnvelope\n触发账户级速率或队列限制，遵循 Retry-After 等待。\n500\nAPIErrorEnvelope\n内部错误，保留任务 ID 和幂等键，仅标记可重试时重试。\n503\nAPIErrorEnvelope\n服务或供应商不可用，仅 error.retryable 为 true 时重试。\n响应头\nHTTP\n响应头\n类型\n含义\n200\nRetry-After\ninteger\n建议等待秒数，遵循服务值并设置总体截止时间。\n429\nRetry-After\ninteger\n建议等待秒数，遵循服务值并设置总体截止时间。\n503\nRetry-After\ninteger\n建议等待秒数，遵循服务值并设置总体截止时间。\n响应示例\n相关教程\n轮询与下载 · 错误与安全重试"},{"id":"api-reference.get-asset","locale":"zh","title":"查询资产下载信息","description":"从源码生成 GET /assets/{asset_id} 的鉴权、字段、响应、错误与安全调用参考。","section":"api-reference","path":"/docs/zh/api-reference/get-asset","url":"https://animgen.com/docs/zh/api-reference/get-asset","status":"beta","lastVerified":"2026-08-30","apiVersion":"1.3.0","audience":["api-developer","ai-agent"],"productAreas":["public-api"],"tags":["reference","API","get-asset"],"translations":{"en":"https://animgen.com/docs/en/api-reference/get-asset","zh":"https://animgen.com/docs/zh/api-reference/get-asset"},"headings":[{"id":"操作","title":"操作","level":2},{"id":"鉴权与副作用","title":"鉴权与副作用","level":2},{"id":"参数","title":"参数","level":2},{"id":"响应","title":"响应","level":2},{"id":"响应头","title":"响应头","level":3},{"id":"响应示例","title":"响应示例","level":3},{"id":"相关教程","title":"相关教程","level":2}],"text":"本页由后端契约生成。字段、必填项、约束和默认值来自源码模型。下载机器可读来源。示例 ID 与数值均为占位说明，不代表实时价格、限额或模型可用性。\n操作\nGET /assets/{asset_id}\noperationId: get_asset_v1_assets__asset_id__get\n读取所属资产并返回新的短期签名下载 URL。持久保存资产 ID，而不是过期链接。实际下载及存储跳转均不应携带 API 凭据，仍受归属和保留策略限制。\n鉴权与副作用\n使用可信环境中的 Bearer API Key。所需权限：animations:read\n此操作不启动付费生成，其他状态变化见上文说明。\n参数\n参数\n位置\n类型\n必填\n约束 / 默认值\n含义\nasset_id\npath\nstring\n是\nformat: uuid\n所属公共资源 UUID；任务、资产、文件 ID 不能互换。\n响应\nHTTP\n正文\n含义\n200\nAssetResponse\n成功的公开响应，示例数值仅用于说明。\n400\nAPIErrorEnvelope\n输入错误，修正请求后再尝试。\n401\nAPIErrorEnvelope\nAPI Key 缺失、到期或被撤销。\n403\nAPIErrorEnvelope\n账户资格、账户状态或 Key 权限不允许此操作。\n404\nAPIErrorEnvelope\n资源不可用、不属于当前用户，或签名无效/过期。\n429\nAPIErrorEnvelope\n触发账户级速率或队列限制，遵循 Retry-After 等待。\n500\nAPIErrorEnvelope\n内部错误，保留任务 ID 和幂等键，仅标记可重试时重试。\n503\nAPIErrorEnvelope\n服务或供应商不可用，仅 error.retryable 为 true 时重试。\n响应头\nHTTP\n响应头\n类型\n含义\n429\nRetry-After\ninteger\n建议等待秒数，遵循服务值并设置总体截止时间。\n503\nRetry-After\ninteger\n建议等待秒数，遵循服务值并设置总体截止时间。\n响应示例\n相关教程\n轮询与下载 · 错误与安全重试"},{"id":"api-reference.get-credit-balance","locale":"zh","title":"查询积分余额","description":"从源码生成 GET /credits/balance 的鉴权、字段、响应、错误与安全调用参考。","section":"api-reference","path":"/docs/zh/api-reference/get-credit-balance","url":"https://animgen.com/docs/zh/api-reference/get-credit-balance","status":"beta","lastVerified":"2026-08-30","apiVersion":"1.3.0","audience":["api-developer","ai-agent"],"productAreas":["public-api"],"tags":["reference","API","get-credit-balance"],"translations":{"en":"https://animgen.com/docs/en/api-reference/get-credit-balance","zh":"https://animgen.com/docs/zh/api-reference/get-credit-balance"},"headings":[{"id":"操作","title":"操作","level":2},{"id":"鉴权与副作用","title":"鉴权与副作用","level":2},{"id":"参数","title":"参数","level":2},{"id":"响应","title":"响应","level":2},{"id":"响应头","title":"响应头","level":3},{"id":"响应示例","title":"响应示例","level":3},{"id":"相关教程","title":"相关教程","level":2}],"text":"本页由后端契约生成。字段、必填项、约束和默认值来自源码模型。下载机器可读来源。示例 ID 与数值均为占位说明，不代表实时价格、限额或模型可用性。\n操作\nGET /credits/balance\noperationId: credits_balance_v1_credits_balance_get\n读取 Web 与 API 共用的可用积分。已验证账户可使用 API，但产生费用的生成仍要求积分充足；消费前先为目标操作报价。\n鉴权与副作用\n使用可信环境中的 Bearer API Key。所需权限：animations:read\n此操作不启动付费生成，其他状态变化见上文说明。\n参数\n无路径、查询或操作专属请求头参数。\n响应\nHTTP\n正文\n含义\n200\nCreditsBalanceResponse\n成功的公开响应，示例数值仅用于说明。\n400\nAPIErrorEnvelope\n输入错误，修正请求后再尝试。\n401\nAPIErrorEnvelope\nAPI Key 缺失、到期或被撤销。\n403\nAPIErrorEnvelope\n账户资格、账户状态或 Key 权限不允许此操作。\n404\nAPIErrorEnvelope\n资源不可用、不属于当前用户，或签名无效/过期。\n429\nAPIErrorEnvelope\n触发账户级速率或队列限制，遵循 Retry-After 等待。\n500\nAPIErrorEnvelope\n内部错误，保留任务 ID 和幂等键，仅标记可重试时重试。\n503\nAPIErrorEnvelope\n服务或供应商不可用，仅 error.retryable 为 true 时重试。\n响应头\nHTTP\n响应头\n类型\n含义\n429\nRetry-After\ninteger\n建议等待秒数，遵循服务值并设置总体截止时间。\n503\nRetry-After\ninteger\n建议等待秒数，遵循服务值并设置总体截止时间。\n响应示例\n相关教程\n轮询与下载 · 错误与安全重试"},{"id":"api-reference.get-video-generations","locale":"zh","title":"查询视频生成","description":"从源码生成 GET /video-generations/{job_id} 的鉴权、字段、响应、错误与安全调用参考。","section":"api-reference","path":"/docs/zh/api-reference/get-video-generations","url":"https://animgen.com/docs/zh/api-reference/get-video-generations","status":"beta","lastVerified":"2026-08-30","apiVersion":"1.3.0","audience":["api-developer","ai-agent"],"productAreas":["public-api"],"tags":["reference","API","get-video-generations"],"translations":{"en":"https://animgen.com/docs/en/api-reference/get-video-generations","zh":"https://animgen.com/docs/zh/api-reference/get-video-generations"},"headings":[{"id":"操作","title":"操作","level":2},{"id":"鉴权与副作用","title":"鉴权与副作用","level":2},{"id":"参数","title":"参数","level":2},{"id":"响应","title":"响应","level":2},{"id":"响应头","title":"响应头","level":3},{"id":"响应示例","title":"响应示例","level":3},{"id":"相关教程","title":"相关教程","level":2}],"text":"本页由后端契约生成。字段、必填项、约束和默认值来自源码模型。下载机器可读来源。示例 ID 与数值均为占位说明，不代表实时价格、限额或模型可用性。\n操作\nGET /video-generations/{job_id}\noperationId: get_video_generation_v1_video_generations__job_id__get\n读取所属任务。遵循 Retry-After 并设置轮询截止时间。queued、running、cancelling 非终态；succeeded、failed、cancelled 为终态。后续阶段失败仍可能有可用产物，进度不代表精确时间。\n鉴权与副作用\n使用可信环境中的 Bearer API Key。所需权限：animations:read\n此操作不启动付费生成，其他状态变化见上文说明。\n参数\n参数\n位置\n类型\n必填\n约束 / 默认值\n含义\njob_id\npath\nstring\n是\nformat: uuid\n所属公共资源 UUID；任务、资产、文件 ID 不能互换。\n响应\nHTTP\n正文\n含义\n200\nTaskResponse\n成功的公开响应，示例数值仅用于说明。\n400\nAPIErrorEnvelope\n输入错误，修正请求后再尝试。\n401\nAPIErrorEnvelope\nAPI Key 缺失、到期或被撤销。\n403\nAPIErrorEnvelope\n账户资格、账户状态或 Key 权限不允许此操作。\n404\nAPIErrorEnvelope\n资源不可用、不属于当前用户，或签名无效/过期。\n429\nAPIErrorEnvelope\n触发账户级速率或队列限制，遵循 Retry-After 等待。\n500\nAPIErrorEnvelope\n内部错误，保留任务 ID 和幂等键，仅标记可重试时重试。\n503\nAPIErrorEnvelope\n服务或供应商不可用，仅 error.retryable 为 true 时重试。\n响应头\nHTTP\n响应头\n类型\n含义\n200\nRetry-After\ninteger\n建议等待秒数，遵循服务值并设置总体截止时间。\n429\nRetry-After\ninteger\n建议等待秒数，遵循服务值并设置总体截止时间。\n503\nRetry-After\ninteger\n建议等待秒数，遵循服务值并设置总体截止时间。\n响应示例\n相关教程\n轮询与下载 · 错误与安全重试"},{"id":"api-reference.list-animation-exports","locale":"zh","title":"列出动画导出任务","description":"从源码生成 GET /animation-exports 的鉴权、字段、响应、错误与安全调用参考。","section":"api-reference","path":"/docs/zh/api-reference/list-animation-exports","url":"https://animgen.com/docs/zh/api-reference/list-animation-exports","status":"beta","lastVerified":"2026-08-30","apiVersion":"1.3.0","audience":["api-developer","ai-agent"],"productAreas":["public-api"],"tags":["reference","API","list-animation-exports"],"translations":{"en":"https://animgen.com/docs/en/api-reference/list-animation-exports","zh":"https://animgen.com/docs/zh/api-reference/list-animation-exports"},"headings":[{"id":"操作","title":"操作","level":2},{"id":"鉴权与副作用","title":"鉴权与副作用","level":2},{"id":"参数","title":"参数","level":2},{"id":"响应","title":"响应","level":2},{"id":"响应头","title":"响应头","level":3},{"id":"响应示例","title":"响应示例","level":3},{"id":"相关教程","title":"相关教程","level":2}],"text":"本页由后端契约生成。字段、必填项、约束和默认值来自源码模型。下载机器可读来源。示例 ID 与数值均为占位说明，不代表实时价格、限额或模型可用性。\n操作\nGET /animation-exports\noperationId: list_animation_exports_v1_animation_exports_get\n列出当前账户所属任务。将 next_cursor 原样传回获取下一页，null 表示结束。并发及限流预算按账户共享，不按 Key 独立计算。\n鉴权与副作用\n使用可信环境中的 Bearer API Key。所需权限：animations:read\n此操作不启动付费生成，其他状态变化见上文说明。\n参数\n参数\n位置\n类型\n必填\n约束 / 默认值\n含义\nlimit\nquery\ninteger\n否\nminimum: 1; maximum: 100; default: 20\n本页最多记录数，不是账户并发上限。\ncursor\nquery\nstring / null\n否\n—\n上一页返回的不透明 next_cursor，原样传回。\n响应\nHTTP\n正文\n含义\n200\nTaskListResponse\n成功的公开响应，示例数值仅用于说明。\n400\nAPIErrorEnvelope\n输入错误，修正请求后再尝试。\n401\nAPIErrorEnvelope\nAPI Key 缺失、到期或被撤销。\n403\nAPIErrorEnvelope\n账户资格、账户状态或 Key 权限不允许此操作。\n404\nAPIErrorEnvelope\n资源不可用、不属于当前用户，或签名无效/过期。\n429\nAPIErrorEnvelope\n触发账户级速率或队列限制，遵循 Retry-After 等待。\n500\nAPIErrorEnvelope\n内部错误，保留任务 ID 和幂等键，仅标记可重试时重试。\n503\nAPIErrorEnvelope\n服务或供应商不可用，仅 error.retryable 为 true 时重试。\n响应头\nHTTP\n响应头\n类型\n含义\n429\nRetry-After\ninteger\n建议等待秒数，遵循服务值并设置总体截止时间。\n503\nRetry-After\ninteger\n建议等待秒数，遵循服务值并设置总体截止时间。\n响应示例\n相关教程\n轮询与下载 · 错误与安全重试"},{"id":"api-reference.list-animations","locale":"zh","title":"列出一键动画任务","description":"从源码生成 GET /animations 的鉴权、字段、响应、错误与安全调用参考。","section":"api-reference","path":"/docs/zh/api-reference/list-animations","url":"https://animgen.com/docs/zh/api-reference/list-animations","status":"beta","lastVerified":"2026-08-30","apiVersion":"1.3.0","audience":["api-developer","ai-agent"],"productAreas":["public-api"],"tags":["reference","API","list-animations"],"translations":{"en":"https://animgen.com/docs/en/api-reference/list-animations","zh":"https://animgen.com/docs/zh/api-reference/list-animations"},"headings":[{"id":"操作","title":"操作","level":2},{"id":"鉴权与副作用","title":"鉴权与副作用","level":2},{"id":"参数","title":"参数","level":2},{"id":"响应","title":"响应","level":2},{"id":"响应头","title":"响应头","level":3},{"id":"响应示例","title":"响应示例","level":3},{"id":"相关教程","title":"相关教程","level":2}],"text":"本页由后端契约生成。字段、必填项、约束和默认值来自源码模型。下载机器可读来源。示例 ID 与数值均为占位说明，不代表实时价格、限额或模型可用性。\n操作\nGET /animations\noperationId: list_one_click_animations_v1_animations_get\n列出当前账户所属任务。将 next_cursor 原样传回获取下一页，null 表示结束。并发及限流预算按账户共享，不按 Key 独立计算。\n鉴权与副作用\n使用可信环境中的 Bearer API Key。所需权限：animations:read\n此操作不启动付费生成，其他状态变化见上文说明。\n参数\n参数\n位置\n类型\n必填\n约束 / 默认值\n含义\nlimit\nquery\ninteger\n否\nminimum: 1; maximum: 100; default: 20\n本页最多记录数，不是账户并发上限。\ncursor\nquery\nstring / null\n否\n—\n上一页返回的不透明 next_cursor，原样传回。\n响应\nHTTP\n正文\n含义\n200\nTaskListResponse\n成功的公开响应，示例数值仅用于说明。\n400\nAPIErrorEnvelope\n输入错误，修正请求后再尝试。\n401\nAPIErrorEnvelope\nAPI Key 缺失、到期或被撤销。\n403\nAPIErrorEnvelope\n账户资格、账户状态或 Key 权限不允许此操作。\n404\nAPIErrorEnvelope\n资源不可用、不属于当前用户，或签名无效/过期。\n429\nAPIErrorEnvelope\n触发账户级速率或队列限制，遵循 Retry-After 等待。\n500\nAPIErrorEnvelope\n内部错误，保留任务 ID 和幂等键，仅标记可重试时重试。\n503\nAPIErrorEnvelope\n服务或供应商不可用，仅 error.retryable 为 true 时重试。\n响应头\nHTTP\n响应头\n类型\n含义\n429\nRetry-After\ninteger\n建议等待秒数，遵循服务值并设置总体截止时间。\n503\nRetry-After\ninteger\n建议等待秒数，遵循服务值并设置总体截止时间。\n响应示例\n相关教程\n轮询与下载 · 错误与安全重试"},{"id":"api-reference.list-models","locale":"zh","title":"查询模型能力","description":"从源码生成 GET /models 的鉴权、字段、响应、错误与安全调用参考。","section":"api-reference","path":"/docs/zh/api-reference/list-models","url":"https://animgen.com/docs/zh/api-reference/list-models","status":"beta","lastVerified":"2026-08-30","apiVersion":"1.3.0","audience":["api-developer","ai-agent"],"productAreas":["public-api"],"tags":["reference","API","list-models"],"translations":{"en":"https://animgen.com/docs/en/api-reference/list-models","zh":"https://animgen.com/docs/zh/api-reference/list-models"},"headings":[{"id":"操作","title":"操作","level":2},{"id":"鉴权与副作用","title":"鉴权与副作用","level":2},{"id":"参数","title":"参数","level":2},{"id":"响应","title":"响应","level":2},{"id":"响应头","title":"响应头","level":3},{"id":"响应示例","title":"响应示例","level":3},{"id":"相关教程","title":"相关教程","level":2}],"text":"本页由后端契约生成。字段、必填项、约束和默认值来自源码模型。下载机器可读来源。示例 ID 与数值均为占位说明，不代表实时价格、限额或模型可用性。\n操作\nGET /models\noperationId: list_models_v1_models_get\n发现当前启用的模型、默认值和输入能力。报价前检查模式、各模式比例、各分辨率时长和能力标志。不要根据文档示例写死模型 ID、参数组合或价格。\n鉴权与副作用\n使用可信环境中的 Bearer API Key。所需权限：animations:read\n此操作不启动付费生成，其他状态变化见上文说明。\n参数\n无路径、查询或操作专属请求头参数。\n响应\nHTTP\n正文\n含义\n200\nModelsResponse\n成功的公开响应，示例数值仅用于说明。\n400\nAPIErrorEnvelope\n输入错误，修正请求后再尝试。\n401\nAPIErrorEnvelope\nAPI Key 缺失、到期或被撤销。\n403\nAPIErrorEnvelope\n账户资格、账户状态或 Key 权限不允许此操作。\n404\nAPIErrorEnvelope\n资源不可用、不属于当前用户，或签名无效/过期。\n429\nAPIErrorEnvelope\n触发账户级速率或队列限制，遵循 Retry-After 等待。\n500\nAPIErrorEnvelope\n内部错误，保留任务 ID 和幂等键，仅标记可重试时重试。\n503\nAPIErrorEnvelope\n服务或供应商不可用，仅 error.retryable 为 true 时重试。\n响应头\nHTTP\n响应头\n类型\n含义\n429\nRetry-After\ninteger\n建议等待秒数，遵循服务值并设置总体截止时间。\n503\nRetry-After\ninteger\n建议等待秒数，遵循服务值并设置总体截止时间。\n响应示例\n相关教程\n轮询与下载 · 错误与安全重试"},{"id":"api-reference.list-video-generations","locale":"zh","title":"列出视频生成任务","description":"从源码生成 GET /video-generations 的鉴权、字段、响应、错误与安全调用参考。","section":"api-reference","path":"/docs/zh/api-reference/list-video-generations","url":"https://animgen.com/docs/zh/api-reference/list-video-generations","status":"beta","lastVerified":"2026-08-30","apiVersion":"1.3.0","audience":["api-developer","ai-agent"],"productAreas":["public-api"],"tags":["reference","API","list-video-generations"],"translations":{"en":"https://animgen.com/docs/en/api-reference/list-video-generations","zh":"https://animgen.com/docs/zh/api-reference/list-video-generations"},"headings":[{"id":"操作","title":"操作","level":2},{"id":"鉴权与副作用","title":"鉴权与副作用","level":2},{"id":"参数","title":"参数","level":2},{"id":"响应","title":"响应","level":2},{"id":"响应头","title":"响应头","level":3},{"id":"响应示例","title":"响应示例","level":3},{"id":"相关教程","title":"相关教程","level":2}],"text":"本页由后端契约生成。字段、必填项、约束和默认值来自源码模型。下载机器可读来源。示例 ID 与数值均为占位说明，不代表实时价格、限额或模型可用性。\n操作\nGET /video-generations\noperationId: list_video_generations_v1_video_generations_get\n列出当前账户所属任务。将 next_cursor 原样传回获取下一页，null 表示结束。并发及限流预算按账户共享，不按 Key 独立计算。\n鉴权与副作用\n使用可信环境中的 Bearer API Key。所需权限：animations:read\n此操作不启动付费生成，其他状态变化见上文说明。\n参数\n参数\n位置\n类型\n必填\n约束 / 默认值\n含义\nlimit\nquery\ninteger\n否\nminimum: 1; maximum: 100; default: 20\n本页最多记录数，不是账户并发上限。\ncursor\nquery\nstring / null\n否\n—\n上一页返回的不透明 next_cursor，原样传回。\n响应\nHTTP\n正文\n含义\n200\nTaskListResponse\n成功的公开响应，示例数值仅用于说明。\n400\nAPIErrorEnvelope\n输入错误，修正请求后再尝试。\n401\nAPIErrorEnvelope\nAPI Key 缺失、到期或被撤销。\n403\nAPIErrorEnvelope\n账户资格、账户状态或 Key 权限不允许此操作。\n404\nAPIErrorEnvelope\n资源不可用、不属于当前用户，或签名无效/过期。\n429\nAPIErrorEnvelope\n触发账户级速率或队列限制，遵循 Retry-After 等待。\n500\nAPIErrorEnvelope\n内部错误，保留任务 ID 和幂等键，仅标记可重试时重试。\n503\nAPIErrorEnvelope\n服务或供应商不可用，仅 error.retryable 为 true 时重试。\n响应头\nHTTP\n响应头\n类型\n含义\n429\nRetry-After\ninteger\n建议等待秒数，遵循服务值并设置总体截止时间。\n503\nRetry-After\ninteger\n建议等待秒数，遵循服务值并设置总体截止时间。\n响应示例\n相关教程\n轮询与下载 · 错误与安全重试"},{"id":"api-reference.quote-animation-exports","locale":"zh","title":"动画导出报价","description":"从源码生成 POST /animation-exports/quote 的鉴权、字段、响应、错误与安全调用参考。","section":"api-reference","path":"/docs/zh/api-reference/quote-animation-exports","url":"https://animgen.com/docs/zh/api-reference/quote-animation-exports","status":"beta","lastVerified":"2026-08-30","apiVersion":"1.3.0","audience":["api-developer","ai-agent"],"productAreas":["public-api"],"tags":["reference","API","quote-animation-exports"],"translations":{"en":"https://animgen.com/docs/en/api-reference/quote-animation-exports","zh":"https://animgen.com/docs/zh/api-reference/quote-animation-exports"},"headings":[{"id":"操作","title":"操作","level":2},{"id":"鉴权与副作用","title":"鉴权与副作用","level":2},{"id":"参数","title":"参数","level":2},{"id":"请求体-application-json","title":"请求体 (application/json)","level":2},{"id":"请求示例","title":"请求示例","level":3},{"id":"响应","title":"响应","level":2},{"id":"响应头","title":"响应头","level":3},{"id":"响应示例","title":"响应示例","level":3},{"id":"相关教程","title":"相关教程","level":2}],"text":"本页由后端契约生成。字段、必填项、约束和默认值来自源码模型。下载机器可读来源。示例 ID 与数值均为占位说明，不代表实时价格、限额或模型可用性。\n操作\nPOST /animation-exports/quote\noperationId: quote_animation_export_v1_animation_exports_quote_post\n为计划操作估算积分，不启动生产也不扣费。此报价不锁价、不构成支出批准；创建时重新计算，应先确认报价，并保持影响价格的选项与后续请求一致。\n鉴权与副作用\n使用可信环境中的 Bearer API Key。所需权限：animations:write\n此操作不启动付费生成，其他状态变化见上文说明。\n参数\n无路径、查询或操作专属请求头参数。\n请求体 (application/json)\n请求体必填：true\n字段\n类型\n必填\n默认值\n约束\n含义\nexport\nExportOptions\n否\n{\"frame_count\":24,\"output_formats\":[\"spritesheet\"],\"output_height\":512,\"output_width\":512,\"transparent\":{\"enabled\":false},\"unity\":{\"pivot\":\"bottom_center\",\"pixels_per_unit\":100}}\n—\n输出格式及处理设置。\nmetadata\nobject\n否\n{}\n—\n简单标量或 null 元数据，JSON 不超过 4 KiB，不包含凭据。\nselection\nSelection\n否\n{\"duration_seconds\":null,\"mode\":\"full\",\"start_seconds\":0}\n—\n需要导出的源视频区间。\nsource_video_asset_id\nstring\n是\n—\nformat: uuid\n所属源视频资产 ID，不是任务 ID；复用已有视频可避免重新生成动作。\n完整嵌套结构：AnimationExportCreateRequest\n请求示例\n响应\nHTTP\n正文\n含义\n200\nQuoteResponse\n成功的公开响应，示例数值仅用于说明。\n400\nAPIErrorEnvelope\n输入错误，修正请求后再尝试。\n401\nAPIErrorEnvelope\nAPI Key 缺失、到期或被撤销。\n402\nAPIErrorEnvelope\n积分不足，不自动购买。\n403\nAPIErrorEnvelope\n账户资格、账户状态或 Key 权限不允许此操作。\n404\nAPIErrorEnvelope\n资源不可用、不属于当前用户，或签名无效/过期。\n413\nAPIErrorEnvelope\n请求或解码后的图片超过配置限制。\n415\nAPIErrorEnvelope\n使用支持的图片媒体类型。\n422\nAPIErrorEnvelope\n图片解码后尺寸超过限制。\n429\nAPIErrorEnvelope\n触发账户级速率或队列限制，遵循 Retry-After 等待。\n500\nAPIErrorEnvelope\n内部错误，保留任务 ID 和幂等键，仅标记可重试时重试。\n503\nAPIErrorEnvelope\n服务或供应商不可用，仅 error.retryable 为 true 时重试。\n响应头\nHTTP\n响应头\n类型\n含义\n429\nRetry-After\ninteger\n建议等待秒数，遵循服务值并设置总体截止时间。\n503\nRetry-After\ninteger\n建议等待秒数，遵循服务值并设置总体截止时间。\n响应示例\n相关教程\n轮询与下载 · 错误与安全重试"},{"id":"api-reference.quote-animations","locale":"zh","title":"一键动画报价","description":"从源码生成 POST /animations/quote 的鉴权、字段、响应、错误与安全调用参考。","section":"api-reference","path":"/docs/zh/api-reference/quote-animations","url":"https://animgen.com/docs/zh/api-reference/quote-animations","status":"beta","lastVerified":"2026-08-30","apiVersion":"1.3.0","audience":["api-developer","ai-agent"],"productAreas":["public-api"],"tags":["reference","API","quote-animations"],"translations":{"en":"https://animgen.com/docs/en/api-reference/quote-animations","zh":"https://animgen.com/docs/zh/api-reference/quote-animations"},"headings":[{"id":"操作","title":"操作","level":2},{"id":"鉴权与副作用","title":"鉴权与副作用","level":2},{"id":"参数","title":"参数","level":2},{"id":"请求体-application-json","title":"请求体 (application/json)","level":2},{"id":"请求示例","title":"请求示例","level":3},{"id":"响应","title":"响应","level":2},{"id":"响应头","title":"响应头","level":3},{"id":"响应示例","title":"响应示例","level":3},{"id":"相关教程","title":"相关教程","level":2}],"text":"本页由后端契约生成。字段、必填项、约束和默认值来自源码模型。下载机器可读来源。示例 ID 与数值均为占位说明，不代表实时价格、限额或模型可用性。\n操作\nPOST /animations/quote\noperationId: quote_one_click_animation_v1_animations_quote_post\n为计划操作估算积分，不启动生产也不扣费。此报价不锁价、不构成支出批准；创建时重新计算，应先确认报价，并保持影响价格的选项与后续请求一致。\n鉴权与副作用\n使用可信环境中的 Bearer API Key。所需权限：animations:write\n此操作不启动付费生成，其他状态变化见上文说明。\n参数\n无路径、查询或操作专属请求头参数。\n请求体 (application/json)\n请求体必填：true\n字段\n类型\n必填\n默认值\n约束\n含义\nexport\nExportOptions\n否\n{\"frame_count\":24,\"output_formats\":[\"spritesheet\"],\"output_height\":512,\"output_width\":512,\"transparent\":{\"enabled\":false},\"unity\":{\"pivot\":\"bottom_center\",\"pixels_per_unit\":100}}\n—\n视频生成后执行导出；带 Alpha 的格式要求 alpha_key 来源，适配格式会自动启用其透明处理。\ninput\nGenerationInput\n是\n—\n—\n调用方所属或本次提供的生成图片。\nmetadata\nobject\n否\n{}\n—\n调用方元数据，仅字符串、数字、布尔或 null；JSON 不超过 4 KiB，不存凭据。\nnegative_prompt\nstring\n否\n\"\"\nmaxLength: 4000\n可选负向提示词，仅适用于支持的模型。\nprompt\nstring\n否\n\"\"\nmaxLength: 8000\n动作提示词；模型要求时不能为空，私有提示词不得写入日志。\nselection\nSelection\n否\n{\"duration_seconds\":null,\"mode\":\"full\",\"start_seconds\":0}\n—\n生成后选取的区间，默认完整视频。\nvideo\nVideoOptions\n否\n{\"duration_seconds\":null,\"input_canvas\":null,\"model\":null,\"ratio\":null,\"resolution\":null,\"seed\":null,\"style_preset\":null,\"transparency\":{\"key_color\":null,\"key_selection\":\"auto\",\"mode\":\"standard\"},\"watermark\":null}\n—\n符合模型能力的生成设置。\n完整嵌套结构：AnimationCreateRequest\n请求示例\n响应\nHTTP\n正文\n含义\n200\nQuoteResponse\n成功的公开响应，示例数值仅用于说明。\n400\nAPIErrorEnvelope\n输入错误，修正请求后再尝试。\n401\nAPIErrorEnvelope\nAPI Key 缺失、到期或被撤销。\n402\nAPIErrorEnvelope\n积分不足，不自动购买。\n403\nAPIErrorEnvelope\n账户资格、账户状态或 Key 权限不允许此操作。\n404\nAPIErrorEnvelope\n资源不可用、不属于当前用户，或签名无效/过期。\n413\nAPIErrorEnvelope\n请求或解码后的图片超过配置限制。\n415\nAPIErrorEnvelope\n使用支持的图片媒体类型。\n422\nAPIErrorEnvelope\n图片解码后尺寸超过限制。\n429\nAPIErrorEnvelope\n触发账户级速率或队列限制，遵循 Retry-After 等待。\n500\nAPIErrorEnvelope\n内部错误，保留任务 ID 和幂等键，仅标记可重试时重试。\n503\nAPIErrorEnvelope\n服务或供应商不可用，仅 error.retryable 为 true 时重试。\n响应头\nHTTP\n响应头\n类型\n含义\n429\nRetry-After\ninteger\n建议等待秒数，遵循服务值并设置总体截止时间。\n503\nRetry-After\ninteger\n建议等待秒数，遵循服务值并设置总体截止时间。\n响应示例\n相关教程\n轮询与下载 · 错误与安全重试"},{"id":"api-reference.quote-video-generations","locale":"zh","title":"视频生成报价","description":"从源码生成 POST /video-generations/quote 的鉴权、字段、响应、错误与安全调用参考。","section":"api-reference","path":"/docs/zh/api-reference/quote-video-generations","url":"https://animgen.com/docs/zh/api-reference/quote-video-generations","status":"beta","lastVerified":"2026-08-30","apiVersion":"1.3.0","audience":["api-developer","ai-agent"],"productAreas":["public-api"],"tags":["reference","API","quote-video-generations"],"translations":{"en":"https://animgen.com/docs/en/api-reference/quote-video-generations","zh":"https://animgen.com/docs/zh/api-reference/quote-video-generations"},"headings":[{"id":"操作","title":"操作","level":2},{"id":"鉴权与副作用","title":"鉴权与副作用","level":2},{"id":"参数","title":"参数","level":2},{"id":"请求体-application-json","title":"请求体 (application/json)","level":2},{"id":"请求示例","title":"请求示例","level":3},{"id":"响应","title":"响应","level":2},{"id":"响应头","title":"响应头","level":3},{"id":"响应示例","title":"响应示例","level":3},{"id":"相关教程","title":"相关教程","level":2}],"text":"本页由后端契约生成。字段、必填项、约束和默认值来自源码模型。下载机器可读来源。示例 ID 与数值均为占位说明，不代表实时价格、限额或模型可用性。\n操作\nPOST /video-generations/quote\noperationId: quote_video_generation_v1_video_generations_quote_post\n为计划操作估算积分，不启动生产也不扣费。此报价不锁价、不构成支出批准；创建时重新计算，应先确认报价，并保持影响价格的选项与后续请求一致。\n鉴权与副作用\n使用可信环境中的 Bearer API Key。所需权限：animations:write\n此操作不启动付费生成，其他状态变化见上文说明。\n参数\n无路径、查询或操作专属请求头参数。\n请求体 (application/json)\n请求体必填：true\n字段\n类型\n必填\n默认值\n约束\n含义\nhas_last_frame\nboolean\n否\nfalse\n—\n计划请求是否包含尾帧。\nreference_image_count\ninteger\n否\n0\nminimum: 0; maximum: 8\n额外参考图数量，不含首帧。\nvideo\nVideoOptions\n否\n{\"duration_seconds\":null,\"input_canvas\":null,\"model\":null,\"ratio\":null,\"resolution\":null,\"seed\":null,\"style_preset\":null,\"transparency\":{\"key_color\":null,\"key_selection\":\"auto\",\"mode\":\"standard\"},\"watermark\":null}\n—\n拟报价的生成选项，应与后续创建一致。\n完整嵌套结构：VideoGenerationQuoteRequest\n请求示例\n响应\nHTTP\n正文\n含义\n200\nQuoteResponse\n成功的公开响应，示例数值仅用于说明。\n400\nAPIErrorEnvelope\n输入错误，修正请求后再尝试。\n401\nAPIErrorEnvelope\nAPI Key 缺失、到期或被撤销。\n402\nAPIErrorEnvelope\n积分不足，不自动购买。\n403\nAPIErrorEnvelope\n账户资格、账户状态或 Key 权限不允许此操作。\n404\nAPIErrorEnvelope\n资源不可用、不属于当前用户，或签名无效/过期。\n413\nAPIErrorEnvelope\n请求或解码后的图片超过配置限制。\n415\nAPIErrorEnvelope\n使用支持的图片媒体类型。\n422\nAPIErrorEnvelope\n图片解码后尺寸超过限制。\n429\nAPIErrorEnvelope\n触发账户级速率或队列限制，遵循 Retry-After 等待。\n500\nAPIErrorEnvelope\n内部错误，保留任务 ID 和幂等键，仅标记可重试时重试。\n503\nAPIErrorEnvelope\n服务或供应商不可用，仅 error.retryable 为 true 时重试。\n响应头\nHTTP\n响应头\n类型\n含义\n429\nRetry-After\ninteger\n建议等待秒数，遵循服务值并设置总体截止时间。\n503\nRetry-After\ninteger\n建议等待秒数，遵循服务值并设置总体截止时间。\n响应示例\n相关教程\n轮询与下载 · 错误与安全重试"},{"id":"api-reference.schemas","locale":"zh","title":"共享字段与数据结构","description":"从后端源码生成共享字段、嵌套类型、默认值、必填项与约束，避免在文档中维护第二份参数定义。","section":"api-reference","path":"/docs/zh/api-reference/schemas","url":"https://animgen.com/docs/zh/api-reference/schemas","status":"beta","lastVerified":"2026-08-30","apiVersion":"1.3.0","audience":["api-developer","ai-agent"],"productAreas":["public-api"],"tags":["reference","API","schemas"],"translations":{"en":"https://animgen.com/docs/en/api-reference/schemas","zh":"https://animgen.com/docs/zh/api-reference/schemas"},"headings":[{"id":"accountapikey","title":"AccountAPIKey","level":2},{"id":"accountlimits","title":"AccountLimits","level":2},{"id":"accountplan","title":"AccountPlan","level":2},{"id":"accountresponse","title":"AccountResponse","level":2},{"id":"animationcreaterequest","title":"AnimationCreateRequest","level":2},{"id":"animationexportcreaterequest","title":"AnimationExportCreateRequest","level":2},{"id":"apierror","title":"APIError","level":2},{"id":"apierrorenvelope","title":"APIErrorEnvelope","level":2},{"id":"assetresponse","title":"AssetResponse","level":2},{"id":"base64imageinput","title":"Base64ImageInput","level":2},{"id":"body-create-file-v1-files-post","title":"Body_create_file_v1_files_post","level":2},{"id":"creditsbalanceresponse","title":"CreditsBalanceResponse","level":2},{"id":"creditusage","title":"CreditUsage","level":2},{"id":"exportoptions","title":"ExportOptions","level":2},{"id":"exporttransparency","title":"ExportTransparency","level":2},{"id":"fileimageinput","title":"FileImageInput","level":2},{"id":"fileresponse","title":"FileResponse","level":2},{"id":"generationinput","title":"GenerationInput","level":2},{"id":"generationtransparency","title":"GenerationTransparency","level":2},{"id":"inputcanvasoptions","title":"InputCanvasOptions","level":2},{"id":"modelcapabilities","title":"ModelCapabilities","level":2},{"id":"modelsresponse","title":"ModelsResponse","level":2},{"id":"quoteresponse","title":"QuoteResponse","level":2},{"id":"selection","title":"Selection","level":2},{"id":"taskerror","title":"TaskError","level":2},{"id":"tasklistresponse","title":"TaskListResponse","level":2},{"id":"taskresponse","title":"TaskResponse","level":2},{"id":"unityoptions","title":"UnityOptions","level":2},{"id":"urlimageinput","title":"UrlImageInput","level":2},{"id":"videogenerationcreaterequest","title":"VideoGenerationCreateRequest","level":2},{"id":"videogenerationquoterequest","title":"VideoGenerationQuoteRequest","level":2},{"id":"videooptions","title":"VideoOptions","level":2}],"text":"本页由后端契约生成。字段、必填项、约束和默认值来自源码模型。下载机器可读来源。示例 ID 与数值均为占位说明，不代表实时价格、限额或模型可用性。\n“—”表示没有声明默认值，不等于 null。字段在 JSON Schema 中可选，仍可能受工作流的条件必填限制。模型专属选项仍需查询实时能力。\nAccountAPIKey\n禁止未声明的字段。\n字段\n类型\n必填\n默认值\n约束\n含义\nid\nstring\n是\n—\nformat: uuid\n当前 Key 的标识，不是密钥明文；幂等去重受此身份约束。\nscopes\narray<string>\n是\n—\n—\n当前 Key 获得的权限。\nAccountLimits\n禁止未声明的字段。\n字段\n类型\n必填\n默认值\n约束\n含义\nconcurrency\ninteger\n是\n—\n—\n整个账户的最大并发任务数。\ncreate_per_minute\ninteger\n是\n—\n—\n账户每分钟创建请求限额。\nother_per_minute\ninteger\n是\n—\n—\n账户每分钟其他请求限额。\nqueue\ninteger\n是\n—\n—\n整个账户的最大排队任务数。\nAccountPlan\n禁止未声明的字段。\n字段\n类型\n必填\n默认值\n约束\n含义\ncancel_at_period_end\nboolean\n是\n—\n—\n当前付费订阅是否停止续订；注册基础档为 false。\ncode\nstring\n是\n—\n—\n当前开发者访问档位：registered、basic、expert 或 ultra。\ncurrent_period_end\nstring / null\n是\n—\nformat: date-time\n付费订阅周期的 UTC 结束时间；注册基础档为 null。\nAccountResponse\n禁止未声明的字段。\n字段\n类型\n必填\n默认值\n约束\n含义\napi_key\nAccountAPIKey\n是\n—\n—\n当前 Key 标识及权限，不返回密钥明文。\nid\nstring\n是\n—\nformat: uuid\n当前鉴权账户 ID。\nlimits\nAccountLimits\n是\n—\n—\n所有 Key 共用的账户级限额。\nobject\nstring\n否\n\"account\"\nconst: \"account\"\n—\nplan\nAccountPlan\n是\n—\n—\n当前开发者访问档位及可选订阅周期。\nAnimationCreateRequest\n禁止未声明的字段。\n字段\n类型\n必填\n默认值\n约束\n含义\nexport\nExportOptions\n否\n{\"frame_count\":24,\"output_formats\":[\"spritesheet\"],\"output_height\":512,\"output_width\":512,\"transparent\":{\"enabled\":false},\"unity\":{\"pivot\":\"bottom_center\",\"pixels_per_unit\":100}}\n—\n视频生成后执行导出；带 Alpha 的格式要求 alpha_key 来源，适配格式会自动启用其透明处理。\ninput\nGenerationInput\n是\n—\n—\n调用方所属或本次提供的生成图片。\nmetadata\nobject\n否\n{}\n—\n调用方元数据，仅字符串、数字、布尔或 null；JSON 不超过 4 KiB，不存凭据。\nnegative_prompt\nstring\n否\n\"\"\nmaxLength: 4000\n可选负向提示词，仅适用于支持的模型。\nprompt\nstring\n否\n\"\"\nmaxLength: 8000\n动作提示词；模型要求时不能为空，私有提示词不得写入日志。\nselection\nSelection\n否\n{\"duration_seconds\":null,\"mode\":\"full\",\"start_seconds\":0}\n—\n生成后选取的区间，默认完整视频。\nvideo\nVideoOptions\n否\n{\"duration_seconds\":null,\"input_canvas\":null,\"model\":null,\"ratio\":null,\"resolution\":null,\"seed\":null,\"style_preset\":null,\"transparency\":{\"key_color\":null,\"key_selection\":\"auto\",\"mode\":\"standard\"},\"watermark\":null}\n—\n符合模型能力的生成设置。\nAnimationExportCreateRequest\n禁止未声明的字段。\n字段\n类型\n必填\n默认值\n约束\n含义\nexport\nExportOptions\n否\n{\"frame_count\":24,\"output_formats\":[\"spritesheet\"],\"output_height\":512,\"output_width\":512,\"transparent\":{\"enabled\":false},\"unity\":{\"pivot\":\"bottom_center\",\"pixels_per_unit\":100}}\n—\n输出格式及处理设置。\nmetadata\nobject\n否\n{}\n—\n简单标量或 null 元数据，JSON 不超过 4 KiB，不包含凭据。\nselection\nSelection\n否\n{\"duration_seconds\":null,\"mode\":\"full\",\"start_seconds\":0}\n—\n需要导出的源视频区间。\nsource_video_asset_id\nstring\n是\n—\nformat: uuid\n所属源视频资产 ID，不是任务 ID；复用已有视频可避免重新生成动作。\nAPIError\n字段\n类型\n必填\n默认值\n约束\n含义\ncode\nstring\n是\n—\n—\n稳定的程序错误码。\ndetails\nobject\n是\n—\n—\n特定错误的公开详情，检查时不记录私有输入。\nmessage\nstring\n是\n—\n—\n人类可读说明，不依赖精确文本分支。\nparam\nstring / null\n否\n—\n—\n已知时指向相关公开参数。\nrequest_id\nstring / null\n是\n—\n—\n供支持关联排查的公共请求 ID，不是凭据。\nretryable\nboolean\n是\n—\n—\n重试可能有帮助，但仍需保持幂等并遵循 Retry-After。\nAPIErrorEnvelope\n字段\n类型\n必填\n默认值\n约束\n含义\nerror\nAPIError\n是\n—\n—\n—\nAssetResponse\n禁止未声明的字段。\n字段\n类型\n必填\n默认值\n约束\n含义\nbyte_size\ninteger\n是\n—\n—\n文件预期字节数。\ncreated_at\nstring\n是\n—\nformat: date-time\nUTC 创建时间。\ndownload_expires_at\nstring\n是\n—\nformat: date-time\n签名 URL 的 UTC 过期时间；过期后重新查询资产。\ndownload_url\nstring\n是\n—\n—\n敏感短期签名 URL；下载及跳转时均不携带 Bearer 头，不记录此 URL。\nformat\nstring\n是\n—\n—\n实际资产格式，不要依赖 outputs 固定顺序。\nid\nstring\n是\n—\nformat: uuid\n稳定公共资产 ID，用于刷新下载信息。\nmime_type\nstring\n是\n—\n—\n资产媒体类型。\nobject\nstring\n否\n\"asset\"\nconst: \"asset\"\n—\nBase64ImageInput\n禁止未声明的字段。\n字段\n类型\n必填\n默认值\n约束\n含义\ndata\nstring\n是\n—\nminLength: 4\n纯 Base64，不含 data URL 前缀；解码后单张 10 MiB、合计 20 MiB。\nmedia_type\nstring\n是\n—\nenum: \"image/png\", \"image/jpeg\", \"image/webp\"\n图片实际 MIME 类型。\ntype\nstring\n是\n—\nconst: \"base64\"\n—\nBody_create_file_v1_files_post\n字段\n类型\n必填\n默认值\n约束\n含义\nfile\nstring\n是\n—\nformat: binary\nPNG、JPEG 或 WebP 图片字节，校验后返回公共文件 ID。\nCreditsBalanceResponse\n禁止未声明的字段。\n字段\n类型\n必填\n默认值\n约束\n含义\navailable\ninteger\n是\n—\n—\n当前账户可用积分，不代表功能权益已解锁。\nobject\nstring\n否\n\"credit_balance\"\nconst: \"credit_balance\"\n—\nCreditUsage\n禁止未声明的字段。\n字段\n类型\n必填\n默认值\n约束\n含义\ncharged\ninteger\n是\n—\n—\n最终净扣费积分。供应商明确审核拒绝会退分，取消本身不代表退款。\nheld\ninteger\n是\n—\n—\n当前预占积分，不应与 charged 相加当作扣费。\nquoted\ninteger\n是\n—\n—\n报价总额，不一定等于最终扣费。\nrefunded\ninteger\n否\n0\n—\n扣费后退回的积分，已从 charged 中扣除，不是现金退款。\nreleased\ninteger\n否\n0\n—\n尚未确认扣费即释放的积分。\nstatus\nstring / null\n否\nnull\n—\n积分状态：held、charged、released、refunded，内部子任务可为 managed。\nExportOptions\n禁止未声明的字段。\n字段\n类型\n必填\n默认值\n约束\n含义\nframe_count\ninteger\n否\n24\nminimum: 1; maximum: 240\n在选段内采样的帧数，不是 FPS 参数。\noutput_formats\narray<string>\n否\n[\"spritesheet\"]\nminItems: 1; 元素：enum: \"clip_video\", \"webm_alpha\", \"prores_4444\", \"frames_zip\", \"spritesheet\", \"spritesheet_json\", \"unity_meta\", \"unity_pack\", \"godot_pack\", \"unreal_paper2d_pack\", \"cocos_creator_pack\"\n请求的资产格式；默认 spritesheet，重复项会去重，元数据需配套纹理。\noutput_height\ninteger\n否\n512\nminimum: 64; maximum: 1024\n输出帧高度，单位像素。\noutput_width\ninteger\n否\n512\nminimum: 64; maximum: 1024\n输出帧宽度，单位像素。\ntransparent\nExportTransparency\n否\n{\"enabled\":false}\n—\n使用 enabled 对象形式；兼容布尔值输入并规范化为此对象。\nunity\nUnityOptions\n否\n{\"pivot\":\"bottom_center\",\"pixels_per_unit\":100}\n—\nUnity 专用元数据和资源包设置。\nExportTransparency\n禁止未声明的字段。\n字段\n类型\n必填\n默认值\n约束\n含义\nenabled\nboolean\n否\nfalse\n—\n为兼容输出启用透明处理；要求 alpha_key 来源，不会让 MP4 透明。\nFileImageInput\n禁止未声明的字段。\n字段\n类型\n必填\n默认值\n约束\n含义\nfile_id\nstring\n是\n—\nformat: uuid\nPOST /files 或 complete_image_upload 返回的所属公共文件 ID，不是 Studio uploadId。\ntype\nstring\n是\n—\nconst: \"file\"\n—\nFileResponse\n禁止未声明的字段。\n字段\n类型\n必填\n默认值\n约束\n含义\nbyte_size\ninteger\n是\n—\n—\n存储图片字节数。\ncreated_at\nstring\n是\n—\nformat: date-time\n上传创建的 UTC 时间。\nheight\ninteger\n是\n—\n—\n解码后图片高度，像素。\nid\nstring\n是\n—\nformat: uuid\ntype=file 输入使用的可复用公共文件 ID。\nmime_type\nstring\n是\n—\n—\n校验后的图片媒体类型。\nobject\nstring\n否\n\"file\"\nconst: \"file\"\n—\nsha256\nstring\n是\n—\n—\n图片字节的 SHA-256。\nwidth\ninteger\n是\n—\n—\n解码后图片宽度，像素。\nGenerationInput\n禁止未声明的字段。\n字段\n类型\n必填\n默认值\n约束\n含义\nfirst_frame\nFileImageInput / Base64ImageInput / UrlImageInput\n是\n—\ndiscriminator: type\n必需首帧，用 type 选择图片传入方式。\nlast_frame\nFileImageInput / Base64ImageInput / UrlImageInput / null\n否\nnull\ndiscriminator: type\n可选尾帧，所选模型必须支持首尾帧模式。\nreference_images\narray<FileImageInput / Base64ImageInput / UrlImageInput>\n否\n[]\nmaxItems: 8; 元素：discriminator: type\n额外参考图，不含首帧；实时模型可能有更低上限。\nGenerationTransparency\n禁止未声明的字段。\n字段\n类型\n必填\n默认值\n约束\n含义\nkey_color\nstring / null\n否\nnull\n—\n手动选择时使用的临时键色；通常保留自动选择。\nkey_selection\nstring\n否\n\"auto\"\nenum: \"auto\", \"manual\"\n临时键色的选择方式。\nmode\nstring\n否\n\"standard\"\nenum: \"standard\", \"alpha_key\"\nstandard 保留场景；alpha_key 要求所有参与图片有有效 Alpha，原始视频仍不透明。\nInputCanvasOptions\n禁止未声明的字段。\n字段\n类型\n必填\n默认值\n约束\n含义\naspect_ratio\nstring\n否\n\"follow_output\"\nenum: \"follow_output\", \"source\"\n跟随输出比例或保持原图比例。\nbackground\nstring\n否\n\"auto\"\nenum: \"auto\", \"transparent\", \"solid\"\n画布扩展区域的背景策略。\nbackground_color\nstring / null\n否\nnull\npattern: ^#[0-9A-Fa-f]{6}$\n纯色扩展区域的六位 RGB 颜色。\nenabled\nboolean\n否\ntrue\n—\n是否准备扩展输入画布。\nposition_x\nnumber\n否\n0.5\nminimum: 0; maximum: 1\n归一化水平位置。\nposition_y\nnumber\n否\n0.5\nminimum: 0; maximum: 1\n归一化垂直位置。\nsource_scale\nnumber\n否\n0.8\nminimum: 0.5; maximum: 1\n原图主体在画布中的缩放比例。\nModelCapabilities\n禁止未声明的字段。\n字段\n类型\n必填\n默认值\n约束\n含义\naspect_ratio_mode\nstring\n是\n—\n—\n供应商对画幅比例的处理模式。\ndefault_duration_seconds\ninteger\n是\n—\n—\n默认生成时长，秒。\ndefault_ratio\nstring / null\n是\n—\n—\n默认比例，不适用时为 null。\ndefault_resolution\nstring / null\n是\n—\n—\n默认分辨率，不适用时为 null。\ndurations\narray<integer>\n是\n—\n—\n支持的生成秒数，同时检查分辨率专属限制。\ndurations_by_resolution\nobject\n否\n{}\n—\n各分辨率支持的时长秒数。\nid\nstring\n是\n—\n—\n请求使用的 provider:model 标识，以实时目录为准。\nlabel\nstring\n是\n—\n—\n人类可读模型名称。\nmax_reference_images\ninteger\n是\n—\n—\n模型参考图容量；参考图模式中首帧占第一个参考图槽位。\nmodel\nstring\n是\n—\n—\n供应商内的模型标识。\nmodes\narray<string>\n是\n—\n—\n支持的输入模式，如 first_frame、first_last_frame、reference_images。\nprovider\nstring\n是\n—\n—\n公开供应商标识。\nratios\narray<string>\n是\n—\n—\n支持的比例；存在 ratios_by_mode 时同时检查。\nratios_by_mode\nobject\n否\n{}\n—\n各输入模式支持的比例。\nreference_image_duration_seconds\ninteger / null\n是\n—\n—\n参考图模式有固定限制时要求的秒数。\nrequires_prompt\nboolean\n是\n—\n—\n是否要求提示词非空。\nresolutions\narray<string>\n是\n—\n—\n支持的分辨率选项。\nreturns_last_frame\nboolean\n是\n—\n—\n模型是否可返回末帧资产。\nsupports_first_frame\nboolean\n是\n—\n—\n是否支持首帧输入。\nsupports_last_frame\nboolean\n是\n—\n—\n是否支持尾帧输入。\nsupports_negative_prompt\nboolean\n是\n—\n—\n是否支持负向提示词。\nsupports_reference_images\nboolean\n是\n—\n—\n是否支持参考图模式。\nsupports_seed\nboolean\n是\n—\n—\n是否支持 seed。\nsupports_watermark\nboolean\n是\n—\n—\n是否支持水印设置。\nModelsResponse\n禁止未声明的字段。\n字段\n类型\n必填\n默认值\n约束\n含义\ndata\narray<ModelCapabilities>\n是\n—\n—\n当前启用的模型，客户端不要写死此清单。\nobject\nstring\n否\n\"list\"\nconst: \"list\"\n—\nQuoteResponse\n禁止未声明的字段。\n字段\n类型\n必填\n默认值\n约束\n含义\nbreakdown\nobject\n否\n{}\n—\n公开费用组成，以 credits 为报价总额。\ncredits\ninteger\n是\n—\n—\n当前预计积分，不锁价也不构成支出授权；创建时会重新报价。\nobject\nstring\n否\n\"quote\"\nconst: \"quote\"\n—\nSelection\n禁止未声明的字段。\n字段\n类型\n必填\n默认值\n约束\n含义\nduration_seconds\nnumber / null\n否\nnull\nexclusiveMinimum: 0\nmode=range 时必填，选段时长秒数必须为正。\nmode\nstring\n否\n\"full\"\nenum: \"full\", \"range\"\nfull 使用完整来源；range 必须提供 duration_seconds。\nstart_seconds\nnumber\n否\n0\nminimum: 0\n相对源视频起点的选段开始秒数。\nTaskError\n禁止未声明的字段。\n字段\n类型\n必填\n默认值\n约束\n含义\ncode\nstring\n是\n—\n—\n供程序识别的任务错误码。\nmessage\nstring\n是\n—\n—\n人类可读说明，不应作为稳定分支条件。\nretryable\nboolean\n否\nfalse\n—\n重试是否可能有帮助；新建付费任务前先检查部分产物。\nTaskListResponse\n禁止未声明的字段。\n字段\n类型\n必填\n默认值\n约束\n含义\ndata\narray<TaskResponse>\n是\n—\n—\n当前页中归属自己的任务。\nnext_cursor\nstring / null\n否\nnull\n—\n不透明的下一页游标，null 表示无下一页，使用时原样传回。\nobject\nstring\n否\n\"list\"\nconst: \"list\"\n—\nTaskResponse\n禁止未声明的字段。\n字段\n类型\n必填\n默认值\n约束\n含义\ncreated_at\nstring\n是\n—\nformat: date-time\n任务被接受的 UTC 时间。\ncredits\nCreditUsage\n是\n—\n—\n报价、预占及已扣积分状态。\nerror\nTaskError / null\n否\nnull\n—\n任务失败信息，与是否存在可用产物分别判断。\nfinished_at\nstring / null\n否\nnull\nformat: date-time\n已知时返回 UTC 终态时间。\nid\nstring\n是\n—\nformat: uuid\n创建后立即保存任务 ID，通过它轮询，不要再次创建。\nmetadata\nobject\n否\n{}\n—\n调用方提供的元数据。\nnormalized_input\nobject\n否\n{}\n—\n规范化公共输入，可能含私有提示词或图片引用，不要整体写入日志。\nobject\nstring\n是\n—\nenum: \"video_generation\", \"animation_export\", \"animation\"\n公共任务资源类型。\noutputs\narray<AssetResponse>\n否\n[]\n—\n可用资产，失败或取消也可能有部分产物；所有终态都应检查。\nprogress\nnumber\n是\n—\nminimum: 0; maximum: 1\n0 至 1 的进度值，不代表精确完成时间。\nstage\nstring / null\n否\nnull\nenum: \"queued\", \"video_generation\", \"animation_export\", \"completed\"\n可用时显示当前流水线阶段。\nstarted_at\nstring / null\n否\nnull\nformat: date-time\n已知时返回 UTC 生产开始时间。\nstatus\nstring\n是\n—\nenum: \"queued\", \"running\", \"cancelling\", \"succeeded\", \"failed\", \"cancelled\"\nsucceeded、failed、cancelled 为终态；cancelling 不是终态。\nUnityOptions\n禁止未声明的字段。\n字段\n类型\n必填\n默认值\n约束\n含义\npivot\nstring\n否\n\"bottom_center\"\nconst: \"bottom_center\"\n支持的 Unity 精灵锚点。\npixels_per_unit\ninteger\n否\n100\nminimum: 1; maximum: 1000\nUnity 每世界单位对应的纹理像素数。\nUrlImageInput\n禁止未声明的字段。\n字段\n类型\n必填\n默认值\n约束\n含义\ntype\nstring\n是\n—\nconst: \"url\"\n—\nurl\nstring\n是\n—\nminLength: 9; maxLength: 2048\n公开 HTTPS 图片，443 端口，不带凭据或 fragment；禁止私网和不安全跳转，重试期间保持图片字节稳定。\nVideoGenerationCreateRequest\n禁止未声明的字段。\n字段\n类型\n必填\n默认值\n约束\n含义\ninput\nGenerationInput\n是\n—\n—\n调用方所属或本次提供的生成图片。\nmetadata\nobject\n否\n{}\n—\n调用方元数据，仅字符串、数字、布尔或 null；JSON 不超过 4 KiB，不存凭据。\nnegative_prompt\nstring\n否\n\"\"\nmaxLength: 4000\n可选负向提示词，仅适用于支持的模型。\nprompt\nstring\n否\n\"\"\nmaxLength: 8000\n动作提示词；模型要求时不能为空，私有提示词不得写入日志。\nvideo\nVideoOptions\n否\n{\"duration_seconds\":null,\"input_canvas\":null,\"model\":null,\"ratio\":null,\"resolution\":null,\"seed\":null,\"style_preset\":null,\"transparency\":{\"key_color\":null,\"key_selection\":\"auto\",\"mode\":\"standard\"},\"watermark\":null}\n—\n符合模型能力的生成设置。\nVideoGenerationQuoteRequest\n禁止未声明的字段。\n字段\n类型\n必填\n默认值\n约束\n含义\nhas_last_frame\nboolean\n否\nfalse\n—\n计划请求是否包含尾帧。\nreference_image_count\ninteger\n否\n0\nminimum: 0; maximum: 8\n额外参考图数量，不含首帧。\nvideo\nVideoOptions\n否\n{\"duration_seconds\":null,\"input_canvas\":null,\"model\":null,\"ratio\":null,\"resolution\":null,\"seed\":null,\"style_preset\":null,\"transparency\":{\"key_color\":null,\"key_selection\":\"auto\",\"mode\":\"standard\"},\"watermark\":null}\n—\n拟报价的生成选项，应与后续创建一致。\nVideoOptions\n禁止未声明的字段。\n字段\n类型\n必填\n默认值\n约束\n含义\nduration_seconds\nnumber / null\n否\nnull\nexclusiveMinimum: 0\n秒数，需符合模型与分辨率支持范围；省略时使用模型默认值。\ninput_canvas\nInputCanvasOptions / null\n否\nnull\n—\n可选输入画布设置；省略时保持来源构图。\nmodel\nstring / null\n否\nnull\n—\nGET /models 返回的 provider:model ID；省略时使用配置的默认模型。\nratio\nstring / null\n否\nnull\n—\n当前模型与输入模式支持的画幅比例。\nresolution\nstring / null\n否\nnull\n—\n实时模型目录中的分辨率值。\nseed\ninteger / null\n否\nnull\nminimum: 0; maximum: 2147483647\n仅适用于声明支持 seed 的模型，不保证所有输出确定性。\nstyle_preset\nstring / null\n否\nnull\n—\n所选供应商或模型支持的可选风格预设。\ntransparency\nGenerationTransparency\n否\n{\"key_color\":null,\"key_selection\":\"auto\",\"mode\":\"standard\"}\n—\n来源透明流程；透明导出要求 alpha_key。\nwatermark\nboolean / null\n否\nnull\n—\n可选水印设置，需检查模型能力。"},{"id":"api-reference.upload-file","locale":"zh","title":"上传图片","description":"从源码生成 POST /files 的鉴权、字段、响应、错误与安全调用参考。","section":"api-reference","path":"/docs/zh/api-reference/upload-file","url":"https://animgen.com/docs/zh/api-reference/upload-file","status":"beta","lastVerified":"2026-08-30","apiVersion":"1.3.0","audience":["api-developer","ai-agent"],"productAreas":["public-api"],"tags":["reference","API","upload-file"],"translations":{"en":"https://animgen.com/docs/en/api-reference/upload-file","zh":"https://animgen.com/docs/zh/api-reference/upload-file"},"headings":[{"id":"操作","title":"操作","level":2},{"id":"鉴权与副作用","title":"鉴权与副作用","level":2},{"id":"参数","title":"参数","level":2},{"id":"请求体-multipart-form-data","title":"请求体 (multipart/form-data)","level":2},{"id":"响应","title":"响应","level":2},{"id":"响应头","title":"响应头","level":3},{"id":"响应示例","title":"响应示例","level":3},{"id":"相关教程","title":"相关教程","level":2}],"text":"本页由后端契约生成。字段、必填项、约束和默认值来自源码模型。下载机器可读来源。示例 ID 与数值均为占位说明，不代表实时价格、限额或模型可用性。\n操作\nPOST /files\noperationId: create_file_v1_files_post\n用 multipart 的 file 字段上传 PNG、JPEG 或 WebP，返回可复用公共文件 ID。服务校验实际图片字节与尺寸，不启动生成。上传不是幂等付费创建，传输异常后不要盲目重放。\n鉴权与副作用\n使用可信环境中的 Bearer API Key。所需权限：animations:write\n此操作不启动付费生成，其他状态变化见上文说明。\n参数\n无路径、查询或操作专属请求头参数。\n请求体 (multipart/form-data)\n请求体必填：true\n字段\n类型\n必填\n默认值\n约束\n含义\nfile\nstring\n是\n—\nformat: binary\nPNG、JPEG 或 WebP 图片字节，校验后返回公共文件 ID。\n完整嵌套结构：Body_create_file_v1_files_post\n响应\nHTTP\n正文\n含义\n201\nFileResponse\n成功的公开响应，示例数值仅用于说明。\n400\nAPIErrorEnvelope\n输入错误，修正请求后再尝试。\n401\nAPIErrorEnvelope\nAPI Key 缺失、到期或被撤销。\n403\nAPIErrorEnvelope\n账户资格、账户状态或 Key 权限不允许此操作。\n404\nAPIErrorEnvelope\n资源不可用、不属于当前用户，或签名无效/过期。\n413\nAPIErrorEnvelope\n请求或解码后的图片超过配置限制。\n415\nAPIErrorEnvelope\n使用支持的图片媒体类型。\n422\nAPIErrorEnvelope\n图片解码后尺寸超过限制。\n429\nAPIErrorEnvelope\n触发账户级速率或队列限制，遵循 Retry-After 等待。\n500\nAPIErrorEnvelope\n内部错误，保留任务 ID 和幂等键，仅标记可重试时重试。\n503\nAPIErrorEnvelope\n服务或供应商不可用，仅 error.retryable 为 true 时重试。\n响应头\nHTTP\n响应头\n类型\n含义\n429\nRetry-After\ninteger\n建议等待秒数，遵循服务值并设置总体截止时间。\n503\nRetry-After\ninteger\n建议等待秒数，遵循服务值并设置总体截止时间。\n响应示例\n相关教程\n轮询与下载 · 错误与安全重试"},{"id":"api.authentication-and-inputs","locale":"zh","title":"鉴权与图片输入","description":"将 API 凭据保留在可信环境，选择正确权限，并通过可复用文件、Base64 或安全的公开 HTTPS 地址传入图片。","section":"api","path":"/docs/zh/api/authentication-and-inputs","url":"https://animgen.com/docs/zh/api/authentication-and-inputs","status":"beta","lastVerified":"2026-08-31","apiVersion":"1.3.0","audience":["api-developer","ai-agent"],"productAreas":["public-api"],"tags":["authentication","API key","upload","Base64","URL","file_id"],"translations":{"en":"https://animgen.com/docs/en/api/authentication-and-inputs","zh":"https://animgen.com/docs/zh/api/authentication-and-inputs"},"headings":[{"id":"在可信环境鉴权","title":"在可信环境鉴权","level":2},{"id":"方案-a-上传后复用文件-id","title":"方案 A：上传后复用文件 ID","level":2},{"id":"方案-b-内联-base64","title":"方案 B：内联 Base64","level":2},{"id":"方案-c-公开-https-地址","title":"方案 C：公开 HTTPS 地址","level":2},{"id":"匹配模型能力","title":"匹配模型能力","level":2}],"text":"在可信环境鉴权\n开放 API 请求使用 Authorization: Bearer <API_KEY>。Key 仅在账户 → 开发者创建时明文显示。请放在密钥存储中；轮换时先更新调用方，再撤销旧 Key，并避免记录请求头。\nAPI 需要已验证的 AnimGen 账户。注册基础档为 1 并发、3 个排队任务、每分钟 3 次创建和 60 次其他请求；有效订阅会提高这些账户级限额。通过 GET /account 查看当前档位、Key 权限与限额，通过 GET /credits/balance 查看可用积分。\n开放 API Key 权限\n对应操作\nanimations:read\n账户、积分、模型、任务读取与列表、资产查询\nanimations:write\n上传文件、报价、创建任务、请求取消\nMCP 使用 OAuth 和更细分的权限，不要把这张 API Key 权限表套用到 MCP。\n方案 A：上传后复用文件 ID\n响应包含 id、MIME 类型、尺寸、字节数和 SHA-256。使用返回的 ID，不要传 Studio 的 uploadId、本地路径或内部任务标识：\n上面的 UUID 是占位符。支持 PNG、JPEG 和 WebP；multipart 默认限制为 20 MB，服务还会校验图片解码与尺寸。应处理服务返回的限制错误，而不是只相信扩展名或 MIME 声明。\n方案 B：内联 Base64\n传入纯 Base64，不要包含 data:image/...;base64, 前缀。解码后单张上限 10 MB，请求内全部内联图片合计上限 20 MB。Base64/JSON 传输体积大于原始文件；较大或反复使用的图片优先先上传。\n创建任务被接受前，Base64 内容会先持久化。幂等重试时应保持原始字节不变。\n方案 C：公开 HTTPS 地址\n把示例域名换成实际可访问的图片地址。服务端必须能在没有浏览器 Cookie 的情况下取得图片。要求公开 HTTPS、443 端口，不能有内嵌用户名密码或 fragment。私网、回环和链路本地地址会被阻止，跳转目标也会重新校验。\n报价和创建期间，应保持该地址的图片字节稳定。不要使用内网地址或返回登录页的 URL。带签名的输入链接同样敏感，而且可能过期。\n匹配模型能力\n每次生成都需要首帧。尾帧和额外参考图是否可用，取决于实时模型的模式支持；请求 Schema 的总上限不能覆盖更低的模型专属上限。\n通过 GET /models 获取合法模式与参数，并对计划提交的完整请求先报价。透明素材要求见透明动画，完整调用见快速开始。"},{"id":"api.errors-and-retries","locale":"zh","title":"错误、幂等与安全重试","description":"区分需修正的输入错误和临时失败，跨重试保留同一次逻辑请求，并在不泄露凭据的前提下排查问题。","section":"api","path":"/docs/zh/api/errors-and-retries","url":"https://animgen.com/docs/zh/api/errors-and-retries","status":"beta","lastVerified":"2026-08-31","apiVersion":"1.3.0","audience":["api-developer","ai-agent"],"productAreas":["public-api"],"tags":["error","retry","429","idempotency","request_id"],"translations":{"en":"https://animgen.com/docs/en/api/errors-and-retries","zh":"https://animgen.com/docs/zh/api/errors-and-retries"},"headings":[{"id":"保持一次逻辑操作不变","title":"保持一次逻辑操作不变","level":2},{"id":"读取错误结构","title":"读取错误结构","level":2},{"id":"如何处理","title":"如何处理","level":2},{"id":"给重试设定边界","title":"给重试设定边界","level":2},{"id":"账户限额与排查","title":"账户限额与排查","level":2}],"text":"保持一次逻辑操作不变\n付费创建接口要求 8–200 字符的 Idempotency-Key。生成一次后，与完整请求一起保存；超时或断线重试时复用两者。\n同一键与同一规范化请求会返回原操作；同一键换了请求内容则冲突。原请求仍在接受过程中时，可能返回可重试的“处理中”冲突。幂等记录至少保留 24 小时，不要假设永久去重。\n去重范围包含账户、操作和 API Key 身份（MCP 对应 OAuth 客户端）。更换 API Key 后，即使幂等字符串相同，也可能创建新任务。创建结果不明时，应先找回已知任务 ID，再处理凭据轮换。\n创建结果不明确时，应先找回原任务，不能悄悄换新键。确实要重新生成或修改请求时，应重新获得批准，并使用新逻辑键。\n读取错误结构\n这是结构示意，不承诺错误消息文本完全相同。根据 HTTP 状态和 error.code 分支处理，检查 retryable，保留 request_id 供支持排查。不要记录原始请求头、图片正文、提示词或签名 URL。\n如何处理\nHTTP / 常见错误码\n操作\n400 INVALID_REQUEST、INVALID_BASE64、INVALID_IMAGE\n修正输入，不要原样重试\n401 INVALID_API_KEY\n检查 Key 是否缺失、到期或被撤销\n402 INSUFFICIENT_CREDITS\n核对余额和报价，不自动购买\n403 API_ACCOUNT_NOT_ELIGIBLE、API_ACCOUNT_PAUSED、INSUFFICIENT_SCOPE\n分别处理邮箱验证、账户状态或权限\n404 NOT_FOUND\n核对公共资源 ID 和归属\n409 IDEMPOTENCY_CONFLICT\n停止，同一键已用于不同请求\n409 IDEMPOTENCY_IN_PROGRESS\n可重试时等待，复用原请求\n413 PAYLOAD_TOO_LARGE、415 UNSUPPORTED_MEDIA_TYPE、422 IMAGE_DIMENSIONS_TOO_LARGE\n修正图片体积、编码或类型\n429 RATE_LIMITED、QUEUE_LIMIT_EXCEEDED\n遵循 Retry-After，限制按账户计算\n503 API_DISABLED、API_UNAVAILABLE、PROVIDER_UNAVAILABLE\n仅在标记可重试时重试，否则检查可用状态\n无权访问资源时，服务可能有意返回“未找到”。不要尝试枚举他人的资源 ID。\n给重试设定边界\n遵循 Retry-After（秒数或 HTTP 日期）；缺失时使用带随机抖动的指数退避。设置最大尝试次数和总体截止时间。停止本地等待，不代表服务端已接受的任务也停止。\n读取操作可在临时传输故障后重试。付费创建结果不明确时，只有已保存幂等键且请求不变，才能重试。不要盲目重试没有幂等保护的上传或其他非幂等操作。\n达到截止时间后，保存已知任务 ID，稍后恢复。任务终态失败时，先检查部分产物，再决定重新导出还是重新生成。\n账户限额与排查\nPROVIDER_CONTENT_REJECTED 目前覆盖 Seedance 明确内容审核拒绝的终态，不属于应原样自动重试的临时错误。读取任务的 credits.status、credits.refunded 和 credits.released；credits.charged 已是净扣费，不要再减一次退分。确认审核拒绝且尚无产物、导出未开始时，一键任务返还原流程整笔积分。客户端超时或导出失败不等同于这一条件，退分也不构成新一轮付费生成的授权。\n通过 GET /account 获取当前限制；响应中的限流头可能反映当前计数窗口。多建 Key 不会增加账户容量。多个任务的轮询应分散执行，避免所有客户端同时突发请求。\n向支持提供公共请求 ID、已知任务 ID、时间、错误码和简短描述。移除凭据和私有输入。不完整结果见轮询与下载，有界重试实现见 Python 示例。"},{"id":"api.examples","locale":"zh","title":"四种语言的完整调用示例","description":"下载 Python、TypeScript、cURL 和 C# 示例，安全完成只报价准备、持久化幂等创建、恢复轮询和实际资产下载。","section":"api","path":"/docs/zh/api/examples","url":"https://animgen.com/docs/zh/api/examples","status":"beta","lastVerified":"2026-08-31","apiVersion":"1.3.0","audience":["api-developer","ai-agent"],"productAreas":["public-api"],"tags":["Python","TypeScript","C#","curl","示例","幂等"],"translations":{"en":"https://animgen.com/docs/en/api/examples","zh":"https://animgen.com/docs/zh/api/examples"},"headings":[{"id":"选择完整工作流","title":"选择完整工作流","level":2},{"id":"准备请求-不启动付费任务","title":"准备请求，不启动付费任务","level":2},{"id":"保护状态-并恢复同一个操作","title":"保护状态，并恢复同一个操作","level":2},{"id":"验收范围","title":"验收范围","level":2}],"text":"选择完整工作流\n每个示例都会发现当前模型、先报价、保存私有状态、轮询同一个任务，并下载实际文件字节。它们是教学示例，不是生产 SDK。下载后先审阅代码再运行。\n语言\n下载\n环境要求\n验收范围\nPython\nanimation-workflow.py\nPython 3.10+，仅标准库\n离线工作流测试\nTypeScript\ntypescript.ts\nNode.js 22.14+\n严格类型检查、离线工作流测试\ncURL\ncurl.sh\nBash、curl 7.55+、jq、SHA-256 工具；PNG 输入\nShell 语法、本机 HTTP Mock\nC#\ncsharp.cs + 项目文件\n.NET 8 SDK\n仅语法解析；验收机器没有 .NET SDK\n先阅读示例完整说明和 API 快速开始。准确参数以自动生成的 API 参考为准。\n准备请求，不启动付费任务\n私密提供 ANIMGEN_API_KEY，把 IMAGE_PATH 设为原图路径，ANIMGEN_MODEL 设为 GET /v1/models 返回的模型 ID。第一次运行 TypeScript、cURL 或 C# 时，不要设置 ANIMGEN_APPROVE_CREDITS。账户需要完成邮箱验证，正式生成还需积分充足。\n根据所选语言，只执行对应命令：\nPython 使用快速开始中分开的 prepare 和 run 命令。其他语言会在显示报价后停止；核对报价后，明确设置接受的 ANIMGEN_APPROVE_CREDITS，再使用原状态重跑同一命令。\n这是本地费用预检查，不是服务端强制预算。开放 API 创建既不接受 quote_id，也不接受 max_credits，创建时会重新计算费用。不要静默批准一个默认金额，也不要把报价理解为锁价。\n保护状态，并恢复同一个操作\nTypeScript 和 C# 使用 ANIMGEN_STATE（默认 animgen-state.json）；cURL 使用 ANIMGEN_STATE_DIR（默认 animgen-curl-state）；Python 使用 --state。状态格式不同，不要切换语言来重试同一个操作。每份状态只运行一个进程。\n状态包含原图与提示词，应放在版本控制之外的私有目录。它保存账户与 API Key 的 ID，但不保存密钥。Windows 下请自行限制目录 ACL。TypeScript/C#/cURL 可通过 ANIMGEN_OUTPUT 选择输出目录，Python 使用 --output。\n创建响应不明确时，保留原状态、账户、原 API Key 身份、请求体及幂等键。切换 Key 会改变服务端幂等作用域。示例对超过 24 小时仍未知的创建停止自动恢复。本地超时不等于远程任务取消。\n已保存任务 ID 后，重跑只轮询该任务，不再创建。失败或取消的任务仍可能有资产，示例会保存它们，再以非零退出码报告结果不完整。签名下载不携带 API Authorization 请求头；链接过期后通过资产元数据获取新链接。\n验收范围\nPython、TypeScript、cURL 通过 Mock 验证只报价、受控创建、状态复用、轮询及部分资产下载。Python/TypeScript 还模拟创建响应丢失，并核对重试沿用原幂等键。文档验收不调用付费供应商。C# 目前仅通过语法检查；实际使用前请在 .NET 8 环境编译并审阅。\n适配自己的项目时，继续阅读错误与重试及轮询与下载。"},{"id":"api.polling-and-downloads","locale":"zh","title":"轮询任务并下载可用产物","description":"正确处理异步状态、积分记账、部分输出、取消任务与过期签名链接，避免泄露下载凭据或重复创建。","section":"api","path":"/docs/zh/api/polling-and-downloads","url":"https://animgen.com/docs/zh/api/polling-and-downloads","status":"beta","lastVerified":"2026-08-31","apiVersion":"1.3.0","audience":["api-developer","ai-agent"],"productAreas":["public-api"],"tags":["polling","Retry-After","outputs","asset","download","cancel"],"translations":{"en":"https://animgen.com/docs/en/api/polling-and-downloads","zh":"https://animgen.com/docs/zh/api/polling-and-downloads"},"headings":[{"id":"创建响应不等于动画完成","title":"创建响应不等于动画完成","level":2},{"id":"状态与阶段","title":"状态与阶段","level":2},{"id":"失败仍可能有可用产物","title":"失败仍可能有可用产物","level":2},{"id":"安全下载","title":"安全下载","level":2},{"id":"取消任务","title":"取消任务","level":2},{"id":"先审核再导出-两阶段流程","title":"先审核再导出：两阶段流程","level":2}],"text":"创建响应不等于动画完成\nPOST /animations 返回 HTTP 202、任务 ID 和 Retry-After。收到 ID 后优先保存；进入队列不代表生产已经完成。\n轮询 GET /animations/{id}。优先遵循服务的 Retry-After（目前通常约五秒），遇到临时错误使用有界退避，并设置总体截止时间。不要因为轮询慢就创建新任务。当前公开流程以轮询为主，不提供 Webhook 工作流。\n状态与阶段\n状态\n调用方应做什么\nqueued\n等待，工作进程尚未完成任务\nrunning\n继续轮询，查看阶段和进度\ncancelling\n已请求取消但未终结，继续轮询\nsucceeded\n终态，检查并下载产物\nfailed\n终态，同时检查错误与已有产物\ncancelled\n终态，检查已完成产物及积分记账\nstage 在适用时标明 video_generation 或 animation_export。progress 范围为 0 到 1，不是精确剩余时间。两次轮询间任务可能跨过多个状态，不保证你观察到每个中间状态。\ncredits.quoted、credits.held、credits.charged 分别表示报价、预占和已扣，不要把初始报价当作最终扣费，也不要把三者相加。\n失败仍可能有可用产物\n一键任务可能先成功生成源视频，再在导出阶段失败。进入终态时，无论 status 是否为 succeeded，都要检查 outputs。\n先下载已有资产，再记录错误和缺失的请求格式，准确报告部分完成。只重做必要步骤：已有源视频可以通过 /animation-exports 重新导出，不必重新生成动作。\n安全下载\n每个资产包含 id、format、mime_type、byte_size、download_url 和 download_expires_at。\n用任务 ID 或资产 ID 保存长期应用状态。\n使用返回的签名 URL 下载字节。\n不要把 API Bearer 头发送给签名 URL 或重定向后的存储主机。\n使用应用自己决定的文件名，并确认下载完整。\n链接过期时，用 API Key 调用 GET /assets/{asset_id} 获取新链接。\n链接有效期较短，应读取 download_expires_at，不要写死时长。资产已受存储或保留策略移除时，重新查询不会恢复文件。\n签名 URL 相当于临时凭据，不应发布到日志、分析事件、工单或 AI 对话记录。\n取消任务\n对归属自己的任务调用 POST /animations/{id}/cancel。取消属于尽力而为，返回的可能仍是中间状态；继续轮询到终态。任务完成也可能先于取消生效。\n已经执行的生产可能保留扣费，未消耗的预占可以释放。应检查返回的积分数据，不要承诺一定全额退款。\n先审核再导出：两阶段流程\n使用 POST /video-generations 创建视频，再轮询 GET /video-generations/{id} 取得视频资产。审核后，把 source_video_asset_id、选段和导出设置提交到 POST /animation-exports，轮询 GET /animation-exports/{id}。\n每个新的付费创建操作都应先报价，并使用自己的幂等键。源资产 ID 和任务 ID 不是同一种资源，不能互换。快速开始示例演示的是更简单的一键生命周期。"},{"id":"api.quickstart","locale":"zh","title":"API 快速开始：从图片到下载资产","description":"安全完成第一次 API 调用：发现模型、准备图片、确认报价、幂等创建、轮询状态，并保存实际输出文件。","section":"api","path":"/docs/zh/api/quickstart","url":"https://animgen.com/docs/zh/api/quickstart","status":"beta","lastVerified":"2026-08-31","apiVersion":"1.3.0","audience":["api-developer","ai-agent"],"productAreas":["public-api"],"tags":["quickstart","Python","curl","quote","idempotency"],"translations":{"en":"https://animgen.com/docs/en/api/quickstart","zh":"https://animgen.com/docs/zh/api/quickstart"},"headings":[{"id":"前提条件","title":"前提条件","level":2},{"id":"1-发现可用模型","title":"1. 发现可用模型","level":2},{"id":"2-准备请求并报价-不启动生成","title":"2. 准备请求并报价，不启动生成","level":2},{"id":"3-明确批准创建","title":"3. 明确批准创建","level":2},{"id":"4-安全恢复并检查结果","title":"4. 安全恢复并检查结果","level":2},{"id":"请求会做什么","title":"请求会做什么","level":2}],"text":"前提条件\n开放 API 处于公开测试阶段。你需要已验证的 AnimGen 账户、包含 animations:read 和 animations:write 的 API Key，以及可信服务端或本地机器。生成要求账户积分充足；订阅会提高开发者限额，但不是访问前提。\n在账户 → 开发者创建 Key。通过密钥管理器或私有 Shell 会话提供 ANIMGEN_API_KEY 环境变量。不要写进浏览器 JavaScript、发布的游戏、代码仓库或 AI 对话。\n基础地址为 https://api.animgen.com/v1。URL 的兼容性版本是 v1，本文对应的契约版本是 1.3.0。\n1. 发现可用模型\n从 data 中选择支持目标输入模式的 id，检查时长、分辨率、比例和能力标志。不要直接使用旧文章中的模型名。\n下面的首帧示例要求模型的 supports_first_frame 为 true，且 modes 支持首帧。示例使用该模型当前公布的默认选项。\n2. 准备请求并报价，不启动生成\n下载并检查 Python 完整工作流示例。它要求 Python 3.10+，仅使用标准库。\n替换图片路径和模型 ID。准备阶段会检查模型目录，生成 Base64 请求，获取报价与余额，并写入私有状态文件；不会调用付费创建接口。\n状态文件包含原图和提示词，请勿提交到版本控制，限制访问，并在不再需要时删除。文件不包含 API Key。\n3. 明确批准创建\n核对积分报价，将 APPROVED_CREDITS 设置为你接受的金额，再运行：\n首次创建前，脚本会重新报价；超过本地批准金额时停止。它会保存幂等键，以同一请求执行一次逻辑创建，然后轮询并下载产物。\n开放 API 不接受 max_credits 或 quote_id。此示例的批准金额只是本地预检查，不是服务端原子支出上限或锁价承诺；创建时会按当前价格重新计算。如果自动化必须有服务端强制上限，不应使用此示例替代该保障。已上线的 MCP 在独立 OAuth 工具流程中提供服务端支出保护。\n4. 安全恢复并检查结果\n命令超时后，使用同一个状态文件重新运行。如果文件已有任务 ID，脚本只恢复轮询，不会再创建。创建响应不明确时，会在保守重试窗口内复用原始幂等键与请求内容。\n不要删除状态文件、重新准备来“重试”，那会变成新逻辑操作，可能重复付费。示例对超过 24 小时仍无法确认结果的创建拒绝自动重试；请先检查任务列表或联系支持。\n进入任何终态后，脚本都会先保存可用资产，再报告失败或取消。结果不完整时返回非零退出码，不把部分产物当作全部成功。文件名使用资产 ID，不使用远端提供的任意名称。\n请求会做什么\n示例使用普通模式、完整视频区间，并请求 PNG 帧 ZIP、24 帧、512 × 512 尺寸。这些只是示例选择，不是 API 默认值，也不是适合所有项目的质量建议。\n复用上传文件或使用公开图片 URL，见鉴权与图片输入。任务生命周期见轮询与下载、错误与重试。精确契约可下载 OpenAPI JSON。\nPython 示例通过本地 Mock 测试验证，没有通过真实付费生成来做测试。正式接入时，使用一个小型且明确批准费用的任务自行验收。其他语言与各自验收范围见完整调用示例，准确参数见自动生成的 API 参考。"},{"id":"editing-and-export.advanced-editor","locale":"zh","title":"使用 Advanced Editor 逐帧精修","description":"从源视频建立非破坏性的输出序列，完成选帧、重排、停顿、播放调整和配方保存，再导出已检查的版本。","section":"editing-and-export","path":"/docs/zh/editing-and-export/advanced-editor","url":"https://animgen.com/docs/zh/editing-and-export/advanced-editor","status":"preview","lastVerified":"2026-08-30","audience":["user","game-developer"],"productAreas":["editor","export"],"tags":["Advanced Editor","Fine-tune animation","精修","选帧","sequence","autosave"],"translations":{"en":"https://animgen.com/docs/en/editing-and-export/advanced-editor","zh":"https://animgen.com/docs/zh/editing-and-export/advanced-editor"},"headings":[{"id":"进入当前编辑器","title":"进入当前编辑器","level":2},{"id":"理解五个面板","title":"理解五个面板","level":2},{"id":"建立输出序列","title":"建立输出序列","level":2},{"id":"调整节奏并理解具体结果","title":"调整节奏并理解具体结果","level":2},{"id":"离开或导出前确认保存","title":"离开或导出前确认保存","level":2},{"id":"当前能力边界","title":"当前能力边界","level":2}],"text":"进入当前编辑器\n在 Quick Mode 中打开已就绪的生成视频或导入视频，选择 Fine-tune animation。编辑器面向宽度至少 1024 px 的桌面窗口；小屏幕请使用 Quick Mode 或扩大窗口。部分界面标签目前仍为英文。\n源视频不会被修改。保存的 composition 是引用源帧的编辑配方，不是重新生成的视频。再次进入同一来源时，可能复用已有默认配方；替换内容前先检查当前序列。\n理解五个面板\n面板\n用途\nSource Monitor\n用独立播放头检查原始视频\nAnimation Preview\n预览输出序列、画布与节奏\nSource Frames\n从解码后的源视频选择帧\nAnimation Sequence\n排列最终需要导出的帧\nCanvas Inspector\n设置全局画布、摆放和 pivot\n源视频与输出序列的播放头相互独立。选中帧不一定等于移动播放头，检查修改时要观察对应预览。\n建立输出序列\n点击源帧缩略图；Shift 点击扩展范围，Ctrl/⌘ 点击切换单帧选择。\n使用 Insert 插入到序列播放头处，Append 追加到末尾，或拖入序列。\n选择输出帧后可移动、重复或删除；成组移动会保留组内顺序。\nDuplicate 会把每个选中项复制到自身旁边，可用于延长姿势停顿。\nReverse 反转的是整个序列，不只是选中部分。\n通过 Undo/Redo 按钮纠正当前编辑会话中的近期操作。\n当前上限为 240 个展开后的输出帧，重复帧也计入。界面没有独立的单帧时长编辑器；可通过重复帧形成停顿，并检查最终序列长度。\n调整节奏并理解具体结果\n输出 FPS 范围为 1–60。固定 FPS 下，时长等于展开帧数除以 FPS。例如 24 帧以 12 FPS 播放，时长两秒；额外重复其中三帧后，27 帧为 2.25 秒；再改为 24 FPS 则为 1.125 秒。\n修改 FPS 不会补出新的中间动作。循环播放只是重复序列，不会修复首尾接缝，应检查边界处的脚底、轮廓与速度。\n源帧时间来自视频实际解码的呈现时间戳。经过重排或重复后，源帧编号不等于输出序列编号。\n离开或导出前确认保存\n停止修改片刻后会自动保存，观察状态：Unsaved → Saving… → Saved。Save failed 不代表已保存。解决错误前保持页面打开，并保留重要编辑内容的记录。\n同一配方尽量只在一个标签页编辑，避免版本冲突。编辑器自身的 Back 和 Export 会尝试提交待保存修改；直接关闭标签页或断网不能保证保存。Undo 历史属于当前编辑会话，不是永久的服务端版本历史。\n导出使用已保存的 composition 版本和配方快照。确认前核对帧数、FPS、画布、格式和报价。之后继续编辑，不会改写已经提交的导出。\n当前能力边界\n当前提供序列编辑和全局画布/角色摆放，不提供逐帧变换关键帧、自动姿势对齐、AI 修帧、多轨合成或音频编辑。公开 API/MCP 生成工具也不接受 Advanced Editor 配方。\n继续阅读画布与 pivot、输出格式和导出排障。"},{"id":"editing-and-export.canvas-and-pivot","locale":"zh","title":"设置输出画布、对齐与 pivot","description":"让同一组源帧在一致画布中摆放，并把预期原点传递到精灵资源和游戏引擎，避免混淆像素位置与锚点。","section":"editing-and-export","path":"/docs/zh/editing-and-export/canvas-and-pivot","url":"https://animgen.com/docs/zh/editing-and-export/canvas-and-pivot","status":"preview","lastVerified":"2026-08-30","audience":["user","game-developer"],"productAreas":["editor","export"],"tags":["canvas","pivot","anchor","画布","锚点","alignment","contain","cover"],"translations":{"en":"https://animgen.com/docs/en/editing-and-export/canvas-and-pivot","zh":"https://animgen.com/docs/zh/editing-and-export/canvas-and-pivot"},"headings":[{"id":"画布改变像素-pivot-改变原点","title":"画布改变像素，pivot 改变原点","level":2},{"id":"选择一致的帧画布","title":"选择一致的帧画布","level":2},{"id":"有意识地设置-pivot","title":"有意识地设置 pivot","level":2},{"id":"读取导出的坐标约定","title":"读取导出的坐标约定","level":2},{"id":"交付前如何检查","title":"交付前如何检查","level":2}],"text":"画布改变像素，pivot 改变原点\n在 Advanced Editor 中，画布和角色控件影响实际渲染的输出帧；pivot 告诉引擎把精灵原点放在哪里。移动 pivot 不会改变 PNG 内已经绘制的像素位置。\n这与生成前准备源图的输入画布不同。输出摆放只复用已有动作。\n选择一致的帧画布\n当前 Inspector 的宽高范围为 64–1024 px，并提供 256、512、1024 方形预设。应结合目标显示尺寸和纹理预算选择；放大画布会增加文件量，但不会恢复源图没有的细节。\n画布背景可选 Transparent 或 Solid。透明画布只让没有绘制内容的区域透明，不会自动去掉源画面已有的不透明背景。\n角色设置\n效果\nCenter / Bottom center\n在画布中全局居中或底部居中\nContain\n完整放入原图，可能留下空白\nCover\n填满画布，可能裁掉部分原图\nOriginal pixels\n从源图原始像素大小开始\nScale\n额外全局缩放，范围 0.1–3\nX / Y offset\n以输出像素为单位的全局位移\n修改后应检查多个姿势。站立帧放得下，不代表跳跃帧不会裁切。全局对齐不会自动跟踪脚底，也不会逐帧独立校准。\n有意识地设置 pivot\nPivot 的两个坐标范围均为 0–1，原点在左下角：\n目标原点\nX\nY\n底部居中\n0.5\n0\n画布中心\n0.5\n0.5\n左下角\n0\n0\n地面角色可从底部居中开始。它表示画布原点，不是自动检测出的脚底。多段动画共用引擎变换时，应保持一致的画布构图。\n读取导出的坐标约定\nanimgen-manifest.json 的 schema 为 animgen.sprite-export.v1。帧矩形使用 rectOrigin: \"top_left\"，而 pivot.origin 为 \"bottom_left\"。两套坐标约定不同是有意设计。\n清单还记录帧尺寸、图集尺寸、FPS、循环、帧数、名称和矩形位置。应读取这些值，不要凭纹理大小猜测网格，尤其是图集包含补边时。\nUnity 元数据保存逐精灵 pivot；Godot 场景通过 offset 应用 pivot，只赋 SpriteFrames 资源不会带上场景偏移；Cocos 示例播放器可把导出的 pivot 应用到 UITransform。对应操作见引擎导入指南入口。\n交付前如何检查\n在固定背景或网格下检查首尾帧、动作伸展部位和原点标记，再把同一段序列放到小型引擎场景中对照。\n导出透明视频时，需要透明画布及合法的透明来源处理。纯色画布与透明视频输出冲突。结果不同于预期时，先做导出与透明排障，再决定是否重新付费生成。"},{"id":"editing-and-export.cocos-creator","locale":"zh","title":"导入 Cocos Creator 3 动画","description":"配对导入 PNG 与 PLIST 图集，挂载生成的精灵播放器，并在多段动画中安全复用组件与设置锚点。","section":"editing-and-export","path":"/docs/zh/editing-and-export/cocos-creator","url":"https://animgen.com/docs/zh/editing-and-export/cocos-creator","status":"stable","lastVerified":"2026-08-30","audience":["user","game-developer","api-developer","ai-agent"],"productAreas":["export"],"tags":["Cocos Creator","cocos_creator_pack","SpriteAtlas","plist","AnimGenSpritePlayer","UITransform"],"translations":{"en":"https://animgen.com/docs/en/editing-and-export/cocos-creator","zh":"https://animgen.com/docs/zh/editing-and-export/cocos-creator"},"headings":[{"id":"了解导出文件","title":"了解导出文件","level":2},{"id":"图集成对导入","title":"图集成对导入","level":2},{"id":"配置播放器","title":"配置播放器","level":2},{"id":"多份导出复用同一个组件","title":"多份导出复用同一个组件","level":2},{"id":"验收结果","title":"验收结果","level":2}],"text":"了解导出文件\n选择 cocos_creator_pack，ZIP 内包含 spritesheet.png、spritesheet.plist、AnimGenSpritePlayer.ts、animgen-manifest.json 和 README。\nPLIST 使用 Cocos2d-x 图集格式 3。TypeScript 文件是 Sprite 组件播放器示例，不是原生 AnimationClip，也不是完整游戏控制器。\n图集成对导入\n保持 PNG 与 PLIST 名称不变，同时导入同一个 Assets 目录。生成的 SpriteAtlas 可以展开为独立 SpriteFrame 子资源。配对导入说明见 Cocos 官方 Atlas 文档。\n导入播放器脚本并等待编译。创建 Sprite 节点，挂载 AnimGenSpritePlayer，把导入的 SpriteAtlas 赋给 atlas 属性。\n配置播放器\n属性\n行为\natlas\n提供逐帧精灵的图集\nfps\n播放速度，初始值来自导出 FPS\nloop\n循环或停在最后一帧\nplayOnLoad\n加载后开始播放\napplyExportedPivot\n将 UITransform 锚点设为本脚本内嵌的导出 pivot\n脚本按帧名的数字顺序排序，先显示首帧，再按经过时间推进，并提供 play()、stop() 供集成。修改运行行为后，应验收自己的组件，不再假定它与生成示例完全一致。\n多份导出复用同一个组件\n每份包都使用 AnimGenSpritePlayer 类名。不要为项目中的每段动画重复导入一份同名类。\n复用一个播放器组件，为各节点明确指定 atlas、FPS 和循环设置。脚本内嵌的是生成该脚本时的 pivot。如果其他导出需要不同 pivot，关闭 applyExportedPivot，分别设置各节点的 UITransform 锚点，或有意识地改造成自己的通用播放器。\n验收结果\n按 animgen-manifest.json 核对帧数和 FPS，再在小场景中检查首尾接缝、节点缩放、锚点、透明和绘制顺序，最后接入游戏逻辑。\n节点空白时，检查脚本编译、atlas 赋值、Sprite 组件及图集子资源是否存在。显示整张图时，确认使用的是 SpriteAtlas，而不是独立纹理。\n缺帧时，确认 PNG 与 PLIST 来自同一次导出且一起导入。切换动画时锚点跳动，则检查上面的逐导出 pivot 处理。详见画布与 pivot和透明格式。\n生成示例面向 Cocos Creator 3.x；包检查不能替代在你实际编辑器和目标构建中的导入运行测试。"},{"id":"editing-and-export.godot","locale":"zh","title":"导入 Godot 4 动画","description":"保留 Godot 包中的资源路径，使用 SpriteFrames 和可播放场景，并正确继承 FPS、循环与 pivot 偏移。","section":"editing-and-export","path":"/docs/zh/editing-and-export/godot","url":"https://animgen.com/docs/zh/editing-and-export/godot","status":"stable","lastVerified":"2026-08-30","audience":["user","game-developer","api-developer","ai-agent"],"productAreas":["export"],"tags":["Godot","Godot 4","godot_pack","SpriteFrames","AnimatedSprite2D","res://"],"translations":{"en":"https://animgen.com/docs/en/editing-and-export/godot","zh":"https://animgen.com/docs/zh/editing-and-export/godot"},"headings":[{"id":"包内有什么","title":"包内有什么","level":2},{"id":"保持根路径一致","title":"保持根路径一致","level":2},{"id":"使用现成场景或已有节点","title":"使用现成场景或已有节点","level":2},{"id":"检查节奏与对齐","title":"检查节奏与对齐","level":2},{"id":"安全复用","title":"安全复用","level":2}],"text":"包内有什么\n导出 godot_pack 后，命名根目录内包含 spritesheet.png、animation.tres、animation.tscn、animgen-manifest.json 和 README。\n.tres 是由 AtlasTexture 帧矩形组成的 Godot 4 SpriteFrames 资源；.tscn 包含使用该资源的 AnimatedSprite2D，配置了自动播放及 pivot 对应的偏移。它不是 Godot 3 的 AnimatedSprite 资源。\n保持根路径一致\n解压后，把包中的命名根目录放到 Godot 项目根目录下。README 会给出预期的 res://<导出目录>/ 路径。\n生成文件中的资源引用包含这个目录名。只移动 animation.tres、重命名根目录，或将其额外嵌套一层但不更新引用，都会导致找不到纹理或资源。\n等待 Godot 导入 PNG，再打开 animation.tscn，或把它实例化到小型测试场景中。\n使用现成场景或已有节点\n最快的方式是使用包内场景。已有 AnimatedSprite2D 时，可把 animation.tres 赋给 Sprite Frames，选中导出的动画并配置播放。\nGodot 官方二维精灵动画指南说明 AnimatedSprite2D、SpriteFrames、播放和 FPS。AnimGen 资源已经写入帧、循环标志及速度，无需重新切割 PNG。\n只赋 SpriteFrames 不会复制生成场景中的 offset。需要保留非居中的 pivot 时，还应同步场景偏移，或在已有节点中设置对应原点。\n检查节奏与对齐\n按 animgen-manifest.json 核对帧数和 FPS，确认父节点变换或项目脚本没有额外修改速度和位置。至少播放一个完整循环，用固定基准线检查落地姿势。\n节点完全不可见时，先查缺失资源报错、纹理导入、所选动画、可见性与场景位置。帧内容不对时，检查是否混用了不同导出任务的纹理和 .tres。\n边缘显示与 Studio 不同时，应使用同一份 PNG 基线检查目标纹理过滤和渲染设置，详见透明格式。\n安全复用\n尽量保留包内名称和路径。确实需要整理目录时，同时修改 animation.tres 的纹理路径与 animation.tscn 的资源路径，再重新打开验证。\n包生成测试通过，不等于你的 Godot 项目已完成运行时验收。接入游戏逻辑或导出到目标设备前，先完成小项目导入测试。"},{"id":"editing-and-export.output-formats","locale":"zh","title":"选择输出格式","description":"对照视频、PNG 序列、精灵图元数据和引擎包，了解透明条件、用途与导出权益要求。","section":"editing-and-export","path":"/docs/zh/editing-and-export/output-formats","url":"https://animgen.com/docs/zh/editing-and-export/output-formats","status":"stable","lastVerified":"2026-08-30","audience":["user","api-developer"],"productAreas":["export"],"tags":["formats","spritesheet","Unity","Godot","Unreal","Cocos","WebM","ProRes"],"translations":{"en":"https://animgen.com/docs/en/editing-and-export/output-formats","zh":"https://animgen.com/docs/zh/editing-and-export/output-formats"},"headings":[{"id":"从使用目标开始选择","title":"从使用目标开始选择","level":2},{"id":"格式对照","title":"格式对照","level":2},{"id":"透明是来源与格式的共同约定","title":"透明是来源与格式的共同约定","level":2},{"id":"完整保留引擎包结构","title":"完整保留引擎包结构","level":2},{"id":"积分-权益与下载","title":"积分、权益与下载","level":2},{"id":"按引擎完成导入","title":"按引擎完成导入","level":2}],"text":"从使用目标开始选择\n想快速检查结果，先下载 PNG 帧 ZIP。自研运行时通常使用精灵图与配套 JSON。需要引擎导入时，选择对应引擎包，并阅读包内说明。\nWeb 导出对话框初始选择 PNG 帧 ZIP；一键开放 API 省略 output_formats 时默认是 spritesheet。如果流水线依赖固定产物，请显式指定格式。\n格式对照\nAPI 格式\n返回内容\n常见用途\nclip_video\n选段 MP4，不透明\n审核、普通视频播放\nwebm_alpha\n带 Alpha 的 WebM\n支持透明视频的播放器，需实测目标环境\nprores_4444\n带 Alpha 的 ProRes 4444\n合成、视频编辑\nframes_zip\nPNG 逐帧 ZIP\n逐帧检查、自定义导入\nspritesheet\nPNG 纹理图集\n打包成单张纹理\nspritesheet_json\n配套帧元数据\n帧矩形和时间信息\nunity_meta\nUnity 纹理元数据\n与匹配的精灵图配套使用\nunity_pack\nUnity ZIP\n图集、元数据、JSON、清单与说明\ngodot_pack\nGodot 4 ZIP\nSpriteFrames 与 AnimatedSprite2D 资源\nunreal_paper2d_pack\nUnreal Paper2D ZIP\nPNG 图集及 Paper2D 精灵描述\ncocos_creator_pack\nCocos Creator 3.x ZIP\nPNG/PLIST 图集和示例播放器\n元数据本身不是图片，应同时请求或保存配套纹理。以响应中的 outputs 为实际资产清单，不要假设某个数组位置或固定扩展名一定存在。\n透明是来源与格式的共同约定\n普通 MP4 和原始生成视频保持不透明。透明 PNG、图集、引擎资源、透明 WebM 和 ProRes 4444 需要合适的来源及导出设置。\n开放 API 只支持 Alpha Key 来源的透明处理，不对任意背景进行抠图，详见透明动画。\n即使文件包含 Alpha，播放器也可能不显示。请在目标软件中测试；可以用 PNG 帧或适配的编辑器，区分显示兼容问题和导出问题。\n完整保留引擎包结构\n引擎 ZIP 内包含 animgen-manifest.json 和说明文件。不要随意打乱相对路径；Godot 资源会引用包内路径，Unreal Paper2D 导入也需要相应引擎工具。\n清单中的帧矩形使用左上角原点；归一化 pivot 使用左下角原点。读取清单，不要仅凭纹理尺寸推断。先在小型测试场景检查帧顺序、播放速度、缩放、锚点和透明效果，再接入整个项目。\n积分、权益与下载\n免费 Web 访问包含 PNG 帧 ZIP。高级格式需要付费导出权益；积分余额与格式权益是独立检查，详见积分与访问权益。\n资产下载使用短期签名链接，应保存文件而不是 URL。API 调用方请查看轮询与下载。\n按引擎完成导入\n导出后继续阅读 Unity、Godot 4、Unreal Paper2D或 Cocos Creator 3。各指南对应包内真实文件、路径和播放器，不假定所有引擎已经完成运行时验收。\n需要调整摆放时参考画布与 pivot，需要视频合成时参考透明格式兼容性。"},{"id":"editing-and-export.transparent-formats","locale":"zh","title":"透明格式与播放兼容性","description":"选择 PNG、精灵资源、WebM Alpha 或 ProRes 4444，并区分来源透明、文件携带 Alpha 和目标软件实际支持。","section":"editing-and-export","path":"/docs/zh/editing-and-export/transparent-formats","url":"https://animgen.com/docs/zh/editing-and-export/transparent-formats","status":"stable","lastVerified":"2026-08-30","audience":["user","game-developer"],"productAreas":["editor","export"],"tags":["Alpha","WebM","VP8","ProRes 4444","PNG","透明","兼容性"],"translations":{"en":"https://animgen.com/docs/en/editing-and-export/transparent-formats","zh":"https://animgen.com/docs/zh/editing-and-export/transparent-formats"},"headings":[{"id":"透明有三个检查点","title":"透明有三个检查点","level":2},{"id":"按目标环境选择格式","title":"按目标环境选择格式","level":2},{"id":"用同一帧做对照排查","title":"用同一帧做对照排查","level":2},{"id":"不只看四角-还要看边缘","title":"不只看四角，还要看边缘","level":2},{"id":"预算与交付","title":"预算与交付","level":2}],"text":"透明有三个检查点\n透明结果需要：合适的来源/处理流程、能保存 Alpha 的格式、实际使用该通道的播放器或渲染器。满足其中一点，不代表其余两点也成立。\n公开 API/MCP 流程应从带有效 Alpha 的图片开始，使用 video.transparency.mode: \"alpha_key\" 并开启透明导出。这不是任意背景移除服务。原始生成视频使用临时键色背景，本身仍不透明。\n按目标环境选择格式\n输出\n当前编码或结构\n如何验收\nPNG 帧 ZIP\n独立 RGBA 图片\n在深浅背景上检查代表帧\n精灵图 / 引擎包\nPNG 加帧信息或引擎元数据\n检查纹理 Alpha、材质和导入设置\nWebM Alpha\n带 Alpha 元数据的 VP8\n实测应用使用的浏览器、系统、设备和解码器\nProRes 4444\nMOV 容器中的 Alpha 兼容 ProRes\n使用支持该 profile 的剪辑或合成软件\nMP4 片段 / 原始视频\n不透明视频\n不应期待透明输出\n当前 WebM Alpha 编码使用 VP8，不是 VP9。仅显示“支持 WebM”不能证明支持此组合中的 Alpha。ProRes 4444 面向编辑和交换，不承诺在所有浏览器内嵌播放。\n不能只看扩展名。任意 MOV 或 PNG 都可能是不透明文件；同一个透明文件也可能在某个查看器里显示黑底，在另一个软件中正确合成。\n用同一帧做对照排查\n选择包含动作和细边缘的短片段。\n在权益和报价允许时，同时导出 PNG 帧与目标格式。\n将同一帧分别放到白色、深灰和对比色背景上。\nPNG Alpha 正确但视频显示异常时，先检查解码与合成，不要直接重新生成动作。\n各种输出都出现同一不透明区域时，检查来源模式、导出透明开关、画布背景和源图 Alpha。\n原图中画上去的棋盘格不是透明；只把输出画布设成透明，也不会消除每帧内部已有的不透明背景。\n不只看四角，还要看边缘\n检查头发、烟雾、半透明服装、运动模糊和接近键色的区域。光晕可能来自源图污染、键色溢出、缩放、滤波或目标软件对 Alpha 的解释方式。\n对照时优先使用原始导出文件，避免经过可能压平透明通道的中间转换器。引擎纹理还应检查目标平台的过滤、压缩和材质设置。改扩展名不能修复丢失的通道。\n导出校验失败时仍可能有部分可用资产。应保存这些文件并检查报错，不能仅因视频已经生成就把整个任务判为成功。\n预算与交付\n高级格式需要导出权益，处理也可能消耗积分。大批量交付前先做小范围兼容性测试；下游需要备用路径时，保留通用的 PNG 基线和匹配元数据。\n继续阅读输出格式和透明导出排障。文档不认证所有浏览器或引擎版本，请验收自己的实际目标环境。"},{"id":"editing-and-export.trim-and-export","locale":"zh","title":"选段与导出","description":"从生成结果中选取有效片段，平衡帧数和尺寸，确认导出费用，并找到完成后的下载资产。","section":"editing-and-export","path":"/docs/zh/editing-and-export/trim-and-export","url":"https://animgen.com/docs/zh/editing-and-export/trim-and-export","status":"stable","lastVerified":"2026-08-30","audience":["user","api-developer"],"productAreas":["studio","export"],"tags":["trim","loop","FPS","download"],"translations":{"en":"https://animgen.com/docs/en/editing-and-export/trim-and-export","zh":"https://animgen.com/docs/zh/editing-and-export/trim-and-export"},"headings":[{"id":"生成和导出是两个步骤","title":"生成和导出是两个步骤","level":2},{"id":"选择有效区间","title":"选择有效区间","level":2},{"id":"设置帧率与尺寸","title":"设置帧率与尺寸","level":2},{"id":"确认导出","title":"确认导出","level":2},{"id":"找到文件","title":"找到文件","level":2},{"id":"api-中的对应流程","title":"API 中的对应流程","level":2},{"id":"需要不连续选帧或重排时","title":"需要不连续选帧或重排时","level":2}],"text":"生成和导出是两个步骤\n生成负责创建源动作；导出负责从选定区间采样并打包结果。你可以先检查源视频，再多次导出不同版本，不必每次重新调用视频模型。\n在 Studio 选择已生成的视频，或通过“导入动画”使用你有权处理的现有视频。来源的背景和透明条件仍会影响可用的导出处理。\n选择有效区间\n先播放源视频，再调整时间线的起止手柄。逐帧检查，避开动作被截断的位置和变形的过渡。需要循环时，重复预览所选区间。\n循环是否自然取决于素材本身；选段和重复播放不会自动生成匹配的结束姿态。\n设置帧率与尺寸\n打开导出对话框前，设置导出帧率和尺寸。区间时长与帧率决定需要打包的帧数；例如一秒区间在 24 FPS 下约为 24 帧，实际以选段边界和界面汇总为准。\n帧数越多，文件越大，也可能增加处理费用。放大输出尺寸不会恢复源视频中不存在的细节。首次测试引擎导入时，先用适中的尺寸检查效果。\n确认导出\n点击“导出”后：\n选择一种或多种输出格式。\n如果需要透明结果，检查透明处理设置。\n核对帧数、尺寸、权益限制和积分报价。\n点击一次“开始导出”，观察任务状态。\n格式锁定时，查看积分与访问权益。无法估算费用不等于费用为零。\n找到文件\n在左侧项目面板打开“当前片段的导出”，选择已完成的记录并下载资产。导入引擎包时，保持 PNG 与配套 JSON、元数据或引擎资源之间的目录关系。\n后续导出失败，不代表源视频或先前成功的产物无效。重新提交前先检查现有结果。下载链接过期时，从结果界面重新获取，不要继续分享旧的签名 URL。\nAPI 中的对应流程\n一键 API 默认选择整个源视频。指定区间时，以秒为单位：\nAPI 使用 frame_count，不是顶层 fps。这只是请求片段，不能单独创建任务。需要先审核再导出时，使用 /video-generations 创建视频，再通过 /animation-exports 导出它的视频资产；详见轮询与下载。\n需要不连续选帧或重排时\n快速裁剪适合连续片段。需要重复姿势、移除中间帧、反转或调整全局画布时，使用 Advanced Editor。先确认配方保存，再导出；它不会重新 AI 生成动作。"},{"id":"editing-and-export.unity","locale":"zh","title":"导入 Unity 动画","description":"完整导入 Unity 图集及元数据，创建精灵动画，并检查帧顺序、比例、pivot 和透明边缘。","section":"editing-and-export","path":"/docs/zh/editing-and-export/unity","url":"https://animgen.com/docs/zh/editing-and-export/unity","status":"stable","lastVerified":"2026-08-30","audience":["user","game-developer","api-developer","ai-agent"],"productAreas":["export"],"tags":["Unity","unity_pack","meta","Sprite Editor","Animator","导入"],"translations":{"en":"https://animgen.com/docs/en/editing-and-export/unity","zh":"https://animgen.com/docs/zh/editing-and-export/unity"},"headings":[{"id":"导出-unity-包","title":"导出 Unity 包","level":2},{"id":"纹理和元数据一起导入","title":"纹理和元数据一起导入","level":2},{"id":"创建所需动画","title":"创建所需动画","level":2},{"id":"在小场景中验收","title":"在小场景中验收","level":2},{"id":"保留可复查的交付","title":"保留可复查的交付","level":2}],"text":"导出 Unity 包\n在导出对话框或公开请求中选择 unity_pack，核对导出权益与报价，等待导出完成并下载 ZIP 文件。\n包内包含 spritesheet.png、spritesheet.png.meta、配套 JSON、animgen-manifest.json 和 README。先解压到新目录，避免意外覆盖项目已有资产或 GUID。\n纹理和元数据一起导入\n把整个导出目录复制到 Unity 项目的 Assets，保持 PNG 与相邻 .meta 的文件名关系。元数据配置了多精灵导入，并携带帧矩形和 pivot。只先导入 PNG 而不带元数据时，Unity 可能生成另一套导入设置。\n在 Project 窗口选择纹理，检查 Sprite (2D and UI)、Multiple，并在 Sprite Editor 中查看切片。控件说明见 Unity 官方 Sprite Editor 文档。\n不要直接按不透明边界重新自动切片，否则可能改变统一帧尺寸、对齐和透明留白。某版本需要手工修复时，应按导出矩形和 pivot 配置，不要猜网格。\n创建所需动画\n导出包提供精灵资源，不提供预制 Animator Controller 或游戏状态机。按数字后缀顺序（_0000、_0001 等）选择精灵，通过项目自身的动画流程创建 Animation Clip。Unity 精灵名以导出任务 ID 为前缀；配套 JSON 中的 frame_0000.png 并不是同名的 Unity 资产。\n按 animgen-manifest.json 中的 animation.fps 设置采样节奏，并明确设置循环行为。循环前检查首尾是否重复造成停顿；Transform 缩放和 pixels-per-unit 应与游戏其他资源保持一致。\n在小场景中验收\n对照 animation.frameCount 检查精灵数量，再与 Studio 播放对比。用固定基准线检查脚底、对象变换原点处的 pivot、透明边缘和首尾接缝。\n只看到整张图集时，检查多精灵设置和正确的 .meta 是否一起导入。动作抖动时，先比对帧矩形与 pivot，不要立即改生成参数。像素模糊或光晕也可能与目标项目的过滤、压缩和材质有关。\n保留可复查的交付\n保存 ZIP 和清单，便于复核。更换元数据可能影响项目中的已有资产引用，建议通过版本控制或副本测试重新导入。\n本指南对应 AnimGen 实际包结构与 Unity 导入流程，不代表所有 Unity 版本和渲染管线都已认证。显示不同于预期时，查看画布与 pivot和透明格式。"},{"id":"editing-and-export.unreal-paper2d","locale":"zh","title":"导入 Unreal Paper2D 动画","description":"将 Paper2D 描述文件与补边图集配套导入，创建或检查 Flipbook，并核对帧率、原点和材质透明行为。","section":"editing-and-export","path":"/docs/zh/editing-and-export/unreal-paper2d","url":"https://animgen.com/docs/zh/editing-and-export/unreal-paper2d","status":"stable","lastVerified":"2026-08-30","audience":["user","game-developer","api-developer","ai-agent"],"productAreas":["export"],"tags":["Unreal","Paper2D","Flipbook","unreal_paper2d_pack","paper2dsprites","导入"],"translations":{"en":"https://animgen.com/docs/en/editing-and-export/unreal-paper2d","zh":"https://animgen.com/docs/zh/editing-and-export/unreal-paper2d"},"headings":[{"id":"导出配套资源包","title":"导出配套资源包","level":2},{"id":"导入描述文件-不只导入-png","title":"导入描述文件，不只导入 PNG","level":2},{"id":"对齐动画设置","title":"对齐动画设置","level":2},{"id":"检查透明边缘与补边","title":"检查透明边缘与补边","level":2},{"id":"重新生成前先排查","title":"重新生成前先排查","level":2}],"text":"导出配套资源包\n选择 unreal_paper2d_pack，检查报价和权益，再下载解压。保持 animation.paper2dsprites 与 spritesheet.png 相邻；包内还包含清单和 README。\n描述文件保存了明确帧矩形。纹理会补成 2 的幂尺寸，但原来的帧矩形位置不会移动。新增空白不是动画帧，不能通过补边后的纹理宽高直接推算帧数。\n导入描述文件，不只导入 PNG\n在当前 Unreal 安装中启用内置 Paper 2D 及其导入器支持，按提示重启编辑器。通过 Content Browser/Content Drawer 导入 animation.paper2dsprites。\nJSON 精灵图导入可以生成纹理、Sprite 和 Flipbook。如果当前流程只产生精灵，可按帧数字顺序选择后创建 Flipbook。操作参考 Epic 官方 Paper 2D Flipbooks 指南。\n只导入 PNG 不会自动还原包中的帧描述。AnimGen 通用精灵图 JSON 也不能代替 Paper2D 专用描述文件。\n对齐动画设置\n打开导入或新建的 Flipbook，按 animgen-manifest.json 核对精灵数量、顺序及 Frames Per Second。导入器默认 FPS 不一致时，要明确改为导出值。\n保留每帧应有的时长，并在实际使用 Flipbook 的组件或游戏逻辑中检查循环播放。本包提供精灵动画，不是骨骼网格或动画蓝图。\n添加碰撞与游戏逻辑前，先在简单场景中检查 pivot/原点和世界缩放。清单的 pivot 原点在左下角；导入器约定及项目中的后续修改都需要通过实际精灵确认。\n检查透明边缘与补边\n用原始 PNG 区分纹理数据问题和材质问题。按阈值裁切 Alpha 的材质，与混合 Alpha 的材质，对半透明边缘的显示不同。应在目标材质、排序和背景下检查代表性软边缘。\n不要裁掉 2 的幂补边后仍沿用旧描述文件。只显示部分帧时，应与原始资源包的矩形比较，而不是与缩放过的纹理或后续自动切片结果比较。\n重新生成前先排查\n描述文件无法识别时，检查导入器是否可用以及文件扩展名。播放太快时，检查 Flipbook FPS 和帧时长。整张图集显示成一个矩形时，确认是否真正导入了描述文件，而不只是图片。\n保留测试项目和原始 ZIP 便于对照。本指南遵循实际包结构和官方导入流程，你使用的引擎版本、插件与目标渲染器仍需运行时验收。详见导出排障。"},{"id":"getting-started.first-animation","locale":"zh","title":"在 Studio 制作第一个动画","description":"用约五分钟熟悉首次操作：上传图片、生成预览、选择有效片段，再下载可用于项目的动画素材。","section":"getting-started","path":"/docs/zh/getting-started/first-animation","url":"https://animgen.com/docs/zh/getting-started/first-animation","status":"stable","lastVerified":"2026-08-30","audience":["user","api-developer"],"productAreas":["studio"],"tags":["beginner","upload","preview","export"],"translations":{"en":"https://animgen.com/docs/en/getting-started/first-animation","zh":"https://animgen.com/docs/zh/getting-started/first-animation"},"headings":[{"id":"开始前准备","title":"开始前准备","level":2},{"id":"1-添加首帧图片","title":"1. 添加首帧图片","level":2},{"id":"2-选择背景处理模式","title":"2. 选择背景处理模式","level":2},{"id":"3-描述动作并确认费用","title":"3. 描述动作并确认费用","level":2},{"id":"4-检查结果","title":"4. 检查结果","level":2},{"id":"5-导出并下载","title":"5. 导出并下载","level":2},{"id":"接下来","title":"接下来","level":2}],"text":"开始前准备\n打开 Studio 并登录。准备一张你有权使用的图片，并确认账户积分足以支付页面显示的报价。只想先认识界面，可以使用交互演示。\n本教程的“五分钟”指操作准备时间。实际生成和导出耗时受模型、排队和处理选项影响，不保证五分钟内完成计算。\n1. 添加首帧图片\n在左侧面板选择或新建工作区，找到“首帧图片”。上传本地 PNG、JPEG 或 WebP，也可以选择已有图片资源。\n第一次建议使用主体清晰、四周留有动作空间的图片。避免脚、武器或翅膀贴边被裁掉：模型无法可靠保留画面以外的细节。先使用单张首帧；首尾帧和参考图是否可选，取决于当前模型。\n2. 选择背景处理模式\n普通图片动画：保留场景背景，适合普通图片。\n透明素材动画：当前参与生成的每张图片都必须具有有效 Alpha。画在不透明 PNG 上的棋盘格不是真透明。\n不确定时先选普通模式。制作透明游戏素材前，先读普通与透明动画。\n3. 描述动作并确认费用\n选择模型，再从界面提供的选项中设置时长、分辨率和画幅比例。不同模型能力不同，以当前可选项为准。\n可以从一个简单提示词开始：\n第一次不要同时要求多个动作、切换场景和复杂运镜，否则很难从结果中选出干净的循环。\n点击“生成预览”前，检查显示的积分费用。如果无法估算费用或余额不足，先解决原因，不要反复提交。\n4. 检查结果\n左侧项目面板会把源动画和对应导出放在一起。生成完成后，在右侧预览动作。\n检查动作是否合理、角色是否一致、边缘是否被截断。播放视频，在时间线上选择最干净的区间。重复播放选段用于检查循环，不会自动修复首尾姿态不一致的问题。\n5. 导出并下载\n设置选段、帧率和输出尺寸，然后点击“导出”。第一次可以选择 PNG 逐帧 ZIP；其他格式可能需要付费导出权益。\n确认格式、透明设置和导出费用，再点击一次“开始导出”。完成后，在左侧“当前片段的导出”中打开对应记录，下载所需资产。\n预览视频不等于完成导出。能播放视频，并不代表 PNG 序列或引擎包已经生成。\n接下来\n通过选段与导出学习帧数选择，通过输出格式挑选交付物。遇到功能锁定，查看积分与访问权益。\n生成或导出失败后，先检查已有结果，再决定是否重新付费提交。常见问题汇总了常见现象。"},{"id":"getting-started.overview","locale":"zh","title":"理解动画制作工作流","description":"区分生成动作与导出现有视频，选择合适的制作入口，并理解透明资产在哪一步产生。","section":"getting-started","path":"/docs/zh/getting-started/overview","url":"https://animgen.com/docs/zh/getting-started/overview","status":"stable","lastVerified":"2026-08-30","audience":["user"],"productAreas":["studio"],"tags":["工作流","生成","导出"],"translations":{"en":"https://animgen.com/docs/en/getting-started/overview","zh":"https://animgen.com/docs/zh/getting-started/overview"},"headings":[{"id":"开始前准备","title":"开始前准备","level":2},{"id":"生成与导出是两件事","title":"生成与导出是两件事","level":2},{"id":"选择合适的透明模式","title":"选择合适的透明模式","level":2},{"id":"检查结果","title":"检查结果","level":2},{"id":"无法继续时怎么办","title":"无法继续时怎么办","level":2}],"text":"开始前准备\n准备一张你有权使用的图片，或一段需要导出的视频。打开 Studio 并登录后即可创建真实任务。Demo 使用预先准备的示例，让你不消耗积分就能体验交互。\n生成与导出是两件事\n选择源图片，描述你希望产生的动作。\n使用账户中可选的模型与参数，生成视频预览。\n检查视频，选择有用片段的起点和终点。\n按套餐支持的格式，把选中动作导出为图片帧、精灵图、视频或引擎包。\n如果已经有视频，使用视频导入工作流，直接从检查和选段开始，无需重复生成已有动作。\n选择合适的透明模式\n源素材与目标\n工作流\n普通美术图片或不透明场景\n普通图片动画\n带有效 Alpha 的独立主体 PNG\n透明素材动画\n已有视频，需要帧或精灵图\n导入视频后导出\n透明素材动画会先生成包含键色背景的不透明预览，在导出时恢复 Alpha。绿色或洋红色的生成预览并不是最终透明交付文件。\n检查结果\n将导出资产放到不同底色上预览。开始批量制作前，确认动作范围、帧率、尺寸和透明度符合目标应用的要求。\n对于程序接入，同样遵循下面的顺序：\n无法继续时怎么办\n重试前先阅读任务显示的错误。检查模型是否支持所选输入、可用积分是否足够，以及账户是否拥有所需导出权益。后续阶段失败时，前一阶段的有用产物可能仍然保留。\n也可以了解当前的开放 API，或返回文档首页。"},{"id":"getting-started.workspaces-and-assets","locale":"zh","title":"管理工作区、任务与资源","description":"区分项目组织、任务历史和真实文件，复用自己的素材，并理解工作区删除与恢复究竟会影响什么。","section":"getting-started","path":"/docs/zh/getting-started/workspaces-and-assets","url":"https://animgen.com/docs/zh/getting-started/workspaces-and-assets","status":"stable","lastVerified":"2026-08-30","audience":["user","api-developer","ai-agent"],"productAreas":["studio","resources"],"tags":["workspace","asset","resource","job","工作区","资源","恢复"],"translations":{"en":"https://animgen.com/docs/en/getting-started/workspaces-and-assets","zh":"https://animgen.com/docs/zh/getting-started/workspaces-and-assets"},"headings":[{"id":"三类对象-生命周期不同","title":"三类对象，生命周期不同","level":2},{"id":"创建前先整理工作区","title":"创建前先整理工作区","level":2},{"id":"复用素材并区分产物","title":"复用素材并区分产物","level":2},{"id":"有意识地删除和恢复工作区","title":"有意识地删除和恢复工作区","level":2},{"id":"删除源文件前","title":"删除源文件前","level":2}],"text":"三类对象，生命周期不同\n对象\n表示什么\n工作区 Workspace\n组织 Studio 制作内容的方式\n任务 Task / Job\n一次异步生成、导入或导出操作\n资源 Resource / Asset\n上传的源文件或处理产生的文件\n一个完成任务可能产生多个资产；失败任务也可能已经产生可用源视频或部分输出。移除历史记录，不等于删除它关联的所有文件。\n创建前先整理工作区\n通过 Studio 的工作区控件创建、重命名、切换或删除工作区。可按项目或实验命名，便于查找。这是账户内的内容组织方式，不是多人团队权限系统。\n在某工作区创建的任务，不会因为切换界面而变成另一条任务。结果看似丢失时，先回到原工作区刷新任务库，不要直接再付费生成。\n复用素材并区分产物\n兼容的自有资源可直接作为输入，无需重复上传同一本地文件。已生成的视频可以用于多次导出。Advanced Editor 配方引用源视频，并没有独立复制每一帧。\n通过清楚的资源显示名区分原图、预览与最终产物。需要长期保留时，应下载真实文件，而不是只保存临时 URL。配套纹理与元数据要一起保存。\nAPI/MCP 调用方应私下保存任务 ID 和资产 ID。不要把显示名当作 API 标识，也不要默认返回数组第一项就是目标文件。\n有意识地删除和恢复工作区\n删除工作区会隐藏内容，并对其中活跃任务请求取消。排队任务可能很快取消，运行中任务则尽力取消；删除不保证完全不收费。\n使用工作区恢复入口选择已删除工作区，可以重新访问仍保留的内容；但不会自动恢复已取消任务、找回单独删除的文件或撤销已经发生的消费。\n删除工作区不是存储清理操作。只要上传和资产本身没被删除，仍计入空间。为腾空间而误删工作区时，先恢复工作区，再检查资源。\n删除源文件前\n先下载重要结果，检查活跃任务，也检查可能仍依赖该来源的编辑配方和后续导出。活跃任务可能阻止资源删除，但已完成任务之后的编辑配方仍可能继续依赖源文件。\n存储与清理解释删除任务与删除文件的区别。需要协助定位结果时，可私下向支持提供任务 ID 和时间，不要在公开反馈中发布签名链接或凭据。"},{"id":"mcp-reference.index","locale":"zh","title":"MCP 工具参考","description":"从注册 MCP 工具生成参数、返回结构、OAuth 权限、副作用、支出保护与经过核实的开放状态。","section":"mcp-reference","path":"/docs/zh/mcp-reference","url":"https://animgen.com/docs/zh/mcp-reference","status":"beta","lastVerified":"2026-08-30","audience":["api-developer","ai-agent"],"productAreas":["mcp"],"tags":["reference","MCP","index"],"translations":{"en":"https://animgen.com/docs/en/mcp-reference","zh":"https://animgen.com/docs/zh/mcp-reference"},"headings":[{"id":"开放状态与工作流","title":"开放状态与工作流","level":2},{"id":"工具列表","title":"工具列表","level":2}],"text":"本页由后端契约生成。字段、必填项、约束和默认值来自源码模型。下载机器可读来源。示例 ID 与数值均为占位说明，不代表实时价格、限额或模型可用性。\n开放状态与工作流\n官方 MCP 已开放公开测试，端点为 https://api.animgen.com/mcp。使用 Streamable HTTP 与 OAuth，需要已验证的 AnimGen 账户；订阅提高限额，建立连接不等于批准消费。\n开放状态与快速开始 · 标准工作流\n工具列表\n工具\n权限\n用途\nlist_models\nmodels:read\n查询当前启用模型、合法参数、默认值与输入能力，不启动生成。\nprepare_image_upload\nfiles:write\n创建短期上传会话；客户端按返回的方法和请求头上传准确字节，再完成上传。本地路径不能替代文件传输。\ncomplete_image_upload\nfiles:write\n校验已传输的图片并返回可复用 file_id；此 ID 用于生成输入。\nquote_animation\nanimations:write\n计算当前费用并创建属于当前用户和 OAuth 客户端的短期 quote_id，不启动生成或扣费。\ngenerate_animation\nanimations:write\n启动付费异步动画，必须有用户批准的 quote_id 或 max_credits，并保存幂等键。两个支出字段与 request 同级；生成开始后可能扣费。\nget_animation\nanimations:read\n查询状态、进度、积分、错误和已有资产；失败或取消也要检查 outputs。\ndownload_asset\nassets:read\n返回所属资产信息和短期签名 URL，不自动保存本地文件；下载不携带 API 或 OAuth 凭据。\ncancel_animation\nanimations:write\n尽力取消所属任务，可能仍需轮询；已扣积分不自动退回，先前产物可能保留。\n共享数据结构"},{"id":"mcp-reference.cancel-animation","locale":"zh","title":"取消动画任务","description":"从真实 cancel_animation 工具生成输入、输出、OAuth 权限与安全注解，与经过核实的 MCP 契约保持一致。","section":"mcp-reference","path":"/docs/zh/mcp-reference/cancel-animation","url":"https://animgen.com/docs/zh/mcp-reference/cancel-animation","status":"beta","lastVerified":"2026-08-30","audience":["api-developer","ai-agent"],"productAreas":["mcp"],"tags":["reference","MCP","cancel-animation","animation_id"],"translations":{"en":"https://animgen.com/docs/en/mcp-reference/cancel-animation","zh":"https://animgen.com/docs/zh/mcp-reference/cancel-animation"},"headings":[{"id":"工具","title":"工具","level":2},{"id":"权限与安全","title":"权限与安全","level":2},{"id":"输入参数","title":"输入参数","level":2},{"id":"参数示例","title":"参数示例","level":3},{"id":"结构化返回","title":"结构化返回","level":2},{"id":"错误与后续步骤","title":"错误与后续步骤","level":2}],"text":"本页由后端契约生成。字段、必填项、约束和默认值来自源码模型。下载机器可读来源。示例 ID 与数值均为占位说明，不代表实时价格、限额或模型可用性。\n工具\ncancel_animation\n尽力取消所属任务，可能仍需轮询；已扣积分不自动退回，先前产物可能保留。\n权限与安全\nOAuth 权限：animations:write\n信号\n值\ndestructiveHint\ntrue\nidempotentHint\ntrue\nopenWorldHint\nfalse\nreadOnlyHint\nfalse\nspendsCredits\nfalse\nrequiresUserConfirmation\ntrue\nsideEffects\ncancellation_requested\n注解用于描述安全属性，不能替代用户批准、OAuth 授权或服务端校验。\n输入参数\n字段\n类型\n必填\n默认值\n约束\n含义\nanimation_id\nstring\n是\n—\nformat: uuid\n用户要求取消的所属任务 ID。\n参数示例\n结构化返回\n字段\n类型\n必填\n默认值\n约束\n含义\ncreated_at\nstring\n是\n—\nformat: date-time\n任务被接受的 UTC 时间。\ncredits\nCreditUsage\n是\n—\n—\n报价、预占及已扣积分状态。\nerror\nTaskError / null\n否\nnull\n—\n任务失败信息，与是否存在可用产物分别判断。\nfinished_at\nstring / null\n否\nnull\nformat: date-time\n已知时返回 UTC 终态时间。\nid\nstring\n是\n—\nformat: uuid\n创建后立即保存任务 ID，通过它轮询，不要再次创建。\nmetadata\nobject\n否\n{}\n—\n调用方提供的元数据。\nnormalized_input\nobject\n否\n{}\n—\n规范化公共输入，可能含私有提示词或图片引用，不要整体写入日志。\nobject\nstring\n是\n—\nenum: \"video_generation\", \"animation_export\", \"animation\"\n公共任务资源类型。\noutputs\narray<AssetResponse>\n否\n[]\n—\n可用资产，失败或取消也可能有部分产物；所有终态都应检查。\nprogress\nnumber\n是\n—\nminimum: 0; maximum: 1\n0 至 1 的进度值，不代表精确完成时间。\nstage\nstring / null\n否\nnull\nenum: \"queued\", \"video_generation\", \"animation_export\", \"completed\"\n可用时显示当前流水线阶段。\nstarted_at\nstring / null\n否\nnull\nformat: date-time\n已知时返回 UTC 生产开始时间。\nstatus\nstring\n是\n—\nenum: \"queued\", \"running\", \"cancelling\", \"succeeded\", \"failed\", \"cancelled\"\nsucceeded、failed、cancelled 为终态；cancelling 不是终态。\nTaskResponse\n错误与后续步骤\n工具错误包含 error 对象，内有 code、message、retryable、request_id 和 details。不要依赖消息文本分支或泄露私有输入。终态失败也要检查部分产物；返回签名 URL 不代表已保存文件。\n标准工作流 · 支出保护"},{"id":"mcp-reference.complete-image-upload","locale":"zh","title":"完成图片上传","description":"从真实 complete_image_upload 工具生成输入、输出、OAuth 权限与安全注解，与经过核实的 MCP 契约保持一致。","section":"mcp-reference","path":"/docs/zh/mcp-reference/complete-image-upload","url":"https://animgen.com/docs/zh/mcp-reference/complete-image-upload","status":"beta","lastVerified":"2026-08-30","audience":["api-developer","ai-agent"],"productAreas":["mcp"],"tags":["reference","MCP","complete-image-upload","upload_id"],"translations":{"en":"https://animgen.com/docs/en/mcp-reference/complete-image-upload","zh":"https://animgen.com/docs/zh/mcp-reference/complete-image-upload"},"headings":[{"id":"工具","title":"工具","level":2},{"id":"权限与安全","title":"权限与安全","level":2},{"id":"输入参数","title":"输入参数","level":2},{"id":"参数示例","title":"参数示例","level":3},{"id":"结构化返回","title":"结构化返回","level":2},{"id":"错误与后续步骤","title":"错误与后续步骤","level":2}],"text":"本页由后端契约生成。字段、必填项、约束和默认值来自源码模型。下载机器可读来源。示例 ID 与数值均为占位说明，不代表实时价格、限额或模型可用性。\n工具\ncomplete_image_upload\n校验已传输的图片并返回可复用 file_id；此 ID 用于生成输入。\n权限与安全\nOAuth 权限：files:write\n信号\n值\ndestructiveHint\nfalse\nidempotentHint\ntrue\nopenWorldHint\nfalse\nreadOnlyHint\nfalse\nspendsCredits\nfalse\nrequiresUserConfirmation\nfalse\nsideEffects\nuploaded_image_persisted\n注解用于描述安全属性，不能替代用户批准、OAuth 授权或服务端校验。\n输入参数\n字段\n类型\n必填\n默认值\n约束\n含义\nupload_id\nstring\n是\n—\nformat: uuid\n实际字节传输完成后，传入 prepare_image_upload 返回的会话 ID。\n参数示例\n结构化返回\n字段\n类型\n必填\n默认值\n约束\n含义\nbyte_size\ninteger\n是\n—\n—\n校验后的图片字节数。\nfile_id\nstring\n是\n—\nformat: uuid\n用于 request.input.first_frame 的可复用所属公共文件 ID。\nmime_type\nstring\n是\n—\n—\n校验后的图片 MIME 类型。\nsha256\nstring\n是\n—\n—\n上传图片字节的 SHA-256。\nMcpUploadCompleteOutput\n错误与后续步骤\n工具错误包含 error 对象，内有 code、message、retryable、request_id 和 details。不要依赖消息文本分支或泄露私有输入。终态失败也要检查部分产物；返回签名 URL 不代表已保存文件。\n标准工作流 · 支出保护"},{"id":"mcp-reference.download-asset","locale":"zh","title":"获取资产下载信息","description":"从真实 download_asset 工具生成输入、输出、OAuth 权限与安全注解，与经过核实的 MCP 契约保持一致。","section":"mcp-reference","path":"/docs/zh/mcp-reference/download-asset","url":"https://animgen.com/docs/zh/mcp-reference/download-asset","status":"beta","lastVerified":"2026-08-30","audience":["api-developer","ai-agent"],"productAreas":["mcp"],"tags":["reference","MCP","download-asset","asset_id"],"translations":{"en":"https://animgen.com/docs/en/mcp-reference/download-asset","zh":"https://animgen.com/docs/zh/mcp-reference/download-asset"},"headings":[{"id":"工具","title":"工具","level":2},{"id":"权限与安全","title":"权限与安全","level":2},{"id":"输入参数","title":"输入参数","level":2},{"id":"参数示例","title":"参数示例","level":3},{"id":"结构化返回","title":"结构化返回","level":2},{"id":"错误与后续步骤","title":"错误与后续步骤","level":2}],"text":"本页由后端契约生成。字段、必填项、约束和默认值来自源码模型。下载机器可读来源。示例 ID 与数值均为占位说明，不代表实时价格、限额或模型可用性。\n工具\ndownload_asset\n返回所属资产信息和短期签名 URL，不自动保存本地文件；下载不携带 API 或 OAuth 凭据。\n权限与安全\nOAuth 权限：assets:read\n信号\n值\ndestructiveHint\nfalse\nidempotentHint\ntrue\nopenWorldHint\nfalse\nreadOnlyHint\ntrue\nspendsCredits\nfalse\nrequiresUserConfirmation\nfalse\nsideEffects\nsigned_url_issued\n注解用于描述安全属性，不能替代用户批准、OAuth 授权或服务端校验。\n输入参数\n字段\n类型\n必填\n默认值\n约束\n含义\nasset_id\nstring\n是\n—\nformat: uuid\n任务 outputs 中的所属资产 ID，不是任务 ID。\n参数示例\n结构化返回\n字段\n类型\n必填\n默认值\n约束\n含义\nbyte_size\ninteger\n是\n—\n—\n文件预期字节数。\ncreated_at\nstring\n是\n—\nformat: date-time\nUTC 创建时间。\ndownload_expires_at\nstring\n是\n—\nformat: date-time\n签名 URL 的 UTC 过期时间；过期后重新查询资产。\ndownload_url\nstring\n是\n—\n—\n敏感短期签名 URL；下载及跳转时均不携带 Bearer 头，不记录此 URL。\nformat\nstring\n是\n—\n—\n实际资产格式，不要依赖 outputs 固定顺序。\nid\nstring\n是\n—\nformat: uuid\n稳定公共资产 ID，用于刷新下载信息。\nmime_type\nstring\n是\n—\n—\n资产媒体类型。\nobject\nstring\n否\n\"asset\"\nconst: \"asset\"\n—\nAssetResponse\n错误与后续步骤\n工具错误包含 error 对象，内有 code、message、retryable、request_id 和 details。不要依赖消息文本分支或泄露私有输入。终态失败也要检查部分产物；返回签名 URL 不代表已保存文件。\n标准工作流 · 支出保护"},{"id":"mcp-reference.generate-animation","locale":"zh","title":"生成动画","description":"从真实 generate_animation 工具生成输入、输出、OAuth 权限与安全注解，与经过核实的 MCP 契约保持一致。","section":"mcp-reference","path":"/docs/zh/mcp-reference/generate-animation","url":"https://animgen.com/docs/zh/mcp-reference/generate-animation","status":"beta","lastVerified":"2026-08-30","audience":["api-developer","ai-agent"],"productAreas":["mcp"],"tags":["reference","MCP","generate-animation","idempotency_key","max_credits","quote_id","request"],"translations":{"en":"https://animgen.com/docs/en/mcp-reference/generate-animation","zh":"https://animgen.com/docs/zh/mcp-reference/generate-animation"},"headings":[{"id":"工具","title":"工具","level":2},{"id":"权限与安全","title":"权限与安全","level":2},{"id":"输入参数","title":"输入参数","level":2},{"id":"参数示例","title":"参数示例","level":3},{"id":"结构化返回","title":"结构化返回","level":2},{"id":"错误与后续步骤","title":"错误与后续步骤","level":2}],"text":"本页由后端契约生成。字段、必填项、约束和默认值来自源码模型。下载机器可读来源。示例 ID 与数值均为占位说明，不代表实时价格、限额或模型可用性。\n工具\ngenerate_animation\n启动付费异步动画，必须有用户批准的 quote_id 或 max_credits，并保存幂等键。两个支出字段与 request 同级；生成开始后可能扣费。\n权限与安全\nOAuth 权限：animations:write\n信号\n值\ndestructiveHint\ntrue\nidempotentHint\ntrue\nopenWorldHint\ntrue\nreadOnlyHint\nfalse\nspendsCredits\ntrue\nrequiresUserConfirmation\ntrue\nsideEffects\ngeneration_started, credits_reserved_or_charged\n注解用于描述安全属性，不能替代用户批准、OAuth 授权或服务端校验。\nquote_id 与 max_credits 至少提供一个，二者与 request 同级。先取得明确批准，不得擅自提高上限。重试保持同一用户、OAuth 客户端、幂等键与请求。\n输入参数\n字段\n类型\n必填\n默认值\n约束\n含义\nidempotency_key\nstring\n是\n—\nminLength: 8; maxLength: 200\n每次逻辑生成保存一个键；超时后以同一用户及 OAuth 客户端复用。\nmax_credits\ninteger / null\n否\nnull\nminimum: 0\n用户批准的单次积分上限，不得擅自提高，也不是多任务总预算。\nquote_id\nstring / null\n否\nnull\nformat: uuid\n新鲜且已批准的报价；quote_id 与 max_credits 至少一个，可同时提供。\nrequest\nAnimationCreateRequest\n是\n—\n—\n用户批准的完整请求，重试时保持不变。\n参数示例\n结构化返回\n字段\n类型\n必填\n默认值\n约束\n含义\ncreated_at\nstring\n是\n—\nformat: date-time\n任务被接受的 UTC 时间。\ncredits\nCreditUsage\n是\n—\n—\n报价、预占及已扣积分状态。\nerror\nTaskError / null\n否\nnull\n—\n任务失败信息，与是否存在可用产物分别判断。\nfinished_at\nstring / null\n否\nnull\nformat: date-time\n已知时返回 UTC 终态时间。\nid\nstring\n是\n—\nformat: uuid\n创建后立即保存任务 ID，通过它轮询，不要再次创建。\nmetadata\nobject\n否\n{}\n—\n调用方提供的元数据。\nnormalized_input\nobject\n否\n{}\n—\n规范化公共输入，可能含私有提示词或图片引用，不要整体写入日志。\nobject\nstring\n是\n—\nenum: \"video_generation\", \"animation_export\", \"animation\"\n公共任务资源类型。\noutputs\narray<AssetResponse>\n否\n[]\n—\n可用资产，失败或取消也可能有部分产物；所有终态都应检查。\nprogress\nnumber\n是\n—\nminimum: 0; maximum: 1\n0 至 1 的进度值，不代表精确完成时间。\nstage\nstring / null\n否\nnull\nenum: \"queued\", \"video_generation\", \"animation_export\", \"completed\"\n可用时显示当前流水线阶段。\nstarted_at\nstring / null\n否\nnull\nformat: date-time\n已知时返回 UTC 生产开始时间。\nstatus\nstring\n是\n—\nenum: \"queued\", \"running\", \"cancelling\", \"succeeded\", \"failed\", \"cancelled\"\nsucceeded、failed、cancelled 为终态；cancelling 不是终态。\nTaskResponse\n错误与后续步骤\n工具错误包含 error 对象，内有 code、message、retryable、request_id 和 details。不要依赖消息文本分支或泄露私有输入。终态失败也要检查部分产物；返回签名 URL 不代表已保存文件。\n标准工作流 · 支出保护"},{"id":"mcp-reference.get-animation","locale":"zh","title":"查询动画任务","description":"从真实 get_animation 工具生成输入、输出、OAuth 权限与安全注解，与经过核实的 MCP 契约保持一致。","section":"mcp-reference","path":"/docs/zh/mcp-reference/get-animation","url":"https://animgen.com/docs/zh/mcp-reference/get-animation","status":"beta","lastVerified":"2026-08-30","audience":["api-developer","ai-agent"],"productAreas":["mcp"],"tags":["reference","MCP","get-animation","animation_id"],"translations":{"en":"https://animgen.com/docs/en/mcp-reference/get-animation","zh":"https://animgen.com/docs/zh/mcp-reference/get-animation"},"headings":[{"id":"工具","title":"工具","level":2},{"id":"权限与安全","title":"权限与安全","level":2},{"id":"输入参数","title":"输入参数","level":2},{"id":"参数示例","title":"参数示例","level":3},{"id":"结构化返回","title":"结构化返回","level":2},{"id":"错误与后续步骤","title":"错误与后续步骤","level":2}],"text":"本页由后端契约生成。字段、必填项、约束和默认值来自源码模型。下载机器可读来源。示例 ID 与数值均为占位说明，不代表实时价格、限额或模型可用性。\n工具\nget_animation\n查询状态、进度、积分、错误和已有资产；失败或取消也要检查 outputs。\n权限与安全\nOAuth 权限：animations:read\n信号\n值\ndestructiveHint\nfalse\nidempotentHint\ntrue\nopenWorldHint\nfalse\nreadOnlyHint\ntrue\nspendsCredits\nfalse\nrequiresUserConfirmation\nfalse\nsideEffects\n—\n注解用于描述安全属性，不能替代用户批准、OAuth 授权或服务端校验。\n输入参数\n字段\n类型\n必填\n默认值\n约束\n含义\nanimation_id\nstring\n是\n—\nformat: uuid\ngenerate_animation 返回的所属任务 ID。\n参数示例\n结构化返回\n字段\n类型\n必填\n默认值\n约束\n含义\ncreated_at\nstring\n是\n—\nformat: date-time\n任务被接受的 UTC 时间。\ncredits\nCreditUsage\n是\n—\n—\n报价、预占及已扣积分状态。\nerror\nTaskError / null\n否\nnull\n—\n任务失败信息，与是否存在可用产物分别判断。\nfinished_at\nstring / null\n否\nnull\nformat: date-time\n已知时返回 UTC 终态时间。\nid\nstring\n是\n—\nformat: uuid\n创建后立即保存任务 ID，通过它轮询，不要再次创建。\nmetadata\nobject\n否\n{}\n—\n调用方提供的元数据。\nnormalized_input\nobject\n否\n{}\n—\n规范化公共输入，可能含私有提示词或图片引用，不要整体写入日志。\nobject\nstring\n是\n—\nenum: \"video_generation\", \"animation_export\", \"animation\"\n公共任务资源类型。\noutputs\narray<AssetResponse>\n否\n[]\n—\n可用资产，失败或取消也可能有部分产物；所有终态都应检查。\nprogress\nnumber\n是\n—\nminimum: 0; maximum: 1\n0 至 1 的进度值，不代表精确完成时间。\nstage\nstring / null\n否\nnull\nenum: \"queued\", \"video_generation\", \"animation_export\", \"completed\"\n可用时显示当前流水线阶段。\nstarted_at\nstring / null\n否\nnull\nformat: date-time\n已知时返回 UTC 生产开始时间。\nstatus\nstring\n是\n—\nenum: \"queued\", \"running\", \"cancelling\", \"succeeded\", \"failed\", \"cancelled\"\nsucceeded、failed、cancelled 为终态；cancelling 不是终态。\nTaskResponse\n错误与后续步骤\n工具错误包含 error 对象，内有 code、message、retryable、request_id 和 details。不要依赖消息文本分支或泄露私有输入。终态失败也要检查部分产物；返回签名 URL 不代表已保存文件。\n标准工作流 · 支出保护"},{"id":"mcp-reference.list-models","locale":"zh","title":"发现动画模型","description":"从真实 list_models 工具生成输入、输出、OAuth 权限与安全注解，与经过核实的 MCP 契约保持一致。","section":"mcp-reference","path":"/docs/zh/mcp-reference/list-models","url":"https://animgen.com/docs/zh/mcp-reference/list-models","status":"beta","lastVerified":"2026-08-30","audience":["api-developer","ai-agent"],"productAreas":["mcp"],"tags":["reference","MCP","list-models"],"translations":{"en":"https://animgen.com/docs/en/mcp-reference/list-models","zh":"https://animgen.com/docs/zh/mcp-reference/list-models"},"headings":[{"id":"工具","title":"工具","level":2},{"id":"权限与安全","title":"权限与安全","level":2},{"id":"输入参数","title":"输入参数","level":2},{"id":"参数示例","title":"参数示例","level":3},{"id":"结构化返回","title":"结构化返回","level":2},{"id":"错误与后续步骤","title":"错误与后续步骤","level":2}],"text":"本页由后端契约生成。字段、必填项、约束和默认值来自源码模型。下载机器可读来源。示例 ID 与数值均为占位说明，不代表实时价格、限额或模型可用性。\n工具\nlist_models\n查询当前启用模型、合法参数、默认值与输入能力，不启动生成。\n权限与安全\nOAuth 权限：models:read\n信号\n值\ndestructiveHint\nfalse\nidempotentHint\ntrue\nopenWorldHint\nfalse\nreadOnlyHint\ntrue\nspendsCredits\nfalse\nrequiresUserConfirmation\nfalse\nsideEffects\n—\n注解用于描述安全属性，不能替代用户批准、OAuth 授权或服务端校验。\n输入参数\n不需要参数，发送空对象：{}。\n参数示例\n结构化返回\n字段\n类型\n必填\n默认值\n约束\n含义\ndata\narray<ModelCapabilities>\n是\n—\n—\n当前启用的模型，客户端不要写死此清单。\nobject\nstring\n否\n\"list\"\nconst: \"list\"\n—\nModelsResponse\n错误与后续步骤\n工具错误包含 error 对象，内有 code、message、retryable、request_id 和 details。不要依赖消息文本分支或泄露私有输入。终态失败也要检查部分产物；返回签名 URL 不代表已保存文件。\n标准工作流 · 支出保护"},{"id":"mcp-reference.prepare-image-upload","locale":"zh","title":"准备图片上传","description":"从真实 prepare_image_upload 工具生成输入、输出、OAuth 权限与安全注解，与经过核实的 MCP 契约保持一致。","section":"mcp-reference","path":"/docs/zh/mcp-reference/prepare-image-upload","url":"https://animgen.com/docs/zh/mcp-reference/prepare-image-upload","status":"beta","lastVerified":"2026-08-30","audience":["api-developer","ai-agent"],"productAreas":["mcp"],"tags":["reference","MCP","prepare-image-upload","byte_size","filename","mime_type"],"translations":{"en":"https://animgen.com/docs/en/mcp-reference/prepare-image-upload","zh":"https://animgen.com/docs/zh/mcp-reference/prepare-image-upload"},"headings":[{"id":"工具","title":"工具","level":2},{"id":"权限与安全","title":"权限与安全","level":2},{"id":"输入参数","title":"输入参数","level":2},{"id":"参数示例","title":"参数示例","level":3},{"id":"结构化返回","title":"结构化返回","level":2},{"id":"错误与后续步骤","title":"错误与后续步骤","level":2}],"text":"本页由后端契约生成。字段、必填项、约束和默认值来自源码模型。下载机器可读来源。示例 ID 与数值均为占位说明，不代表实时价格、限额或模型可用性。\n工具\nprepare_image_upload\n创建短期上传会话；客户端按返回的方法和请求头上传准确字节，再完成上传。本地路径不能替代文件传输。\n权限与安全\nOAuth 权限：files:write\n信号\n值\ndestructiveHint\nfalse\nidempotentHint\nfalse\nopenWorldHint\ntrue\nreadOnlyHint\nfalse\nspendsCredits\nfalse\nrequiresUserConfirmation\nfalse\nsideEffects\ntemporary_upload_created\n注解用于描述安全属性，不能替代用户批准、OAuth 授权或服务端校验。\n输入参数\n字段\n类型\n必填\n默认值\n约束\n含义\nbyte_size\ninteger\n是\n—\nexclusiveMinimum: 0\n客户端将通过 PUT 发送的准确字节数。\nfilename\nstring\n是\n—\nminLength: 1; maxLength: 240\n客户端文件名，不是服务端可以读取的本地路径。\nmime_type\nstring\n是\n—\npattern: ^image/(png|jpeg|webp)$\n图片实际 MIME 类型。\n参数示例\n结构化返回\n字段\n类型\n必填\n默认值\n约束\n含义\nexpires_at\nstring\n是\n—\nformat: date-time\n上传 URL 过期时间。\nheaders\nobject\n是\n—\n—\n实际传输请求头，不额外添加 MCP Token 或 API Bearer 凭据。\nmax_bytes\ninteger\n是\n—\n—\n允许上传的最大字节数。\nmethod\nstring\n否\n\"PUT\"\nconst: \"PUT\"\n客户端传输字节时必须使用的 HTTP 方法。\nupload_id\nstring\n是\n—\nformat: uuid\n传给 complete_image_upload 的上传会话 ID，不是最终 file_id。\nupload_url\nstring\n是\n—\n—\n敏感短期上传 URL，需传输实际字节，不公开此地址。\nMcpUploadPrepareOutput\n错误与后续步骤\n工具错误包含 error 对象，内有 code、message、retryable、request_id 和 details。不要依赖消息文本分支或泄露私有输入。终态失败也要检查部分产物；返回签名 URL 不代表已保存文件。\n标准工作流 · 支出保护"},{"id":"mcp-reference.quote-animation","locale":"zh","title":"查询动画报价","description":"从真实 quote_animation 工具生成输入、输出、OAuth 权限与安全注解，与经过核实的 MCP 契约保持一致。","section":"mcp-reference","path":"/docs/zh/mcp-reference/quote-animation","url":"https://animgen.com/docs/zh/mcp-reference/quote-animation","status":"beta","lastVerified":"2026-08-30","audience":["api-developer","ai-agent"],"productAreas":["mcp"],"tags":["reference","MCP","quote-animation","request"],"translations":{"en":"https://animgen.com/docs/en/mcp-reference/quote-animation","zh":"https://animgen.com/docs/zh/mcp-reference/quote-animation"},"headings":[{"id":"工具","title":"工具","level":2},{"id":"权限与安全","title":"权限与安全","level":2},{"id":"输入参数","title":"输入参数","level":2},{"id":"参数示例","title":"参数示例","level":3},{"id":"结构化返回","title":"结构化返回","level":2},{"id":"错误与后续步骤","title":"错误与后续步骤","level":2}],"text":"本页由后端契约生成。字段、必填项、约束和默认值来自源码模型。下载机器可读来源。示例 ID 与数值均为占位说明，不代表实时价格、限额或模型可用性。\n工具\nquote_animation\n计算当前费用并创建属于当前用户和 OAuth 客户端的短期 quote_id，不启动生成或扣费。\n权限与安全\nOAuth 权限：animations:write\n信号\n值\ndestructiveHint\nfalse\nidempotentHint\nfalse\nopenWorldHint\nfalse\nreadOnlyHint\ntrue\nspendsCredits\nfalse\nrequiresUserConfirmation\nfalse\nsideEffects\ntemporary_quote_created\n注解用于描述安全属性，不能替代用户批准、OAuth 授权或服务端校验。\n输入参数\n字段\n类型\n必填\n默认值\n约束\n含义\nrequest\nAnimationCreateRequest\n是\n—\n—\n计划生成的完整请求，报价不启动生成。\n参数示例\n结构化返回\n字段\n类型\n必填\n默认值\n约束\n含义\nbreakdown\nobject\n是\n—\n—\n公开费用组成。\ncredits\ninteger\n是\n—\n—\n报价积分，生成前需向用户展示。\nexpires_at\nstring\n是\n—\nformat: date-time\n报价过期时间；过期或变价时重新报价并确认。\nquote_id\nstring\n是\n—\nformat: uuid\n属于当前用户和 OAuth 客户端的短期报价，可绑定一次逻辑生成键。\nMcpQuoteOutput\n错误与后续步骤\n工具错误包含 error 对象，内有 code、message、retryable、request_id 和 details。不要依赖消息文本分支或泄露私有输入。终态失败也要检查部分产物；返回签名 URL 不代表已保存文件。\n标准工作流 · 支出保护"},{"id":"mcp-reference.schemas","locale":"zh","title":"共享字段与数据结构","description":"从后端源码生成共享字段、嵌套类型、默认值、必填项与约束，避免在文档中维护第二份参数定义。","section":"mcp-reference","path":"/docs/zh/mcp-reference/schemas","url":"https://animgen.com/docs/zh/mcp-reference/schemas","status":"beta","lastVerified":"2026-08-30","audience":["api-developer","ai-agent"],"productAreas":["mcp"],"tags":["reference","MCP","schemas"],"translations":{"en":"https://animgen.com/docs/en/mcp-reference/schemas","zh":"https://animgen.com/docs/zh/mcp-reference/schemas"},"headings":[{"id":"animationcreaterequest","title":"AnimationCreateRequest","level":2},{"id":"assetresponse","title":"AssetResponse","level":2},{"id":"base64imageinput","title":"Base64ImageInput","level":2},{"id":"creditusage","title":"CreditUsage","level":2},{"id":"exportoptions","title":"ExportOptions","level":2},{"id":"exporttransparency","title":"ExportTransparency","level":2},{"id":"fileimageinput","title":"FileImageInput","level":2},{"id":"generationinput","title":"GenerationInput","level":2},{"id":"generationtransparency","title":"GenerationTransparency","level":2},{"id":"inputcanvasoptions","title":"InputCanvasOptions","level":2},{"id":"mcpquoteoutput","title":"McpQuoteOutput","level":2},{"id":"mcpuploadcompleteoutput","title":"McpUploadCompleteOutput","level":2},{"id":"mcpuploadprepareoutput","title":"McpUploadPrepareOutput","level":2},{"id":"modelcapabilities","title":"ModelCapabilities","level":2},{"id":"modelsresponse","title":"ModelsResponse","level":2},{"id":"selection","title":"Selection","level":2},{"id":"taskerror","title":"TaskError","level":2},{"id":"taskresponse","title":"TaskResponse","level":2},{"id":"unityoptions","title":"UnityOptions","level":2},{"id":"urlimageinput","title":"UrlImageInput","level":2},{"id":"videooptions","title":"VideoOptions","level":2}],"text":"本页由后端契约生成。字段、必填项、约束和默认值来自源码模型。下载机器可读来源。示例 ID 与数值均为占位说明，不代表实时价格、限额或模型可用性。\n“—”表示没有声明默认值，不等于 null。字段在 JSON Schema 中可选，仍可能受工作流的条件必填限制。模型专属选项仍需查询实时能力。\nAnimationCreateRequest\n禁止未声明的字段。\n字段\n类型\n必填\n默认值\n约束\n含义\nexport\nExportOptions\n否\n{\"frame_count\":24,\"output_formats\":[\"spritesheet\"],\"output_height\":512,\"output_width\":512,\"transparent\":{\"enabled\":false},\"unity\":{\"pivot\":\"bottom_center\",\"pixels_per_unit\":100}}\n—\n视频生成后执行导出；带 Alpha 的格式要求 alpha_key 来源，适配格式会自动启用其透明处理。\ninput\nGenerationInput\n是\n—\n—\n调用方所属或本次提供的生成图片。\nmetadata\nobject\n否\n{}\n—\n调用方元数据，仅字符串、数字、布尔或 null；JSON 不超过 4 KiB，不存凭据。\nnegative_prompt\nstring\n否\n\"\"\nmaxLength: 4000\n可选负向提示词，仅适用于支持的模型。\nprompt\nstring\n否\n\"\"\nmaxLength: 8000\n动作提示词；模型要求时不能为空，私有提示词不得写入日志。\nselection\nSelection\n否\n{\"duration_seconds\":null,\"mode\":\"full\",\"start_seconds\":0}\n—\n生成后选取的区间，默认完整视频。\nvideo\nVideoOptions\n否\n{\"duration_seconds\":null,\"input_canvas\":null,\"model\":null,\"ratio\":null,\"resolution\":null,\"seed\":null,\"style_preset\":null,\"transparency\":{\"key_color\":null,\"key_selection\":\"auto\",\"mode\":\"standard\"},\"watermark\":null}\n—\n符合模型能力的生成设置。\nAssetResponse\n禁止未声明的字段。\n字段\n类型\n必填\n默认值\n约束\n含义\nbyte_size\ninteger\n是\n—\n—\n文件预期字节数。\ncreated_at\nstring\n是\n—\nformat: date-time\nUTC 创建时间。\ndownload_expires_at\nstring\n是\n—\nformat: date-time\n签名 URL 的 UTC 过期时间；过期后重新查询资产。\ndownload_url\nstring\n是\n—\n—\n敏感短期签名 URL；下载及跳转时均不携带 Bearer 头，不记录此 URL。\nformat\nstring\n是\n—\n—\n实际资产格式，不要依赖 outputs 固定顺序。\nid\nstring\n是\n—\nformat: uuid\n稳定公共资产 ID，用于刷新下载信息。\nmime_type\nstring\n是\n—\n—\n资产媒体类型。\nobject\nstring\n否\n\"asset\"\nconst: \"asset\"\n—\nBase64ImageInput\n禁止未声明的字段。\n字段\n类型\n必填\n默认值\n约束\n含义\ndata\nstring\n是\n—\nminLength: 4\n纯 Base64，不含 data URL 前缀；解码后单张 10 MiB、合计 20 MiB。\nmedia_type\nstring\n是\n—\nenum: \"image/png\", \"image/jpeg\", \"image/webp\"\n图片实际 MIME 类型。\ntype\nstring\n是\n—\nconst: \"base64\"\n—\nCreditUsage\n禁止未声明的字段。\n字段\n类型\n必填\n默认值\n约束\n含义\ncharged\ninteger\n是\n—\n—\n最终净扣费积分。供应商明确审核拒绝会退分，取消本身不代表退款。\nheld\ninteger\n是\n—\n—\n当前预占积分，不应与 charged 相加当作扣费。\nquoted\ninteger\n是\n—\n—\n报价总额，不一定等于最终扣费。\nrefunded\ninteger\n否\n0\n—\n扣费后退回的积分，已从 charged 中扣除，不是现金退款。\nreleased\ninteger\n否\n0\n—\n尚未确认扣费即释放的积分。\nstatus\nstring / null\n否\nnull\n—\n积分状态：held、charged、released、refunded，内部子任务可为 managed。\nExportOptions\n禁止未声明的字段。\n字段\n类型\n必填\n默认值\n约束\n含义\nframe_count\ninteger\n否\n24\nminimum: 1; maximum: 240\n在选段内采样的帧数，不是 FPS 参数。\noutput_formats\narray<string>\n否\n[\"spritesheet\"]\nminItems: 1; 元素：enum: \"clip_video\", \"webm_alpha\", \"prores_4444\", \"frames_zip\", \"spritesheet\", \"spritesheet_json\", \"unity_meta\", \"unity_pack\", \"godot_pack\", \"unreal_paper2d_pack\", \"cocos_creator_pack\"\n请求的资产格式；默认 spritesheet，重复项会去重，元数据需配套纹理。\noutput_height\ninteger\n否\n512\nminimum: 64; maximum: 1024\n输出帧高度，单位像素。\noutput_width\ninteger\n否\n512\nminimum: 64; maximum: 1024\n输出帧宽度，单位像素。\ntransparent\nExportTransparency\n否\n{\"enabled\":false}\n—\n使用 enabled 对象形式；兼容布尔值输入并规范化为此对象。\nunity\nUnityOptions\n否\n{\"pivot\":\"bottom_center\",\"pixels_per_unit\":100}\n—\nUnity 专用元数据和资源包设置。\nExportTransparency\n禁止未声明的字段。\n字段\n类型\n必填\n默认值\n约束\n含义\nenabled\nboolean\n否\nfalse\n—\n为兼容输出启用透明处理；要求 alpha_key 来源，不会让 MP4 透明。\nFileImageInput\n禁止未声明的字段。\n字段\n类型\n必填\n默认值\n约束\n含义\nfile_id\nstring\n是\n—\nformat: uuid\nPOST /files 或 complete_image_upload 返回的所属公共文件 ID，不是 Studio uploadId。\ntype\nstring\n是\n—\nconst: \"file\"\n—\nGenerationInput\n禁止未声明的字段。\n字段\n类型\n必填\n默认值\n约束\n含义\nfirst_frame\nFileImageInput / Base64ImageInput / UrlImageInput\n是\n—\ndiscriminator: type\n必需首帧，用 type 选择图片传入方式。\nlast_frame\nFileImageInput / Base64ImageInput / UrlImageInput / null\n否\nnull\ndiscriminator: type\n可选尾帧，所选模型必须支持首尾帧模式。\nreference_images\narray<FileImageInput / Base64ImageInput / UrlImageInput>\n否\n[]\nmaxItems: 8; 元素：discriminator: type\n额外参考图，不含首帧；实时模型可能有更低上限。\nGenerationTransparency\n禁止未声明的字段。\n字段\n类型\n必填\n默认值\n约束\n含义\nkey_color\nstring / null\n否\nnull\n—\n手动选择时使用的临时键色；通常保留自动选择。\nkey_selection\nstring\n否\n\"auto\"\nenum: \"auto\", \"manual\"\n临时键色的选择方式。\nmode\nstring\n否\n\"standard\"\nenum: \"standard\", \"alpha_key\"\nstandard 保留场景；alpha_key 要求所有参与图片有有效 Alpha，原始视频仍不透明。\nInputCanvasOptions\n禁止未声明的字段。\n字段\n类型\n必填\n默认值\n约束\n含义\naspect_ratio\nstring\n否\n\"follow_output\"\nenum: \"follow_output\", \"source\"\n跟随输出比例或保持原图比例。\nbackground\nstring\n否\n\"auto\"\nenum: \"auto\", \"transparent\", \"solid\"\n画布扩展区域的背景策略。\nbackground_color\nstring / null\n否\nnull\npattern: ^#[0-9A-Fa-f]{6}$\n纯色扩展区域的六位 RGB 颜色。\nenabled\nboolean\n否\ntrue\n—\n是否准备扩展输入画布。\nposition_x\nnumber\n否\n0.5\nminimum: 0; maximum: 1\n归一化水平位置。\nposition_y\nnumber\n否\n0.5\nminimum: 0; maximum: 1\n归一化垂直位置。\nsource_scale\nnumber\n否\n0.8\nminimum: 0.5; maximum: 1\n原图主体在画布中的缩放比例。\nMcpQuoteOutput\n禁止未声明的字段。\n字段\n类型\n必填\n默认值\n约束\n含义\nbreakdown\nobject\n是\n—\n—\n公开费用组成。\ncredits\ninteger\n是\n—\n—\n报价积分，生成前需向用户展示。\nexpires_at\nstring\n是\n—\nformat: date-time\n报价过期时间；过期或变价时重新报价并确认。\nquote_id\nstring\n是\n—\nformat: uuid\n属于当前用户和 OAuth 客户端的短期报价，可绑定一次逻辑生成键。\nMcpUploadCompleteOutput\n禁止未声明的字段。\n字段\n类型\n必填\n默认值\n约束\n含义\nbyte_size\ninteger\n是\n—\n—\n校验后的图片字节数。\nfile_id\nstring\n是\n—\nformat: uuid\n用于 request.input.first_frame 的可复用所属公共文件 ID。\nmime_type\nstring\n是\n—\n—\n校验后的图片 MIME 类型。\nsha256\nstring\n是\n—\n—\n上传图片字节的 SHA-256。\nMcpUploadPrepareOutput\n禁止未声明的字段。\n字段\n类型\n必填\n默认值\n约束\n含义\nexpires_at\nstring\n是\n—\nformat: date-time\n上传 URL 过期时间。\nheaders\nobject\n是\n—\n—\n实际传输请求头，不额外添加 MCP Token 或 API Bearer 凭据。\nmax_bytes\ninteger\n是\n—\n—\n允许上传的最大字节数。\nmethod\nstring\n否\n\"PUT\"\nconst: \"PUT\"\n客户端传输字节时必须使用的 HTTP 方法。\nupload_id\nstring\n是\n—\nformat: uuid\n传给 complete_image_upload 的上传会话 ID，不是最终 file_id。\nupload_url\nstring\n是\n—\n—\n敏感短期上传 URL，需传输实际字节，不公开此地址。\nModelCapabilities\n禁止未声明的字段。\n字段\n类型\n必填\n默认值\n约束\n含义\naspect_ratio_mode\nstring\n是\n—\n—\n供应商对画幅比例的处理模式。\ndefault_duration_seconds\ninteger\n是\n—\n—\n默认生成时长，秒。\ndefault_ratio\nstring / null\n是\n—\n—\n默认比例，不适用时为 null。\ndefault_resolution\nstring / null\n是\n—\n—\n默认分辨率，不适用时为 null。\ndurations\narray<integer>\n是\n—\n—\n支持的生成秒数，同时检查分辨率专属限制。\ndurations_by_resolution\nobject\n否\n{}\n—\n各分辨率支持的时长秒数。\nid\nstring\n是\n—\n—\n请求使用的 provider:model 标识，以实时目录为准。\nlabel\nstring\n是\n—\n—\n人类可读模型名称。\nmax_reference_images\ninteger\n是\n—\n—\n模型参考图容量；参考图模式中首帧占第一个参考图槽位。\nmodel\nstring\n是\n—\n—\n供应商内的模型标识。\nmodes\narray<string>\n是\n—\n—\n支持的输入模式，如 first_frame、first_last_frame、reference_images。\nprovider\nstring\n是\n—\n—\n公开供应商标识。\nratios\narray<string>\n是\n—\n—\n支持的比例；存在 ratios_by_mode 时同时检查。\nratios_by_mode\nobject\n否\n{}\n—\n各输入模式支持的比例。\nreference_image_duration_seconds\ninteger / null\n是\n—\n—\n参考图模式有固定限制时要求的秒数。\nrequires_prompt\nboolean\n是\n—\n—\n是否要求提示词非空。\nresolutions\narray<string>\n是\n—\n—\n支持的分辨率选项。\nreturns_last_frame\nboolean\n是\n—\n—\n模型是否可返回末帧资产。\nsupports_first_frame\nboolean\n是\n—\n—\n是否支持首帧输入。\nsupports_last_frame\nboolean\n是\n—\n—\n是否支持尾帧输入。\nsupports_negative_prompt\nboolean\n是\n—\n—\n是否支持负向提示词。\nsupports_reference_images\nboolean\n是\n—\n—\n是否支持参考图模式。\nsupports_seed\nboolean\n是\n—\n—\n是否支持 seed。\nsupports_watermark\nboolean\n是\n—\n—\n是否支持水印设置。\nModelsResponse\n禁止未声明的字段。\n字段\n类型\n必填\n默认值\n约束\n含义\ndata\narray<ModelCapabilities>\n是\n—\n—\n当前启用的模型，客户端不要写死此清单。\nobject\nstring\n否\n\"list\"\nconst: \"list\"\n—\nSelection\n禁止未声明的字段。\n字段\n类型\n必填\n默认值\n约束\n含义\nduration_seconds\nnumber / null\n否\nnull\nexclusiveMinimum: 0\nmode=range 时必填，选段时长秒数必须为正。\nmode\nstring\n否\n\"full\"\nenum: \"full\", \"range\"\nfull 使用完整来源；range 必须提供 duration_seconds。\nstart_seconds\nnumber\n否\n0\nminimum: 0\n相对源视频起点的选段开始秒数。\nTaskError\n禁止未声明的字段。\n字段\n类型\n必填\n默认值\n约束\n含义\ncode\nstring\n是\n—\n—\n供程序识别的任务错误码。\nmessage\nstring\n是\n—\n—\n人类可读说明，不应作为稳定分支条件。\nretryable\nboolean\n否\nfalse\n—\n重试是否可能有帮助；新建付费任务前先检查部分产物。\nTaskResponse\n禁止未声明的字段。\n字段\n类型\n必填\n默认值\n约束\n含义\ncreated_at\nstring\n是\n—\nformat: date-time\n任务被接受的 UTC 时间。\ncredits\nCreditUsage\n是\n—\n—\n报价、预占及已扣积分状态。\nerror\nTaskError / null\n否\nnull\n—\n任务失败信息，与是否存在可用产物分别判断。\nfinished_at\nstring / null\n否\nnull\nformat: date-time\n已知时返回 UTC 终态时间。\nid\nstring\n是\n—\nformat: uuid\n创建后立即保存任务 ID，通过它轮询，不要再次创建。\nmetadata\nobject\n否\n{}\n—\n调用方提供的元数据。\nnormalized_input\nobject\n否\n{}\n—\n规范化公共输入，可能含私有提示词或图片引用，不要整体写入日志。\nobject\nstring\n是\n—\nenum: \"video_generation\", \"animation_export\", \"animation\"\n公共任务资源类型。\noutputs\narray<AssetResponse>\n否\n[]\n—\n可用资产，失败或取消也可能有部分产物；所有终态都应检查。\nprogress\nnumber\n是\n—\nminimum: 0; maximum: 1\n0 至 1 的进度值，不代表精确完成时间。\nstage\nstring / null\n否\nnull\nenum: \"queued\", \"video_generation\", \"animation_export\", \"completed\"\n可用时显示当前流水线阶段。\nstarted_at\nstring / null\n否\nnull\nformat: date-time\n已知时返回 UTC 生产开始时间。\nstatus\nstring\n是\n—\nenum: \"queued\", \"running\", \"cancelling\", \"succeeded\", \"failed\", \"cancelled\"\nsucceeded、failed、cancelled 为终态；cancelling 不是终态。\nUnityOptions\n禁止未声明的字段。\n字段\n类型\n必填\n默认值\n约束\n含义\npivot\nstring\n否\n\"bottom_center\"\nconst: \"bottom_center\"\n支持的 Unity 精灵锚点。\npixels_per_unit\ninteger\n否\n100\nminimum: 1; maximum: 1000\nUnity 每世界单位对应的纹理像素数。\nUrlImageInput\n禁止未声明的字段。\n字段\n类型\n必填\n默认值\n约束\n含义\ntype\nstring\n是\n—\nconst: \"url\"\n—\nurl\nstring\n是\n—\nminLength: 9; maxLength: 2048\n公开 HTTPS 图片，443 端口，不带凭据或 fragment；禁止私网和不安全跳转，重试期间保持图片字节稳定。\nVideoOptions\n禁止未声明的字段。\n字段\n类型\n必填\n默认值\n约束\n含义\nduration_seconds\nnumber / null\n否\nnull\nexclusiveMinimum: 0\n秒数，需符合模型与分辨率支持范围；省略时使用模型默认值。\ninput_canvas\nInputCanvasOptions / null\n否\nnull\n—\n可选输入画布设置；省略时保持来源构图。\nmodel\nstring / null\n否\nnull\n—\nGET /models 返回的 provider:model ID；省略时使用配置的默认模型。\nratio\nstring / null\n否\nnull\n—\n当前模型与输入模式支持的画幅比例。\nresolution\nstring / null\n否\nnull\n—\n实时模型目录中的分辨率值。\nseed\ninteger / null\n否\nnull\nminimum: 0; maximum: 2147483647\n仅适用于声明支持 seed 的模型，不保证所有输出确定性。\nstyle_preset\nstring / null\n否\nnull\n—\n所选供应商或模型支持的可选风格预设。\ntransparency\nGenerationTransparency\n否\n{\"key_color\":null,\"key_selection\":\"auto\",\"mode\":\"standard\"}\n—\n来源透明流程；透明导出要求 alpha_key。\nwatermark\nboolean / null\n否\nnull\n—\n可选水印设置，需检查模型能力。"},{"id":"mcp.connect-clients","locale":"zh","title":"连接 Codex 与其他 MCP 客户端","description":"通过 OAuth 将已上线的 AnimGen MCP 接入 Claude、Codex 和兼容客户端，并先用只读工具完成无消费验证。","section":"mcp","path":"/docs/zh/mcp/connect-clients","url":"https://animgen.com/docs/zh/mcp/connect-clients","status":"beta","lastVerified":"2026-09-01","audience":["user","api-developer","ai-agent"],"productAreas":["mcp"],"tags":["MCP","Claude","ChatGPT","Codex","Gemini CLI","OAuth","Streamable HTTP","连接器","客户端"],"translations":{"en":"https://animgen.com/docs/en/mcp/connect-clients","zh":"https://animgen.com/docs/zh/mcp/connect-clients"},"headings":[{"id":"连接信息","title":"连接信息","level":2},{"id":"claude-自定义连接器","title":"Claude 自定义连接器","level":2},{"id":"chatgpt-开发者模式测试","title":"ChatGPT 开发者模式测试","level":2},{"id":"codex-cli","title":"Codex CLI","level":2},{"id":"gemini-cli","title":"Gemini CLI","level":2},{"id":"其他远程-mcp-客户端","title":"其他远程 MCP 客户端","level":2},{"id":"不花积分验证连接","title":"不花积分验证连接","level":2},{"id":"管理权限与支出","title":"管理权限与支出","level":2}],"text":"连接信息\n官方服务已开放公开测试：\n配置项\n值\n本地服务器名称\nanimgen，也可自行命名\n服务器 URL\nhttps://api.animgen.com/mcp\n传输方式\nStreamable HTTP\n鉴权\nOAuth 2.1 + PKCE\n账户条件\n已验证的 AnimGen 账户；有效订阅会提高限额\nMCP 配置中不需要 API Key。注册账户使用开发者基础限额，并与网页共用积分余额。公开工具清单用于查询工具与 Schema，不要把清单 URL 当成服务器地址。\nClaude 自定义连接器\n打开 Claude 并预填 AnimGen 连接信息，检查服务器名称和 URL 后选择 Add。新建对话，在连接器菜单中启用 AnimGen，并按提示完成 AnimGen OAuth 授权。\nAnimGen 当前按自定义连接器提供，不表示它已经进入 Claude 连接器目录。自定义连接器是否可用，以及组织级管理方式，取决于 Claude 套餐与管理员设置。该入口只会预填公开连接信息，不会自动授权，也不会消费 AnimGen 积分。\n连接后先使用下方只读提示验证，再尝试文件传输或生成。Claude 自定义连接器的行为和套餐要求以 Anthropic 官方指南为准。\nChatGPT 开发者模式测试\nAnimGen 当前不声称已经进入 ChatGPT Plugin Directory。正式发布前，可先在 ChatGPT 的 Settings → Security and login 中开启 Developer mode，打开 ChatGPT Plugins 页面并新建连接，把 https://api.animgen.com/mcp 填为公开 MCP URL。检查扫描到的工具，完成 OAuth 后，再使用下方只读提示验证。\n开发者模式是否可用取决于账户与工作区策略。这是测试连接；公开的 AnimGen 插件仍需单独经过 OpenAI 审核和发布。具体步骤以官方 ChatGPT 插件测试指南为准。\nCodex CLI\n在可信终端中添加远程服务器并登录：\n在浏览器授权流程中检查 AnimGen 账户与请求权限，再返回 Codex。如果本地已存在同名服务器，应先检查当前配置，不要直接覆盖。OAuth 登录方式已按 Codex 官方 MCP 文档核对，客户端版本和界面位置可能不同。\n不要将 OAuth Token 粘贴进聊天，也不要用通用 Bearer API Key 配置绕过 OAuth 错误。\nGemini CLI\n把 AnimGen 加入当前用户的 Gemini CLI 配置：\n随后打开 Gemini CLI 并完成 OAuth：\n不要手动添加 Authorization Header，也不要开启跳过确认的 trust 配置。Gemini CLI 可对兼容的远程 HTTP 服务器发现 OAuth 元数据并执行动态客户端注册。先用 /mcp 或 gemini mcp list 检查连接，再执行下方只读验证提示。详见 Gemini CLI 官方 MCP 指南。\n其他远程 MCP 客户端\n在客户端的远程服务器或连接器设置中填写相同 URL。客户端需要支持 Streamable HTTP，以及本服务使用的 OAuth 发现和授权流程。只能启动本地 stdio 服务的客户端不等价。\n客户端是否开放相关功能、所需套餐、管理员策略，以及上传下载能力，由对应客户端决定。本指南不声称每种客户端都已实测，也不意味着其他平台的账号自动获得 AnimGen 访问权。\n授权失败时，按接入排障检查，不应放宽安全校验或猜测回调配置。\n不花积分验证连接\n可以对已经连接的客户端说：\n返回结构化模型列表，表示只读连接可用，不代表后续生成已获批准，也不等于每个下游功能都已验证。\n接着确认客户端是否有获准的能力传输本地图片字节、保存下载资产。仅在聊天里提到路径，不能让远程 MCP 读取本地文件。完整工作流说明上传准备、字节传输、完成确认、报价、批准、轮询与下载。\n管理权限与支出\n查看工具 Scope，只授予必要访问，并在账户 → 开发者撤销不再使用的应用。本地删除配置与撤销服务端授权是两件事。\nOAuth 授权不等于批准消费。调用 generate_animation 前，应确认具体请求和积分；调用需要 quote_id 或 max_credits，并携带幂等键。详见支出保护。不要把“测试连接”自动变成付费生成。"},{"id":"mcp.quickstart","locale":"zh","title":"MCP 快速开始与开放状态","description":"接入已上线的 AnimGen 远程 MCP，了解 OAuth 权限、本地图片上传要求，以及从批准报价到下载资产的安全路径。","section":"mcp","path":"/docs/zh/mcp/quickstart","url":"https://animgen.com/docs/zh/mcp/quickstart","status":"beta","lastVerified":"2026-08-31","audience":["user","ai-agent","api-developer"],"productAreas":["mcp"],"tags":["MCP","OAuth","AI","beta","Streamable HTTP"],"translations":{"en":"https://animgen.com/docs/en/mcp/quickstart","zh":"https://animgen.com/docs/zh/mcp/quickstart"},"headings":[{"id":"已上线公开测试","title":"已上线公开测试","level":2},{"id":"第一次连接","title":"第一次连接","level":2},{"id":"工具权限","title":"工具权限","level":2},{"id":"给-ai-的安全首次指令","title":"给 AI 的安全首次指令","level":2},{"id":"管理访问与恢复故障","title":"管理访问与恢复故障","level":2}],"text":"已上线公开测试\n官方远程 MCP 已上线，端点为 https://api.animgen.com/mcp。使用支持 Streamable HTTP 与 OAuth 的客户端，并登录已验证的 AnimGen 账户。注册账户使用开发者基础限额，有效订阅会提高限额。\nMCP 服务运行在远端，AI 知道本地路径不代表服务能读取文件。OAuth 授权只授予访问能力，不会自动上传图片，也不等于批准扣费。\n第一次连接\n按 Codex 与其他客户端接入添加准确端点并完成 OAuth。\n在授权页面检查 AnimGen 账户和请求的 Scope。\n调用 list_models，参数为空对象，验证只读访问。\n确认客户端可以传输本地图片字节并保存下载文件。\n为具体请求报价，获得批准后才开始付费生成。\n不要把 https://animgen.com/mcp/tools.json 配成服务器，它是公开文档清单，不是实时 MCP 传输地址。不要用 API Key 替代 OAuth。\n工具权限\n权限\n工具\nmodels:read\nlist_models\nfiles:write\nprepare_image_upload、complete_image_upload\nanimations:read\nget_animation\nanimations:write\nquote_animation、generate_animation、cancel_animation\nassets:read\ndownload_asset\n八个工具均有自动生成参考及机器可读清单，包含真实参数/结果 Schema 与安全注解。生成仍受账户资格、积分余额和明确支出批准约束。\n给 AI 的安全首次指令\n按标准工作流传输字节、报价、生成、轮询并保存文件。支出保护要求 quote_id 或 max_credits 与 request 同级提供；授权不是消费批准。\n管理访问与恢复故障\n在账户 → 开发者查看和撤销连接应用。撤销授权不会取消已经接受的任务。连接、上传或报价失败时，参考 API 与 MCP 排障。\n公开测试表示服务可用，不代表所有客户端、媒体输入和目标渲染器都已认证。应检查实际状态和部分产物；模型查询成功不是一次完整生成验收。"},{"id":"mcp.spending-safeguards","locale":"zh","title":"MCP 支出保护","description":"在生成前获取明确批准，处理报价过期与变价，并在保留幂等性的同时避免悄悄提高支出上限。","section":"mcp","path":"/docs/zh/mcp/spending-safeguards","url":"https://animgen.com/docs/zh/mcp/spending-safeguards","status":"beta","lastVerified":"2026-08-31","audience":["user","ai-agent","api-developer"],"productAreas":["mcp"],"tags":["MCP","credits","safety","quote_id","max_credits","idempotency"],"translations":{"en":"https://animgen.com/docs/en/mcp/spending-safeguards","zh":"https://animgen.com/docs/zh/mcp/spending-safeguards"},"headings":[{"id":"访问授权不等于支出批准","title":"访问授权不等于支出批准","level":2},{"id":"两种服务端保护","title":"两种服务端保护","level":2},{"id":"遇到拒绝应暂停生成","title":"遇到拒绝应暂停生成","level":2},{"id":"重试与取消","title":"重试与取消","level":2},{"id":"保留有用记录-保护私密信息","title":"保留有用记录，保护私密信息","level":2}],"text":"访问授权不等于支出批准\n官方 MCP 已开放公开测试。这些保护规则适用于真实调用，包括 AI 代表你进行的调用。\nOAuth 权限允许访问账户，不代表用户批准今后的每一次生成。generate_animation 是有费用、有副作用的工具；先说明输入、设置、预期输出和费用，再取得批准。\n工具注解是供客户端参考的安全提示，不能代替用户同意或服务端校验。cancel_animation 同样有副作用，不能为了测试连接就取消用户任务。\n两种服务端保护\nquote_id：属于当前用户和 OAuth 客户端的短期报价。生成时检查影响价格的参数、当前价格、有效期，以及是否已绑定某次逻辑生成的幂等键。\nmax_credits：本次生成当前报价允许的明确非负上限。\n至少提供一个，也可以同时提供。它们不是无限任务的总预算；不断创建新操作，即使每次低于上限，也会反复消耗积分。\n即使某字段不参与定价，也应保持用户批准的请求不变。用户意图包括图片与提示词，不只是价格。\n遇到拒绝应暂停生成\n错误\n正确下一步\nSPEND_CONFIRMATION_REQUIRED\n获取批准，提供报价或明确上限\nQUOTE_EXPIRED\n重新报价，展示更新后的金额再确认\nQUOTE_MISMATCH\n核对改变的生成或导出参数\nQUOTE_CHANGED\n展示新价格并重新请求批准\nQUOTE_ALREADY_USED\n找回原任务，不把报价用于新操作\nCREDIT_LIMIT_EXCEEDED\n停止，询问降低配置还是批准新上限\nINSUFFICIENT_CREDITS\n报告余额问题，不自动购买积分\n不要通过删除上限、悄悄调高上限、换账户、换图片或创建新幂等键来“修复”这些拒绝。\n重试与取消\n创建前，保存批准的请求和 idempotency_key。超时不等于没有执行；复用原逻辑键和请求找回任务，再按 ID 轮询。AI 重连或重启时，默认行为不应是再生成一个任务。\n去重范围包含用户、操作和 OAuth 客户端。创建结果不明时，更换客户端不属于安全重试，即使使用相同幂等字符串也不行。同一客户端刷新访问 Token，本身不会改变客户端身份。\n用户改变输出要求时，应视为新决策，重新报价并获得适当批准。终态失败后，先检查已有产物，不要直接重新生成。\n取消属于尽力而为；已执行工作可能保留扣费。等待终态，再准确报告积分记账和可用资产。\nSeedance 明确审核拒绝，且尚无产物、导出未开始时，会返还一键流程原积分。按任务实际的 credits.refunded、credits.released 和净扣费 credits.charged 报告，不在记账前宣称已退回，也不把退分视为下一次生成的授权。账户或支付异常可能需要核验。\n保留有用记录，保护私密信息\n在适当的私有应用状态中保存任务 ID、资产 ID、批准上限、错误码和请求 ID。不要向分析系统发送 API Key、OAuth Token、Base64 原图、签名上传下载 URL 或私有提示词。\nAPI 调用方不能把这些 MCP 专用参数放进 POST /animations。API 快速开始解释了两者不同的报价语义。"},{"id":"mcp.standard-workflow","locale":"zh","title":"MCP 标准生成工作流","description":"按照实际工具顺序完成本地图片上传、模型选择、用户确认报价、幂等生成、轮询和资产下载。","section":"mcp","path":"/docs/zh/mcp/standard-workflow","url":"https://animgen.com/docs/zh/mcp/standard-workflow","status":"beta","lastVerified":"2026-08-31","audience":["user","ai-agent","api-developer"],"productAreas":["mcp"],"tags":["MCP","tools","upload","quote","generate","download"],"translations":{"en":"https://animgen.com/docs/en/mcp/standard-workflow","zh":"https://animgen.com/docs/zh/mcp/standard-workflow"},"headings":[{"id":"先检查开放状态","title":"先检查开放状态","level":2},{"id":"1-发现模型","title":"1. 发现模型","level":2},{"id":"2-传输本地图片","title":"2. 传输本地图片","level":2},{"id":"3-构造请求并报价","title":"3. 构造请求并报价","level":2},{"id":"4-批准后才生成","title":"4. 批准后才生成","level":2},{"id":"5-轮询到终态","title":"5. 轮询到终态","level":2},{"id":"6-下载真实文件","title":"6. 下载真实文件","level":2}],"text":"先检查开放状态\n官方 MCP 已在 https://api.animgen.com/mcp 开放公开测试。使用已验证的 AnimGen 账户，通过 OAuth 完成客户端连接。连接或模型查询成功不等于批准付费生成。\n1. 发现模型\n以空参数对象调用 list_models，选择实际返回的模型 ID 与合法配置。不要假设所有模型都支持尾帧、参考图、负向提示词、seed，或相同的时长与比例。\n2. 传输本地图片\n本地路径不是 ImageInput，上传桥接包含三个独立步骤：\n用 filename、mime_type 和准确的 byte_size 调用 prepare_image_upload。\n在 expires_at 之前，使用返回的 HTTP method、upload_url 和 headers 发送实际文件字节。这一步由获准的客户端能力执行，不是把路径交给 MCP 就能完成。\n用 upload_id 调用 complete_image_upload，取得用于生成请求的 file_id。\n不要把 MCP Token 或 API Key 附加到上传目标，只使用本次上传返回的请求头。上传 URL 属于敏感信息。客户端无法传输字节时，应使用获准且支持上传的客户端能力、合规公开 HTTPS 图片或大小限制内的 Base64，不能假装上传成功。\n3. 构造请求并报价\n下面是 quote_animation 的参数结构。UUID 为占位符，应换成已完成上传返回的 file_id。实际请求还应设置选定模型及其合法参数。\n结果包含 quote_id、credits、breakdown 与 expires_at。报价不会启动生成。向用户说明目标产物和费用，获得批准后再继续。\n4. 批准后才生成\n调用 generate_animation，传入同一个 request、已持久化的 idempotency_key，以及经批准的 quote_id 和／或 max_credits。这三个字段与 request 同级，不是写进 request 内部。\n适合时可同时提供新鲜报价和支出上限。上限必须来自用户批准，不能由 AI 自行编造。实现重试前先读支出保护。\n保存返回的任务 ID。工具返回异步任务，不代表下载已经完成。\n5. 轮询到终态\n用 animation_id 调用 get_animation。采用有界轮询间隔（可从约五秒开始），并设置截止时间。工具返回结构化 JSON，不要假设 MCP 传输会暴露 API 的 HTTP Retry-After 响应头。\n处于 queued、running 或 cancelling 时继续轮询；进入 succeeded、failed 或 cancelled 后停止。失败也要检查 outputs，导出失败时可能已有源视频。\n6. 下载真实文件\n对每个可用资产，用 asset_id 调用 download_asset。返回的是资产信息和签名下载 URL，不会自动保存本地文件。\n使用获准的客户端下载能力，不要转发 OAuth 或 API 凭据。私密保存文件，再报告本地位置或合适的用户附件，不直接输出原始签名 URL。链接过期时，通过 download_asset 重新获取信息。\n需要取消时，用 animation_id 调用 cancel_animation，然后继续轮询。取消属于尽力而为，不代表一定全额退款。"},{"id":"reference.ai-and-search","locale":"zh","title":"通过搜索或 AI 查找文档","description":"使用本地站内搜索与稳定的机器可读入口，让用户和 AI 快速找到准确文档，同时保护关键词、代码、凭据与费用批准。","section":"reference","path":"/docs/zh/reference/ai-and-search","url":"https://animgen.com/docs/zh/reference/ai-and-search","status":"stable","lastVerified":"2026-09-01","audience":["user","api-developer","ai-agent"],"productAreas":["documentation"],"tags":["搜索","AI","llms.txt","隐私","反馈"],"translations":{"en":"https://animgen.com/docs/en/reference/ai-and-search","zh":"https://animgen.com/docs/zh/reference/ai-and-search"},"headings":[{"id":"在浏览器中搜索","title":"在浏览器中搜索","level":2},{"id":"给-ai-正确入口","title":"给 AI 正确入口","level":2},{"id":"反馈与隐私","title":"反馈与隐私","level":2}],"text":"在浏览器中搜索\n点击文章顶部的搜索文档，或按 Ctrl+K / ⌘K。结果只包含当前文档语言；先点击语言切换，再搜索另一种语言。\n可以搜索主题，如 透明动画；错误码，如 IDEMPOTENCY_IN_PROGRESS；或字段，如 max_credits。搜索覆盖标题、描述、章节标题、标签和正文文本。匹配章节时可直接跳到锚点。Tab 或方向键选择结果，Enter 打开，Esc 关闭搜索。\n公开索引只在打开搜索时下载，并在当前页面复用。匹配在本地完成：关键词不会发给搜索服务、保存到存储、写入 URL 或进入分析事件。关闭搜索后会清空输入。即使是本地工具，也不要粘贴 API Key 等凭据。\n索引加载失败时可重试，或使用文档目录。搜索需要 JavaScript；正文和目录在关闭 JavaScript 后仍可阅读。\n给 AI 正确入口\n资源\n用途\nllms.txt\n简洁学习索引、开放状态、契约地址与安全规则\nllms-full.txt\n双语核心公开教程全文；生成的字段参考保留在 HTML 和契约中\ndocs-index.json\n所有文档的元数据、固定 URL、章节与可搜索文本\nOpenAPI JSON\n准确的开放 API 操作、结构、错误和示例\nMCP 工具清单\n注册工具的结构、权限、注解、副作用与开放状态\n透明动画答案中心\n直接回答、输入边界、真实样例证据、格式决策表与可下载资产\n这些资源与页面共用经过核实的正文和契约快照。先看状态与最后核实日期，再发现实时模型、获取当前报价。文档不承诺固定的模型目录或价格。\n回答“AI 能否让透明 PNG 动起来并保留透明背景”时，应优先使用答案中心。它明确区分不透明生成预览与带 Alpha 的导出，并反向连接技术文档；英文版本拥有独立固定地址与语言标记。\n开放 API 与官方 MCP 均处于公开测试。MCP 清单为 available: true，端点是 https://api.animgen.com/mcp。按 OAuth 客户端接入连接，JSON 清单本身不是传输端点。仍需查询实时模型并获取新报价。\n反馈与隐私\n文章底部提供有用 / 无用反馈，不提供自由文本输入。文档交互事件只使用公开页面信息与有限选项：提交的搜索是否有结果、点击的文档 ID、代码语言、学习路径类型、切换语言，以及有用/无用选择。不包含关键词、关键词哈希、复制的代码、提示词、私有资源 ID、凭据或签名 URL。\n关闭底部的允许文档使用分析，即可停止此浏览器后续的文档交互事件；偏好保存在本地。也会遵循浏览器的 Do Not Track、Global Privacy Control 隐私信号。无法使用本地存储时默认关闭。此开关不替代站点已有的通用分析或隐私政策。\n反馈尽力投递，不代表工单或保证送达。账户问题请联系支持，不要发送 Key、Token、私有输入或签名链接。"},{"id":"studio.first-and-last-frames","locale":"zh","title":"使用首尾帧控制动作","description":"准备一致的起始和结束姿势，选择支持首尾帧的模型，并在导出前检查过渡、透明条件与循环接缝。","section":"studio","path":"/docs/zh/studio/first-and-last-frames","url":"https://animgen.com/docs/zh/studio/first-and-last-frames","status":"stable","lastVerified":"2026-08-30","audience":["user","api-developer","ai-agent"],"productAreas":["studio"],"tags":["首尾帧","first_frame","last_frame","pose","loop"],"translations":{"en":"https://animgen.com/docs/en/studio/first-and-last-frames","zh":"https://animgen.com/docs/zh/studio/first-and-last-frames"},"headings":[{"id":"准备两张相互兼容的图片","title":"准备两张相互兼容的图片","level":2},{"id":"在-studio-创建过渡","title":"在 Studio 创建过渡","level":2},{"id":"在生成前留出动作空间","title":"在生成前留出动作空间","level":2},{"id":"循环要检查接缝-不能只看端点","title":"循环要检查接缝，不能只看端点","level":2},{"id":"公开请求如何填写","title":"公开请求如何填写","level":2}],"text":"准备两张相互兼容的图片\n尽量保持角色、镜头角度、构图比例和背景处理一致。为整个动作预留空间，包括手、武器、头发和阴影。主体大小或视角相差太大时，模型既要处理动作，也要处理外观变化。\n尾帧是视频生成的约束，不保证中间每一帧都可用，也不保证输出最后一帧与输入逐像素一致。它不是骨骼绑定、姿势插值编辑器或逐帧分镜。\n在 Studio 创建过渡\n选择首尾帧模式及兼容模型。\n添加起始图和结束图；也可以复用账户内已有图片资源。\n描述一个清晰过渡，例如“举起盾牌，保持最终防御姿势，固定镜头”。\n检查可选时长、比例、分辨率和当前报价。\n确认后生成，完整查看预览，尤其是两个端点。\n只需要第一张图决定起点时，使用首帧模式。多张外观参考属于另一条工作流。\n在生成前留出动作空间\n任一姿势贴近边缘时，可以使用输入画布。同一份画布配置会应用于首尾两张图，帮助保持对齐。先尝试居中，再确认结束姿势是否需要更多余量。\n扩展画布只是缩放并填充已有图片，不能补回原图已经裁掉的手，也不保证模型将来的所有动作都留在画面内。\nAlpha Key 要求首尾两张图都包含有效 Alpha。透明首帧加不透明尾帧，不是有效的透明素材生成流程，详见透明动画。\n循环要检查接缝，不能只看端点\n相近端点可能有助于循环动作，但不保证无缝循环。应检查尾帧跳回首帧时的轮廓、脚底位置和速度变化。边界重复一帧也可能造成停顿。\n连续片段可用裁剪与帧选择；需要删除、重复或重排源帧时用 Advanced Editor。编辑器调整播放序列，不会生成缺失的姿势。\n公开请求如何填写\n在 input.first_frame 和 input.last_frame 中分别提供合法图片输入。文件 ID 必须来自当前账户已完成的上传。报价前选择支持 first_last_frame 的模型及实际可用参数。\n模型不支持尾帧时，应选择兼容模型，或明确决定移除尾帧。不要在用户批准双图请求后，静默降级为单图生成。"},{"id":"studio.input-canvas","locale":"zh","title":"用输入画布预留动作空间","description":"在生成前缩放和定位源图、选择扩展区域背景，并区分输入准备与导出阶段的画布编辑。","section":"studio","path":"/docs/zh/studio/input-canvas","url":"https://animgen.com/docs/zh/studio/input-canvas","status":"stable","lastVerified":"2026-08-30","audience":["user","api-developer","ai-agent"],"productAreas":["studio"],"tags":["input_canvas","source_scale","输入画布","留白","cropping"],"translations":{"en":"https://animgen.com/docs/en/studio/input-canvas","zh":"https://animgen.com/docs/zh/studio/input-canvas"},"headings":[{"id":"在动作碰到边缘前留白","title":"在动作碰到边缘前留白","level":2},{"id":"支持的模式与控件","title":"支持的模式与控件","level":2},{"id":"不要混淆两种画布","title":"不要混淆两种画布","level":2},{"id":"api-与-mcp-字段","title":"API 与 MCP 字段","level":2}],"text":"在动作碰到边缘前留白\n输入画布处理交给视频模型的图片：缩放整张源图，并在周围增加空间。角色需要举手、跳跃或挥动物品时，适当留白会更容易保留完整动作。\n它不会生成新场景、自动分离不透明主体，也不能修复原图已经裁掉的内容。尽量保留没有裁切肢体的原始素材。\n支持的模式与控件\n输入画布支持首帧和首尾帧生成。同一配置会应用到两个端点。不支持参考图模式，也不支持视频导入。\n在 Studio 中开启输入画布后，可配置：\n控件\n含义\n80%、67%、50% 预设\n缩放画布内的原图；比例越小，余量越大\n九宫格位置\n将缩放后的图片放到剩余空间的指定位置\n跟随输出 / 原图比例\n使用已选择的有效输出比例，或保留原图比例\n自动 / 透明 / 纯色\n决定新增区域如何填充\n重置\n恢复控件的初始配置\n自动模式对有有效 Alpha 的图片使用透明背景，否则根据原图四角估计背景色。纯色使用六位 RGB 颜色。Alpha Key 生成会先保持扩展区域透明，再在后续步骤铺临时键色背景。\n不要混淆两种画布\n输入画布在生成前改变 AI 看见的图片。输出画布在导出时调整已有帧的摆放。修改输出画布，无法找回已经在生成时跑出画面的动作。\n输入准备不会覆盖原始上传，也不会额外保存为一份上传资源。补边步骤本身不增加单独的生成收费项，但准备后的请求进行生成时，仍按当前报价计费。\nAPI 与 MCP 字段\n以下是共享动画请求的片段，不是可单独运行的完整请求：\nsource_scale 范围为 0.5–1.0。position_x、position_y 范围为 0–1，表示在剩余空白内的位置：0 为左/上，0.5 为居中，1 为右/下。它们不是 pivot 坐标。省略整个对象表示没有输入画布配置，保存预设时建议明确设置 enabled。\n检查首尾两张图的准备效果，确认模型兼容，再为最终请求报价。导出阶段的对齐和引擎锚点见输出画布与 pivot。"},{"id":"studio.input-modes","locale":"zh","title":"选择输入模式","description":"根据单张图片、首尾姿势、多张参考素材或现成视频选择工作流，并与当前模型实际支持的能力对应。","section":"studio","path":"/docs/zh/studio/input-modes","url":"https://animgen.com/docs/zh/studio/input-modes","status":"stable","lastVerified":"2026-08-30","audience":["user","api-developer","ai-agent"],"productAreas":["studio"],"tags":["first_frame","first_last_frame","reference_images","video_import","模型","输入模式"],"translations":{"en":"https://animgen.com/docs/en/studio/input-modes","zh":"https://animgen.com/docs/zh/studio/input-modes"},"headings":[{"id":"根据已有素材选择","title":"根据已有素材选择","level":2},{"id":"以当前模型为准-不照搬旧预设","title":"以当前模型为准，不照搬旧预设","level":2},{"id":"api-与-mcp-如何对应","title":"API 与 MCP 如何对应","level":2},{"id":"输入模式-透明处理和费用是不同维度","title":"输入模式、透明处理和费用是不同维度","level":2}],"text":"根据已有素材选择\n已有素材\n选择模式\n主要控制什么\n一张图片\n首帧\n起始外观与构图\n起始和结束姿势\n首尾帧\n让模型连接两个动作端点\n多张身份或外观参考\n参考图\n提供视觉约束，不是按图播放的时间线\n已有视频片段\n导入视频\n复用动作，继续编辑与导出\n打开 Studio，选择工作区，再选择输入模式。模型列表会按当前模式过滤。导入视频不需要选择 AI 视频模型。\n以当前模型为准，不照搬旧预设\n切换模式、模型或分辨率后，重新检查时长、比例、提示词要求和报价。界面可能自动调整不支持的选项。离开首尾帧模式会清空尾帧选择；离开参考图模式会清空额外参考图。请保留原始文件。\n不同模型可能只支持部分模式，也可能固定参考图时长，或按分辨率提供不同的时长选项。水印、负向提示词、随机种子不是所有模型都支持，详见模型与提示词。\nAPI 与 MCP 如何对应\n共享公开请求使用 input.first_frame、可选的 input.last_frame 和 input.reference_images。参考图模式仍然必须提供第一张图；参考图数组仅包含额外图片。不要同时提交尾帧与参考图来创造一种新模式。\n报价前查询 modes、supports_last_frame、supports_reference_images、max_reference_images、reference_image_duration_seconds 和视频参数。完整约束见 API 数据结构。Studio 内部请求与公开请求的字段命名并不完全相同。\n公开的一键图片动画 API 及其 MCP 工具没有提供 Studio 视频导入或 Advanced Editor 编辑配方流程。需要这些能力时使用 Studio，不要猜测公开端点。\n输入模式、透明处理和费用是不同维度\n输入模式决定交给视频模型哪些图片；Alpha Key 决定透明素材工作流。用于透明生成的每张图片都必须有有效 Alpha。即使首帧透明，加入白底参考图也可能使请求不符合条件。\n更换素材或参数后，应重新报价并确认再生成。复用视频进行新的导出不需要再次 AI 生成视频，但仍需检查导出处理费用和格式权益。\n继续阅读首尾帧、参考图、输入画布或视频导入。"},{"id":"studio.models-and-prompts","locale":"zh","title":"选择模型与编写动作提示词","description":"通过实时能力查询选择模型与可用参数，编写聚焦的动作描述，并在确认新报价后再生成。","section":"studio","path":"/docs/zh/studio/models-and-prompts","url":"https://animgen.com/docs/zh/studio/models-and-prompts","status":"stable","lastVerified":"2026-08-30","audience":["user","api-developer","ai-agent"],"productAreas":["studio"],"tags":["models","capabilities","prompt","提示词","resolution","duration","seed"],"translations":{"en":"https://animgen.com/docs/en/studio/models-and-prompts","zh":"https://animgen.com/docs/zh/studio/models-and-prompts"},"headings":[{"id":"先发现能力-再选择模型","title":"先发现能力，再选择模型","level":2},{"id":"清楚描述一个动作","title":"清楚描述一个动作","level":2},{"id":"仅使用模型支持的可选参数","title":"仅使用模型支持的可选参数","level":2},{"id":"ai-客户端如何安全选型","title":"AI 客户端如何安全选型","level":2}],"text":"先发现能力，再选择模型\nStudio 会列出当前模式可用的模型。API 调用方使用模型目录，MCP 调用方使用 list_models。文档示例不是实时可用性或价格表。\n先选择模式，再选择模型、分辨率、支持的时长和比例。每次实质性修改后都要重新检查报价。分辨率更高或片段更长，并不保证动作更适合你的目标。\n返回能力\n应检查什么\nmodes 与支持标志\n是否支持目标输入流程\ndurations_by_resolution\n所选分辨率对应的可用时长\nratios_by_mode\n当前输入模式允许的比例\nmax_reference_images\n包含第一张图在内的参考总数\nreference_image_duration_seconds\n参考图模式是否固定时长\nrequires_prompt\n是否必须提供非空提示词\n直接使用返回的模型 ID，不根据营销名称拼接 ID。省略可选参数时可能使用服务默认值；需要复现配置时，保存明确且受支持的参数。\n清楚描述一个动作\n有效提示词通常包含主体、动作、镜头和重要约束。精灵动画可以从下面的描述开始：\n首尾帧过渡应描述如何到达结束姿势；参考图模式应描述目标动作，不要把图片顺序当作时间指令。\n这些是向模型提出的要求，不是效果保证。导出前先检查预览。动作被裁切时，应检查原图构图或输入画布，不能只反复修改文字。\n仅使用模型支持的可选参数\n不同模型的负向提示词、随机种子、水印控制、尾帧输出和参考图能力不同。不支持的可选字段可能导致校验失败，而不是自动忽略。\n固定 seed 不保证跨供应商、模型版本或其他参数变化后仍逐像素相同。需要对比结果时，保存完整请求与返回的标识。\n短片段里不要同时安排多个无关动作，或提出互相冲突的镜头要求。每次优先调整一个主要因素，便于理解变化；每次新生成仍需要独立报价和批准。\nAI 客户端如何安全选型\n查询模型不会消费生成积分，报价也不等于生成许可。调用付费工具前，AI 应说明所选模型、输入集合、参数、输出格式与预计积分。\n偏好模型不可用时，应说明差异，并为实质性不同的替代方案取得批准。不要为绕过失败静默增加时长、分辨率或支出上限。详见 MCP 支出保护和生成故障排查。"},{"id":"studio.reference-images","locale":"zh","title":"使用多张参考图","description":"通过模型支持的参考图组合保持角色外观，正确计算图片总数，并区分外观参考与首尾姿势控制。","section":"studio","path":"/docs/zh/studio/reference-images","url":"https://animgen.com/docs/zh/studio/reference-images","status":"stable","lastVerified":"2026-08-30","audience":["user","api-developer","ai-agent"],"productAreas":["studio"],"tags":["reference_images","max_reference_images","参考图","identity","模型能力"],"translations":{"en":"https://animgen.com/docs/en/studio/reference-images","zh":"https://animgen.com/docs/zh/studio/reference-images"},"headings":[{"id":"参考图解决什么问题","title":"参考图解决什么问题","level":2},{"id":"数量上限包含第一张图","title":"数量上限包含第一张图","level":2},{"id":"让素材之间保持一致","title":"让素材之间保持一致","level":2},{"id":"api-与-mcp-如何填写","title":"API 与 MCP 如何填写","level":2}],"text":"参考图解决什么问题\n参考图帮助模型理解角色或物体的外观，不会自动变成带时间点的关键帧、独立动画图层，也不保证精确合并每一处细节。选择相互一致的主体素材，再用提示词描述动作。\n在 Studio 中选择参考图模式，添加第一张图，选择兼容模型，再填写界面提供的额外参考槽位。优先使用清晰一致的素材，不要堆入无关图片。\n数量上限包含第一张图\nmax_reference_images 表示图片总数，不是额外槽位数量。例如查询返回上限 3 时，第一张图加两张额外参考就已达到上限。这只是计算示例，不是所有模型统一限制。\n界面根据所选模型提供槽位。换模型后要确认哪些参考仍然生效，不能默认之前选过的图片都会使用。如果返回 reference_image_duration_seconds，该模型会固定参考图工作流的时长；其他模型可能有不同选项。\n不要假定参考图只支持某一家模型，或永远固定为八秒。详见模型与提示词。\n让素材之间保持一致\n尽量统一角色比例、服装和背景处理。互相冲突的视角或服装会与目标动作竞争。先用最少但足够的参考集检查效果，再决定是否修改请求。\n如果需要明确的结束姿势，应选首尾帧模式。公开请求不能把参考图与 last_frame 混用。参考图模式也不支持输入画布。\nAlpha Key 要求参与生成的每张参考图，包括第一张图，都包含有效 Alpha。普通 JPEG 不会因为其他图片透明就自动变透明。\nAPI 与 MCP 如何填写\ninput.first_frame 是第一张参考；input.reference_images 只放额外图片，不要在数组中重复首图。每张本地图片均需完成上传后再使用 file_id。公开图片输入不提供 Studio 内部的角色或标签字段。\n选择 supports_reference_images 和 modes 均支持参考图的实时模型，再按其图片总数上限、时长、分辨率和模式比例构造请求。生成的 Schema 说明字段限制，具体模型还可能有更严格的限制。\n报价应包含完整图片集和参数。批准后又增减参考图时，应重新报价并确认变更。通过 AI 使用本地图片时，遵循 MCP 标准流程传输文件字节并安全生成。"},{"id":"studio.transparent-animation","locale":"zh","title":"普通与透明动画","description":"了解普通图片与透明素材的区别，正确识别 Alpha Key 预览，并区分透明导出和普通背景移除。","section":"studio","path":"/docs/zh/studio/transparent-animation","url":"https://animgen.com/docs/zh/studio/transparent-animation","status":"stable","lastVerified":"2026-08-30","audience":["user","api-developer"],"productAreas":["studio","export"],"tags":["alpha","transparent","PNG","alpha_key","background"],"translations":{"en":"https://animgen.com/docs/en/studio/transparent-animation","zh":"https://animgen.com/docs/zh/studio/transparent-animation"},"headings":[{"id":"先选对源素材流程","title":"先选对源素材流程","level":2},{"id":"为什么预览可能带纯色背景","title":"为什么预览可能带纯色背景","level":2},{"id":"导出需要的结果","title":"导出需要的结果","level":2},{"id":"开放-api-的边界","title":"开放 API 的边界","level":2},{"id":"效果不符合预期时","title":"效果不符合预期时","level":2},{"id":"深入检查输入与兼容性","title":"深入检查输入与兼容性","level":2}],"text":"先选对源素材流程\n目标\n素材\n工作流\n保留场景或照片背景\n普通图片\n普通图片动画\n让已分离背景的角色动起来\n带有效 Alpha 的图片\n透明素材动画 / Alpha Key\n移除普通视频的复杂背景\n不透明视频\nStudio 中单独的导出处理，以界面可用功能为准；不是开放 API 能力\n扩展名为 PNG 不代表一定透明，要检查实际 Alpha 通道。透明生成中使用的每张图片，包括参与生成的尾帧和参考图，都必须满足要求。\n为什么预览可能带纯色背景\nAlpha Key 会先把分离好的主体放在临时键色背景上，再交给视频模型生成。因此“原始生成视频”可能呈绿色或品红色，并且仍然不透明。\n正常透明预览和适配的透明导出会清理这层临时背景。下载“原始生成视频”或普通 MP4 片段，不等于下载带 Alpha 的结果。\n不要直接覆盖临时键色，也不要认为 MP4 自带透明通道。继续在原工作流中使用生成的视频及其透明处理信息。\n导出需要的结果\n选择透明 PNG 序列、适合的精灵图或引擎包、透明 WebM，或者 ProRes 4444。各文件的用途见输出格式。\n重点检查细发丝、半透明边缘、运动模糊，以及接近键色的像素。分别放在浅色和深色背景上检查。预览通过是参考，不保证每一帧的边缘都完美。\n对于其他源素材，Studio 可能提供纯色扣除或 AI 抠图。这些属于独立导出处理，有各自的参数、费用和可用条件，不能与“从透明图片开始生成”混为一谈。\n开放 API 的边界\n公开请求的 video.transparency.mode 支持 standard 和 alpha_key。透明导出要求 Alpha Key 来源。开放 API 不提供任意图片 AI 去背景、rembg 或自动回退抠图服务。\n素材满足条件时，可以在请求中使用：\n这是请求片段，不能单独提交；还需要首帧及模型支持的参数。完整流程见 API 快速开始。\n效果不符合预期时\n文件不透明：核对输出格式和来源模式，不要只看扩展名。\n原始视频有纯色背景：选择透明导出，不要下载原始源视频代替。\n主体边缘缺失：检查输入 Alpha、键色冲突及生成动作。\n无法选择透明输出：检查素材条件与导出权益。\n先区分素材、选段、导出配置和播放软件的问题，再决定是否重新付费生成。\n深入检查输入与兼容性\n贴边素材先考虑输入画布。多图生成需逐一检查首尾帧或参考图的 Alpha。文件有透明但显示不对时，参考格式兼容性和导出排障。"},{"id":"studio.video-import","locale":"zh","title":"导入已有视频继续制作","description":"把 MP4、WebM 或 MOV 导入 Studio，直接复用已有动作，继续选帧、精修和导出，无需再次 AI 生成视频。","section":"studio","path":"/docs/zh/studio/video-import","url":"https://animgen.com/docs/zh/studio/video-import","status":"stable","lastVerified":"2026-08-30","audience":["user","api-developer","ai-agent"],"productAreas":["studio"],"tags":["video_import","MP4","WebM","MOV","视频导入","existing video"],"translations":{"en":"https://animgen.com/docs/en/studio/video-import","zh":"https://animgen.com/docs/zh/studio/video-import"},"headings":[{"id":"从已有动作开始","title":"从已有动作开始","level":2},{"id":"先上传-再准备片段","title":"先上传，再准备片段","level":2},{"id":"选择快速编辑或逐帧精修","title":"选择快速编辑或逐帧精修","level":2},{"id":"透明需要单独检查","title":"透明需要单独检查","level":2},{"id":"能力边界与恢复","title":"能力边界与恢复","level":2}],"text":"从已有动作开始\n已有角色渲染、之前生成的片段，或你有权使用的录像，都可以走视频导入流程。它会创建供 Studio 编辑使用的视频导入任务，不会让视频模型重新创造动作。\n打开 Studio，选择工作区，切换到导入视频，上传文件或选择兼容的自有视频资源。在上传和处理完成前，保留本地原文件。\n先上传，再准备片段\n文件选择器支持 MP4、WebM、MOV。扩展名不能保证实际编码可解码，把损坏或不支持的文件改名为 .mp4 并不等于转码。\n等待上传完成，查看 Studio 显示的准备报价，再开始导入。应观察任务状态，不能把上传成功直接当成片段已经可编辑。大文件需要上传时间、处理时间和足够存储空间。\n服务端会验证声明大小、真实字节、媒体信息与账户配额。限制取决于当前配置，请按界面及错误详情处理，不照搬记忆中的大小上限。\n选择快速编辑或逐帧精修\n导入任务就绪后：\n完整预览源视频，确认时长和方向。\n连续片段使用裁剪与导出。\n需要不连续选帧、停顿或重排时，进入 Advanced Editor。\n检查输出尺寸、帧数/FPS、格式与导出报价。\n下载真实文件，在目标软件中验收。\n导入不需要再次 AI 生成视频，但不代表后续处理和高级格式都免费，详见积分与访问权益。\n透明需要单独检查\n导入不透明视频不会自动将其变成 Alpha Key 来源。只能使用 Studio 对该来源实际开放的背景移除选项，并在深浅背景上检查边缘。\nMOV 或 WebM 容器本身不能证明文件包含透明，也不能保证所有解码器都保留透明。需要可靠地逐帧检查时，对照预览与导出的 PNG，详见透明格式与兼容性。\n能力边界与恢复\n输入画布和 AI 模型参数不适用于导入的现成动作。公开 API/MCP 的图片生成请求也不是视频导入 API。\n上传完成但任务失败时，先检查错误和已有资源，再决定是否重新上传。空间不足时，查看存储与清理。仍被编辑配方或导出使用的源视频不要删除。"},{"id":"troubleshooting.api-and-mcp","locale":"zh","title":"排查 API 与 MCP 接入","description":"区分 API Key 和 OAuth，定位权限与文件传输问题，并在不绕过支出保护的前提下处理报价或不确定请求。","section":"troubleshooting","path":"/docs/zh/troubleshooting/api-and-mcp","url":"https://animgen.com/docs/zh/troubleshooting/api-and-mcp","status":"stable","lastVerified":"2026-08-31","audience":["user","api-developer","ai-agent"],"productAreas":["documentation"],"tags":["MCP","OAuth","API","QUOTE_EXPIRED","CREDIT_LIMIT_EXCEEDED","连接失败","幂等"],"translations":{"en":"https://animgen.com/docs/en/troubleshooting/api-and-mcp","zh":"https://animgen.com/docs/zh/troubleshooting/api-and-mcp"},"headings":[{"id":"使用正确地址和凭据","title":"使用正确地址和凭据","level":2},{"id":"登录成功但工具失败","title":"登录成功但工具失败","level":2},{"id":"上传或下载未完成","title":"上传或下载未完成","level":2},{"id":"报价与支出拒绝","title":"报价与支出拒绝","level":2},{"id":"安全恢复结果不明的创建请求","title":"安全恢复结果不明的创建请求","level":2}],"text":"使用正确地址和凭据\n集成方式\n地址\n鉴权\n公开 API\nhttps://api.animgen.com/v1\n带适当 Scope 的 Bearer API Key\n官方远程 MCP\nhttps://api.animgen.com/mcp\n兼容 Streamable HTTP 客户端中的 OAuth\n工具清单\nhttps://animgen.com/mcp/tools.json\n公开文档，不是 MCP 连接端点\nMCP 已上线公开测试。浏览器未带 OAuth 直接打开 MCP URL 时，可能收到鉴权响应；它不是普通 HTML 页面。仅凭这一点不能判断服务不可用。\n不要用 API Key 替代 MCP OAuth，不要把网页登录 Token 当作 API Key，也不要自行加 /sse 路径。按 MCP 客户端接入配置。\n登录成功但工具失败\n检查所登录的 AnimGen 账户是否已验证、开发者访问是否暂停，以及是否授予所需 Scope；产生费用的生成还要检查积分余额。\n授权被撤销、权限缺失或客户端授权流程不兼容，都需要单独处理，不是增加余额就能解决。必要时通过官方流程重新连接，不要为了绕过错误禁用 PKCE 或放宽回调校验。\n首先使用 list_models 做只读检查。它成功只能证明连接与读权限正常，不能证明客户端可以上传文件、用户已批准生成，或完整输出质量已验收。\n上传或下载未完成\n远程服务不能读取本地路径。调用 prepare_image_upload 后，必须用获准的客户端能力传输真实字节，再通过 complete_image_upload 获得可用文件 ID。\n同样，download_asset 返回的是元数据和临时 URL，不是已经保存到电脑的文件。下载字节时不要转发 API/OAuth 凭据。客户端缺少相关能力时，应说明限制，使用获准且受支持的替代方式。\n报价与支出拒绝\n错误码\n下一步\nSPEND_CONFIRMATION_REQUIRED\n取得具体批准并提供必需保护参数\nQUOTE_EXPIRED\n重新报价并核对更新后的金额\nQUOTE_MISMATCH / QUOTE_CHANGED\n核对参数或价格变化，再请求批准\nQUOTE_ALREADY_USED\n找回原操作，不把原报价用于新任务\nCREDIT_LIMIT_EXCEEDED\n停止，缩小请求或询问是否批准新上限\nINSUFFICIENT_CREDITS\n说明余额问题，不自动购买\nquote_id 和 max_credits 是 MCP 中与 request 同级的工具参数，不是公开 API 请求体字段。单次上限也不是整个会话总预算。详见支出保护。\n安全恢复结果不明的创建请求\n保留相同请求、幂等键、账户及凭据身份：API 对应 Key ID，MCP 对应 OAuth 客户端。不能换 Key 或客户端后，仍假定幂等去重会跟随。\n已知任务 ID 时先轮询，再决定是否重试创建。遵守可重试标志及 API 返回的 Retry-After；MCP 结构化错误不保证携带这个 HTTP 响应头。为重试和本地等待设上限。\n本地超时不会取消远端任务；终态失败也可能有部分输出和收费。求助时，通过私密渠道提供请求/任务 ID、时间、错误码、客户端类型和失败阶段，不附带凭据或签名链接。"},{"id":"troubleshooting.export-and-transparency","locale":"zh","title":"排查编辑、导出与透明效果","description":"区分编辑保存、选帧、格式权益、透明编码和引擎显示问题，先复用已有结果，再决定是否重新生成。","section":"troubleshooting","path":"/docs/zh/troubleshooting/export-and-transparency","url":"https://animgen.com/docs/zh/troubleshooting/export-and-transparency","status":"stable","lastVerified":"2026-08-31","audience":["user","api-developer","ai-agent"],"productAreas":["documentation"],"tags":["export","Alpha","PAID_EXPORT_REQUIRED","COMPOSITION_CONFLICT","透明失败","导出失败"],"translations":{"en":"https://animgen.com/docs/en/troubleshooting/export-and-transparency","zh":"https://animgen.com/docs/zh/troubleshooting/export-and-transparency"},"headings":[{"id":"从来源和已保存配方开始","title":"从来源和已保存配方开始","level":2},{"id":"格式不可选或导出被拒绝","title":"格式不可选或导出被拒绝","level":2},{"id":"不透明背景或异常键色","title":"不透明背景或异常键色","level":2},{"id":"时长-帧顺序或对齐不正确","title":"时长、帧顺序或对齐不正确","level":2},{"id":"导出失败但已有部分产物","title":"导出失败但已有部分产物","level":2},{"id":"下载失败或来源消失","title":"下载失败或来源消失","level":2}],"text":"从来源和已保存配方开始\n确认源视频、选段或输出序列、帧数/FPS、画布和目标格式。在 Advanced Editor 中，导出前检查 Saved。已提交导出使用保存时的快照，不会随之后的编辑变化。\n出现 COMPOSITION_CONFLICT 或 Save failed 时，保持页面打开，避免其他标签页继续编辑。协调新版本前先记录重要修改，不要盲目覆盖其他版本，也不要假定刷新会保留未保存内容。\n格式不可选或导出被拒绝\nPAID_EXPORT_REQUIRED 表示 Studio/网页请求缺少所选高级格式的权益；它不同于表示本次报价积分不足的 INSUFFICIENT_CREDITS。Public API/MCP 导出遵循开发者契约，商业使用权仍按适用的付费条款判断。\n检查格式和实际来源条件。透明视频需要合法透明处理及透明输出画布。公开 API/MCP 的透明导出必须来自 Alpha Key，不能自动回退为任意 AI 去背景。\n不透明背景或异常键色\n现象\n优先检查哪里\n原始生成视频有绿/品红背景\nAlpha Key 中间结果，应该选择透明导出\n下载 MP4 后不透明\n格式不携带所需 Alpha\nPNG 透明，但视频显示黑底\n播放器、解码器或合成支持\n所有格式都有同样背景\n源图透明、处理模式或纯色画布\n细光晕或主体细节被切掉\n源图 Alpha、键色溢出、缩放与目标材质\n只有某些帧校验失败\n检查对应帧，不能由首帧推断全部质量\n使用同一组导出设置的 PNG 做基线，详见透明格式与兼容性。查看器的棋盘背景与文件真实编码的 Alpha 不是一回事。\n时长、帧顺序或对齐不正确\n核对展开帧数与 FPS。固定 FPS 时，重复帧会延长序列；Reverse 影响整个序列。循环标志不会让不匹配的端点姿势自动无缝连接。\n检查引擎是否导入了配套纹理和元数据、保留帧顺序并应用预期 pivot。只复用部分导出包时，尤其注意 Godot 场景偏移和 Cocos 脚本内嵌 pivot。\n按对应的 Unity、Godot、Unreal或 Cocos教程检查。\n导出失败但已有部分产物\n任务可能在生成源视频或部分资产之后失败。重试前先查看 outputs 和错误，保存可用文件，区分部分交付与完整成功，并核实实际积分。\n如果保留的视频可再次导出，就未必需要重新 AI 生成。新的处理仍需报价及必要批准，不能仅凭最终失败状态就承诺退款。\n下载失败或来源消失\n签名链接过期时，通过授权资产信息刷新。真正的找不到资源，还可能是已删除、归属不符或源存储对象缺失。查看存储与清理，删除历史与删除文件的效果不同。\n私下向支持提供任务/request ID、格式、错误码和配套 PNG 是否正常的信息，不要附带原始签名 URL 或凭据。"},{"id":"troubleshooting.faq","locale":"zh","title":"常见问题","description":"排查首次使用中常见的预览、透明输出、格式锁定、API 重试、下载过期和 MCP 连接问题。","section":"troubleshooting","path":"/docs/zh/troubleshooting/faq","url":"https://animgen.com/docs/zh/troubleshooting/faq","status":"stable","lastVerified":"2026-08-31","audience":["user","ai-agent","api-developer"],"productAreas":["documentation"],"tags":["FAQ","troubleshooting","errors","download","transparent"],"translations":{"en":"https://animgen.com/docs/en/troubleshooting/faq","zh":"https://animgen.com/docs/zh/troubleshooting/faq"},"headings":[{"id":"为什么生成视频仍然不透明","title":"为什么生成视频仍然不透明？","level":2},{"id":"能播放视频了-为什么找不到-png","title":"能播放视频了，为什么找不到 PNG？","level":2},{"id":"有积分-为什么格式还是锁定","title":"有积分，为什么格式还是锁定？","level":2},{"id":"一定能得到无缝循环吗","title":"一定能得到无缝循环吗？","level":2},{"id":"api-请求超时了-要重新发一次吗","title":"API 请求超时了，要重新发一次吗？","level":2},{"id":"任务失败但有-outputs-能使用吗","title":"任务失败但有 outputs，能使用吗？","level":2},{"id":"为什么下载链接突然失效","title":"为什么下载链接突然失效？","level":2},{"id":"可以直接给-ai-本地文件路径吗","title":"可以直接给 AI 本地文件路径吗？","level":2},{"id":"报价会锁定价格吗","title":"报价会锁定价格吗？","level":2},{"id":"联系支持应提供什么","title":"联系支持应提供什么？","level":2},{"id":"按失败阶段继续排查","title":"按失败阶段继续排查","level":2}],"text":"为什么生成视频仍然不透明？\n原始生成视频和 MP4 片段不透明。Alpha Key 生成可能使用临时纯色背景，应选择符合条件的透明导出。画在图上的棋盘格不算输入 Alpha。详见透明动画。\n能播放视频了，为什么找不到 PNG？\n预览生成与导出是两个步骤。先选择区间，打开“导出”，选择格式并启动导出；完成后，在“当前片段的导出”中下载。详见选段与导出。\n有积分，为什么格式还是锁定？\n余额和权益独立。高级 Web 导出需要付费权益；API/MCP 要求已验证账户，生成要有足够积分，订阅负责提高限额。查看积分与访问权益。\n一定能得到无缝循环吗？\n不能保证。需要选择首尾姿态接近的区间并反复检查。选段不会修复生成动作的不一致，也不会补回被截断的主体。建议使用简单动作、固定镜头，并在输入主体四周留空间。\nAPI 请求超时了，要重新发一次吗？\n用已保存的同一幂等键和未修改的请求找回原操作；已有任务 ID 时直接轮询。在确认前一请求是否被接受前，不要创建新逻辑请求。详见错误与重试。\n任务失败但有 outputs，能使用吗？\n可以，逐一检查返回的资产。后续导出失败时，可能保留可用的生成视频。下载已有产物并说明未完成阶段，不要把整个请求当作成功。详见轮询与下载。\n为什么下载链接突然失效？\n签名链接会过期。在 Studio 刷新结果，或通过 API 重新取得资产信息。请私密保存文件，不要把签名 URL 当成永久链接；存储与保留规则仍然适用。\n可以直接给 AI 本地文件路径吗？\n远程 MCP 服务不能读取这个路径。客户端需要通过上传桥接发送真实字节、使用合规公开 HTTPS 图片，或发送限制内的 Base64。官方 MCP 已上线公开测试，参见客户端连接与 MCP 工作流。\n报价会锁定价格吗？\n开放 API 报价会在创建时重新计算，不返回锁价凭据。MCP 使用短期报价和／或单次操作的上限作为支出保护，不要混淆两种契约。\n联系支持应提供什么？\n提供公共请求 ID 或任务 ID、大致时间、错误码，以及期望行为的简短描述。移除 Key、Token、私有原图或提示词、签名 URL，然后联系支持。\n反馈生成图片或动画质量时，可先描述现象；只有在你主动决定并选择合适支持渠道时，才分享私有素材。\n按失败阶段继续排查\n上传与生成：文件、Alpha、模型参数、排队和部分结果。\n编辑、导出与透明：保存冲突、格式权益、编码和引擎显示。\nAPI 与 MCP 接入：OAuth、Scope、报价保护和不确定请求恢复。\n存储清理：空间不足、资源依赖、删除与恢复。\n没有得到任务结果时，不要默认换账号、换 Key 或重新生成。先查原任务和已有产物。"},{"id":"troubleshooting.generation-and-uploads","locale":"zh","title":"排查上传与生成问题","description":"区分上传前、参数校验和任务接受后的故障，并在不重复付费创建任务的前提下恢复制作。","section":"troubleshooting","path":"/docs/zh/troubleshooting/generation-and-uploads","url":"https://animgen.com/docs/zh/troubleshooting/generation-and-uploads","status":"stable","lastVerified":"2026-08-30","audience":["user","api-developer","ai-agent"],"productAreas":["documentation"],"tags":["upload","generation","ALPHA_REQUIRED","PAYLOAD_TOO_LARGE","上传失败","生成失败"],"translations":{"en":"https://animgen.com/docs/en/troubleshooting/generation-and-uploads","zh":"https://animgen.com/docs/zh/troubleshooting/generation-and-uploads"},"headings":[{"id":"先定位失败阶段","title":"先定位失败阶段","level":2},{"id":"上传问题","title":"上传问题","level":2},{"id":"输入或模型参数不支持","title":"输入或模型参数不支持","level":2},{"id":"已接受任务看似卡住","title":"已接受任务看似卡住","level":2},{"id":"生成成功但效果不好","title":"生成成功但效果不好","level":2},{"id":"用简短安全的信息求助","title":"用简短安全的信息求助","level":2}],"text":"先定位失败阶段\n记录所选账户/工作区、大致时间、可见错误码和已知任务 ID。不要公开私有图片数据、凭据或签名 URL。\n上传失败、创建请求被拒绝、已经接受的任务失败，需要不同处理。发生超时后，先查任务历史或保存的任务 ID，再决定是否重新生成。\n上传问题\n现象或错误码\n下一步检查\nPAYLOAD_TOO_LARGE\n按返回上限减少真实文件字节\n图片无效 / UNSUPPORTED_MEDIA_TYPE\n检查真实解码格式与 MIME，不只看扩展名\n图片尺寸被拒绝\n按返回的宽高限制缩放\nSTORAGE_QUOTA_EXCEEDED\n检查账户空间并安全清理资源\n上传 URL 过期\n核对原上传状态后，再准备新上传\n传输完成但没有文件 ID\n完成上传确认，只有 PUT 不代表整条流程结束\nMCP 使用本地图片时，客户端必须在 prepare_image_upload 与 complete_image_upload 之间传输真实字节，声明大小必须与原文件一致。不能把本地路径当成 HTTP URL 或图片文件 ID。\nWeb 上传与公开 API 对相似错误可能使用不同结构或错误码，应读取实际错误详情及公开错误参考。\n输入或模型参数不支持\n切换模式、模型、分辨率或时长后，重新查询模型能力。检查参考图总数、可选字段和提示词要求。\n遇到 ALPHA_REQUIRED 时，检查每张参与生成的图片。Alpha 通道完全不透明的 PNG，或者画有棋盘格的图片，不算有效透明。首尾帧模式两张都要符合，参考图模式则包含全部参考。\n修复参数意味着请求和报价发生变化。AI 不能悄悄移除必须的尾帧、换更贵模型，或绕过积分上限。\n已接受任务看似卡住\nqueued、running、cancelling 都不是终态。应限频、限时轮询，不要连续点击生成。本地等待超时或关闭浏览器不会取消已接受任务。\n任务到达 failed 或 cancelled 后，阅读错误及现有输出。供应商生成失败与后续导出失败不同，后者可能已经有可用源视频。\n取消是尽力执行，应报告实际积分记录，不承诺失败或取消就完全免费。\n生成成功但效果不好\n肢体被裁时，检查原图构图和输入画布；外观不一致时，简化参考图与提示词；循环接缝差或停顿不合适时，检查 Advanced Editor中的帧选择。\n适用时复用已有动作重新导出。新的 AI 生成是一项新的付费决定，不应作为默认排障步骤。\n用简短安全的信息求助\n通过私密支持渠道提供错误码、可用的 request ID、任务 ID、时间和失败阶段，并说明是否已有源视频或部分输出。移除 Token、包含隐私的提示词、图片正文及签名链接。"}]}