Generate video

Create a job with POST /v1/videos. Set API_BASE_URL and CICORA_API_KEY as shown in the overview.

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.

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.

Request fields

First and last frames

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

{
  "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.

{
  "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