🎉 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

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.

shell
curl -sS https://api.dreamutopia.net/v1/generations/$MID \
  -H "Authorization: Bearer $DREAMUTOPIA_API_KEY"
resposta
{
  "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

  • 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.url está 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

bash
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
done

Comece 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.

shell
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:

shell
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 200 e 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.

© 2026 DreamUtopia. Todos os direitos reservados.