🎉 Gerações grátis na primeira compra de cada pacote — até 20 vídeos Lite + 20 imagens Lite + 10 vídeos Medium + 10 imagens Pro + 2 vídeos Pro.

Começar
DreamUtopia
pt

O Codex agora pode gerar imagens

O Codex já edita o seu código. Com a API REST do DreamUtopia, a mesma sessão pode criar uma imagem principal, reestilizar a foto de um produto ou transformar uma imagem estática em um vídeo de oito segundos. Cole um arquivo de habilidade, peça em inglês simples e o agente cuida do upload, da requisição e do polling.

Comece com um exemplo real

Estes são os prompts usados nos exemplos desta página. Abra o gerador, escolha um exemplo e ajuste um detalhe de cada vez.

Repinte esta costa tempestuosa ao anoitecer. Mantenha o farol e as rochas negras, faça o feixe atravessar a névoa do mar e intensifique as nuvens de tempestade.

Prompt de exemplo 01

Repinte esta costa tempestuosa ao anoitecer. Mantenha o farol e as rochas negras, faça o feixe atravessar a névoa do mar e intensifique as nuvens de tempestade.

Transforme este balcão de cozinha em uma cena aconchegante de outono. Mantenha a caneca branca e o balcão de madeira, adicione paus de canela espalhados, um pano de linho e um sol baixo mais quente.

Prompt de exemplo 02

Transforme este balcão de cozinha em uma cena aconchegante de outono. Mantenha a caneca branca e o balcão de madeira, adicione paus de canela espalhados, um pano de linho e um sol baixo mais quente.

Pinte este lago alpino como uma aguarela solta. Mantenha os picos e o reflexo, suavize os pinheiros e aqueça a luz da madrugada.

Prompt de exemplo 03

Pinte este lago alpino como uma aguarela solta. Mantenha os picos e o reflexo, suavize os pinheiros e aqueça a luz da madrugada.

Codex Image Generation, sem sair do terminal

A geração de imagens do Codex torna-se uma parte normal de uma sessão de programação quando o agente pode chamar uma API de mídia diretamente. Agentes de programação são bons em executar comandos, ler respostas e tentar novamente de forma inteligente, que é exatamente o que uma API de mídia precisa. Em vez de sair do terminal para abrir um aplicativo web, você pode pedir ao Codex uma imagem de cabeçalho 16:9 e receber uma URL de resultado de volta na mesma conversa. Construímos a API DreamUtopia como REST simples por esse motivo. Não há servidor MCP para configurar e nenhum plugin para instalar. O arquivo de skill ensina ao agente a URL base, o cabeçalho de autenticação, o upload multipart, os dois endpoints de criação, o loop de polling e as regras de erro. Uma skill colada e uma variável de ambiente são toda a configuração. A mesma chave também funciona nos seus próprios scripts, o que significa que o agente e seu pipeline de build compartilham uma integração e um saldo de créditos. Isso importa quando uma tarefa de design começa em um chat e termina em um script de deploy: o formato da requisição não muda entre os dois. O fluxo de trabalho também se encaixa na forma como os agentes de programação já trabalham: uma requisição é um comando de shell normal, uma falha é um status HTTP normal, e um trabalho longo é um id normal para fazer polling. Isso significa que o Codex pode explicar uma falha com a mesma voz que usa para um teste que falha, e pode manter o recurso gerado ao lado do código que o referencia. Para um repositório com muito design, a diferença é prática e não cosmética: a pessoa que escreve o componente é também a pessoa que pode produzir a imagem de que ele precisa, sem trocar de ferramenta ou perder o contexto da mudança. O Codex pode executar a requisição, ler a resposta JSON e explicar uma falha sem sair da tarefa que você lhe deu. Esse ciclo de feedback é o ponto central: o agente já sabe como executar um comando e interpretar o resultado, então a geração de mídia se torna mais uma ferramenta que ele pode usar.

O que você recebe

Uma habilidade de copiar e colar

Cole o bloco de habilidades abaixo no chat do Codex. O agente segue a receita pelo restante da conversa sem necessidade de prompts adicionais. O texto é curto o suficiente para ser lido de uma só vez e específico o suficiente para que o agente não improvise nomes de campos. Ele declara os valores exatos que cada campo aceita, de modo que uma requisição malformada é corrigida antes de chegar à API. Nada é gravado no seu repositório e nada é instalado.

Arquivos locais tratados

O agente carrega uma foto do seu projeto com uma requisição multipart e, em seguida, passa o id retornado para a geração. O limite é de 30 MB para JPEG, PNG e WebP. Um arquivo que está no repositório nunca precisa de uma URL pública primeiro.

Imagens e vídeo, uma chave

Texto para imagem, imagem para imagem, texto para vídeo, imagem para vídeo e transições de primeiro/último quadro usam todos a mesma chave e o mesmo saldo de créditos. Você não gerencia contas separadas para imagens estáticas e movimento, e a skill pode encadear uma imagem finalizada na próxima solicitação de vídeo.

Empregos que sobrevivem ao chat

