🎉 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

Windsurf agora pode gerar vídeo

O Windsurf já funciona no seu editor. Com a API REST do DreamUtopia, a mesma sessão pode transformar a foto de um produto em um clipe curto, animar um retrato ou encadear uma imagem finalizada em um vídeo de primeiro quadro. Cole um arquivo de skill, pergunte em inglês simples e o agente cuida do upload, da requisição e do polling. Você continua trabalhando na mesma conversa enquanto a renderização é executada nos nossos servidores.

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.

Um festival de lanternas de papel ao anoitecer, lanternas subindo enquanto a câmera se inclina para cima em direção ao céu quente.

Prompt de exemplo 01

Um festival de lanternas de papel ao anoitecer, lanternas subindo enquanto a câmera se inclina para cima em direção ao céu quente.

Uma janela de trem vintage em alta velocidade, o campo passando desfocado enquanto o vapor serpenteia do lado de fora do vidro.

Prompt de exemplo 02

Uma janela de trem vintage em alta velocidade, o campo passando desfocado enquanto o vapor serpenteia do lado de fora do vidro.

Geração de vídeo no Windsurf, sem sair do editor

A geração de vídeo no Windsurf torna-se 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 JSON e tentar novamente com discernimento, que é exatamente do que uma API de imagem para vídeo precisa. Em vez de sair do editor para abrir um aplicativo web, você pode pedir ao Windsurf para transformar ./photo.png em um clipe de cinco segundos em 720p e receber de volta uma URL de resultado assinada 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. Um único arquivo de skill ensina ao agente a URL base, o cabeçalho de autenticação, o upload multipart para imagens de referência, o endpoint de criação de vídeo, o endpoint de job compartilhado e as regras de estado terminal. Uma skill colada e uma variável de ambiente são toda a configuração. A mesma chave também funciona a partir de seus próprios scripts, então o agente e seu pipeline de build compartilham uma integração e um saldo de créditos. Um job de vídeo é mais lento que um job de imagem, geralmente entre um e três minutos, então o loop de polling importa. A skill instrui o agente a esperar com backoff, parar em uma falha terminal e nunca tentar novamente uma recusa por política de conteúdo ou um saldo vazio. Ela também distingue um job que ainda está na fila de um que parou de fazer progresso. Essa distinção é a diferença entre uma espera calma e uma tempestade de retentativas. Um loop de polling que tenta novamente indiscriminadamente pode consumir a cota antes que a primeira renderização termine, enquanto um loop que para cedo demais abandona um job que ainda estava progredindo. Para um repositório que entrega mídia junto com código, o ganho prático é que a pessoa que escreve o componente também pode produzir o clipe de que ele precisa, sem perder o contexto da mudança ou copiar arquivos entre ferramentas. O agente pode explicar uma renderização falha com a mesma voz que usa para um teste falhando, e pode manter o resultado ao lado do código que o referencia.

O Que Você Recebe

Uma habilidade de copiar e colar

Cole o bloco de habilidades abaixo no chat do Windsurf. O agente segue a receita pelo restante da conversa sem prompting adicional. 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.

Fotos locais processadas

Peça ao agente para usar um arquivo no projeto. Ele envia um upload multipart, recebe um id de upload e usa esse id como o primeiro frame. JPEG, PNG e WebP são aceitos até 30 MB. Um arquivo no repositório nunca precisa primeiro de uma URL pública, o que mantém fotos privadas de produtos fora de uma etapa separada de hospedagem.

Cada formato de vídeo

Transições de imagem para vídeo, texto para vídeo e primeiro e último quadro compartilham uma chave. Escolha 480p, 720p ou 1080p e uma duração de cinco a quinze segundos. O nível Lite tem limite de 720p e dez segundos; Medium e Pro alcançam 1080p e quinze segundos. A skill lê esses limites da lista de modelos ativa em vez de adivinhar.

Empregos que sobrevivem ao chat

Cada renderizaçã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. O link assinado permanece válido durante sete dias, tempo suficiente para descarregar o ficheiro ou copiá-lo para um artefacto de compilação. Um trabalho falhado mantém o seu código de erro, para que a sessão seguinte possa explicar o que aconteceu. Recolher o resultado mais tarde também é mais seguro do que manter um terminal aberto durante vários minutos enquanto a renderização é concluída, especialmente numa máquina remota ou numa ligação intermitente.

Movimento em inglês simples

Descreva o enquadramento, não a API: um avanço lento, um desvio para a direita, o cabelo a mover-se ao vento. A competência mapeia as suas palavras para o nível do modelo, resolução, duração e proporção, e depois verifica a matriz de preços em tempo real antes de gastar. Ainda pode indicar definições exatas quando uma tarefa o exigir, e o agente comunica as definições que escolheu para que um resultado inesperado seja mais fácil de diagnosticar. Um pedido ambíguo é resolvido com uma pergunta de esclarecimento em vez de uma renderização especulativa que gasta créditos na duração errada.

Uma lista de preços

A API e o aplicativo web cobram os mesmos créditos. GET /v1/models retorna a matriz ativa 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. Os créditos são cobrados quando a tarefa é criada e devolvidos automaticamente se ela falhar.

Como Funciona

1

Crie e exporte a chave

Abra o Perfil e depois Chaves de API, e crie uma chave nomeada. Exporte-a como DREAMUTOPIA_API_KEY no shell que inicia o Windsurf. 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 Windsurf. O agente então conhece os endpoints, nomes de campos e regras de polling para essa conversa. A skill também indica o que não fazer: não repetir um job 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 um clipe

Escreva uma solicitação normal: anime ./portrait.png, cabelo se movendo ao vento, cinco segundos. 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 sucesso e, em seguida, retorna a URL assinada do resultado. Ele aplica backoff 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 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 existir mais.

Cole o DreamUtopia Skill no Windsurf

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

Paste into Windsurf
Download
> Paste this into the Windsurf 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/windsurf.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 gerar vídeo a partir do Windsurf?

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

Onde a chave de API deve ficar?

▼
No ambiente de shell como DREAMUTOPIA_API_KEY. Mantenha-a fora da skill colada, do repositório e do prompt. A skill instrui o agente a parar e perguntar se a variável estiver ausente, o que evita uma requisição semiconfigurada.

O agente pode carregar uma foto local como primeiro quadro?

▼
Sim. Peça-lhe para usar um ficheiro no projeto. O agente envia um upload multipart, recebe um id de upload e passa esse id ao pedido de vídeo. JPEG, PNG e WebP são aceites até 30 MB, o que cobre a maioria das imagens de câmara e de produto.

Qual é a duração máxima de um clipe gerado?

▼
Cinco a quinze segundos, dependendo do nível. O nível Lite para aos dez segundos; Medium e Pro chegam a quinze. A skill lê o limite máximo de GET /v1/models antes de enviar a solicitação, portanto uma duração excessiva é corrigida em vez de rejeitada.

Quais resoluções estão disponíveis?

▼
480p, 720p e 1080p. O nível Lite tem limite de 720p, enquanto Medium e Pro renderizam em 1080p. A proporção de aspeto é adaptativa por predefinição, e o agente pode escolher um enquadramento vertical, quadrado ou horizontal quando o destino é conhecido.

Como os créditos são cobrados por um vídeo?

▼
Os créditos são cobrados quando a tarefa é criada e devolvidos automaticamente 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, portanto não há pressa para o recolher.

Dê ao Windsurf uma Ferramenta de Vídeo

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