Guide a Video with Reference Images

Use this guide when pictures should guide a video — keep a character's face, a product's look, a brand's style — without forcing an exact first or last frame. By the end you will have submitted a reference-to-video job with input_references.

Submitting POST /v1/videos starts a real video job and is billed in DA when the clip is delivered.

Before you start#

• An API key in OPENDUNES_API_KEY.
• One or more pictures at public HTTPS addresses that answer 200 with an image type.
• A video model that takes reference pictures. Not every model does, and the model list has no field that says so: read the model's description on GET /v1/videos/models or its page in the catalogue.

Step 1: Say how to use the references#

Reference pictures work best when the prompt says what must stay the same:

The woman from the reference pictures walks through the Casbah of Algiers at dusk.
Keep her face, her red scarf and her green jacket exactly as in the references.

Step 2: Submit the job#

curl https://opendunes.com/v1/videos \
  -H "Authorization: Bearer $OPENDUNES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bytedance/seedance-2.0-fast",
    "prompt": "The woman from the reference pictures walks through the Casbah of Algiers at dusk. Keep her face, her red scarf and her green jacket exactly as in the references.",
    "duration": 5,
    "input_references": [
      { "type": "image_url", "image_url": { "url": "https://your-cdn.example/character-front.jpg" } },
      { "type": "image_url", "image_url": { "url": "https://your-cdn.example/character-side.jpg" } }
    ]
  }'

The answer is 202, with the job's id, its polling_url and its status. input_references travels to the model as you send it. A model that takes no reference, or a value it does not take, is refused by its provider, and the words come back.

Step 3: Poll and download#

Poll GET /v1/videos/{id} until status is completed, then fetch the clip from GET /v1/videos/{id}/content — or pass a callback_url and be told when it ends. See Generate and Download a Video from Text.

References or frames#

input_references guides. To pin the exact first or last frame, use frame_images — see Turn an Image into a Video.