# Reference pictures

Make a clip that keeps the look of pictures you give, without fixing any one frame.

1. [Pick a model that takes them](#1-pick-a-model-that-takes-them).
2. [Say what must stay the same](#2-say-what-must-stay-the-same).
3. [Send the job](#3-send-the-job) with the pictures in `input_references`.
4. [Wait and fetch the clip](#4-wait-and-fetch-the-clip).

## 1. Pick a model that takes them

No field of the video models list says whether a model takes reference pictures. Its description does, and on one model its price. On 2026-09-29, these models named them.

| Lab | Models | The list says |
|---|---|---|
| Alibaba | `alibaba/wan-3.0` | reference-guided video generation |
| Alibaba | `alibaba/wan-2.7` | multiple reference images guide the style and content |
| Alibaba | `alibaba/happyhorse-1.0`, `alibaba/happyhorse-1.1` | a set of reference images |
| ByteDance | `bytedance/seedance-2.0`, `-2.0-fast`, `-2.0-mini` | multimodal reference-to-video |
| ByteDance | `bytedance/seedance-2.5` | multimodal reference-based generation |
| xAI | `x-ai/grok-imagine-video` | reference-conditioned |
| MiniMax | `minimax/hailuo-2.3` | reference images as input |
| MiniMax | `minimax/hailuo-3` | its `pricing_skus` holds `reference_images` |

Read a model's description on its page in *Models* before you build on it. The other fields that narrow the choice: [Choose a video model](/docs/cookbook/choose-a-video-model).

## 2. Say what must stay the same

The pictures show the model what to keep. The prompt says what to keep, and what to change around it.

| Prompt part | Example |
|---|---|
| What the pictures hold | the mark from the reference picture |
| What must not change | its shape and its orange gradient |
| The new scene | carved in a clay tile on a potter's bench in Maatkas |
| Camera and light | slow orbit, soft window light |

## 3. Send the job

The sample sends the OpenDunes mark as the one reference picture, to `bytedance/seedance-2.0-fast`, for 5 seconds at `720p` in `1:1`. Up to the model, more pictures of the same thing, from other angles, hold it steadier.

```python
import json
import os
import urllib.request

API_KEY = os.environ["OPENDUNES_API_KEY"]
ADDRESS = "https://opendunes.com/v1/videos"
MODEL = "bytedance/seedance-2.0-fast"
REFERENCE = "https://opendunes.com/icon.png"
PROMPT = (
    "The mark from the reference picture, carved in a clay tile on a "
    "potter's bench in Maatkas, slow orbit, soft window light. Keep the "
    "mark's shape and its orange gradient."
)

request = urllib.request.Request(
    ADDRESS,
    data=json.dumps(
        {
            "model": MODEL,
            "prompt": PROMPT,
            "duration": 5,
            "resolution": "720p",
            "aspect_ratio": "1:1",
            "input_references": [
                {"type": "image_url", "image_url": {"url": REFERENCE}},
            ],
        }
    ).encode(),
    headers={
        "Authorization": "Bearer " + API_KEY,
        "Content-Type": "application/json",
    },
)
with urllib.request.urlopen(request) as response:
    job = json.load(response)

print(job["id"], job["status"])
```

```javascript
const API_KEY = process.env.OPENDUNES_API_KEY;
const ADDRESS = "https://opendunes.com/v1/videos";
const MODEL = "bytedance/seedance-2.0-fast";
const REFERENCE = "https://opendunes.com/icon.png";
const PROMPT =
  "The mark from the reference picture, carved in a clay tile on a " +
  "potter's bench in Maatkas, slow orbit, soft window light. Keep the " +
  "mark's shape and its orange gradient.";

const response = await fetch(ADDRESS, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: MODEL,
    prompt: PROMPT,
    duration: 5,
    resolution: "720p",
    aspect_ratio: "1:1",
    input_references: [
      { type: "image_url", image_url: { url: REFERENCE } },
    ],
  }),
});
const job = await response.json();

console.log(job.id, job.status);
```

```go
package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
	"os"
)

const (
	address   = "https://opendunes.com/v1/videos"
	model     = "bytedance/seedance-2.0-fast"
	reference = "https://opendunes.com/icon.png"
	prompt    = "The mark from the reference picture, carved in a clay " +
		"tile on a potter's bench in Maatkas, slow orbit, soft window " +
		"light. Keep the mark's shape and its orange gradient."
)

func main() {
	apiKey := os.Getenv("OPENDUNES_API_KEY")

	body, err := json.Marshal(map[string]any{
		"model":        model,
		"prompt":       prompt,
		"duration":     5,
		"resolution":   "720p",
		"aspect_ratio": "1:1",
		"input_references": []map[string]any{
			{
				"type":      "image_url",
				"image_url": map[string]string{"url": reference},
			},
		},
	})
	if err != nil {
		panic(err)
	}

	req, err := http.NewRequest("POST", address, bytes.NewReader(body))
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+apiKey)
	req.Header.Set("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	var job struct {
		ID     string `json:"id"`
		Status string `json:"status"`
	}
	if err := json.NewDecoder(res.Body).Decode(&job); err != nil {
		panic(err)
	}
	fmt.Println(job.ID, job.Status)
}
```

```bash cURL
ADDRESS="https://opendunes.com/v1/videos"
MODEL="bytedance/seedance-2.0-fast"
REFERENCE="https://opendunes.com/icon.png"
PROMPT="The mark from the reference picture, carved in a clay tile on a"
PROMPT="$PROMPT potter's bench in Maatkas, slow orbit, soft window light."
PROMPT="$PROMPT Keep the mark's shape and its orange gradient."

curl "$ADDRESS" \
  -H "Authorization: Bearer $OPENDUNES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$MODEL"'",
    "prompt": "'"$PROMPT"'",
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "1:1",
    "input_references": [
      {"type": "image_url", "image_url": {"url": "'"$REFERENCE"'"}}
    ]
  }'
```

| In each `input_references` entry | Holds |
|---|---|
| `type` | `image_url` |
| `image_url.url` | the picture's address: public HTTPS, answering with the picture itself |

<div class="watch-out">
<p>A picture behind a login, a cookie or a web page is not a picture the provider can read. Test the address in a private browser window: it must show the picture alone.</p>
</div>

The answer is `202`, with the job's `id` and `status` `pending`. Every field: [Clips](/docs/reference/videos).

<div class="good-to-know">
<p>References guide the look; they fix no frame. To make a picture the clip's exact first or last frame, send it in <code>frame_images</code>: <a href="/docs/cookbook/picture-to-video">Picture to video</a>. When both are sent, <code>frame_images</code> wins.</p>
</div>

## 4. Wait and fetch the clip

The job runs as any other: ask [`GET /v1/videos/{id}`](/docs/reference/videos-id) every ten seconds until it ends, then fetch the clip from `/v1/videos/{id}/content?index=0`, or give a `callback_url` and have the end posted to you. The whole loop, in four languages: [Text to video](/docs/cookbook/text-to-video). The post: [Video webhooks](/docs/cookbook/video-webhooks).

The clip is charged in DA once, when the job reports `completed`. On some models each picture sent in is charged too: the model's page in *Models* lists what it charges for, and Choose a video model names the models. A job that ends any other way charges nothing.
