> For the complete documentation index, see [llms.txt](https://docs.nebulablock.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nebulablock.com/api-reference/inference-api/videos.md).

# Videos

Submit, poll, and stream asynchronous video generations on Nebula Block.

Generate video from a text prompt or an input image. Because generation is long-running, this API is asynchronous: creating a generation returns immediately, and you poll for the result.

For a walkthrough, see [Video Generation](/products/serverless-inference/video-generation.md).

## Create a video generation

### HTTP Request

`POST` `{API_URL}/videos/generations`

where `API_URL = https://inference.nebulablock.com/v1`.

### Body Parameters

#### model `string` *required*

The video model to use, for example `Google/veo-3.1-fast`. Must be a video model — passing a text or image model returns `400` with code `invalid_model_type`.

#### prompt `string` *required*

The text prompt describing the video.

#### n\_seconds `integer`

Duration of the generated video in seconds. Between `1` and `24`. Defaults to `5`.

#### size `string`

Output size in `WxH` form. Defaults to `1280x720`.

#### aspect\_ratio `string`

Aspect ratio of the output — `"16:9"`, `"9:16"`, or `"1:1"`.

#### resolution `string`

Output resolution — `"720p"`, `"1080p"`, or `"4k"`. Higher resolutions cost more.

#### image\_url `string`

Publicly reachable URL of the source image. **Required for image-to-video models** (those with `-i2v` in the model ID); omitting it returns `400` with code `missing_parameter`.

#### include\_audio `boolean`

Generate audio alongside the video. Supported by Veo models, and increases the cost of the generation.

#### seed `integer`

Seed for reproducible generation.

#### provider\_options `dict`

Provider-specific options passed through unchanged.

#### user `string`

An optional identifier for the end user making the request.

### Response Attributes

#### id `string`

The generation ID. Use it to poll for the result.

#### object `string`

Always `video.generation`.

#### created\_at `integer`

Unix timestamp of when the generation was created.

#### status `string`

One of `pending`, `in_progress`, `completed`, or `failed`.

#### model `string`

The resolved model name.

#### estimated\_cost `float`

The estimated cost of the generation in USD, returned when the job is created.

#### url `string`

Download URL for the finished video. Present only when `status` is `completed`.

#### error `dict`

Error details. Present only when `status` is `failed`.

### Example

#### Request

```bash
curl -X POST "https://inference.nebulablock.com/v1/videos/generations" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $NEBULA_API_KEY" \
    --data-raw '{
        "model": "Google/veo-3.1-fast",
        "prompt": "A time-lapse of the Montreal skyline at sunset, cinematic, 35mm",
        "n_seconds": 5,
        "resolution": "720p"
    }'
```

#### Response

```json
{
  "id": "b3f1c0e2-6d1a-4e2b-9f77-6a1a2b3c4d5e",
  "object": "video.generation",
  "created_at": 1756944000,
  "status": "pending",
  "model": "Google/veo-3.1-fast",
  "estimated_cost": 0.6
}
```

## Retrieve a video generation

### HTTP Request

`GET` `{API_URL}/videos/generations/{generation_id}`

### Example

#### Request

```bash
curl "https://inference.nebulablock.com/v1/videos/generations/$GENERATION_ID" \
    -H "Authorization: Bearer $NEBULA_API_KEY"
```

#### Response

```json
{
  "id": "b3f1c0e2-6d1a-4e2b-9f77-6a1a2b3c4d5e",
  "object": "video.generation",
  "created_at": 1756944000,
  "status": "completed",
  "model": "Google/veo-3.1-fast",
  "url": "https://..."
}
```

## Stream generation progress

### HTTP Request

`GET` `{API_URL}/videos/generations/{generation_id}/stream`

Streams progress as Server-Sent Events until the generation reaches a terminal state. Use this instead of polling when you want to surface progress in a UI.

## Errors

| Status | Code                         | Meaning                                                                                       |
| ------ | ---------------------------- | --------------------------------------------------------------------------------------------- |
| `400`  | `model_not_found`            | The model ID does not exist                                                                   |
| `400`  | `invalid_model_type`         | The model is not a video model                                                                |
| `400`  | `model_not_supported`        | The model is not currently dispatchable                                                       |
| `400`  | `missing_parameter`          | An `-i2v` model was called without `image_url`                                                |
| `402`  | `insufficient_credits`       | Your balance cannot cover the estimated cost                                                  |
| `403`  | `enterprise_access_required` | The model is restricted to enterprise accounts                                                |
| `429`  | `rate_limit_exceeded`        | Daily or per-minute limit reached — see [Tiers and Rate Limits](/account/tiers-and-limits.md) |

## See also

* [Video Generation](/products/serverless-inference/video-generation.md)
* [Images](/api-reference/inference-api/images.md)
* [Model Catalog](/products/serverless-inference/model-catalog.md)