Empleos y sondeo
Ambos endpoints de creación devuelven un id de trabajo. Un endpoint informa el resultado para cualquiera de los dos tipos de medio, así que un agente solo necesita un patrón de sondeo.
curl -sS https://api.dreamutopia.net/v1/generations/$MID \
-H "Authorization: Bearer $DREAMUTOPIA_API_KEY"{
"id": "3f2b…",
"type": "video",
"status": "succeeded",
"model": "medium",
"credits_used": 13,
"created_at": "2026-10-24T12:00:00Z",
"updated_at": "2026-10-24T12:02:10Z",
"result": { "url": "<result_url>" },
"error": null
}Estados
| estado | Significado | Terminal |
|---|---|---|
| queued | Aceptado, a la espera de comenzar | No |
| processing | La generación está en curso | No |
| succeeded | result.url está listo | Sí |
| failed | error.code es internal; los créditos fueron reembolsados | Sí |
queued
- Significado
- Aceptado, a la espera de comenzar
- Terminal
- No
processing
- Significado
- La generación está en curso
- Terminal
- No
succeeded
- Significado
result.urlestá listo- Terminal
- Sí
failed
- Significado
error.codeesinternal; los créditos fueron reembolsados- Terminal
- Sí
No hay ningún campo de porcentaje de progreso. Consulta `status` hasta que sea terminal.
credits_used es el importe cobrado cuando se creó el trabajo. Un trabajo fallido se reembolsa automáticamente, pero el campo sigue informando el cargo original; una oportunidad gratuita informa 0.
Un bucle de sondeo
MID="3f2b…"
while :; do
BODY=$(curl -sS "https://api.dreamutopia.net/v1/generations/$MID" \
-H "Authorization: Bearer $DREAMUTOPIA_API_KEY")
case "$(jq -r .status <<<"$BODY")" in
succeeded) jq -r .result.url <<<"$BODY"; break ;;
failed) jq -r .error.message <<<"$BODY" >&2; exit 1 ;;
*) sleep 4 ;;
esac
doneEmpieza a los 3–5 segundos y aumenta el intervalo hasta 10. Una imagen típica tarda 10–40 segundos; un video puede tardar unos minutos. No consultes con más frecuencia que una vez por segundo.
Listado y recuperación
Si se pierde un id de trabajo, enumera los trabajos recientes. El endpoint está limitado a la cuenta autenticada y devuelve primero los más recientes.
curl -sS "https://api.dreamutopia.net/v1/generations?type=video&limit=20" \
-H "Authorization: Bearer $DREAMUTOPIA_API_KEY"type es image, video, all, o se omite para ambos. limit es de 1 a 50. Pasa next_cursor de vuelta como cursor para la siguiente página.
Reintentos e idempotencia
Una creación consume créditos, por lo que un reintento no debe crear un segundo trabajo. Envía un encabezado Idempotency-Key con un valor único por solicitud lógica:
curl -sS -X POST https://api.dreamutopia.net/v1/images/generations \
-H "Authorization: Bearer $DREAMUTOPIA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: my-request-0001" \
-d '{"model":"lite","prompt":"a red fox","resolution":"2k","aspect_ratio":"1:1"}'- La primera llamada devuelve
202. - Un reintento con la misma clave y el mismo cuerpo devuelve
200y el trabajo existente; no se produce un segundo cargo. - Reutilizar la clave con un cuerpo diferente, o mientras la primera llamada aún está en curso, devuelve
409.
Duración de los resultados
result.url es una URL firmada válida durante siete días. Descarga y guarda el archivo si lo necesitas durante más tiempo.