KozeKoze
← 返回部落格
教學2026年8月19日·管理员

圖片產生 API 呼叫文檔

KozeAI 提供 OpenAI 風格的圖片產生和圖片編輯介面。圖片介面返回統一的圖片回應格式，但具體模型支援的尺寸、品質、參考圖和輸出格式由頻道適配器決定。

圖片產生 API 呼叫文件

KozeAI 提供 OpenAI 風格的圖片產生和圖片編輯介面。圖片介面返回統一的圖片回應格式，但具體模型支援的尺寸、品質、參考圖和輸出格式由頻道適配器決定。

鑑權

所有請求透過 Authorization: Bearer <API_TOKEN> 鑑權。在控制台建立 API 令牌後使用。 

export KOZEAI_API_KEY="sk-your-token"
export KOZEAI_BASE_URL="https://your-kozeai-domain"

介面總覽

方法 路徑 Content-Type 用途
POST /v1/images/generations application/json 文生圖
POST /v1/images/edits multipart/form-data 圖片編輯/參考圖產生

圖片模型也可以透過 /v1/chat/completions 呼叫。聊天介面會擷取文字和訊息中的圖片，再轉換到圖片介面格式；直接對接時建議使用上面的圖片專用介面。

1. 文生圖

curl "$KOZEAI_BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $KOZEAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-1",
    "prompt": "坐在窗邊的橘貓，電影感光影",
    "n": 1,
    "size": "1024x1024",
    "quality": "auto",
    "response_format": "url"
  }'

請求參數

參數 型別 必填 說明
model string 是 圖片模型名稱。實際可用模型以 /v1/models 返回為準。
prompt string 是 圖片內容描述。建議使用非空字串。
n integer 否 產生數量，預設 1，公共校驗範圍為 1-10。
size string 否 圖片尺寸或比例，具體取值由模型決定。
quality string 否 品質檔位，常見值為 standard、hd、auto、2k、4k。
response_format string 否 常見值為 url 或 b64_json。
style any 否 OpenAI 相容風格參數。
user / user_id any 否 呼叫方用戶標識。
extra_fields object 否 額外結構化參數；是否生效取決於通路適配器。
background any 否 背景設定。
moderation any 否 內容審核設定。
output_format any 否 輸出圖片格式。
output_compression integer 否 輸出壓縮參數，部分 Codex 圖片模型支援。
partial_images integer 否 部分圖片/流式相關參數，部分 Codex 圖片模型支援。
watermark boolean 否 水印開關，是否生效取決於渠道。
watermark_enabled any 否 相容於部分上游的水印參數。
image string/object/array 否 參考圖片 URL、data URL 或圖片物件；部分管道會自動進入編輯流程。

DALL·E 尺寸與預設值

模型 size 允許值 預設值
dall-e-2 / dall-e 256x256、512x512、1024x1024 1024x1024
dall-e-3 1024x1024、1024x1792、1792x1024 1024x1024
gpt-image-1 / gpt-image-2 由上游模型決定 quality=auto

size 必須使用半角字母 x，不要使用乘號 ×。

2. 圖片編輯

標準編輯請求使用 multipart 表單，圖片欄位名為 image。多個輸入圖片可以重複使用 image 或使用 image[]。 

curl "$KOZEAI_BASE_URL/v1/images/edits" \
  -H "Authorization: Bearer $KOZEAI_API_KEY" \
  -F "model=gpt-image-1" \
  -F "prompt=把背景改成夜景，並保留主體細節" \
  -F "image=@./input.png" \
  -F "n=1" \
  -F "quality=standard"

常用表單欄位：

欄位 型別 說明
model string 圖片編輯模型。
prompt string 編輯要求。
image / image[] file 輸入圖片，至少一張。
mask file 遮罩圖片；主要用於 OpenAI/Codex 相容編輯流程。
n integer 產生數量，預設 1，範圍 1-10。
size string 輸出尺寸或比例。
quality string 輸出質量。
response_format string url 或 b64_json，取決於頻道。
watermark boolean 浮水印開關，取決於渠道。

部分管道也支援 JSON 編輯請求，例如將 image 設定為 data URL 或圖片 URL；但 OpenAI、Codex、ChatGPT OAuth 編輯路徑優先使用 multipart。

3. 渠道差異

頻道 額外行為
OpenAI / DALL·E 按 OpenAI 圖片欄位轉送；DALL·E 對 size 有嚴格校驗。
xAI size 會轉換為 aspect_ratio 和 resolution；response_format 預設 b64_json。支援 aspect_ratio、resolution 等額外 JSON 參數。
Flow size 支援 1:1、16:9、9:16、4:3、3:4 等比例；quality=2k/4k參考圖透過 image 上傳。
Jimeng / Dreamina size 用於比例映射，quality=hd 會選擇更高解析度；參考圖會進入 blend 流程。
Codex 額外支援 input_fidelity、mask、stream、output_format、output_compression、partial_images。
ChatGPT OAuth 實際消費 model、prompt、n 和編輯圖片，其他圖片參數可能被忽略。
Grok response_format 只支援 url 或 b64_json，預設 url；編輯請求需要至少一張圖片。

未在公用欄位中定義的參數不會自動保證透傳。只有對應通路適配器明確讀取的額外參數才會生效。

4. 回應格式

{
  "created": 1751000000,
  "data": [
    {
      "url": "https://example.com/generated.png",
      "b64_json": "",
      "revised_prompt": "坐在窗邊的橘貓，電影感光影"
    }
  ]
}

當 response_format=b64_json 時，圖片內容位於 data[].b64_json；使用 URL 格式時，圖片位址位於 data[].url。不同頻道可能會將未使用的欄位傳回為空字串。

5. JavaScript 呼叫範例

const baseURL = process.env.KOZEAI_BASE_URL;
const apiKey = process.env.KOZEAI_API_KEY;

const response = await fetch(`${baseURL}/v1/images/generations`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'gpt-image-1',
    prompt: 'A minimal product illustration on a white background',
    n: 1,
    size: '1024x1024',
    response_format: 'url',
  }),
});

if (!response.ok) {
  throw new Error(await response.text());
}

const result = await response.json();
console.log(result.data[0].url || result.data[0].b64_json);

6. 常見錯誤

  • model is required：未傳模型名。
  • prompt is required：提示詞為空。
  • n must be between 1 and 10：產生數量超出公共限制。
  • size must be one of ...：DALL·E 使用了不支援的尺寸。
  • image is required：編輯介面未上傳圖片或未提供可辨識的圖片引用。
  • unsupported ... response_format：目標頻道不支援請求的輸出格式。
圖片產生 API 呼叫文檔 | Koze AI