Reference Media

Use reference images, videos, and audio to guide AI generation with the AirCube API.

Some models support reference media — existing images, videos, or audio files that guide the generation process. This enables more controlled outputs like style transfer, character consistency, and audio-driven video.

Reference parameters

Parameter	Type	Max items	Description
`reference_images`	string[]	9	URLs of reference images
`reference_videos`	string[]	3	URLs of reference videos
`reference_audios`	string[]	3	URLs of reference audio files

These parameters are used with the reference-to-video task and other reference-aware tasks.

Prompt markers

When using reference media, you can reference specific items in your prompt using numbered markers:

Marker	References
`@image1`, `@image2`, ...	Items from `reference_images` (1-indexed)
`@video1`, `@video2`, ...	Items from `reference_videos` (1-indexed)
`@audio1`, `@audio2`, ...	Items from `reference_audios` (1-indexed)

These markers tell the model which reference to use for which part of the generation.

Example: Reference-to-video

Generate a video using reference images and audio.

cURL

curl -X POST https://aircube.ai/api/v3/wan-2.1/reference-to-video \
  -H "Authorization: Bearer $AIRCUBE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "@image1 walks through a forest while @audio1 plays in the background",
    "reference_images": [
      "https://example.com/character.jpg"
    ],
    "reference_audios": [
      "https://example.com/ambient-forest.mp3"
    ],
    "duration": "5"
  }'

Python

import os
import time
import requests

API_KEY = os.environ["AIRCUBE_API_KEY"]
BASE_URL = "https://aircube.ai/api/v3"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

# Submit with multiple references
response = requests.post(
    f"{BASE_URL}/wan-2.1/reference-to-video",
    headers=HEADERS,
    json={
        "prompt": "@image1 walks through a forest while @audio1 plays in the background",
        "reference_images": [
            "https://example.com/character.jpg",
        ],
        "reference_audios": [
            "https://example.com/ambient-forest.mp3",
        ],
        "duration": "5",
    },
)
generation_id = response.json()["data"]["id"]

# Poll
while True:
    result = requests.get(f"{BASE_URL}/status/{generation_id}", headers=HEADERS).json()
    if result["data"]["status"] == "completed":
        print(result["data"]["output_url"])
        break
    elif result["data"]["status"] == "failed":
        print("Failed")
        break
    time.sleep(5)

JavaScript

const API_KEY = process.env.AIRCUBE_API_KEY;
const BASE_URL = "https://aircube.ai/api/v3";

const submitRes = await fetch(`${BASE_URL}/wan-2.1/reference-to-video`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    prompt:
      "@image1 walks through a forest while @audio1 plays in the background",
    reference_images: ["https://example.com/character.jpg"],
    reference_audios: ["https://example.com/ambient-forest.mp3"],
    duration: "5",
  }),
});
const { data } = await submitRes.json();

while (true) {
  const pollRes = await fetch(`${BASE_URL}/status/${data.id}`, {
    headers: { Authorization: `Bearer ${API_KEY}` },
  });
  const result = await pollRes.json();
  if (result.data.status === "completed") {
    console.log(result.data.output_url);
    break;
  } else if (result.data.status === "failed") {
    throw new Error("Failed");
  }
  await new Promise((r) => setTimeout(r, 5000));
}

Multiple reference images

You can provide up to 9 reference images and use them selectively in your prompt:

{
  "prompt": "@image1 and @image2 are standing together in a park, cinematic lighting",
  "reference_images": [
    "https://example.com/person-a.jpg",
    "https://example.com/person-b.jpg"
  ],
  "duration": "5"
}

Supported formats

All reference media URLs are downloaded automatically. Supported formats:

Type	Formats
Images	jpg, jpeg, png, webp, gif
Videos	mp4, webm, mkv
Audio	mp3, wav, m4a

Tips

Use clear reference images — high-resolution, well-lit images with distinct subjects produce the best results.
Match the prompt to markers — make sure your prompt text explains what each reference should be used for.
Start simple — try with a single reference image before combining multiple references.
Check model support — not all models support all reference types. Check the model catalog for supported tasks.

Reference Media

On this page