Empregos e sondagem
Ambos endpoints de criação retornam um id de tarefa. Um endpoint informa o resultado para qualquer um dos tipos de mídia, então um agente precisa apenas de um padrão de polling.
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
}Status
| status | Significado | Terminal |
|---|---|---|
| queued | Aceito, aguardando para começar | Não |
| processing | A geração está em execução | Não |
| succeeded | result.url está pronto | Sim |
| failed | error.code é internal; os créditos foram reembolsados | Sim |
queued
- Significado
- Aceito, aguardando para começar
- Terminal
- Não
processing
- Significado
- A geração está em execução
- Terminal
- Não
succeeded
- Significado
result.urlestá pronto- Terminal
- Sim
failed
- Significado
error.codeéinternal; os créditos foram reembolsados- Terminal
- Sim
Não há campo de progresso percentual. Consulte `status` até que seja terminal.
credits_used é o valor cobrado quando a tarefa foi criada. Uma tarefa com falha é reembolsada automaticamente, mas o campo ainda informa a cobrança original; uma chance gratuita informa 0.
Um loop de polling
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
doneComece em 3–5 segundos e aumente para 10. Uma imagem típica leva de 10 a 40 segundos; um vídeo pode levar alguns minutos. Não faça polling mais de uma vez por segundo.
Listagem e recuperação
Se um id de tarefa for perdido, liste as tarefas recentes. O endpoint é restrito à conta autenticada e retorna os mais recentes primeiro.
curl -sS "https://api.dreamutopia.net/v1/generations?type=video&limit=20" \
-H "Authorization: Bearer $DREAMUTOPIA_API_KEY"type é image, video, all, ou omitido para ambos. limit é 1–50. Passe next_cursor de volta como cursor para a próxima página.
Tentativas e idempotência
Uma criação consome créditos, portanto uma nova tentativa não deve criar um segundo job. Envie um cabeçalho Idempotency-Key com um valor único por requisição 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"}'- A primeira chamada retorna
202. - Uma nova tentativa com a mesma chave e corpo retorna
200e o trabalho existente; nenhuma segunda cobrança. - Reutilizar a chave com um corpo diferente, ou enquanto a primeira chamada ainda está em andamento, retorna
409.
Tempos de vida do resultado
result.url é um URL assinado válido por sete dias. Baixe e armazene o arquivo se precisar dele por mais tempo.