參考圖生成圖像 API 參考

    透過 Gate.AI 圖生圖接口上傳參考圖生成或編輯圖片。此接口使用 multipart/form-data，同步回傳圖片 URL 與計費資訊，usage.input_tokens 會包含參考圖讀取計入的 image_tokens。

    欄位值
    Base URLhttps://api.gate.ai/openai/v1
    認證Authorization: Bearer <API_KEY>
    格式OpenAI 相容；使用 multipart/form-data 請求主體

    圖像接口路徑位於 /openai/v1 下；生成結果 data\[\].url 為短時 S3 預簽名地址，請盡快下載或轉存，落盤物件 TTL 30 天。

    基於參考圖生成圖像

    POST/images/edits

    透過 multipart/form-data 上傳參考圖並同步生成或編輯圖片，usage.input_tokens 會包含參考圖讀取計入的 image_tokens。

    請求參數

    名稱位置類型必填說明
    Authorizationheaderstring是Gate.AI API Key。格式：Bearer <API_KEY>
    Content-Typeheaderstring是請求主體格式：multipart/form-data

    請求主體

    名稱類型必填說明
    modelstring是圖像模型 ID，如 gpt-image-1、qwen-image-2.0-pro、seedream-4.0；缺失返回 400 model is required
    imagefile是參考圖檔案。gpt-image-1 要求 PNG、小於 4 MB、方形；無 mask 時須帶透明通道作蒙版
    maskfile否PNG 蒙版，透明區為編輯區域，尺寸需與 image 一致
    promptstring是編輯描述，最長 1000 字元
    ninteger否生成張數，1–10，預設 1；多圖按張計費
    sizestring否輸出尺寸。gpt-image-1 支援 256x256、512x512 或 1024x1024，並參與費用預估
    response_formatstring否url 或 b64_json。gpt-image-1 不支援此參數，傳入可能被上游拒絕

    示例

    text
    1model=gpt-image-12prompt=Add a yellow border and a small sun in the corner3size=1024x10244image=@./input.png

    返回欄位說明

    名稱類型說明
    createdinteger生成時間戳（秒）
    dataarray結果陣列，長度等於 n
    data\[\].urlstring圖片 S3 預簽名 URL，短時有效，落盤 30 天
    usageobject用量。OpenAI 系為 token 明細；Qwen 系為 width、height、image_count
    model_extend.coststring實際計費金額（USD），扣款以此為準
    model_extend.line_itemsarray計費分項。token 計費含 input/output/cache；按張計費含 billing_unit、rate_usd_per_image、resolution_tier
    model_extend.providerstring實際上游 provider，如 openai、qwen
    size / quality / output_format / backgroundstring部分模型回顯的入參
    modelstring僅 Qwen 系在頂層回顯

    回傳範例

    json
    1{2  "created": 1781604390,3  "data": [4    {5      "url": "https://ai-gateway-file.s3.ap-northeast-1.amazonaws.com/multimodal/image/2026/06/16/example-edit-0.png?X-Amz-Expires=600&X-Amz-Signature=..."6    }7  ],8  "size": "1024x1024",9  "quality": "low",10  "output_format": "png",11  "usage": {12    "input_tokens": 220,13    "input_tokens_details": {14      "image_tokens": 194,15      "text_tokens": 2616    },17    "output_tokens": 272,18    "total_tokens": 49219  },20  "model_extend": {21    "cost": "0.009804",22    "provider": "openai",23    "total_tokens": "492"24  }25}

    回傳結果

    狀態碼狀態碼含義說明資料模型
    200OK成功，同步回傳圖片結果與計費資訊。ImageResponse
    400Bad Request請求主體錯誤、JSON 無效，或 model / prompt 缺失。OpenAIErrorResponse
    401UnauthorizedAPI Key 無效或缺失。OpenAIErrorResponse
    402Payment Required餘額不足，響應中包含當前餘額與預估費用。InsufficientBalanceResponse
    404Not Found模型不存在，或圖像端點未啟用。OpenAIErrorResponse
    413Payload Too Large請求主體過大，預設上限 8 MiB。OpenAIErrorResponse
    429Too Many Requests請求過於頻繁，請降低呼叫頻率。OpenAIErrorResponse
    500Internal Server Error服務內部錯誤。OpenAIErrorResponse
    502Bad Gateway上游圖像服務失敗。OpenAIErrorResponse