🎉 Generaciones gratis en la primera compra de cada pack — hasta 20 videos Lite + 20 imágenes Lite + 10 videos Medium + 10 imágenes Pro + 2 videos Pro.

Empezar
DreamUtopia
es

Windsurf ya puede generar vídeo

Windsurf ya funciona en tu editor. Con la API REST de DreamUtopia, esa misma sesión puede convertir una foto de producto en un clip corto, animar un retrato o encadenar una imagen terminada en un video de primer fotograma. Pega un archivo de habilidad, pregunta en lenguaje natural y el agente se encarga de la carga, la solicitud y el sondeo. Tú sigues trabajando en la misma conversación mientras el render se ejecuta en nuestros servidores.

Empieza con un ejemplo real

Estos son los prompts de los ejemplos de esta página. Abre el generador, elige un ejemplo y ajusta un detalle cada vez.

Un festival de farolillos de papel al atardecer, con los farolillos elevándose mientras la cámara se inclina hacia el cálido cielo.

Prompt de ejemplo 01

Un festival de farolillos de papel al atardecer, con los farolillos elevándose mientras la cámara se inclina hacia el cálido cielo.

Una ventanilla de tren vintage a toda velocidad, el campo pasando borroso mientras el vapor se enrosca fuera del cristal.

Prompt de ejemplo 02

Una ventanilla de tren vintage a toda velocidad, el campo pasando borroso mientras el vapor se enrosca fuera del cristal.

Windsurf Generación de video, sin salir del editor

La generación de video de Windsurf se convierte en una parte normal de una sesión de programación cuando el agente puede llamar directamente a una API de medios. Los agentes de programación son buenos ejecutando comandos, leyendo respuestas JSON y reintentando con criterio, que es exactamente lo que necesita una API de imagen a video. En lugar de dejar el editor para abrir una aplicación web, puedes pedirle a Windsurf que convierta ./photo.png en un clip de cinco segundos en 720p y recibir una URL de resultado firmada en la misma conversación. Construimos la API de DreamUtopia como REST simple por esta razón. No hay un servidor MCP que configurar ni un plugin que instalar. Un solo archivo de skill le enseña al agente la URL base, el encabezado de autenticación, la carga multipart para imágenes de referencia, el endpoint de creación de video, el endpoint de trabajo compartido y las reglas de estado terminal. Un skill pegado y una variable de entorno son toda la configuración. La misma clave también funciona desde tus propios scripts, así que el agente y tu pipeline de compilación comparten una integración y un saldo de créditos. Un trabajo de video es más lento que un trabajo de imagen, normalmente entre uno y tres minutos, así que el bucle de sondeo importa. El skill le indica al agente que espere con retroceso exponencial, que se detenga ante un fallo terminal y que nunca reintente un rechazo por política de contenido o un saldo vacío. También distingue un trabajo que sigue en cola de uno que ha dejado de progresar. Esa distinción es la diferencia entre una espera tranquila y una tormenta de reintentos. Un bucle de sondeo que reintenta indiscriminadamente puede consumir la asignación antes de que termine el primer renderizado, mientras que un bucle que se detiene demasiado pronto abandona un trabajo que aún estaba progresando. Para un repositorio que entrega medios junto con código, la ganancia práctica es que la persona que escribe el componente también puede producir el clip que necesita, sin perder el contexto del cambio ni copiar archivos entre herramientas. El agente puede explicar un renderizado fallido con la misma voz que usa para una prueba fallida, y puede mantener el resultado junto al código que lo referencia.

Lo que obtienes

Una habilidad de copiar y pegar

Pega el bloque de habilidades a continuación en el chat de Windsurf. El agente sigue la receta durante el resto de la conversación sin necesidad de indicaciones adicionales. El texto es lo suficientemente corto como para leerse de una sola vez y lo suficientemente específico como para que el agente no improvise nombres de campos. Indica los valores exactos que acepta cada campo, de modo que una solicitud mal formada se corrige antes de llegar a la API. No se escribe nada en tu repositorio y no se instala nada.

Fotos locales gestionadas

Pide al agente que use un archivo en el proyecto. Envía una carga multipart, recibe un id de carga y usa ese id como primer fotograma. Se aceptan JPEG, PNG y WebP de hasta 30 MB. Un archivo en el repositorio nunca necesita primero una URL pública, lo que mantiene las fotos privadas de productos fuera de un paso de alojamiento separado.

Cada formato de video

La conversión de imagen a vídeo, de texto a vídeo y las transiciones de primer y último fotograma comparten una misma clave. Elige 480p, 720p o 1080p y una duración de entre cinco y quince segundos. El nivel Lite se limita a 720p y diez segundos; Medium y Pro alcanzan 1080p y quince segundos. La skill lee esos límites máximos de la lista de modelos en vivo en lugar de adivinarlos.

Trabajos que sobreviven al chat

Cada renderizado se ejecuta en nuestros servidores. Si la sesión termina, el agente puede listar los trabajos recientes por id y recoger el resultado más tarde. El enlace firmado permanece válido durante siete días, tiempo suficiente para descargar el archivo o copiarlo en un artefacto de compilación. Un trabajo fallido conserva su código de error, de modo que la siguiente sesión puede explicar qué ocurrió. Recoger el resultado más tarde también es más seguro que mantener una terminal abierta durante varios minutos mientras se completa el renderizado, especialmente en una máquina remota o con una conexión intermitente.

