---
title: "Start a video generation"
method: POST
path: "/api/v1/video-generations"
tags: ["Videos"]
---

# Start a video generation

`POST /api/v1/video-generations`

## Request

- Base URL: `https://your-deployment.example.com`
- URL: `https://your-deployment.example.com/api/v1/video-generations`
- Auth: one of:
  - HTTP bearer
  - API key in header `x-api-key`

Queues a video generation and returns `202` with the job. Poll `GET /api/v1/video-generations/{id}` until `state` is `succeeded`, `failed`, `blocked` or `cancelled`. On success, `output.availability` says whether the clip can be downloaded: `ready` means `output.url` is a signed download URL valid for 15 minutes (re-fetch the job for a fresh one); `pending_scan` means the saved file is still being scanned, so keep re-fetching the job (self-hosted installs can stay here for up to ~30 minutes); `unavailable` means the file was blocked or deleted and `output.url` will never be set, so stop polling. Credits for the requested duration are reserved up front and settled on completion; a failed or cancelled job is not charged. A `blocked` job is not charged either, unless the provider generated the clip before rejecting it and billed it: then the requested duration is charged and `credits.settled` shows it. Send an `Idempotency-Key` header (1-255 printable ASCII characters) to make retries safe: a repeat with the same key and body returns the original job, and the same key with a different body is a 422 `idempotency_key_reused`. Omitted fields take the model defaults from `GET /api/v1/video-models`. Set `organization_id` to bill an organization you belong to, or `null` to bill your personal credits; omitted, the job bills your home organization (or your personal credits if you have none). Keys are scoped to the billed account, so the same key sent for a different `organization_id` starts a new job. An organization-billed API key always bills its own organization (see `organization_id`).

## Request body

- CreateVideoGenerationRequest
  - `model` string, required: A model id from GET /api/v1/video-models.
  - `prompt` string, required
  - `mode` 'text_to_video' | 'image_to_video': Defaults to image_to_video when input_image_file_id is set, else text_to_video.
  - `duration_seconds` number: Defaults to the model's default duration.
  - `aspect_ratio` '16:9' | '9:16' | '1:1' | '4:3' | '3:4' | '3:2' | '2:3' | '21:9'
  - `resolution` '360p' | '480p' | '720p' | '1080p' | '4k'
  - `input_image_file_id` string: An image file you own, for image_to_video.
  - `audio` boolean
  - `organization_id` string, nullable: The organization to bill: one you belong to, or null for your personal credits. Omitted bills your home organization, or your personal credits if you have none. An organization-billed API key always bills its own organization: omit this or set it to the key's organization; any other value, null included, is rejected with a 403 (`errorCode: billing_organization_mismatch`).

## Response `202`

Accepted; the job is queued (or replayed for a repeated Idempotency-Key).

- CreateVideoGenerationResponse202
  - `id` string, required
  - `object` 'video_generation', required
  - `state` 'pending' | 'running' | 'storing' | 'succeeded' | 'failed' | 'blocked' | 'cancelled', required
  - `model` string, required
  - `mode` 'text_to_video' | 'image_to_video', required
  - `prompt` string, required
  - `duration_seconds` number, required
  - `aspect_ratio` '16:9' | '9:16' | '1:1' | '4:3' | '3:4' | '3:2' | '2:3' | '21:9', required
  - `resolution` '360p' | '480p' | '720p' | '1080p' | '4k', required
  - `source` 'api' | 'studio' | 'agent', required
  - `progress` number, nullable, required
  - `error` object, nullable, required
    - `code` 'content_blocked' | 'provider_timeout' | 'provider_error' | 'region_unavailable' | 'output_too_large' | 'input_image_not_found' | 'cancelled', required
    - `message` string, required
  - `output` object, nullable, required
    - `availability` 'ready' | 'pending_scan' | 'unavailable', required: `ready`: url is set. `pending_scan`: the saved file is still being scanned; re-fetch the job until it changes (self-hosted installs can stay here for up to ~30 minutes). `unavailable`: the file was blocked by the scan or deleted and url will never be set; stop polling.
    - `url` string, nullable, required: Signed download URL, valid until expires_at; re-fetch the job for a fresh one. Set only when availability is `ready`, otherwise null.
    - `expires_at` string, nullable, required: ISO 8601. When url stops working; null whenever url is.
    - `content_type` string, required
    - `duration_seconds` number, required
    - `file_id` string, nullable, required: The Files entry, or null when the clip was stored outside Files.
  - `credits` object, required
    - `reserved` number, nullable, required
    - `settled` number, nullable, required
  - `created_at` string, required
  - `updated_at` string, required

## Other responses

- `400`: An organization-billed API key bills an organization that no longer exists, or one its owner is no longer a member of; re-mint the key.
- `401`: Missing or invalid credentials.
- `403`: The API key lacks the `ai:generate` scope, or the billing organization names one you do not belong to (or is not a valid id), or an organization-billed API key names any organization but its own (`errorCode: billing_organization_mismatch`).
- `404`: `input_image_file_id` does not name an image you own (`errorCode: input_image_not_found`). A nonexistent `organization_id` is `404` only for an admin caller; for anyone else it is `403`.
- `405`: The path does not serve this HTTP method.
- `422`: The request cannot run: a body or capability violation (`errorCode` names it, e.g. `unsupported_duration`), an unknown or unavailable model (`model_unavailable`), a model your administrator disabled (`model_disabled`), too few credits (`insufficient_credits`), or an Idempotency-Key problem (`invalid_idempotency_key`, `idempotency_key_reused`).
- `429`: Per-user rate limit exceeded.

---

[API](https://skmtc.dev/bike4mind/apis/bike4mind-api.md) · [All operations](https://skmtc.dev/bike4mind/apis/bike4mind-api/llms.txt) · [OpenAPI document](https://skmtc.dev/bike4mind/apis/bike4mind-api/revisions/db47495b892f?raw)