Midjourney
用 Midjourney 异步生成图片:参数、返回与注意事项。
| 项目 | 值 |
|---|---|
| Base URL | https://api.hop-base.com/v1 |
| 提交任务 | POST /v1/images/generations |
| 查询任务 | GET /v1/video/tasks/{task_id} |
| 任务列表 | GET /v1/video/tasks |
| 密钥分组 | 「Midjourney 生图分组」 |
Midjourney 是异步接口:提交任务拿到 HopBase 任务 ID,再轮询结果;每个任务固定出四张图,每张都计费。
可用型号
| 型号 | 模型 ID | 档位/尺寸 | 官方价 |
|---|---|---|---|
| Midjourney v8.2 | midjourney-v8-2 | 默认 1K;--hd 原生 2K | $0.0067起/ 张 |
正式发起付费任务前,先用 GET /v1/models 确认密钥可用的准确模型 ID。
请求参数
所有请求使用 Authorization: Bearer sk-你的密钥 和 Content-Type: application/json。尺寸、画质等都写在 prompt 末尾的 -- 参数里,不是请求字段。
请求体字段
| 参数 | 必填 | 类型与限制 | 默认 | 说明 |
|---|---|---|---|---|
model | 必填 | 字符串,精确匹配 | — | midjourney-v8-2 |
prompt | 必填 | 字符串,须有画面描述 | — | 可在描述后加 -- 参数 |
images | 可选 | 数组,0–1 项 | — | 参考图 |
n | 可选 | 只能是 4 | 4 | 每个任务固定四张 |
quality | 请省略 | 必须为空 | — | 要 2K 用 --hd |
extra | 请省略 | 必须为空 | — | 不接受额外参数 |
prompt必须有画面描述,不能只有--参数,也不能含::;只传图片、没有描述会被拒绝。images是参考图,例如[{"url":"https://example.com/ref.png"}]。只能放 1 张;要用多张见下方「多张参考图」。images[]每项url(公网绝对 HTTP(S) 地址)/file_id二选一,不能带usage。quality非空返回 400;要 2K 请在 prompt 写--hd。extra非空对象返回 400,这个模型不接受额外参数。
请求体按严格 JSON 解析,表外的任何字段都会在提交时直接返回 400,任务不会创建、也不计费。画幅请写在提示词里的 --ar,画质用 --hd。
OpenAI Images 习惯带的 size、response_format、style 等都属于表外字段,完整清单见下方「注意事项」的「更多细节」。
尺寸与画幅比例
图片尺寸由提示词里的 --ar(也可写作 --aspect)决定。--hd 会以大约两倍的边长原生出图。
任意正整数比例都可以用,不限于下表——只要横竖两个方向都不超过 14:1(加 --hd 时为 4:1)。下表列出常用比例,尺寸均为实测值,不是换算得出的——--hd 并不是精确的两倍。
--ar | 默认 | 加 --hd |
|---|---|---|
1:1(默认) | 1024 × 1024 | 2048 × 2048 |
1:2 | 768 × 1536 | 1552 × 3104 |
9:16 | 816 × 1456 | 1648 × 2944 |
2:3 | 896 × 1344 | 1792 × 2688 |
3:4 | 928 × 1232 | 1904 × 2544 |
5:6 | 992 × 1200 | 2016 × 2416 |
6:5 | 1200 × 992 | 2416 × 2016 |
4:3 | 1232 × 928 | 2544 × 1904 |
3:2 | 1344 × 896 | 2688 × 1792 |
16:9 | 1456 × 816 | 2944 × 1648 |
2:1 | 1536 × 768 | 3104 × 1552 |
21:9 | 1680 × 720 | 3376 × 1440 |
14:1 | 4096 × 288 | 拒绝——见下文 |
--ar必须带且只带一个宽:高形式的值,两边都是正整数,--ar 1.5:1会被拒绝。- 横竖两个方向的比例都不得超过 14:1。
--hd会把这个上限压到 4:1:--hd --ar 14:1会被拒绝,--hd --ar 4:1出图 4096 × 1184。
提示词参数
下列参数会被接受并透传:
| 参数 | 取值范围 | 用途 |
|---|---|---|
--ar / --aspect | 整数比 | 画幅比例 |
--hd | 开关 | 原生 2K 出图 |
--s / --stylize | 0-1000 | 风格化强度 |
--c / --chaos | 0-100 | 四张图之间的差异度 |
--weird / --w | 0-3000 | 非常规美学 |
--iw | 0-3 | 参考图权重 |
--sref + --sw | --sw 0-1000 | 风格参考及其强度 |
--no | 文本 | 排除元素 |
--seed | 整数 | 复现结果 |
--tile、--exp | 开关 / 0-100 | 无缝平铺;动态范围 |
- 请把所有参数写在描述之后:第一个
--参数之后的文字都会被当作参数的值。 - 带取值范围的数值参数必须紧跟且只跟一个数字,缺值、多值、非数字或超出范围都返回 400。
多张参考图
images 只能放 1 张。要用多张,把图片 URL 用空格隔开写在 prompt 最前面,后面再接画面描述——这是 Midjourney 官方的 Image Prompt 写法:
"prompt": "https://example.com/a.png https://example.com/b.png a cat sitting in a vintage car --ar 1:1"
- 每个 URL 都必须是公开可访问的 HTTP(S) 地址。
- 参考图是灵感来源,不是拼贴:几张图的影响力不会平均分配,某张图里主体特别鲜明时可能压过其他图。
- 想让某张图里的元素一定出现,请在描述里写明,或用
--iw(0-3)提高参考图的权重。
不接受的参数
下列参数在提交时直接返回 400。官方要么静默忽略它们,让你为没生效的效果付钱;要么在几分钟后把任务判失败。
| 参数 | 原因 |
|---|---|
--q / --quality | 在这个模型版本上没有效果 |
--niji | Niji 是另一个模型版本,不是这里的参数 |
--repeat | 没有效果;每个任务的出图张数是固定的 |
--oref、--cref | v8.x 上没有 Omni 参考与角色参考 |
--stealth、--stop | 这个模型版本不支持 |
--relax、--turbo | 任务一律以 Fast 模式运行:本接口不提供 Relax,v8.x 不支持 Turbo |
--draft | 每个任务会返回 24 张低分辨率图;不提供 |
--profile / --p | 本接口不支持个性化配置档 |
:: | 这个模型版本不支持多段提示词权重 |
返回结果
提交响应
提交成功返回 HTTP 202:
| 字段 | 类型 | 说明 |
|---|---|---|
id | string | HopBase 任务 ID,用于查询 |
object | string | 固定为 image.generation.task |
model | string | midjourney-v8-2 |
status | string | 初始为 queued |
created | integer | 创建时间(Unix 秒) |
billing_bucket | string | 按默认档还是 --hd 2K 档计价 |
requested_images | integer | 固定为 4 |
images_per_task | integer | 固定为 4 |
notice | string | 固定四张、每张计费的提示 |
{
"id": "ktEXAMPLE",
"object": "image.generation.task",
"model": "midjourney-v8-2",
"status": "queued",
"created": 1790000000,
"billing_bucket": "img_1k",
"requested_images": 4,
"images_per_task": 4,
"notice": "this model always returns 4 images per task and bills every returned image"
}查询结果
status 依次经过 queued → processing → completed 或 failed。只有后两者是终态,其他任何值都按进行中处理。
| 字段 | 类型 | 说明 |
|---|---|---|
id | string | 任务 ID |
object | string | 固定为 video.generation.task,生图任务也一样 |
status | string | queued / processing / completed / failed |
outputs | string[] | 完成后带四个图片地址,24 小时有效 |
usage | object | 完成后的计量:bucket(即提交时的计费档位)与 billed_images(固定为 4) |
usage.cost | number | 本任务扣费的人民币金额(与 usage.cost_usd 为同一笔扣费) |
usage.cost_usd | number | 本任务实际从余额扣除的美元金额,与使用记录相同 |
usage.currency | string | usage.cost 的币种,恒为 CNY |
error.code | string | 失败时的稳定错误码 |
error.message | string | 失败原因的英文说明 |
下例为已完成任务的结构节选,ID 与 URL 为示意值:
{
"id": "ktEXAMPLE",
"object": "video.generation.task",
"model": "midjourney-v8-2",
"status": "completed",
"created": 1790000000,
"outputs": [
"https://api.hop-base.com/example-signed-image-1.png",
"https://api.hop-base.com/example-signed-image-2.png",
"https://api.hop-base.com/example-signed-image-3.png",
"https://api.hop-base.com/example-signed-image-4.png"
],
"usage": { "bucket": "img_1k", "billed_images": 4, "cost": 0.1496, "cost_usd": 0.022, "currency": "CNY" }
}输出地址在 api.hop-base.com 域名下,是自任务完成起 24 小时有效的签名链接。再次查询返回同一地址、不会续期,过期访问返回 410,请在有效期内下载保存。
任务结束后,查询响应根对象的 usage 还会带 cost_usd(本任务从余额实际扣除的美元金额,未扣费的失败为 0)、cost(同一笔的人民币金额)与 currency(恒为 CNY),详见视频生成。任务列表(GET /v1/video/tasks)里每个终态任务的 usage 也带同样的 cost、cost_usd 与 currency。
示例
提交一个 16:9 任务,再轮询到终态:
curl https://api.hop-base.com/v1/images/generations \
-H "Authorization: Bearer sk-你的密钥" \
-H "Content-Type: application/json" \
-d '{
"model": "midjourney-v8-2",
"prompt": "a red apple on a wooden table, studio light --ar 16:9"
}'
# 用返回的 id 查询,不要传计费标头
curl https://api.hop-base.com/v1/video/tasks/YOUR_TASK_ID \
-H "Authorization: Bearer sk-你的密钥"注意事项
- 每个任务固定出四张图、每张都计费,请按每次提交四张图来做预算。
n只接受4或整个省略。- 画幅写
--ar、2K 写--hd,请求体里带size或quality都会返回 400。 - 带
--hd时画幅上限从 14:1 降到 4:1。 - 所有
--参数都写在画面描述之后。 - 并发很有限,并行提交一大批任务只会让多数失败,而不是排队等待。
- 创建 2 小时后仍未结束的任务会被判为失败,不计费。
即使是时尚、商业类人像,对人物身材、体型、腿部等身体部位的细致描写或对贴身、轻薄服装的强调,叠加在一起时也可能被判定不通过。建议改为描述整体造型、风格、场景和光线后再提交。
-
OpenAI Images 习惯带的下列字段都属于表外字段,会返回 400:
size response_format style user background output_format -
请求体只能是一个 JSON 对象,后面不能再跟第二个 JSON 值。
-
参数名不区分大小写。
-
两张参数表都没有列出的参数不会在提交时拦截,但也不保证生效。
-
--repeat的简写--r目前不会在提交时被拦截,但同样不生效,请不要使用。 -
Midjourney 的内容审核比多数图片模型严格,被拒的任务不计费。
-
同时只允许少量提示词在出图,远少于同步生图模型;请少量多次提交,对返回繁忙的任务重试即可。
-
查询方式与其他异步媒体任务相同,查询时不要传计费标头。
-
较早失败的任务可能没有
error.code。
常见报错
提交阶段的错误都是 HTTP 400,任务不会创建、不计费。网关按顺序检查,遇到第一处错误即返回,响应体结构:
{
"error": {
"message": "request body does not match the JSON contract: json: unknown field \"size\"",
"type": "invalid_request_error"
}
}| 报错 | 改法 |
|---|---|
json: unknown field "size" | 删掉表外字段,画幅写 --ar |
the quality field has no effect on this model | 删掉 quality,2K 写 --hd |
the n field cannot change that | 省略 n 或设为 4 |
prompt must contain a description | 在参数前补上画面描述 |
parameter --draft is not accepted | 删掉不接受的参数 |
may not exceed 4:1 when --hd is used | 缩小比例,或去掉 --hd |
任务失败
任务失败时,查询接口仍返回 HTTP 200,status 为 failed。请按 status 判断成败,按 error.code 分支处理,并展示 error.message。
| 原因 | error.code | 建议 |
|---|---|---|
| 提示词未通过内容审核 | input_sensitive | 改写提示词后重新提交 |
| 参考图未通过内容审核 | input_sensitive | 换一张参考图后重新提交 |
| 审核未通过(未说明是哪一项) | input_sensitive | 改写提示词;带了参考图就一并更换 |
| 并发已满 | rate_limited | 稍后重试,减少同时在跑的任务 |
| 缺少描述 | prompt_required | 补上画面描述 |
| 参数不被支持 | invalid_request | 删除提示词末尾不在支持列表里的参数 |
| 画幅比例无效 | invalid_request | 改用整数比例,遵守上限 |
| 提示词格式错误 | invalid_request | 检查末尾参数的写法与取值 |
| 生成失败(其他原因) | generation_failed | 可原样重试一次;仍失败请带任务 ID 联系支持 |
| 任务无法追踪 | generation_failed | 带任务 ID 联系支持 |
| 超时 | timeout | 重新提交 |
| 结束但没有产出 | no_output | 重新提交 |
# 行是触发条件,下一行是 error.message 原文,尖括号内为随请求变化的部分:
# 出现表外字段
request body does not match the JSON contract: json: unknown field "<字段名>"
# quality 非空
the quality field has no effect on this model; ask for 2K output with --hd in the prompt instead
# n 不是 4
this model always returns 4 images per task and bills every returned image; the n field cannot change that, so omit it or set it to 4
# prompt 为空
prompt is required for this model, even when input images are provided
# 提示词含 ::
multi-prompt weighting (::) is not supported on this model version
# 提示词只有参数、没有描述
prompt must contain a description, not only parameters
# 使用了不接受的参数
parameter --<参数> is not accepted: <原因>
# images[] 某项 url / file_id 都没有或都有
images[<序号>] must provide exactly one of url or file_id
# url 不是公网 http(s) 绝对地址
images[<序号>].url must be a publicly accessible absolute http(s) URL
# images[] 带了 usage
images[<序号>].usage is not part of the image generation API; remove this field
# extra 非空
model "midjourney-v8-2" does not accept unverified extra parameters
# 参考图超过 1 张
model "midjourney-v8-2" accepts at most 1 input images, got <张数># --ar 没有值或有多个值
parameter --ar requires exactly one value such as 16:9
# --ar 不是 宽:高 形式
parameter --ar must look like 16:9, got "<值>"
# --ar 含小数
parameter --ar must use whole numbers such as 3:2; decimals are rejected, got "<值>"
# --ar 含 0 或负数
parameter --ar must use positive numbers, got "<值>"
# 比例超过 14:1
parameter --ar may not exceed 14:1, got "<值>"
# 带 --hd 时比例超过 4:1
parameter --ar may not exceed 4:1 when --hd is used, got "<值>"
# 数值参数缺值或多值
parameter --<参数> requires exactly one numeric value
# 数值参数不是数字
parameter --<参数> must be a number, got "<值>"
# 数值参数超出范围
parameter --<参数> must be between <下限> and <上限>, got <值>{
"id": "ktEXAMPLE",
"object": "video.generation.task",
"model": "midjourney-v8-2",
"status": "failed",
"created": 1790000000,
"error": {
"code": "input_sensitive",
"message": "the prompt was rejected by content moderation; rephrase it and submit again"
}
}# input_sensitive:提示词未通过内容审核
the prompt was rejected by content moderation; rephrase it and submit again
# input_sensitive:参考图未通过内容审核
the reference image was rejected by content moderation; replace it and submit again
# input_sensitive:内容审核未通过(未说明是哪一项)
the prompt or reference image was rejected by content moderation; revise it and submit again
# rate_limited:并发已满
this model is at its concurrency limit right now; please retry shortly
# prompt_required:缺少描述
prompt is required for this model, even when input images are provided
# invalid_request:参数不被支持
the prompt uses a parameter that this model version does not support
# invalid_request:画幅比例无效
the --ar value is not a valid aspect ratio for this model
# invalid_request:提示词格式错误
the prompt was rejected by the model; check the parameters at the end of the prompt
# generation_failed:生成失败(其他原因)
image generation failed; please retry, and contact support with the task ID if it keeps failing
# generation_failed:任务无法追踪(以此结尾)
… contact support with the task ID
# timeout:超时
task did not reach a billable terminal state within 2 hours; polling stopped
# no_output:结束但没有产出
image generation finished without a usable output; please retry, and contact support with the task ID if it keeps failing计费
按返回的图片张数计费,一个任务按所在档位的单价收四张图的费用;默认出图与 --hd 2K 出图分属两个价格档。只有成功完成的任务才计费,提交被拒、审核拒绝与失败的任务都不计费。
官方牌价见价格页,你的实际单价以登录后的模型广场为准,每次请求的实际扣费见用量记录。
模型规格与官方价也可在模型卡查看。
下一步
- 图片生成总览:各图片模型系列与共同规则
- 可灵生图:同样走异步任务的生图系列
- 生成图片 API 参考:请求体完整字段
- 查询视频任务 API 参考:Midjourney 任务的查询接口
- 创作工作台:不写代码直接生成图片和视频
- 报错速查:按报错原文排查