Reference to video - Five API

Reference to video builds a new video around assets you provide: the look of a character or product from images, the motion of a clip, the sound of an audio file. The prompt says how to combine them.

Model	Endpoint	Resolutions	Duration	Assets
Video Fast 1.0	`POST /v1/video-fast/v1.0/reference-to-video`	480p, 768p	3–30 s	up to 9 images, 3 videos, 3 audio files
Wan 3.0 Spark	`POST /v1/wan/v3.0-spark/reference-to-video`	480p, 720p, 1080p	2–30 s	up to 10 images, 5 videos, 5 audio files

Name your assets in the prompt

Assets are numbered by their position in each array, starting at 1:

Token	Refers to
`@Image1`, `@Image2`, …	`reference_images[0]`, `reference_images[1]`, …
`@Video1`, `@Video2`, …	`reference_videos[0]`, `reference_videos[1]`, …
`@Audio1`, `@Audio2`, …	`reference_audios[0]`, `reference_audios[1]`, …

{
  "prompt": "@Image1 walks along the beach at sunset carrying @Image2, the camera follows, @Audio1 plays softly",
  "reference_images": [
    "https://assets.example.com/inputs/character.png",
    "https://assets.example.com/inputs/surfboard.png"
  ],
  "reference_audios": ["https://assets.example.com/inputs/theme.mp3"],
  "duration": 8,
  "resolution": "480p"
}

Create a task

curl https://api.fiveapi.ai/v1/wan/v3.0-spark/reference-to-video \
  -H "Authorization: Bearer $FIVEAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "@Image1 and @Image2 dance together in a sunlit studio, the camera circles them",
    "reference_images": [
      "https://assets.example.com/inputs/dancer-a.png",
      "https://assets.example.com/inputs/dancer-b.png"
    ],
    "duration": 5,
    "resolution": "720p",
    "webhook_url": "https://hooks.example.com/fiveapi"
  }'

import os
import requests

task = requests.post(
    "https://api.fiveapi.ai/v1/wan/v3.0-spark/reference-to-video",
    headers={"Authorization": f"Bearer {os.environ['FIVEAPI_API_KEY']}"},
    json={
        "prompt": "@Image1 and @Image2 dance together in a sunlit studio, the camera circles them",
        "reference_images": [
            "https://assets.example.com/inputs/dancer-a.png",
            "https://assets.example.com/inputs/dancer-b.png",
        ],
        "duration": 5,
        "resolution": "720p",
        "webhook_url": "https://hooks.example.com/fiveapi",
    },
    timeout=30,
).json()
print(task["id"], task["status"])

const res = await fetch("https://api.fiveapi.ai/v1/wan/v3.0-spark/reference-to-video", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.FIVEAPI_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    prompt: "@Image1 and @Image2 dance together in a sunlit studio, the camera circles them",
    reference_images: [
      "https://assets.example.com/inputs/dancer-a.png",
      "https://assets.example.com/inputs/dancer-b.png",
    ],
    duration: 5,
    resolution: "720p",
    webhook_url: "https://hooks.example.com/fiveapi",
  }),
});
const task = await res.json();
console.log(task.id, task.status);

Parameters

Field	Required	Description
`prompt`	yes	What to generate, naming the assets with `@Image1`, `@Video1`, `@Audio1`. Up to 2,000 characters.
`reference_images`	at least one asset	Array of public HTTPS image URLs.
`reference_videos`	at least one asset	Array of public HTTPS video URLs.
`reference_audios`	at least one asset	Array of public HTTPS audio URLs.
`duration`	yes	Length in seconds, within the model’s range.
`resolution`	yes	One of the model’s resolutions.
`webhook_url`, `metadata`	no	See Webhooks and Tasks.

Send at least one asset. image_url is not accepted on reference to video: put a start image in reference_images instead.

Asset limits

Model	Images	Videos	Audio
Video Fast 1.0	Up to 9; JPG, PNG or WebP; 256–5,760 px; at most 30 MB each	Up to 3; 2–15 seconds and at most 50 MB each	Up to 3; at most 15 MB each; send with an image or a video
Wan 3.0 Spark	Up to 10; JPG, PNG or WebP; at most 20 MB each	Up to 5; at most 100 MB each	Up to 5; at most 15 MB each

Every URL follows the URL policy. The files are downloaded and prepared while the task is queued, so a reference task stays queued a little longer than a text task. Keep presigned URLs valid for at least an hour.

Tips for good results

One subject per image. A clean shot of the character or product on a plain background works best.
Refer to every asset in the prompt, so the model knows the role of each one.
Say what each asset is for: “@Image1 is the main character, @Video1 shows the dance move to copy”.
Keep the scene simple when you combine several characters, and describe their positions: “on the left”, “in the background”.