🎉 每个积分包首次购买都有免费生成好礼 —— 最高 20 个 Lite 视频 + 20 张 Lite 图片 + 10 个 Medium 视频 + 10 张 Pro 图片 + 2 个 Pro 视频。

立即开始

工作和轮询

两个创建端点都会返回一个任务 ID。一个端点即可报告任一媒体类型的结果,因此代理只需一种轮询模式。

shell
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;积分已退还
    终端
    是的

没有百分比进度字段。请轮询 `status`,直到它进入终态。

credits_used 是任务创建时收取的费用。失败的任务会自动退款,但该字段仍会显示原始扣费;免费机会则显示为 0。

一个轮询循环

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

从3–5秒开始,然后退避到10秒。一张典型图像需要10–40秒;一段视频可能需要几分钟。轮询频率不要快于每秒一次。

上架与恢复

如果任务 id 丢失,请列出最近的任务。该端点限定于经过身份验证的账户,并按最新优先返回。

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

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"}'
  • 第一次调用返回 202。
  • 使用相同的键和请求体进行重试会返回 200 和现有作业;不会产生第二次扣费。
  • 复用同一个 key 但使用不同的请求体,或在首次调用仍在进行时复用该 key,会返回 409。

结果有效期

result.url 是一个有效期为七天的签名 URL。如果需要更长时间,请下载并存储该文件。

© 2026 DreamUtopia。保留所有权利。