> For the complete documentation index, see [llms.txt](https://docs.avis.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.avis.xyz/api-reference/endpoints/video-generation.md). # Video Generation Create task: `POST /api/v1/video/generations` Read task: `GET /api/v1/video/tasks/:taskId` Video generation is task-based. The create endpoint returns the initial persisted task. Poll the task endpoint until `status` is terminal. Terminal statuses: `succeeded`, `failed`, `cancelled`. ### Request Fields | Field | Type | Required | Validation | Description | | --------------- | --------- | -------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `model` | string | Yes | Minimum length `1` | User-facing model identifier from `/ai/models`. | | `content` | object\[] | Yes | Non-empty array | Ordered text, image, and video inputs. For first/last-frame generation, order and image `role` matter. | | `duration` | integer | No | Positive integer | Desired duration in seconds. Allowed range/steps vary per model — read `capabilities.video.params.duration` from `GET /ai/models` for the selected model before sending this; see `capabilities.params` Value Shapes. | | `resolution` | string | No | `480p`, `720p`, `1080p`, `4k` | Resolution token. Allowed values vary per model — read `capabilities.video.params.resolution` from `GET /ai/models` for the selected model. | | `ratio` | string | No | String | Aspect ratio token, for example `16:9`, `9:16`, or `adaptive`. Open string; allowed values vary per model — read `capabilities.video.params.ratio` from `GET /ai/models` for the selected model. Forwarded to both BytePlus and OpenRouter video adapters. | | `generateAudio` | boolean | No | Boolean | Whether to generate synchronized audio. Supported by the Seedance 2.0 series and Seedance 1.5 Pro; defaults to true on those models. | | `seed` | integer | No | Integer, minimum `-1` | Seed for reproducible generation. The same seed yields similar - not guaranteed identical - output. Support and range vary by model. | | `watermark` | boolean | No | Boolean | Add an "AI Generated" watermark to the lower-right corner when the model supports it. | | `cameraFixed` | boolean | No | Boolean | Append a fixed-camera instruction to the prompt. Not supported by the Seedance 2.0 series; sending it to a Seedance 2.0 model returns Bad request status code `400`. | | `maxTokens` | integer | No | Positive integer | DTO accepts this field, but current BytePlus and OpenRouter video adapters reject it with `400` because video generation does not support `maxTokens`. | ### Video Content Parts | Type | Fields | Description | | ----------------- | ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `text` | `text: string` | Prompt text. | | `imageUrl` | `url: string`, `role?: string` | Public image URL. Optional `role` controls how the image is used. | | `imageBase64` | `data: string`, `mediaType?: string`, `role?: string` | Raw base64 image bytes or data URL. `mediaType` is required for raw base64. | | `videoUrl` | `url: string` | Public video URL. Accepted by DTO; provider support can vary. | | `videoBase64` | `data: string`, `mediaType?: string` | Raw base64 video bytes or full data URL. `mediaType` is required for raw base64. | | `audioUrl` | `url: string`, `role: string` | Public audio URL (wav or mp3). `role` is required and must be `referenceAudio`. Seedance 2.0 series only. | | `audioBase64` | `data: string`, `mediaType: string` | Raw base64 audio bytes or a full data URL. **`mediaType` is required** (`audio/mpeg`, `audio/mp3`, `audio/wav`, ...) - there is no safe default, so a missing/unsupported format returns `400`. Offloaded to storage and sent to the provider as a URL. Seedance 2.0 series only. | | `kycImageAssetId` | `assetId: string` | BytePlus KYC image asset id. Seedance 2.0 series only. | | `kycVideoAssetId` | `assetId: string` | BytePlus KYC video asset id. Seedance 2.0 series only. | | `kycAudioAssetId` | `assetId: string` | BytePlus KYC audio asset id. Seedance 2.0 series only. | The `kyc*AssetId` fields are for identity verification, not file upload. See Seedance 2.0 KYC Flow for details. > **File upload is not supported.** Provide your media as either a public URL (`imageUrl`, `videoUrl`, `audioUrl`) or inline base64 (`imageBase64`, `videoBase64`, `audioBase64`). There is no way to upload a file once and reuse it later — every request must include the full URL or base64 data. Audio input (`audioUrl` / `audioBase64`) is accepted only by the Seedance 2.0 series and cannot be sent alone - at least one image or video reference must accompany it in the same request, otherwise the request returns `400`. Image `role` values: | Value | Description | | ---------------- | -------------------------------------------------------------------- | | `firstFrame` | Treat image as the first frame/keyframe. | | `lastFrame` | Treat image as the last frame/keyframe. | | `referenceImage` | Treat image as a visual reference. This is the default when omitted. | ### Request Example ```json { "model": "seedance-1-0-pro", "content": [ { "type": "text", "text": "Smooth interpolation between the two frames" }, { "type": "imageUrl", "url": "https://example.com/first.jpeg", "role": "firstFrame" }, { "type": "imageUrl", "url": "https://example.com/last.jpeg", "role": "lastFrame" } ], "duration": 5, "resolution": "720p", "ratio": "16:9", "seed": 42, "generateAudio": false } ``` ### VideoTask Fields | Field | Type | Required | Description | | ------------------------ | --------- | -------- | ----------------------------------------------------------------------------------------------------------------- | | `taskId` | string | Yes | Provider-issued task id. Use this with `GET /video/tasks/:taskId`. | | `generationId` | string | Yes | Generation record id linked to this task. | | `providerId` | string | Yes | Stable provider id the task belongs to. | | `status` | string | Yes | Current task status: `queued`, `running`, `succeeded`, `failed`, or `cancelled`. | | `model` | string | Yes | User-facing model identifier used for the request. | | `content` | object\[] | Yes | Original ordered request content persisted with the task. Base64 values are truncated before database storage. | | `videoUrl` | string | No | URL for the generated video. For some providers this can be an API proxy URL or an archived signed URL. | | `downloadUrl` | string | No | Presigned R2 download link for the archived output. This URL expires; re-fetch instead of storing it permanently. | | `assetId` | string | No | Asset id of the archived output. Reuse via `videoAssetId` in later requests. | | `usage` | object | No | Provider-reported usage. | | `usage.completionTokens` | number | No | Tokens generated in completion when reported. | | `usage.totalTokens` | number | No | Total tokens consumed when reported. | | `usage.usdCost` | number | No | Provider-reported USD cost when the provider reports a billing figure. | | `usage.durationSeconds` | number | No | Output video duration in seconds for per-second-billed providers. | | `usage.providerUsage` | object | No | Full provider usage payload (provider/model-specific shape). | | `error` | string | No | Failure message when `status` is `failed`. | | `createdAt` | string | No | Task creation timestamp. | | `updatedAt` | string | No | Last task update timestamp. | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.avis.xyz/api-reference/endpoints/video-generation.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.