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 任務的查詢介面
- 創作工作台:不寫程式直接生成圖片和影片
- 報錯速查:按報錯原文排查