通过 Webhook 接收任务结果
Webhook 可在图像生成任务发生状态变化或完成时通知您的服务，帮助您构建无需持续轮询的异步工作流。
适合对象
异步后端、SaaS 产品和基于队列的工作流。
主要字段
在 /midjourney/v1/submit-jobs 中传入 hookUrl。
备用路径
需要时使用 /midjourney/v1/job-status 查询状态。
Webhook 与轮询
| 方式 | 适用场景 | 权衡 |
|---|---|---|
| Webhook | 生产应用、异步管线、任务通知 | 需要可公开访问的回调端点 |
| 轮询 | 快速原型、本地测试、手动排查 | 会重复发送状态请求 |
Webhook 工作流程
创建任务时提供可公开访问的 HTTPS hookUrl。服务完成任务后向该地址发送回调，其中包含任务标识和结果信息。接收端应检查事件、保存状态，并及时返回成功响应。
网络请求可能重复、延迟或失败，因此回调处理应设计为幂等。保存已处理的事件或任务状态，避免重复创建业务记录或重复通知用户。
提交带有 hookUrl 的任务
在任务提交请求中加入您服务端的回调 URL。为每个任务保存任务 ID 与回调地址的关联，并确认回调端点可从公网通过 HTTPS 访问。
不要在 URL 中放置秘密令牌或个人敏感信息。若需要验证回调来源，请使用服务支持的签名机制；如果当前集成没有签名能力，可在处理层增加随机令牌校验、来源限制及幂等防护。
推荐的端点处理逻辑
- 校验请求结构与任务 ID。
- 快速持久化事件并返回成功状态，避免在 HTTP 请求内执行耗时工作。
- 将图像结果、安全校验和后续通知交给后台队列处理。
- 识别重复事件并安全忽略已完成的处理。
- 记录处理错误并配置告警与重试。
建议持久化的字段
至少保存内部业务对象 ID、API 返回的任务 ID、当前状态、创建与完成时间、生成参数摘要、结果 URL、最后一次回调时间及失败原因。不要记录 API 密钥或不必要的敏感用户信息。
Webhook 与轮询对比
Webhook 由服务主动通知，减少无意义的重复请求，适用于持续运行的产品服务。轮询更易于初期接入，也可用于回调故障后的兜底。生产系统通常以 Webhook 为主、受控轮询为辅，并设置超时、退避和速率限制。
常见问题
若回调不可用，先检查 HTTPS、公开可达性、防火墙与响应状态。不要假设失败通知一定按固定次数重试；应通过持久化状态和查询接口设计恢复流程。
Webhook 工作流程
- 提交任务时传入 hookUrl。
- 在应用中保存返回的 taskId。
- 任务完成后接收回调并更新内部任务。
- 保留轮询作为回调延迟或不可用时的备用方式。
hookUrl 请求示例
在提交任务时附带可公开访问的回调地址，完成后 API 会把任务结果发送到该地址。
POST /midjourney/v1/submit-jobs
{
"prompt": "a cinematic landscape",
"hookUrl": "https://yourapp.com/webhooks/midjourney"
}推荐的端点逻辑
- 验证回调请求并识别 taskId。
- 将 taskId 映射到内部任务记录。
- 持久化图像结果和任务状态。
- 触发后续通知或业务逻辑。
- 尽快返回成功响应，再通过队列执行耗时操作；对重复事件采用幂等处理。
建议保存的回调字段
- taskId：关联内部任务或队列项目。
- status：判断任务成功、失败或仍在处理中。
- image / images：保存最终图像 URL，供展示或后处理。
- prompt / mjPrompt：用于调试、分析和支持。
- meta：可选元数据，可辅助图像显示或下游转换。
下一步阅读
- 快速开始：从 API 密钥到第一个生成任务的完整生命周期。
- Replicate 替代方案：了解何时专用 Midjourney 工作流更合适。
- 功能介绍：Webhook、并发、Niji 与模式控制。
- Node.js 教程：使用 fetch 和 TypeScript 实现异步回调。
常见问题
Midjourney API 中的 hookUrl 是什么？
hookUrl 是提交任务时提供的回调端点。图像生成完成后，API 会把结果 POST 到该地址，供后端异步处理。
应使用 Webhook 还是轮询？
简单原型可轮询；生产环境通常更适合 Webhook，因为它减少重复状态查询，并更自然地适配后端任务队列。
使用 Webhook 后还需要 job-status 吗？
通常仍建议保留为备用路径。Webhook 可作为主流程，job-status 可在回调延迟或不可用时帮助恢复。
Webhook 端点至少要做什么？
验证请求，将 taskId 映射到内部任务记录，持久化图像结果，并触发下游通知或业务逻辑。