ジョブとポーリング
どちらのcreateエンドポイントもジョブIDを返します。1つのエンドポイントがどちらのメディアタイプの結果も報告するため、エージェントは1つのポーリングパターンだけを必要とします。
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
}ステータス
| ステータス | 意味 | ターミナル |
|---|---|---|
| queued | 受理しました。開始待ちです | いいえ |
| processing | 生成を実行中です | いいえ |
| succeeded | result.url の準備ができました | はい |
| failed | error.code は internal です。クレジットは返金されました | はい |
queued
- 意味
- 受理しました。開始待ちです
- ターミナル
- いいえ
processing
- 意味
- 生成を実行中です
- ターミナル
- いいえ
succeeded
- 意味
result.urlの準備ができました- ターミナル
- はい
failed
- 意味
error.codeはinternalです。クレジットは返金されました- ターミナル
- はい
パーセントの進捗フィールドはありません。終端状態になるまで `status` をポーリングしてください。
credits_used は、ジョブ作成時に課金された金額です。失敗したジョブは自動的に返金されますが、このフィールドには元の請求額が引き続き表示されます。無料枠の場合は 0 と表示されます。
ポーリングループ
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
done3〜5秒から始めて、10秒まで間隔を広げます。一般的な画像は10〜40秒かかります。動画は数分かかることがあります。1秒に1回より速くポーリングしないでください。
出品およびリカバリ
ジョブIDが失われた場合は、最近のジョブを一覧表示します。このエンドポイントは認証済みアカウントにスコープされ、新しい順に返します。
curl -sS "https://api.dreamutopia.net/v1/generations?type=video&limit=20" \
-H "Authorization: Bearer $DREAMUTOPIA_API_KEY"type は image、video、all、または両方の場合は省略します。limit は 1~50 です。次のページには next_cursor を cursor として渡してください。
リトライと冪等性
作成にはクレジットが消費されるため、再試行で2つ目のジョブを作成してはなりません。論理リクエストごとに一意の値を持つ Idempotency-Key ヘッダーを送信してください:
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"}'- 最初の呼び出しは
202を返します。 - 同じキーと同じボディで再試行すると、
200と既存のジョブが返され、二重の課金は発生しません。 - 異なる本文でキーを再利用した場合、または最初の呼び出しがまだ進行中に再利用した場合は、
409を返します。
結果の有効期間
result.url は7日間有効な署名付きURLです。それ以上保存が必要な場合は、ファイルをダウンロードして保管してください。