# Generate video

Source: https://cicora.ai/en/docs/video-generation

Create a job with `POST /v1/videos`. Set `API_BASE_URL` and `CICORA_API_KEY` as shown in the [overview](/en/docs/videos).

## Generate from text

Replace `MODEL_ID_FROM_CATALOG` with an available model ID. This example requires a model that accepts text without mandatory references and supports **5 seconds, 720p, 16:9**. Change the values to match its catalog before sending.

```bash
export VIDEO_MODEL="MODEL_ID_FROM_CATALOG"

jq -n --arg model "$VIDEO_MODEL" '{
  model: $model,
  prompt: "A slow camera pan across a quiet mountain lake at sunrise.",
  duration: 5,
  resolution: "720p",
  aspect_ratio: "16:9"
}' > video-request.json

curl --fail-with-body --silent --show-error \
  "$API_BASE_URL/v1/videos" \
  -H "Authorization: Bearer $CICORA_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @video-request.json -o video-job.json

jq '{id, status, polling_url}' video-job.json
```

A `202` response confirms job creation, not completed generation. Keep `video-job.json` to [retrieve the result](/en/docs/video-jobs).

## Request fields

| Field            | Purpose                                                                          |
| ---------------- | -------------------------------------------------------------------------------- |
| `model`          | Required public model ID                                                         |
| `prompt`         | Scene description, up to 8,000 characters; model limits may be stricter          |
| `duration`       | Integer seconds from 1 to 120, further restricted by the model                   |
| `resolution`     | Catalog value such as `720p`                                                     |
| `size`           | Dimensions such as `1280x720`, when supported                                    |
| `aspect_ratio`   | Aspect ratio such as `16:9`                                                      |
| `generate_audio` | Generate sound, when supported                                                   |
| `seed`           | Integer from 0 to 2,147,483,647, when supported; not a reproducibility guarantee |
| `callback_url`   | Public HTTPS endpoint for completion notifications                               |

## First and last frames

Add `frame_images` to the main request. Use `first_frame` or `last_frame` only when the model supports it.

```json
{
  "frame_images": [
    {
      "type": "image_url",
      "frame_type": "first_frame",
      "image_url": {"url": "https://media.example.com/first-frame.jpg"}
    }
  ]
}
```

Replace the example URL with a real accessible file. `input_constraints.image` also applies to frames.

## Image, audio and video references

Each `input_references` entry contains a type and a nested URL. The following shows all three shapes; include only the entries required and supported by your model.

```json
{
  "input_references": [
    {"type": "image_url", "image_url": {"url": "https://media.example.com/reference.jpg"}},
    {"type": "audio_url", "audio_url": {"url": "https://media.example.com/reference.mp3"}},
    {"type": "video_url", "video_url": {"url": "https://media.example.com/reference.mp4"}}
  ]
}
```

Include every type listed in `required_input_reference_types`. Check duration, size, MIME type and file-count limits. If `reference_audio_requires_visual_input` is enabled, audio also needs visual input; check `maximum_reference_audio_duration_seconds` too.

For API calls, use HTTPS URLs that the provider can fetch without cookies or authorization headers. Local filesystem paths do not work. Temporary URLs must remain valid through queueing and processing. Cabinet uploads use a separate session-authenticated interface; there is no public multipart `/v1/videos/input-assets` endpoint.

## Sound and additional controls

`generate_audio=true` requests generated sound. An audio reference alone does not establish speech preservation, voice cloning or lip-sync support. Use such a mode only with a confirmed model contract; it is not guaranteed across video models.

`allowed_passthrough_parameters` lists permitted extension fields. Do not copy fields such as root-level `audio` from another service without checking our contract. `provider` and additional controls also depend on the supported route.

## Creation errors

For validation errors, check the fields and supported combination in the catalog. If HTTP disconnects after sending, do not automatically repeat creation: the job may already exist. `POST /v1/videos` has no public idempotency contract; a repeated POST may create another billable job.

## Troubleshooting


**Request rejected**


Check required references and file constraints against the catalog. Send only supported parameter combinations.

## 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.