🎉 每个积分包首次购买都有免费生成好礼 —— 最高 20 个 Lite 视频 + 20 张 Lite 图片 + 10 个 Medium 视频 + 10 张 Pro 图片 + 2 个 Pro 视频。

立即开始

Codex 现在可以生成视频了

Codex 已经在你的终端中运行。借助 DreamUtopia REST API,同一个会话可以将产品照片变成短片、让肖像动起来,或将已完成的图像串联成首帧视频。粘贴一个技能文件,用自然语言提问,智能体便会处理上传、请求和轮询。渲染在我们的服务器上运行时,你可以继续在同一对话中工作。

从实际示例开始

这些是本页示例所使用的提示词。打开生成器,选择一个示例,然后逐一调整细节。

黄金时刻的海滨公路,镜头缓缓向前漂移,海洋在悬崖下方波光粼粼。

示例提示词 01

黄金时刻的海滨公路,镜头缓缓向前漂移,海洋在悬崖下方波光粼粼。

日出时分,一只热气球飘浮在薄雾笼罩的葡萄园上空,它的倒影在下方河面上移动。

示例提示词 02

日出时分,一只热气球飘浮在薄雾笼罩的葡萄园上空,它的倒影在下方河面上移动。

黄昏时分的纸灯笼节,灯笼升起,镜头向上摇入温暖的天空。

示例提示词 03

黄昏时分的纸灯笼节,灯笼升起,镜头向上摇入温暖的天空。

Codex 视频生成,无需离开终端

当智能体能够直接调用媒体 API 时,Codex 视频生成就成了编码会话中正常的一部分。编码智能体擅长运行命令、读取 JSON 响应并凭判断重试,而这恰恰是图生视频 API 所需要的。你不必离开终端去打开网页应用,而是可以让 Codex 把 ./photo.png 变成一个五秒钟的 720p 片段,并在同一次对话中拿回一个带签名的结果 URL。正因如此,我们把 DreamUtopia API 构建成纯 REST。没有需要配置的 MCP 服务器,也没有需要安装的插件。一个技能文件就能教会智能体基础 URL、认证头、用于参考图像的多部分上传、视频创建端点、共享任务端点以及终态规则。粘贴一个技能并设置一个环境变量就是全部设置。同一个密钥也能在你自己的脚本中使用,因此智能体和你的构建流水线共享同一套集成和同一个额度余额。视频任务比图像任务慢,通常在一到三分钟之间,因此轮询循环很重要。该技能告诉智能体采用退避方式等待,在遇到终态失败时停止,并且绝不对内容策略拒绝或空余额进行重试。它还能区分仍在排队的任务与已停止推进的任务。这种区分就是平静等待与重试风暴之间的差别。不加区分地重试的轮询循环可能会在第一次渲染完成之前就耗尽额度,而过早停止的循环则会放弃一个仍在推进的任务。对于将媒体与代码一同交付的代码仓库,实际收益在于编写组件的人也能生成它所需的片段,而不会失去变更的上下文,也不必在工具之间复制文件。智能体可以用它处理失败测试时的同一种口吻来解释失败的渲染,并且可以把结果保存在引用它的代码旁边。

你会得到什么

一项复制粘贴技能

将下面的技能块粘贴到 Codex 聊天中。智能体会在接下来的对话中按照该配方执行,无需额外提示。文本足够简短,可以一次性读完,并且足够具体,智能体不会自行臆造字段名。它明确说明了每个字段所接受的确切值,因此格式错误的请求会在到达 API 之前被纠正。不会向你的代码仓库写入任何内容,也不会安装任何东西。

本地照片已处理

让 agent 使用项目中的文件。它会发送一个 multipart 上传,收到一个 upload id,并将该 id 用作第一帧。接受 JPEG、PNG 和 WebP,最大 30 MB。仓库中的文件永远不需要先有一个公开 URL,这使私密产品图片无需经过单独的托管步骤。

每种视频形式

图生视频、文生视频以及首尾帧过渡共用一个密钥。可选择 480p、720p 或 1080p,时长从五到十五秒。Lite 档位上限为 720p 和十秒;Medium 和 Pro 档位可达 1080p 和十五秒。该技能从实时模型列表中读取这些上限,而非进行猜测。

比聊天更持久的职位

每次渲染都在我们的服务器上运行。如果会话结束,智能体可以按 id 列出最近的作业,并在稍后收取结果。签名链接的有效期为七天,足以下载文件或将其复制到构建产物中。失败的作业会保留其错误代码,因此下一次会话可以解释发生了什么。与在渲染完成时保持终端打开数分钟相比,稍后收取结果也更安全,尤其是在远程机器或连接不稳定的情况下。