Movimiento en inglés sencillo

Describe el plano, no la API: un lento acercamiento, una deriva hacia la derecha, el pelo moviéndose con el viento. La habilidad traduce tus palabras a nivel de modelo, resolución, duración y relación de aspecto, y luego consulta la matriz de precios en vivo antes de gastar. Aun así puedes indicar ajustes exactos cuando una tarea los requiera, y el agente informa los ajustes que eligió para que un resultado inesperado sea más fácil de diagnosticar. Una solicitud ambigua se resuelve con una sola pregunta aclaratoria en lugar de un render especulativo que gaste créditos en la duración equivocada.

Una lista de precios

La API y la aplicación web cobran los mismos créditos. GET /v1/models devuelve la matriz activa de resolución, duración y créditos, para que el agente pueda comparar un clip de cinco segundos con uno de diez antes de crear nada. Los créditos se cobran cuando se crea el trabajo y se devuelven automáticamente si falla.

Cómo funciona

1

Crea y exporta la clave

Abre Perfil, luego Claves API y crea una clave con nombre. Expórtala como DREAMUTOPIA_API_KEY en el shell que inicia Windsurf. Las claves están disponibles para cuentas de pago, se muestran una sola vez y pueden revocarse sin afectar tus otras integraciones.

2

Pega la habilidad

Copia el bloque de abajo y pégalo en el chat de Windsurf. El agente entonces conoce los endpoints, los nombres de los campos y las reglas de sondeo para esa conversación. La skill también indica qué no hacer: no reintentar un trabajo rechazado y no pegar la clave en la conversación. Repite el pegado en una nueva sesión; no se añade nada a tu repositorio.

3

Solicitar un clip

Escribe una solicitud normal: anima ./portrait.png, con el cabello moviéndose con el viento, cinco segundos. El agente elige la configuración, puede consultar /v1/models primero y gestiona la carga cuando la fuente es un archivo local. Si la solicitud es ambigua, hace una breve pregunta en lugar de adivinar una duración o una relación de aspecto.

4

Encuesta y usa el resultado

El agente consulta GET /v1/generations/{id} hasta que el trabajo se completa correctamente y, a continuación, devuelve la URL firmada del resultado. Aplica un retroceso entre consultas y se detiene ante un fallo terminal en lugar de reintentar un rechazo por políticas de contenido o un saldo agotado. La respuesta final incluye el id del trabajo además del enlace, de modo que el resultado pueda volver a encontrarse una vez que la conversación haya desaparecido.

Pega la habilidad DreamUtopia en Windsurf

Copia la habilidad de abajo y pégala en el chat de Windsurf. A partir de entonces, el agente conoce la superficie de la API, los límites de vídeo, las reglas de error y cuándo no reintentar durante el resto de la conversación.

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

Explora herramientas relacionadas

Elige la herramienta que se adapte a tu siguiente paso.

Preguntas frecuentes

Por el equipo de DreamUtopia · Última actualización 15 de noviembre de 2026

¿Necesito un servidor MCP para generar vídeo desde Windsurf?

▼
No. La API es HTTP simple, y la skill enseña a Windsurf a llamarla con curl. No necesitas un servidor MCP, un binario CLI ni un plugin. La única configuración es pegar la skill y la variable de entorno.

¿Dónde debería estar la clave de API?

▼
En el entorno de shell como DREAMUTOPIA_API_KEY. Mantenla fuera de la skill pegada, del repositorio y del prompt. La skill indica al agente que se detenga y pregunte si falta la variable, lo que evita una solicitud a medio configurar.

¿Puede el agente subir una foto local como primer fotograma?

▼
Sí. Pídele que use un archivo del proyecto. El agente envía una carga multipart, recibe un id de carga y pasa ese id a la solicitud de video. Se aceptan JPEG, PNG y WebP de hasta 30 MB, lo que cubre la mayoría de las imágenes de cámara y de producto.

¿Cuánto puede durar un clip generado?

▼
Entre cinco y quince segundos según el nivel. El nivel Lite se detiene a los diez segundos; Medium y Pro llegan a quince. La skill lee el límite máximo desde GET /v1/models antes de enviar la solicitud, por lo que una duración demasiado larga se corrige en lugar de rechazarse.

¿Qué resoluciones están disponibles?

▼
480p, 720p y 1080p. El nivel Lite tiene un límite de 720p, mientras que Medium y Pro renderizan a 1080p. La relación de aspecto es adaptable por defecto, y el agente puede elegir un encuadre vertical, cuadrado u horizontal cuando se conoce el destino.

¿Cómo se cobran los créditos por un video?

▼
Los créditos se cobran cuando se crea el trabajo y se devuelven automáticamente si falla. La matriz de precios en vivo está en GET /v1/models, y la skill la consulta cuando preguntas sobre el costo. Se requiere una cuenta de pago antes de poder crear una clave.

¿Qué sucede si cierro la sesión?

▼
El trabajo sigue ejecutándose en nuestros servidores. Usa GET /v1/generations/{id} con el id, o lista los trabajos recientes con GET /v1/generations?limit=20. La URL del resultado firmada permanece válida durante siete días, así que no hay prisa por recogerlo.

Dale a Windsurf una herramienta de video

Crea una clave, pega la skill y pide tu primer clip. La documentación de la API cubre cada campo, estado y código de error.