@imageN reference not working in a Seedance prompt: ordering and content array pitfalls

When an @imageN reference fails in a Seedance prompt on RelayDance, the cause is usually a mismatch between the order of items in metadata.content[] and the @image tokens in your prompt: @image1 maps to the first content entry, @image2 to the second, and so on. You can include up to 9 reference images, 3 reference videos and 3 audio tracks per request, and each token must point to an existing index in the array.

How the @imageN token maps to the content array

Each @imageN token refers to the item at position N in metadata.content[], so ordering is the primary pitfall. If your prompt cites @image2 but only one item exists in the array, the reference cannot resolve. Reference media go in metadata.content[] and are cited in the prompt as @image1 to @imageN. The per-request ceilings are fixed: up to 9 reference images, 3 reference videos and 3 audio tracks, with clips up to 15 seconds. According to the official relaydance.com/docs, keep the array order stable so every token has a matching entry. See the current model list at relaydance.com/models.

Steps to fix a broken reference

To repair a non-resolving @imageN reference, align the array index with the token before resubmitting.

1. List your reference media in metadata.content[] in the exact order you intend to cite them.
2. Confirm @image1 points to the first entry, @image2 to the second, and so on.
3. Check that no token exceeds the array length or the limit of 9 reference images.
4. Submit the task with POST /v1/video/generations, then poll GET /v1/video/generations/{task_id} until status is succeeded or failed.
5. If it errors, correct the mapping and retry: 据 relaydance.com 官方文档,「Failed or errored requests are never billed」, so retries during debugging carry no charge.

Verifying the endpoint and SDK setup

A reference can also appear to fail when requests hit the wrong endpoint, so verify the base URL first. RelayDance is OpenAI-compatible: 据 relaydance.com 官方文档,「Set base_url to https://relaydance.com/v1 and keep your OpenAI SDK」. Authenticate with Authorization: Bearer YOUR_API_KEY, using keys created at the console. Submit video tasks with model, prompt, seconds, and metadata (including content[], ratio, resolution, generate_audio, and optional callback_url). For webhook mode, set metadata.callback_url and the final state is POSTed to your server. Full details are at relaydance.com/docs.

Cost while testing reference prompts

Debugging reference ordering does not create billing risk, because failed requests are not charged and pricing is pay-as-you-go per generated video.

Only successful generations are billed, so correcting an @imageN mapping and resubmitting adds no cost for the failed attempts. Live per-model rates are at relaydance.com/models.

FAQ

Why does @image3 fail when I only listed two images? The token points to index 3 in metadata.content[], which does not exist. Add a third entry or change the token to @image1 or @image2.

How many reference images can I use per request? Up to 9 reference images, plus up to 3 reference videos and 3 audio tracks, with clips up to 15 seconds.

Am I charged for a request that errors on a bad reference? No. 据 relaydance.com 官方文档,「Failed or errored requests are never billed」.