Troubleshoot uploads and generation
Identify whether a problem happened before upload, during request validation, or after job acceptance, and recover without duplicate paid work.
On this page
Locate the failing stage first
Keep the selected account/workspace, approximate time, visible error code, and known task ID. Do not publish private image data, credentials, or signed URLs.
A failed upload, a rejected create request, and a failed accepted task need different responses. After a timeout, check task history or the persisted task ID before starting another generation.
Upload problems
| Symptom or code | Check next |
|---|---|
PAYLOAD_TOO_LARGE |
Reduce actual bytes according to the returned limit |
Invalid image / UNSUPPORTED_MEDIA_TYPE |
Verify decoded format and MIME, not just extension |
| Image dimensions rejected | Resize within the service's returned width/height limits |
STORAGE_QUOTA_EXCEEDED |
Review account storage and safe resource cleanup |
| Upload URL expired | Prepare a new upload only after checking the original upload state |
| Completed transfer but no file ID | Complete the upload; a PUT alone is not the whole flow |
For local images in MCP, the client must transfer actual bytes between prepare_image_upload and complete_image_upload. The declared byte size must match the original file. Do not pass a local path as an HTTP URL or an image file ID.
Web upload errors and the public API may use different envelopes or codes for similar validation failures. Read the current error details and the public error reference.
Unsupported input or model parameters
Rediscover model capabilities after switching mode, model, resolution, or duration. Check total reference count, optional-field support, and prompt requirements.
For ALPHA_REQUIRED, inspect every participating image. A PNG with a fully opaque Alpha channel or a painted checkerboard is not meaningful transparency. In first + last frame mode both images must qualify; reference mode includes every reference.
Changing parameters to fix validation means the request and quote have changed. An AI must not quietly remove a required end image, pick a more expensive model, or bypass a credit cap.
Accepted tasks that appear stuck
queued, running, and cancelling are nonterminal. Poll with a bounded interval and deadline; do not repeatedly click Generate. A local waiting deadline or closed browser does not cancel accepted work.
If the task is terminally failed or cancelled, read its error and available outputs. A provider failure and a later export failure are different: a source video may already exist in the second case.
Cancellation is best effort. Report actual credit accounting instead of promising that failed or cancelled work was free.
Quality problems after a successful generation
For cropped limbs, inspect original framing and input canvas. For inconsistent appearance, simplify reference images and the prompt. For a poor loop seam or unwanted pause, inspect frame selection in Advanced Editor.
Use retained motion for another export when appropriate. A new AI generation is a new paid decision, not the default troubleshooting step.
Escalate with a small, safe report
Privately provide support with the error code, request ID where available, task ID, time, and failing stage. Include whether a usable source video or partial outputs exist. Redact tokens, prompts containing private material, image bodies, and signed links.
Was this page helpful?
No search queries, code, or free text are collected. This switch controls documentation interactions only; general site analytics follow the privacy policy. Privacy policy