> ## Documentation Index > Fetch the complete documentation index at: https://docs.spatius.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create a Video > Accepts an Avatar ID and public audio URL, saves a job, and immediately returns its ID. Media processing happens asynchronously; poll the job every 15 seconds until it succeeds, fails, or expires. Video access must be enabled separately from Avatar creation. Apps owned by one account share video jobs, retry keys, and independent video rate limits. Accepted jobs count toward creation limits even if processing later fails. The Console API does not impose an active-video-job quota; the video service manages execution concurrency. Use requestId to retry uncertain submissions without creating another render. A retry returns the existing job's current state. Use a new requestId to render again after a terminal failure. ## OpenAPI ````yaml /openapi/video-open-api.json post /videos openapi: 3.0.3 info: title: Spatius Video API version: 1.0.0 description: >- Generate an MP4 from an existing Avatar and an audio URL. Submit a job, poll its status, and download the result. Video API access requires separate account enablement. See the [Video generation guide](/api-reference/video-generation) and [Authentication](/api-reference/authentication). servers: - url: https://console.spatius.ai/v1/open description: Spatius Console API (global) security: - AppId: [] ApiKey: [] tags: - name: Videos description: Submit asynchronous video generation jobs. - name: Video Jobs description: Read video job history and get fresh MP4 download links. paths: /videos: post: tags: - Videos summary: Create a Video description: >- Accepts an Avatar ID and public audio URL, saves a job, and immediately returns its ID. Media processing happens asynchronously; poll the job every 15 seconds until it succeeds, fails, or expires. Video access must be enabled separately from Avatar creation. Apps owned by one account share video jobs, retry keys, and independent video rate limits. Accepted jobs count toward creation limits even if processing later fails. The Console API does not impose an active-video-job quota; the video service manages execution concurrency. Use requestId to retry uncertain submissions without creating another render. A retry returns the existing job's current state. Use a new requestId to render again after a terminal failure. operationId: createVideo requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateVideoRequest' example: avatarId: d385dd22-9200-4806-94a0-dce464ca916d audioUrl: https://example.com/media/speech.wav name: Welcome video requestId: 9628ee92-d5d9-4eac-bf2a-39cd3f804f02 video: width: 1024 height: 1024 responses: '200': description: Job accepted, or an existing job returned for a retry. content: application/json: schema: $ref: '#/components/schemas/CreateVideoResponse' example: jobId: 6f1e2b3c-9a1d-4e5f-8b0a-2c4d6e8f0a1b status: queued createdAt: '2026-09-12T09:00:00Z' '400': $ref: '#/components/responses/InvalidRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/ServiceUnavailable' components: schemas: CreateVideoRequest: type: object required: - avatarId - audioUrl properties: avatarId: type: string description: >- An existing public Avatar, an Avatar actively assigned to your account, or an Avatar explicitly allowed for your account. Access is checked on every creation and before rendering. format: uuid audioUrl: type: string description: >- Audio source in WAV format only, at most 500 MiB and no longer than 20 minutes. Use a public HTTP(S) URL without embedded credentials. Signed query parameters are supported. Keep the URL accessible for the preparation window of up to 30 minutes. Each transfer has a five-minute limit. The source must return a supported Content-Type; application/octet-stream is not supported. See [Media requirements](/api-reference/video-generation#media-requirements). format: uri minLength: 1 maxLength: 4096 pattern: ^https?://[^/?#@\s]+([/?#].*)?$ backgroundUrl: type: string description: >- Optional background image, at most 50 MiB. Use a public HTTP(S) URL without embedded credentials. Signed query parameters are supported. Keep the URL accessible for the preparation window of up to 30 minutes. Each transfer has a five-minute limit. The source must return a supported Content-Type; application/octet-stream is not supported. See [Media requirements](/api-reference/video-generation#media-requirements). Its pixel dimensions determine omitted output dimensions according to the [Output sizing rules](/api-reference/video-generation#output-sizing). format: uri minLength: 1 maxLength: 4096 pattern: ^https?://[^/?#@\s]+([/?#].*)?$ name: type: string description: >- Optional job name. When omitted, Spatius generates a name from the job ID. minLength: 1 maxLength: 128 requestId: type: string description: >- Optional retry key, shared across Apps owned by your account. The same requestId and normalized input return the existing job without consuming creation quota again. Different input with the same key returns HTTP 409. Omitted video.width, video.height, and video.fit are distinct from explicit values, even if output is identical. Other omitted presentation settings remain equivalent to their documented defaults. Keep the key and request body unchanged when retrying an uncertain response. Requests accepted before the change to background-based sizing can return 409 on replay even with the original body; check the existing job before submitting a new requestId. Omit this field to create a new job on every call. format: uuid video: $ref: '#/components/schemas/VideoSettings' CreateVideoResponse: type: object required: - jobId - status - createdAt properties: jobId: type: string description: The accepted job ID. format: uuid status: allOf: - $ref: '#/components/schemas/VideoJobStatus' description: >- New jobs return queued. A retry returns the existing job's current status, which may already be terminal. createdAt: type: string description: Original acceptance time, including on a retry. format: date-time VideoSettings: type: object description: >- Optional presentation settings. When both dimensions are omitted and the background image dimensions are available, output follows the image size, scaled down proportionally to fit the limits and rounded down to even dimensions with a minimum of 64 pixels. If only one dimension is supplied, the missing dimension follows the background aspect ratio with the same rounding and minimum. Without usable background dimensions, each omitted dimension falls back to 1024. An invalid derived size can fail the job during preparation. Explicit dimensions must be even, from 64 to 1920, with an effective product at most 2,073,600 pixels; request validation substitutes 1024 for an omitted dimension. Omitted width, height, and fit remain distinct from explicit values for retry comparison. Encoding settings are managed by Spatius. Opening and closing transitions are included even when lead-in and lead-out are zero. See [Output sizing](/api-reference/video-generation#output-sizing). properties: width: type: integer format: int32 minimum: 64 maximum: 1920 multipleOf: 2 description: >- Output width in pixels. If omitted, derive from the background image according to the output sizing rules; fall back to 1024 when background image dimensions are unavailable. Omission is distinct from an explicit value for retry comparison. height: type: integer format: int32 minimum: 64 maximum: 1920 multipleOf: 2 description: >- Output height in pixels. If omitted, derive from the background image according to the output sizing rules; fall back to 1024 when background image dimensions are unavailable. Omission is distinct from an explicit value for retry comparison. fit: type: string description: >- How the Avatar fits the output frame. If omitted, use contain when both width and height are omitted and background image dimensions are available; otherwise use crop. An explicit value takes precedence and is distinct from omission for retry comparison. enum: - crop - contain backgroundColor: type: string description: Six-digit RGB hex color. pattern: ^#[0-9a-fA-F]{6}$ default: '#000000' backgroundFit: type: string description: How the background image fits the output frame. enum: - cover - contain - stretch default: cover leadInSeconds: type: number format: double minimum: 0 maximum: 60 default: 0 description: Additional idle time before the opening transition. Must be finite. leadOutSeconds: type: number format: double minimum: 0 maximum: 60 default: 0 description: Additional idle time after the closing transition. Must be finite. VideoJobStatus: type: string enum: - queued - processing - succeeded - failed - expired description: >- New jobs start queued. Successful output becomes expired after its retention deadline. Failed jobs remain failed. Error: type: object description: The single public error envelope returned by every Spatius API endpoint. properties: error: type: object properties: code: type: string description: Stable machine-readable error code. enum: - unauthorized - forbidden - invalid_request - not_found - conflict - rate_limit_exceeded - service_unavailable - internal_error message: type: string description: Human-readable explanation specific to this occurrence. requestId: type: string description: >- Unique identifier for this request. Quote it when contacting support. responses: InvalidRequest: description: The request has invalid fields, settings, or pagination. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: invalid_request message: Invalid video request or presentation settings. requestId: b3f0c2d1-4a5b-4c6d-8e9f-0a1b2c3d4e5f Unauthorized: description: Missing or mismatched App credentials, or an inactive owner account. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: unauthorized message: Unauthorized. requestId: b3f0c2d1-4a5b-4c6d-8e9f-0a1b2c3d4e5f Forbidden: description: >- Video access is absent, creation is disabled, or Avatar access is denied. Disabling creation alone preserves reads. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: forbidden message: Video API access is not configured. requestId: b3f0c2d1-4a5b-4c6d-8e9f-0a1b2c3d4e5f Conflict: description: >- The requestId already identifies different normalized input. Omitted video.width, video.height, and video.fit differ from explicit values. Retry the original body. Requests accepted before the change to background-based sizing can conflict even with the original body; check the existing job before using a new UUID, which creates another render. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: conflict message: requestId was already used for a different video request requestId: b3f0c2d1-4a5b-4c6d-8e9f-0a1b2c3d4e5f RateLimited: description: >- An independent video request limit was exceeded. Back off before retrying. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: rate_limit_exceeded message: Open API rate limit exceeded. requestId: b3f0c2d1-4a5b-4c6d-8e9f-0a1b2c3d4e5f InternalError: description: >- Unexpected server failure. Use bounded backoff and retain the creation requestId when retrying. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: internal_error message: An internal error occurred. requestId: b3f0c2d1-4a5b-4c6d-8e9f-0a1b2c3d4e5f ServiceUnavailable: description: >- Temporary service or download-link availability failure. Retry with the same requestId and body for creation, or retry the detail read. A link refresh failure preserves saved success. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: service_unavailable message: Video generation is unavailable; retry later. requestId: b3f0c2d1-4a5b-4c6d-8e9f-0a1b2c3d4e5f securitySchemes: AppId: type: apiKey in: header name: X-App-ID description: Your Spatius App ID. ApiKey: type: apiKey in: header name: X-API-Key description: The API key bound to the App ID. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.