🎉 Free generations on your first purchase of each pack — up to 20 Lite videos + 20 Lite images + 10 Medium videos + 10 Pro images + 2 Pro videos.

Get started

Codex Can Generate Video Now

Codex already works in your terminal. With the DreamUtopia REST API, the same session can turn a product photo into a short clip, animate a portrait, or chain a finished image into a first-frame video. Paste one skill file, ask in plain English, and the agent handles the upload, the request and the polling. You keep working in the same conversation while the render runs on our servers.

Start with a real example

These are the prompts paired with this page’s examples. Open the generator, choose an example, then adjust one detail at a time.

A coastal road at golden hour, camera drifting forward as the ocean glints below the cliffs.

Example prompt 01

A coastal road at golden hour, camera drifting forward as the ocean glints below the cliffs.

A hot-air balloon drifting over misty vineyards at sunrise, its reflection moving across the river below.

Example prompt 02

A hot-air balloon drifting over misty vineyards at sunrise, its reflection moving across the river below.

A paper lantern festival at dusk, lanterns rising as the camera tilts up into the warm sky.

Example prompt 03

A paper lantern festival at dusk, lanterns rising as the camera tilts up into the warm sky.

Codex Video Generation, Without Leaving the Terminal

Codex video generation becomes a normal part of a coding session when the agent can call a media API directly. Coding agents are good at running commands, reading JSON responses and retrying with judgment, which is exactly what an image-to-video API needs. Instead of leaving the terminal to open a web app, you can ask Codex to turn ./photo.png into a five-second 720p clip and get a signed result URL back in the same conversation. We built the DreamUtopia API as plain REST for this reason. There is no MCP server to configure and no plugin to install. One skill file teaches the agent the base URL, the authentication header, the multipart upload for reference images, the video creation endpoint, the shared job endpoint and the terminal-state rules. One pasted skill and one environment variable are the whole setup. The same key also works from your own scripts, so the agent and your build pipeline share one integration and one credit balance. A video job is slower than an image job, usually between one and three minutes, so the polling loop matters. The skill tells the agent to wait with backoff, to stop on a terminal failure, and never to retry a content-policy refusal or an empty balance. It also distinguishes a job that is still queued from one that has stopped making progress. That distinction is the difference between a calm wait and a retry storm. A polling loop that retries indiscriminately can consume the allowance before the first render finishes, while a loop that stops too early abandons a job that was still progressing. For a repository that ships media alongside code, the practical gain is that the person writing the component can also produce the clip it needs, without losing the context of the change or copying files between tools. The agent can explain a failed render in the same voice it uses for a failing test, and it can keep the result next to the code that references it.

What You Get

One copy-paste skill

Paste the skill block below into the Codex chat. The agent follows the recipe for the rest of the conversation without extra prompting. The text is short enough to read in one sitting and specific enough that the agent does not improvise field names. It states the exact values each field accepts, so a malformed request is corrected before it reaches the API. Nothing is written to your repository and nothing is installed.

Local photos handled

Ask the agent to use a file in the project. It sends a multipart upload, receives an upload id, and uses that id as the first frame. JPEG, PNG and WebP are accepted up to 30 MB. A file in the repository never needs a public URL first, which keeps private product shots out of a separate hosting step.

Every video shape

Image-to-video, text-to-video and first-and-last-frame transitions share one key. Choose 480p, 720p or 1080p and a duration from five to fifteen seconds. The Lite tier caps at 720p and ten seconds; Medium and Pro reach 1080p and fifteen seconds. The skill reads those ceilings from the live model list instead of guessing.

Jobs that outlive the chat

Every render runs on our servers. If the session ends, the agent can list recent jobs by id and collect the result later. The signed link stays valid for seven days, long enough to download the file or copy it into a build artifact. A failed job keeps its error code, so the next session can explain what happened. Collecting the result later is also safer than holding a terminal open for several minutes while the render completes, especially on a remote machine or an intermittent connection.

Plain-English motion

Describe the shot, not the API: a slow push-in, a drift to the right, hair moving in the wind. The skill maps your words to model tier, resolution, duration and aspect ratio, then checks the live price matrix before it spends. You can still name exact settings when a task needs them, and the agent reports the settings it chose so an unexpected result is easier to diagnose. An ambiguous request is resolved with one clarifying question instead of a speculative render that spends credits on the wrong duration.

One price list

The API and the web app charge the same credits. GET /v1/models returns the live resolution, duration and credit matrix, so the agent can compare a five-second clip with a ten-second one before it creates anything. Credits are charged when the job is created and returned automatically if it fails.

How It Works

1

Create and export the key

Open Profile, then API keys, and create a named key. Export it as DREAMUTOPIA_API_KEY in the shell that launches Codex. Keys are available to paid accounts, are shown once, and can be revoked without touching your other integrations.

2

Paste the skill

Copy the block below and paste it into the Codex chat. The agent then knows the endpoints, field names and polling rules for that conversation. The skill also states what not to do: do not retry a refused job, and do not paste the key into the conversation. Repeat the paste in a new session; nothing is added to your repository.

