使用 Python 接入 Midjourney API
本教程介绍如何通过 Python 标准 HTTP 客户端提交图像生成任务、跟踪异步状态并获取图像结果。
准备条件
Python 3.7+、API 密钥，以及 requests（pip install requests）。
准备条件
- Python 3.7 或更高版本。
- 一个 Midjourney API 密钥，请在服务端安全保存。
- requests 库：运行 pip install requests 安装。
步骤一：安全读取 API 密钥
将密钥保存到环境变量，并使用 os.environ 在程序中读取。不要把真实密钥硬编码在源文件、笔记本或公开代码仓库中。
步骤二：提交图像任务
使用 requests.post 向任务提交端点发送 JSON 请求。请求头包含 API 密钥，请求体包含 prompt 及可选参数。检查 HTTP 响应状态，并从成功响应中保存任务 ID。
步骤三：查询任务状态
使用 requests.get 携带任务 ID 查询状态，设置合理的连接与读取超时，并在循环中采用有间隔的重试策略。遇到成功状态时读取图像 URL；遇到失败状态则记录原因并结束轮询。
步骤四：生产环境使用 Webhook
实际应用中，可在提交任务时配置 Webhook，由 Python Web 框架提供 HTTPS 回调路由。先持久化事件，再将后续工作放入队列；对重复回调执行幂等处理。
错误处理与最佳实践
- 对非成功 HTTP 状态调用 raise_for_status 或显式检查状态码。
- 设置请求超时，避免工作进程无限等待。
- 不要过于频繁地轮询任务。
- 对密钥使用环境变量或专用密钥管理系统。
- 保留任务 ID、状态与结果 URL，方便问题追踪。
Python 集成步骤
- 安装 requests 并从环境变量读取 API 密钥。
- 向提交任务端点发送 POST 请求，并将响应中的 taskId 保存下来。
- 通过 job-status 轮询结果；status 为 1 表示成功，status 为 2 表示失败。
- 生产环境建议传入 hookUrl，并由 Webhook 接收生成结果。
查询任务状态与 API 参数
轮询时可向 /midjourney/v1/job-status 传入 taskIds 数组。成功后读取 job.image；失败时记录错误并停止继续等待。常见参数包括 prompt（必填，支持 --ar、--niji 等 Midjourney 参数）、mode（可选，fast 或 relaxed，默认 fast，Fast 消耗额度约为 2 倍）、hookUrl（可选，接收完成回调）和 timeout（可选，秒，范围 300–1200，默认 600）。
import os
import time
import requests
api_key = os.environ["MIDJOURNEY_API_KEY"]
headers = {"API-KEY": api_key, "Content-Type": "application/json"}
response = requests.post(
"https://api.midjourney-api.com/midjourney/v1/submit-jobs",
headers=headers,
json={"prompt": "a cinematic landscape --ar 16:9", "mode": "fast"},
timeout=30,
)
response.raise_for_status()
task_id = response.json()["data"]["taskId"]
while True:
result = requests.post(
"https://api.midjourney-api.com/midjourney/v1/job-status",
headers=headers, json={"taskIds": [task_id]}, timeout=30
).json()["data"][0]
if result["status"] == 1:
print("Image URL:", result["image"]); break
if result["status"] == 2:
raise RuntimeError("Image generation failed")
time.sleep(5)API 参数参考
- prompt（string，必填）：图像提示词，可使用标准 Midjourney 参数。
- mode（string，可选）：fast 或 relaxed；默认 fast，Fast 消耗约为 Relax 的两倍额度。
- hookUrl（string，可选）：生成完成时接收结果的 Webhook URL。
- timeout（integer，可选）：任务超时时间，范围 300–1200 秒，默认 600。