> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dreamlayer.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Image-to-video

> Animate one owned first-frame reference using the same quoted Video workflow.

## What this lets you do

Turn one reference image into an MP4. Describe movement, camera behavior, and sound. The reference supplies the first frame; it does not guarantee exact identity, fine detail, or motion throughout the result.

## What you need

* An API key with Video enabled and enough API credits
* One PNG, JPEG, or WebP reference, at most 20 MiB and 4096 pixels per side
* A nonblank prompt of at most 4,000 characters
* `curl` and `jq` for the examples

The quote checks the normalized image's size and dimensions. Use an image owned by the authenticated account and accept the quote before the source expires.

## Steps

### 1. Upload the reference

```bash theme={null}
curl --fail-with-body https://api.dreamlayer.io/v1/input-assets \
  -H "Authorization: Bearer $DREAMLAYER_API_KEY" \
  -F 'file=@./reference.png' --output video-input.json
```

Keep the returned `input_asset_id`. Do not pass a local path or an arbitrary image URL as the source of a video quote.

### 2. Quote the animation

```bash theme={null}
jq '{
  operation: "image_to_video",
  input_asset_id: .input_asset_id,
  input_mode: "first_frame",
  prompt: "Animate this scene with a gentle camera push, leaves swaying in the breeze, and soft outdoor ambience.",
  options: {duration_seconds: 10, resolution: "720p", generate_audio: true}
}' video-input.json > video-quote-request.json

curl --fail-with-body https://api.dreamlayer.io/v1/video/quotes \
  -H "Authorization: Bearer $DREAMLAYER_API_KEY" \
  -H "DreamLayer-Version: 1" \
  -H "Content-Type: application/json" \
  --data-binary @video-quote-request.json --output video-quote.json

jq '{status, quote_id, expires_at, resolved_settings, customer_price}' video-quote.json
```

Do not set `options.aspect_ratio` or request a fixed aspect in the prompt. Image-to-video uses the source-driven native aspect profile; a fixed aspect request is rejected rather than silently cropped. Only one source image is supported.

### 3. Approve, accept, and follow

Follow [text-to-video steps 3 through 5](/agent-api/text-to-video#3-review-and-authorize-the-price) using this `video-quote.json`. Review the resolved settings and price, save the acceptance body and a new stable idempotency key, then submit to `/v1/execute`.

The acceptance contains only `quote_id` and `max_credits`. The source, prompt, and sound settings are already bound to the quote. Poll the returned execution and use the [authenticated download flow](/agent-api/video-jobs#3-download-the-mp4).

## Confirm it worked

The execution reads `completed`, the MP4 downloads, and the first-frame content and motion are suitable for your project. Review audio as well as visuals.

## Common errors

* `404 asset_expired` while quoting: the source is missing, expired, or unavailable to this account.
* `409 asset_expired` on acceptance: the quoted source is no longer usable. Confirm no execution was admitted before uploading a replacement and obtaining another quote.
* `422 unsupported_settings`: remove a fixed aspect request, reduce the source size, or use a supported duration and resolution.
* `422 invalid_request`: supply exactly one source for `image_to_video`; do not attach a source to `text_to_video`.

## Troubleshooting

Do not re-upload after an uncertain acceptance. Recover the original quote and execution first. A replacement upload has a new asset ID and requires a new quote. Existing image conversations are not used as implicit video references.

## Next steps

* [Video settings and sound](/agent-api/video-settings)
* [Progress, download, and recovery](/agent-api/video-jobs)
* [Input asset handling](/agent-api/assets)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.