Cada geração é executada nos nossos servidores. Se a sessão terminar, o agente pode listar os trabalhos recentes por id e recolher o resultado mais tarde. A ligação assinada para o resultado permanece válida durante sete dias, o que é tempo suficiente para a descarregar ou copiá-la para um artefacto de compilação.

Pedidos em inglês simples

Peça uma foto quadrada de produto ou um clipe social vertical. A skill mapeia suas palavras para modelo, resolução, duração e proporção, depois verifica a matriz de preços ao vivo antes de gastar. Você ainda pode especificar configurações exatas quando uma tarefa precisar delas. O agente informa as configurações escolhidas de volta para você, o que facilita diagnosticar um resultado inesperado.

Uma lista de preços

A API e o aplicativo web cobram os mesmos créditos. GET /v1/models retorna a matriz ao vivo de resolução, duração e créditos, para que o agente possa comparar um clipe de cinco segundos com um de dez segundos antes de criar qualquer coisa.

Como Funciona

1

Crie e exporte a chave

Abra o Perfil, depois API keys, e crie uma chave nomeada. Exporte-a como DREAMUTOPIA_API_KEY no shell que inicia o Codex. As chaves estão disponíveis para contas pagas, são exibidas uma única vez e podem ser revogadas sem afetar suas outras integrações.

2

Cole a habilidade

Copie o bloco abaixo e cole-o no chat do Codex. O agente então conhece os endpoints, os nomes dos campos e as regras de polling para essa conversa. A skill também indica o que não fazer: não repetir um trabalho recusado e não colar a chave na conversa. Repita a colagem em uma nova sessão; nada é adicionado ao seu repositório.

3

Peça o que você precisa

Escreva uma solicitação normal: gere uma imagem 2K de uma raposa vermelha na neve, ou transforme ./photo.png em um clipe 720p com um push lento. O agente escolhe as configurações, pode verificar /v1/models primeiro e cuida do upload quando a origem é um arquivo local. Se a solicitação for ambígua, ele faz uma pergunta curta em vez de adivinhar uma duração ou uma proporção de aspecto.

4

Enquete e use o resultado

O agente consulta GET /v1/generations/{id} até que a tarefa seja concluída com êxito e, em seguida, retorna a URL assinada do resultado. Ele aguarda intervalos crescentes entre as consultas e para em caso de falha terminal, em vez de tentar novamente uma recusa por política de conteúdo ou um saldo de créditos esgotado. A resposta final inclui o id da tarefa, bem como o link, para que o resultado possa ser encontrado novamente depois que a conversa não estiver mais disponível.

Cole o DreamUtopia Skill no Codex

Copie a skill abaixo e cole no chat do Codex. O agente então conhece a superfície da API, as regras de erro e quando não tentar novamente pelo resto da conversa.

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

Escolha a ferramenta que combina com seu próximo passo.

Perguntas Frequentes

Pela Equipe DreamUtopia · Última atualização em 15 de novembro de 2026

Preciso de um servidor MCP para usar o DreamUtopia a partir do Codex?

▼
Não. A API é HTTP simples, e a skill ensina o Codex a chamá-la com curl. Você não precisa de um servidor MCP, de um binário de CLI ou de um plugin. A única configuração é colar a skill e a variável de ambiente.

Onde deve ficar o arquivo de skill no Codex?

▼
Cole o bloco de habilidades no chat do Codex. Ele se aplica a essa conversa; repita a colagem em uma nova sessão. Nada é adicionado ao seu repositório e nenhum arquivo precisa ser criado. Mantenha a chave de API no ambiente do shell como DREAMUTOPIA_API_KEY, não no texto colado.

O Codex consegue enviar uma imagem local?

▼
Sim. Peça para usar um arquivo no projeto. O agente envia um upload multipart, recebe um id de upload e usa esse id na geração. JPEG, PNG e WebP são aceitos até 30 MB.

A habilidade gera vídeo além de imagens?

▼
Sim. A mesma chave cobre texto para vídeo e imagem para vídeo, com durações de cinco a quinze segundos, dependendo do nível do modelo. As transições de primeiro e último quadro estão disponíveis nos níveis superiores.

Como os créditos são cobrados?

▼
Os créditos são cobrados quando uma tarefa é criada e devolvidos se ela falhar. A matriz de preços em tempo real está em GET /v1/models, e a skill a consulta quando você pergunta sobre custo. É necessária uma conta paga antes que uma chave possa ser criada.

O que acontece se eu fechar a sessão?

▼
A tarefa continua em execução nos nossos servidores. Use GET /v1/generations/{id} com o id ou liste as tarefas recentes com GET /v1/generations?limit=20. O URL do resultado assinado permanece válido por sete dias.

É seguro revogar uma chave?

▼
Sim. A revogação interrompe novas solicitações imediatamente e deixa os trabalhos em execução intactos. Uma conta pode conter várias chaves, de modo que uma integração pode ser desativada sem afetar as outras.

Dê ao Codex uma Ferramenta de Mídia

Crie uma chave, cole a skill e peça sua primeira imagem. A documentação da API cobre cada campo, status e código de erro.