3

Ask for a clip

Write a normal request: animate ./product.png with a slow orbit and soft window light. The agent chooses settings, can check /v1/models first, and handles the upload when the source is a local file. If the request is ambiguous, it asks one short question rather than guessing at a duration or an aspect ratio.

4

Poll and use the result

The agent polls GET /v1/generations/{id} until the job succeeds, then returns the signed result URL. It backs off between polls and stops on a terminal failure instead of retrying a content-policy refusal or a spent balance. The final answer includes the job id as well as the link, so the result can be found again after the conversation is gone.

Paste the DreamUtopia Skill into Codex

Copy the skill below and paste it into the Codex chat. The agent then knows the API surface, the video ceilings, the error rules and when not to retry for the rest of the conversation.

Paste into Codex
Download
> Paste this into the Codex chat. It teaches the agent the DreamUtopia API for the
> rest of the conversation. Keep the `DREAMUTOPIA_API_KEY` in your shell environment,
> not in the pasted text.

# DreamUtopia media generation

Use this skill when the user asks you to generate an image or a video with DreamUtopia.

## Prerequisites

- **API access requires a paid account.** Keys cannot be minted by a free account.
- The user sets their key in the environment:

  ```sh
  export DREAMUTOPIA_API_KEY="du_live_..."
  ```

  If `DREAMUTOPIA_API_KEY` is unset, **stop and ask the user to set it**. Never write the key
  into a project file, a commit, or a message.
- Base URL: `https://api.dreamutopia.net/v1`
- Every request sends `Authorization: Bearer $DREAMUTOPIA_API_KEY`.

## Keeping this skill current

This skill is served by the product and can change without notice. If a request fails in a way
this document does not describe — an unknown field, an unexpected status or error code, or a
route that returns `404` — the skill may be stale. Re-fetch it, paste the new version into the
conversation, and re-read it before retrying:

```sh
curl -fsSL https://dreamutopia.net/skills/dreamutopia/codex.md
```

Do not invent request fields from memory. The re-fetched file is the current contract; the copy
in the conversation is only a snapshot.

## 1. Upload a local reference image (optional)

Only needed when the user has a local file. A previous generation's `result.url` can be used
directly instead.

```sh
curl -sS -X POST https://api.dreamutopia.net/v1/uploads \
  -H "Authorization: Bearer $DREAMUTOPIA_API_KEY" \
  -F "file=@/path/to/photo.png"
```

Response `201`:

```json
{ "id": "<upload_id>",
  "url": "<upload_url>",
  "expires_at": "2026-10-31T12:00:00Z" }
```

Use `id` (not `url`) in the next request. Accepted: JPEG, PNG, WebP, up to 30 MB.
`id` only works for the account that uploaded it.

## 2. Create an image

```sh
curl -sS -X POST https://api.dreamutopia.net/v1/images/generations \
  -H "Authorization: Bearer $DREAMUTOPIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "lite",
    "prompt": "a red fox in fresh snow, cinematic",
    "resolution": "2k",
    "aspect_ratio": "1:1"
  }'
```

| Field | Values |
|---|---|
| `model` | `lite`, `pro` |
| `resolution` | `2k`, `4k` (`lite` accepts `2k` only) |
| `aspect_ratio` | `1:1`, `4:3`, `3:4`, `16:9`, `9:16`, `3:2`, `2:3`, `adaptive` |
| `reference_images` | array of upload ids or DreamUtopia URLs; 0–3 for `lite`, 0–14 for `pro` |
| `prompt` | non-empty, up to 8000 characters |

`adaptive` requires at least one reference image. `resolution` defaults to `2k` and
`aspect_ratio` to `1:1`.

Response `202`:

```json
{ "id": "3f2b…", "type": "image", "status": "queued", "created_at": "2026-10-24T12:00:00Z" }
```

## 3. Create a video

```sh
curl -sS -X POST https://api.dreamutopia.net/v1/videos/generations \
  -H "Authorization: Bearer $DREAMUTOPIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "medium",
    "prompt": "the fox turns and looks at the camera",
    "image": "<upload_id>",
    "resolution": "720p",
    "duration": 8
  }'
```

| Field | Values |
|---|---|
| `model` | `lite`, `medium`, `pro` |
| `resolution` | `480p`, `720p`, `1080p` (`lite` cannot use `1080p`) |
| `duration` | 5–10 seconds (`lite`), 5–15 (`medium`), 5–30 (`pro`) |
| `image` | first-frame upload id or DreamUtopia URL (omit for text-to-video) |
| `last_frame_image` | requires `image`; not supported by `lite` |
| `generate_audio` | `pro` only, and the account must hold premium; `lite` and `medium` are rejected |

Response `202` with `type: "video"`.

## 4. Poll until it finishes

```sh
curl -sS https://api.dreamutopia.net/v1/generations/$MID \
  -H "Authorization: Bearer $DREAMUTOPIA_API_KEY"
```

`status` is one of `queued`, `processing`, `succeeded`, `failed`.

