Skip to main content

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

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

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.

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

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