# Video API

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

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.cicora.ai"
export CICORA_API_KEY="YOUR_API_KEY"

curl --fail-with-body --silent --show-error \
  "$API_BASE_URL/v1/videos/models" \
  -H "Authorization: Bearer $CICORA_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. Actual cicora.ai charges appear in the USD 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.

## FAQ

### What is cicora.ai?

cicora.ai is a multi-model AI workspace and compatible API for chat, text, images, video, coding tools, and teams. Start with the [overview](/en.md), [documentation](/en/docs.md), or [model catalog](/en/models.md).

### How is usage billed?

Confirmed usage is charged in USD from the active workspace's prepaid balance. Use the live catalog for current model prices and the [usage guide](/en/docs/usage-costs.md) for settlement details.

### Which protocols and integrations are available?

Documentation covers OpenAI-compatible Chat Completions and Responses, Anthropic Messages, image interfaces, Claude Code, OpenCode, and Codex CLI. Compatibility does not imply support for every upstream parameter.

### Which sources are authoritative and current?

For model IDs, availability, capabilities, limits, and prices, use the [live catalog](/en/models.md). For API behavior, use the matching [documentation page](/en/docs.md). Never include API keys, private workspace data, or preview URLs in public documents.