> ## 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.

# Text-to-video

> Get a quote for a scene, authorize its API credit price, and start a video with sound.

## What this lets you do

Generate an MP4 from a text description. A quote previews the resolved settings and credit price without starting generation. Accepting it starts a real, billable execution.

## What you need

* A server-side DreamLayer API key in `DREAMLAYER_API_KEY`
* Enough available API credits for the returned quote
* `curl` and `jq` for the examples below
* A unique idempotency key, saved with each accepted quote

## Steps

### 1. Check availability

```bash theme={null}
curl --fail-with-body https://api.dreamlayer.io/v1/video/capabilities \
  -H "Authorization: Bearer $DREAMLAYER_API_KEY" \
  -H "DreamLayer-Version: 1"
```

Continue only when `enabled` is `true`. Read `default_duration_seconds`, `audio_default`, `resolution`, `max_images`, and `quote_required`. Video capability is separate from `/v1/capabilities`, which describes image and sprite operations.

### 2. Request a quote

```bash theme={null}
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" \
  -d '{
    "operation": "text_to_video",
    "prompt": "A slow camera push toward a waterfall in a forest, with rushing water and birdsong.",
    "options": {
      "duration_seconds": 10,
      "resolution": "720p",
      "aspect_ratio": "16:9",
      "generate_audio": true
    }
  }' --output video-quote.json

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

The prompt must be nonblank and at most 4,000 characters. Omit `generate_audio` to use the sound-on default, unless your prompt requests silence. Explicit options and prompt instructions must agree. See [settings and sound](/agent-api/video-settings).

### 3. Review and authorize the price

Check that `status` is `ready`, the currency is `api_credits`, and the resolved settings match what you want. Quotes normally expire after 10 minutes; use the returned `expires_at`. A `pricing_pending` quote is not executable.

The amount is a decimal string. This example checks the quote and prepares an acceptance file using its exact credit amount. **Run the submission only after you approve that price.** Store the file and key before submitting, and keep the quote private because it can contain request details.

```bash theme={null}
jq -e '
  .status == "ready" and
  .customer_price.currency == "api_credits" and
  (.customer_price.amount | tonumber) > 0 and
  (.customer_price.amount | tonumber) <= 100
' video-quote.json

# After the check succeeds and you approve the displayed price:
jq '{quote_id, max_credits: .customer_price.amount}' video-quote.json > video-accept.json
```

`max_credits` is your ceiling, not an extra fee. It must cover the quote and cannot exceed 100. Change the prompt or options by requesting a new quote, never by adding them to the acceptance body.

### 4. Start the approved execution

Choose a new key for this logical request. Save it with `video-accept.json`. Do not reuse this example key for another video.

```bash theme={null}
curl --fail-with-body https://api.dreamlayer.io/v1/execute \
  -H "Authorization: Bearer $DREAMLAYER_API_KEY" \
  -H "DreamLayer-Version: 1" \
  -H "Idempotency-Key: waterfall-video-001" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  --data-binary @video-accept.json --output video-execution.json
```

A successful acceptance returns `202` JSON with `execution_id`, `status`, and `video_job`. Persist the execution ID. Unlike image admission, Video can return `402 insufficient_credits` or `429 too_many_active_jobs` immediately, without creating an execution.

### 5. Follow progress

```bash theme={null}
VIDEO_EXECUTION_ID=$(jq -er '.execution_id' video-execution.json)
curl --fail-with-body "https://api.dreamlayer.io/v1/executions/$VIDEO_EXECUTION_ID" \
  -H "Authorization: Bearer $DREAMLAYER_API_KEY" \
  -H "DreamLayer-Version: 1"
```

Poll at a modest interval, such as five seconds, and back off on throttling. On `completed`, use `video_job.download_url`. See [downloads and event streams](/agent-api/video-jobs) for the complete retrieval flow.

## Confirm it worked

The canonical execution reads `completed`, its `video_job.download_url` is present, and the MP4 plays. Check the delivered metadata and listen to the audio. `requested_settings.generate_audio: true` records the requested setting; playing the result confirms it meets your needs.

## Common errors

* `422 clarification_required`: make the prompt and options agree, then request another quote.
* `409 quote_expired`: a new acceptance was not admitted; obtain a new quote and approve its price.
* `409 price_exceeds_limit`: your ceiling is below the quote. Do not raise it without approval.
* `402 insufficient_credits`: add API credits before resubmitting the approved request.
* `429`: back off. Do not create another quote or key to get around a limit.

## Troubleshooting

If submission times out, replay the exact saved acceptance body with the same API key and idempotency key. Do not generate a replacement quote automatically. An already-accepted quote returns its original execution even after its original expiry. If you have an execution ID, read it first.

## Next steps

* [Animate an image](/agent-api/image-to-video)
* [Adjust sound, settings, and pricing](/agent-api/video-settings)
* [Resume, download, cancel, and recover](/agent-api/video-jobs)


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