工作和轮询
两个创建端点都会返回一个任务 ID。一个端点即可报告任一媒体类型的结果,因此代理只需一种轮询模式。
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 | 已接受,等待开始 | No |
| processing | 生成正在运行 | No |
| succeeded | result.url 已就绪 | 是的 |
| failed | error.code 为 internal;积分已退还 | 是的 |
queued
- 含义
- 已接受,等待开始
- 终端
- No
processing
- 含义
- 生成正在运行
- 终端
- No
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
done从3–5秒开始,然后退避到10秒。一张典型图像需要10–40秒;一段视频可能需要几分钟。轮询频率不要快于每秒一次。
上架与恢复
如果任务 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 传回以获取下一页。
重试与幂等性
创建会消耗积分,因此重试绝不能创建第二个任务。请为每个逻辑请求发送带有唯一值的 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和现有作业;不会产生第二次扣费。 - 复用同一个 key 但使用不同的请求体,或在首次调用仍在进行时复用该 key,会返回
409。
结果有效期
result.url 是一个有效期为七天的签名 URL。如果需要更长时间,请下载并存储该文件。