🎉 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 imágenes

Windsurf ya edita tu código. Con la API REST de DreamUtopia, esa misma sesión puede crear una imagen principal, cambiar el estilo de una foto de producto o convertir una imagen fija en un vídeo de ocho segundos. Pega un archivo de habilidades, pregunta en lenguaje natural y el agente se encarga de la carga, la solicitud y el sondeo.

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.

Repinta esta costa tormentosa al atardecer. Mantén el faro y las rocas negras, haz que su haz atraviese la niebla marina y intensifica las nubes de tormenta.

Prompt de ejemplo 01

Repinta esta costa tormentosa al atardecer. Mantén el faro y las rocas negras, haz que su haz atraviese la niebla marina y intensifica las nubes de tormenta.

Convierte esta encimera de cocina en una acogedora escena otoñal. Mantén la taza blanca y la encimera de madera, añade ramas de canela dispersas, un paño de lino y un sol bajo más cálido.

Prompt de ejemplo 02

Convierte esta encimera de cocina en una acogedora escena otoñal. Mantén la taza blanca y la encimera de madera, añade ramas de canela dispersas, un paño de lino y un sol bajo más cálido.

Pinta este lago alpino como una acuarela suelta. Mantén los picos y el reflejo, suaviza los pinos y da calidez a la luz del amanecer.

Prompt de ejemplo 03

Pinta este lago alpino como una acuarela suelta. Mantén los picos y el reflejo, suaviza los pinos y da calidez a la luz del amanecer.

Generación de imágenes de Windsurf, sin salir del editor

La generación de imágenes de Windsurf se convierte en una parte normal de una sesión de programación cuando el agente puede llamar a una API de medios directamente. Los agentes de programación son buenos ejecutando comandos, leyendo respuestas y reintentando de forma inteligente, que es exactamente lo que necesita una API de medios. En lugar de dejar el editor para abrir una aplicación web, puedes pedirle a Windsurf una imagen de cabecera en 16:9 y recibir una URL de resultado en la misma conversación. Construimos la API de DreamUtopia como REST simple por esta razón. No hay ningún servidor MCP que configurar ni ningún plugin que instalar. El archivo de habilidad enseña al agente la URL base, la cabecera de autenticación, la carga multipart, los dos endpoints de creación, el bucle de sondeo y las reglas de error. Una habilidad pegada y una variable de entorno son toda la configuración. La misma clave también funciona desde tus propios scripts, lo que significa que el agente y tu pipeline de compilación comparten una integración y un saldo de créditos. Eso importa cuando una tarea de diseño empieza en un chat y termina en un script de despliegue: la forma de la solicitud no cambia entre los dos. El flujo de trabajo también encaja con la forma en que los agentes de programación ya trabajan: una solicitud es un comando de shell normal, un fallo es un estado HTTP normal y un trabajo largo es un id normal que sondear. Eso significa que Windsurf puede explicar un fallo con la misma voz que usa para una prueba fallida, y puede mantener el recurso generado junto al código que lo referencia. Para un repositorio con mucho diseño, la diferencia es práctica más que cosmética: la persona que escribe el componente es también la persona que puede producir la imagen que necesita, sin cambiar de herramienta ni perder el contexto del cambio. Windsurf puede ejecutar la solicitud, leer la respuesta JSON y explicar un fallo sin salir del archivo que estás editando. Ese bucle de retroalimentación es el punto central: el agente ya sabe cómo ejecutar un comando e interpretar el resultado, así que la generación de medios se convierte en otra herramienta que puede usar.

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.

Archivos locales gestionados

El agente sube una foto de tu proyecto con una solicitud multipart y luego pasa el id devuelto a la generación. El límite es de 30 MB para JPEG, PNG y WebP. Un archivo que reside en el repositorio nunca necesita primero una URL pública.

Imágenes y vídeo, una clave

Texto a imagen, imagen a imagen, texto a video, imagen a video y las transiciones de primer/último fotograma usan la misma clave y el mismo saldo de créditos. No gestionas cuentas separadas para imágenes fijas y movimiento, y la skill puede encadenar una imagen terminada en la siguiente solicitud de video.

Empleos que sobreviven al chat

Cada generación se ejecuta en nuestros servidores. Si la sesión finaliza, el agente puede listar los trabajos recientes por id y recoger el resultado más tarde. El enlace firmado del resultado permanece válido durante siete días, tiempo suficiente para descargarlo o copiarlo en un artefacto de compilación.

Solicitudes en inglés sencillo

Solicita una toma de producto cuadrada o un clip social vertical. La skill asigna tus palabras al modelo, la resolución, la duración y la 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. El agente te informa los ajustes elegidos, lo que facilita diagnosticar un resultado inesperado.

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.

Cómo funciona

1

Crear y exportar 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 se pueden revocar 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

Pide lo que necesitas.

Escribe una solicitud normal: genera una imagen 2K de un zorro rojo en la nieve, o convierte ./photo.png en un clip de 720p con un acercamiento lento. El agente elige la configuración, puede consultar primero /v1/models 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 utiliza el resultado

El agente consulta GET /v1/generations/{id} hasta que la tarea se completa con éxito, y luego devuelve la URL firmada del resultado. Aplica una espera progresiva entre consultas y se detiene ante un fallo del editor en lugar de reintentar un rechazo por política de contenido o un saldo de créditos agotado. La respuesta final incluye el id de la tarea además del enlace, para que el resultado pueda encontrarse de nuevo una vez que la conversación ya no esté disponible.

Pega la Skill de DreamUtopia en Windsurf

Copia la habilidad de abajo y pégala en el chat de Windsurf. El agente entonces conoce la superficie de la API, 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 usar DreamUtopia desde Windsurf?

▼
No. La API es HTTP simple, y la skill le 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 debe ir el archivo de habilidad en Windsurf?

▼
Pega el bloque de habilidades en el chat de Windsurf. Se aplica para esa conversación; repite el pegado en una nueva sesión. No se añade nada a tu repositorio y no es necesario crear ningún archivo. Mantén la clave API en el entorno del shell como DREAMUTOPIA_API_KEY, no en el texto pegado.

¿Puede Windsurf subir una imagen local?

▼
Sí. Pídele que use un archivo en el proyecto. El agente envía una carga multipart, recibe un id de carga y usa ese id en la generación. Se aceptan JPEG, PNG y WebP de hasta 30 MB.

¿La habilidad genera video además de imágenes?

▼
Sí. La misma clave cubre texto a vídeo e imagen a vídeo, con duraciones de cinco a quince segundos según el nivel del modelo. Las transiciones de primer y último fotograma están disponibles en los niveles superiores.

¿Cómo se cobran los créditos?

▼
Los créditos se cobran cuando se crea un trabajo y se devuelven si este falla. La matriz de precios en vivo está en GET /v1/models, y la skill la consulta cuando preguntas por 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 enumera los trabajos recientes con GET /v1/generations?limit=20. La URL firmada del resultado permanece válida durante siete días.

¿Es seguro revocar una clave?

▼
Sí. La revocación detiene las nuevas solicitudes de inmediato y deja intactos los trabajos en curso. Una cuenta puede contener varias claves, de modo que una integración puede retirarse sin afectar a las demás.

Dale a Windsurf una herramienta de medios

Crea una clave, pega la habilidad y solicita tu primera imagen. La documentación de la API cubre cada campo, estado y código de error.