# Video API

Source: https://provod.ai/en/docs/videos

*Create a video and retrieve the result*

Video generation runs as a background job. `POST /v1/videos` returns `202` and a job ID; download the completed file in a separate request.

| Step                                        | Endpoint                              | Result                   |
| ------------------------------------------- | ------------------------------------- | ------------------------ |
| Choose a model                              | `GET /v1/videos/models`               | Capabilities and pricing |
| [Create a video](/en/docs/video-generation) | `POST /v1/videos`                     | Job ID and `polling_url` |
| [Check the job](/en/docs/video-jobs)        | `GET /v1/videos/{id}`                 | Status and result        |
| Download                                    | `GET /v1/videos/{id}/content?index=0` | Video bytes              |

Use a [workspace API key](/en/docs/authentication). These endpoints also accept the `/api/v1/videos` prefix. Do not add `/v1` twice.

## Choose a model

```bash
export API_BASE_URL="https://api.provod.ai"
export PROVOD_API_KEY="YOUR_API_KEY"

curl --fail-with-body --silent --show-error \
  "$API_BASE_URL/v1/videos/models" \
  -H "Authorization: Bearer $PROVOD_API_KEY" -o video-models.json

jq '.data[] | {id, available, supported_durations, supported_resolutions,
  supported_aspect_ratios, required_input_reference_types, currency,
  minimum_price_per_second}' video-models.json
```

Pass the exact `id` as `model`. The unified catalog also supports `GET /api/models?kind=video`; these examples use the dedicated `/v1/videos/models` catalog and its field names.

Check `available` and `unavailable_reason`, then the model constraints:

* `supported_durations`, `supported_resolutions`, `supported_sizes`, `supported_aspect_ratios`: output settings;
* `supported_frame_images`: first/last frame support;
* `supported_input_reference_types` and `required_input_reference_types`: accepted and required source media;
* `input_constraints`: known file limits;
* `generate_audio` and `seed`: support for those controls.

A `null` or missing bound does not mean unlimited support. Individually listed values may not work in every combination. Catalog availability does not guarantee success for every request.

## Pricing and balance

`currency` identifies the catalog currency. `minimum_price_per_second` is a minimum estimate, not an exact price for every mode. The charge depends on the model and variant, including resolution and audio. Multiplying the minimum rate by duration is not a guaranteed quote.

Creating a job reserves funds. Successful completion settles the charge using the saved pricing snapshot; final failure releases the reservation. Funds may remain reserved while a job is running or being retried by the service. Check final charges in [usage and costs](/en/docs/usage-costs).

When present, public `usage.cost` is expressed in USD, not rubles. For provod.ai, actual ruble charges appear in the balance history. `usage.is_byok` is `false`.

There is currently no public exact-price quote endpoint authenticated by API key. The cabinet estimate belongs to its session-authenticated interface; it is not `/v1/videos/quote`.

## Next steps

Choose a model without required source media and [generate from text](/en/docs/video-generation). Save its ID and set up [polling or a webhook](/en/docs/video-jobs).

## Troubleshooting


**Model unavailable**


Refresh the catalog and check `available`, `unavailable_reason` and the exact model ID. Do not substitute an ID from the text catalog.