通俗易懂的运动

描述镜头,而非API:缓慢推近、向右漂移、头发随风飘动。该技能会将你的描述映射到模型档位、分辨率、时长和宽高比,然后在消费前检查实时价格矩阵。当任务需要时,你仍然可以指定精确设置,智能体会报告它所选择的设置,这样意外结果更容易诊断。模糊的请求会通过一个澄清问题来解决,而不是进行一次推测性渲染,把积分浪费在错误的时长上。

一份价目表

API 和 Web 应用扣除相同的积分。GET /v1/models 返回实时的分辨率、时长和积分矩阵,因此智能体可以在创建任何内容之前,先比较五秒片段与十秒片段。积分在任务创建时扣除,若任务失败则会自动退还。

工作原理

1

创建并导出密钥

打开 Profile,然后进入 API keys,创建一个有名称的密钥。在启动 Codex 的 shell 中将其导出为 DREAMUTOPIA_API_KEY。密钥仅对付费账户可用,仅显示一次,并且可以在不影响其他集成的情况下撤销。

2

粘贴技能

复制下面的区块并粘贴到 Codex 聊天中。代理随后就会知道该对话的端点、字段名和轮询规则。该技能还说明了哪些事情不要做:不要重试被拒绝的任务,也不要把密钥粘贴到对话中。在新的会话中重复粘贴;不会向你的代码仓库添加任何内容。

3

请求一个片段

写一个普通请求:用缓慢环绕和柔和窗光为 ./product.png 制作动画。代理会选择设置,可以先检查 /v1/models,并在源文件为本地文件时处理上传。如果请求含糊不清,它会问一个简短的问题,而不是猜测时长或宽高比。

4

投票并使用结果

代理会轮询 GET /v1/generations/{id},直到任务成功,然后返回已签名的结果 URL。它在轮询之间进行退避,并在遇到终态失败时停止,而不是对内容策略拒绝或余额耗尽进行重试。最终答案包含任务 id 以及链接,因此即使对话已不存在,也能再次找到结果。

将 DreamUtopia Skill 粘贴到 Codex 中

复制下面的技能并粘贴到 Codex 聊天中。此后在整个对话中,该智能体就能了解 API 接口、视频上限、错误规则以及何时不应重试。

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

探索相关工具

选择适合你下一步创作的工具。

常见问题

由DreamUtopia团队 · 更新于 2026年11月15日

我需要一个 MCP 服务器才能从 Codex 生成视频吗?

▼
不。该 API 是纯 HTTP,该技能教 Codex 用 curl 调用它。你不需要 MCP 服务器、CLI 二进制文件或插件。唯一的设置是粘贴该技能和环境变量。

API 密钥应该放在哪里?

▼
在shell环境中设置为DREAMUTOPIA_API_KEY。请勿将其写入粘贴的技能、代码仓库和提示词中。该技能会指示智能体在变量缺失时停止并询问,从而避免发出配置不完整的请求。

代理能否上传本地照片作为第一帧?

▼
是的。让它使用项目中的文件。代理会发送一个 multipart 上传,收到一个上传 id,并将该 id 传递给视频请求。JPEG、PNG 和 WebP 均可接受,最大 30 MB,足以覆盖大多数相机和产品图片。

生成的片段可以有多长?

▼
根据套餐不同,时长在五到十五秒之间。Lite 套餐上限为十秒;Med 和 Pro 可达十五秒。该技能在发送请求前会从 GET /v1/models 读取上限,因此过长的时长会被修正而非被拒绝。

有哪些分辨率可用?

▼
480p、720p 和 1080p。Lite 档位最高支持 720p,而 Medium 和 Pro 可渲染 1080p。宽高比默认自适应,当目标位置已知时,agent 可以选择竖屏、方形或横屏画幅。

视频的积分是如何扣除的?

▼
任务创建时即扣除积分,若任务失败则会自动退还。实时价格矩阵位于 GET /v1/models,当您询问费用时,该技能会进行检查。在创建密钥之前,需要拥有付费账户。

如果我关闭会话会发生什么?

▼
任务会在我们的服务器上继续运行。使用 GET /v1/generations/{id} 并传入该 id,或通过 GET /v1/generations?limit=20 列出最近的任务。签名结果 URL 的有效期为七天,因此无需急于获取。

给 Codex 一个视频工具

创建密钥,粘贴技能,然后请求你的第一个片段。API 文档涵盖每个字段、状态和错误代码。