生成任务
通过长轮询跟踪 Direct API 生成任务直到最终状态，一次读取多个任务，并了解何时轮询。
生成任务是一个异步工作单元：一张图片、一段视频、一条音轨或一次渲染。returns_generation: true 的工具会启动一个或多个生成任务，并立即返回它们的 ID。你可以通过轮询、webhook 或两者结合来跟踪它们：以 webhook 作为主要信号，并偶尔轮询作为兜底。
状态
queued ──► in_progress ──► succeeded
│ │
│ ├──────► failed
└─────────────┴──────► cancelled| 状态 | 最终状态 | 含义 |
|---|---|---|
queued | 否 | 已接受，正在等待模型容量 |
in_progress | 否 | 模型正在处理 |
succeeded | 是 | assets 包含输出 |
failed | 是 | error 说明原因；扣除的积分会退还，billing.credits_refunded 说明退还了多少 |
cancelled | 是 | 在产生输出之前被停止；扣除的积分会退还 |
将任何你不认识的状态视为非最终状态，并继续跟踪该生成任务；以后可能会新增中间状态。
生成任务对象
{
"object": "generation",
"id": "0192a7b3-a1c4-7e02-8f9d-1a2b3c4d5e6f",
"tool": "generate_video",
"status": "succeeded",
"project_id": "01928f4e-5b7c-7d2a-9e11-3c4b5a6d7e8f",
"model_id": "mdl_7rk2pq9vxa4m",
"created_at": "2026-10-25T09:14:03.120Z",
"completed_at": "2026-10-25T09:15:41.902Z",
"error": null,
"billing": {
"estimated_credits": 120,
"credits_charged": 96,
"credits_refunded": 0,
"credits_are_final": true,
"credits_settle_on_output_duration": true
},
"assets": [
{
"id": "0192a7b4-0f1e-7d3c-9b8a-7c6d5e4f3a2b",
"type": "video",
"name": "Bicycle hero shot",
"mime_type": "video/mp4",
"width": 1920,
"height": 1080,
"duration_seconds": 8,
"url": "https://mcp.morphic.com/m/Xk29dPq",
"url_expires_at": null,
"studio_url": "https://studio.morphic.com/…",
"final_generation_expires_at": null
}
],
"content_left_out": [],
"render_warnings": [],
"metadata": { "order_id": "4411" },
"poll_after_seconds": null
}| 字段 | 含义 |
|---|---|
error | null，或在 failed 时为 { "error_code": "…", "message": "…" }。该消息可以安全地展示给你的用户。 |
billing | 此生成任务的费用；参见 积分与用量 |
assets[].id | 其他工具作为输入接收的素材 ID（image_asset_id、video_asset_id……） |
assets[].url | 用于下载媒体的短链接；它不会过期，url_expires_at 为 null |
assets[].studio_url | 为你的团队在 Morphic Studio 中打开该素材 |
assets[].final_generation_expires_at | 仅限草稿视频：在此时间之前，finalize_video_draft 可以将其渲染为全分辨率 |
content_left_out、render_warnings | 仅限合成和时间线导出：输出中未能包含的内容及原因 |
poll_after_seconds | 在非最终状态时，下一次读取前应等待的时长；进入最终状态后为 null |
读取单个生成任务
GET /v1/direct/generations/{id} 返回 200 和 { "generation": { … } }。
curl -s "https://mcp.morphic.com/v1/direct/generations/$ID?wait=45" \
-H "Authorization: Bearer $MORPHIC_API_KEY"wait为可选参数，取值0到45秒。请求会保持打开，直到生成任务的状态发生变化或任务完成，然后立即返回。- 等待时间用完时，返回当前状态。大于 45 的值会被截断为 45。
- 其他组织的生成任务，或此密钥无权读取的生成任务，会返回
404而不是403，因此无法通过 ID 进行探测。
读取多个生成任务
POST /v1/direct/generations/batch-get 在一个请求中最多读取 10 个生成任务。
curl -s https://mcp.morphic.com/v1/direct/generations/batch-get \
-H "Authorization: Bearer $MORPHIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"ids": ["0192a7b3-…", "0192a7b3-…"], "wait": 30}'- 使用
wait时，只要其中任何一个状态发生变化，或全部进入最终状态，请求就会立即返回。 - 响应为
{ "generations": [ … ], "not_found": ["…"] }，顺序与请求中的顺序一致。
轮询频率
每次启动和每次非最终状态的读取都带有 poll_after_seconds。在下一次读取前至少等待这么长时间，然后逐步退避。
| 输出 | 首次轮询时间 | 通常到达最终状态的时间 |
|---|---|---|
| 图片、图片编辑、放大、图片操作 | 5 秒 | 5 到 60 秒 |
| 语音、音效、转录 | 10 秒 | 10 到 90 秒 |
| 音乐、对话 | 20 秒 | 30 秒到 3 分钟 |
| 视频、视频编辑、口型同步、渲染 | 30 秒 | 1 到 10 分钟，高负载时更长 |
一次长轮询（wait=45）无论保持多久都只算一次读取，因此它既是最快也是最便宜的轮询方式。将你的 HTTP 客户端超时设置得比等待时间更长：wait=45 时设为 60 秒。
import time, requests
def wait_for(generation_id, key):
headers = {"Authorization": f"Bearer {key}"}
url = f"https://mcp.morphic.com/v1/direct/generations/{generation_id}"
while True:
r = requests.get(url, params={"wait": 45}, headers=headers, timeout=60)
if r.status_code == 429:
time.sleep(int(r.headers.get("Retry-After", "5")))
continue
r.raise_for_status()
gen = r.json()["generation"]
if gen["status"] in ("succeeded", "failed", "cancelled"):
return gen
# A long-poll already waited; only sleep if the server asks for more.
time.sleep(max(0, (gen.get("poll_after_seconds") or 0) - 45))轮询限制
| 限制 | 值 | 超出时 |
|---|---|---|
| 一个密钥对单个生成任务的读取 | 每分钟 30 次 | 429，Retry-After |
| 一个密钥对所有生成任务的读取 | 每分钟 1,200 次 | 429，Retry-After |
wait | 45 秒 | 截断 |
| 每次批量读取的 ID 数 | 10 | 400 |
批量读取中的每个 ID 都分别计入这两项限制。按推荐的频率，一个密钥可以同时跟踪数百个进行中的生成任务；如果需要跟踪更多，请使用 webhook。
如果您遇到任何问题或有任何疑问，欢迎随时联系我们。我们很乐意提供帮助。请发送邮件至 support@morphic.com.