- Poll every 3–5 seconds, backing off to 10 seconds. Give up after about 10 minutes.
- On `succeeded`, download `result.url`. The link is valid for 7 days.
- On `failed`, report `error.message` to the user and stop. A failed job is terminal; do
  **not** submit it again automatically.
- If an id is lost, `GET /generations?limit=20` lists recent jobs, newest first.

Terminal response:

```json
{
  "id": "3f2b…",
  "type": "video",
  "status": "succeeded",
  "model": "medium",
  "credits_used": 12,
  "created_at": "2026-10-24T12:00:00Z",
  "updated_at": "2026-10-24T12:02:10Z",
  "result": { "url": "<result_url>" },
  "error": null
}
```

## 5. Check credits and prices

```sh
curl -sS https://api.dreamutopia.net/v1/account -H "Authorization: Bearer $DREAMUTOPIA_API_KEY"
curl -sS https://api.dreamutopia.net/v1/models
```

`/models` is public and returns every tier's allowed resolutions and durations plus the
`resolution → duration → credits` matrix. Check it before choosing settings when the user
cares about cost.

## Errors

Every error body is exactly:

```json
{ "error": { "code": "insufficient_credits", "message": "You need more credits to generate." } }
```

| HTTP | Meaning |
|---|---|
| 400 | invalid input (`invalid_request`, `prompt_too_long`, `invalid_reference_image`, …) |
| 401 | missing, malformed, revoked or removed-account key |
| 402 | not enough credits |
| 403 | unpaid key creation, or audio requested without premium |
| 404 | unknown job, or a job belonging to another account |
| 409 | `Idempotency-Key` reused with a different body, or still in flight |
| 413 / 415 | upload too large / not a supported image |
| 429 | rate limited; read `Retry-After` |
| 500 / 503 | internal; retry later |

Retry only HTTP `429`, `timeout` and `internal` responses. Never retry
`insufficient_credits`, and never resubmit a job that already finished as `failed`.

## Idempotency

Send `Idempotency-Key: <unique value>` on a create request. A retry with the same key and
body returns the existing job (`200`) instead of creating and charging a second one. Use a
fresh value for every genuinely different request.

## Complete example

```sh
#!/usr/bin/env bash
set -euo pipefail
: "${DREAMUTOPIA_API_KEY:?set DREAMUTOPIA_API_KEY first}"
API="https://api.dreamutopia.net/v1"

ID=$(curl -sS -X POST "$API/images/generations" \
  -H "Authorization: Bearer $DREAMUTOPIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"lite","prompt":"a red fox in fresh snow","resolution":"2k","aspect_ratio":"1:1"}' \
  | jq -r .id)

while :; do
  BODY=$(curl -sS "$API/generations/$ID" -H "Authorization: Bearer $DREAMUTOPIA_API_KEY")
  STATUS=$(jq -r .status <<<"$BODY")
  case "$STATUS" in
    succeeded) jq -r .result.url <<<"$BODY"; break ;;
    failed)    jq -r .error.message <<<"$BODY" >&2; exit 1 ;;
    *)         sleep 4 ;;
  esac
done
```

Explore related tools

Choose the tool that matches your next step.

Frequently Asked Questions

By the DreamUtopia Team · Last updated November 15, 2026

Do I need an MCP server to generate video from Codex?

▼
No. The API is plain HTTP, and the skill teaches Codex to call it with curl. You do not need an MCP server, a CLI binary or a plugin. The only setup is pasting the skill and the environment variable.

Where should the API key live?

▼
In the shell environment as DREAMUTOPIA_API_KEY. Keep it out of the pasted skill, the repository and the prompt. The skill tells the agent to stop and ask if the variable is missing, which prevents a half-configured request.

Can the agent upload a local photo as the first frame?

▼
Yes. Ask it to use a file in the project. The agent sends a multipart upload, receives an upload id, and passes that id to the video request. JPEG, PNG and WebP are accepted up to 30 MB, which covers most camera and product images.

How long can a generated clip be?

▼
Five to fifteen seconds depending on the tier. The Lite tier stops at ten seconds; Medium and Pro reach fifteen. The skill reads the ceiling from GET /v1/models before it sends the request, so an over-long duration is corrected rather than rejected.

Which resolutions are available?

▼
480p, 720p and 1080p. The Lite tier caps at 720p, while Medium and Pro render 1080p. Aspect ratio is adaptive by default, and the agent can pick a portrait, square or landscape frame when the destination is known.

How are credits charged for a video?

▼
Credits are charged when the job is created and returned automatically if it fails. The live price matrix is at GET /v1/models, and the skill checks it when you ask about cost. A paid account is required before a key can be created.

What happens if I close the session?

▼
The job keeps running on our servers. Use GET /v1/generations/{id} with the id, or list recent jobs with GET /v1/generations?limit=20. The signed result URL stays valid for seven days, so there is no rush to collect it.

Give Codex a Video Tool

Create a key, paste the skill, and ask for your first clip. The API docs cover every field, status and error code.