---
title: "Generate a video from 1-5 reference images and a text prompt (references-to-video). Unlike createVideo, which animates a single source image, this composes a new scene that borrows characters, objects, and style from the reference images. Each image can be a URL or base64. Synchronous: the call blocks until rendering finishes and returns the video URL and its actual duration in seconds. Choose the output shape with `aspect_ratio` (\"default\" lets the model decide). The chosen `model` and `duration` must be compatible (incompatible combinations return HTTP 400). Credits are charged only on success, based on the produced duration and never more than the duration you requested. Pass an optional `request_id` to tag the result so you can locate it later via `getVideoResults`. Related tools: `createVideo` for image-to-video, `editVideo` to modify a generated video. Requires an API key (user scope)."
method: POST
path: "/assets/video/references"
tags: ["Videos"]
---

# Generate a video from 1-5 reference images and a text prompt (references-to-video). Unlike createVideo, which animates a single source image, this composes a new scene that borrows characters, objects, and style from the reference images. Each image can be a URL or base64. Synchronous: the call blocks until rendering finishes and returns the video URL and its actual duration in seconds. Choose the output shape with `aspect_ratio` ("default" lets the model decide). The chosen `model` and `duration` must be compatible (incompatible combinations return HTTP 400). Credits are charged only on success, based on the produced duration and never more than the duration you requested. Pass an optional `request_id` to tag the result so you can locate it later via `getVideoResults`. Related tools: `createVideo` for image-to-video, `editVideo` to modify a generated video. Requires an API key (user scope).

`POST /assets/video/references`

## Request body

- ReferencesToVideoPayloadPublic — Payload for generating a video from 1-5 reference images and a text prompt.
  - `prompt` string, required — Text description of the video to generate.
  - `images` string[], required — Reference images (1 to 5), each a URL or base64. The generated video borrows characters, objects, and style from them.
  - `duration` number, float — Video length in seconds.
  - `model` 'eagle' | 'eagle-audio' — Video model to use.
  - `aspect_ratio` 'default' | 'ar_1_1' | 'ar_16_9' | 'ar_9_16' | 'ar_4_3' | 'ar_3_4' | 'ar_21_9' — Output aspect ratio. "default" lets the model choose.
  - `request_id` string — Optional client-provided identifier for this request. Use this to retrieve results later via the results endpoint.

## Response `200`

Success

- VideoResult
  - `url` string — URL to the generated video file
  - `duration` number, float — Duration of the video in seconds
  - `has_audio` boolean
  - `request_id` string
  - `created_at` integer

## Other responses

- `400` — Error

---

[API](https://skmtc.net/ludo/apis/ludo-ai-api.md) · [All operations](https://skmtc.net/ludo/apis/ludo-ai-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/ludo/ludo-ai-api/revisions/3af866d68651/schema)