文字生成圖像 API 參考

    透過 Gate.AI 文生圖接口呼叫 OpenAI、Qwen、Seedream 等供應商的圖像模型。此接口使用 JSON 請求主體，同步回傳圖片 URL 與計費資訊，無需 job_id 輪詢或 Webhook。

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

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

    文字生成圖像

    POST/images/generations

    根據文字 prompt 同步生成圖片，成功後回傳 OpenAI 相容的圖像結果，data[].url 為生成圖片地址。

    請求參數

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

    請求主體

    名稱類型必填說明
    modelstring是圖像模型 ID，如 gpt-image-1、qwen-image-2.0-pro、seedream-4.0；缺失返回 400 model is required
    promptstring是圖像文字描述。gpt-image-1 上限 32000 字元
    ninteger否生成張數，1–10，預設 1；多圖按張計費
    sizestring否輸出尺寸。gpt-image-1 支援 1024x1024、1536x1024、1024x1536 或 auto，並參與費用預估
    response_formatstring否url 或 b64_json。gpt-image-1 不支援此參數，傳入可能被上游拒絕
    streamboolean否透傳欄位；目前圖像為同步鏈路，不依其分流

    示例

    json
    1{2  "model": "gpt-image-1",3  "prompt": "A golden retriever running on a sunny beach, cinematic",4  "n": 1,5  "size": "1024x1024"6}

    返回欄位說明

    名稱類型說明
    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": 1781604363,3  "data": [4    {5      "url": "https://ai-gateway-file.s3.ap-northeast-1.amazonaws.com/multimodal/image/2026/06/16/example-0.png?X-Amz-Expires=600&X-Amz-Signature=..."6    }7  ],8  "size": "1024x1024",9  "quality": "low",10  "output_format": "png",11  "background": "opaque",12  "usage": {13    "input_tokens": 10,14    "output_tokens": 196,15    "total_tokens": 206,16    "output_tokens_details": {17      "image_tokens": 196,18      "text_tokens": 019    }20  },21  "model_extend": {22    "cost": "0.006322",23    "provider": "openai",24    "total_tokens": "206",25    "line_items": [26      {27        "kind": "uncached_input",28        "tokens": 10,29        "rate_usd_per_million": "5.0000000000",30        "amount_usd": "0.0000500000"31      },32      {33        "kind": "output",34        "tokens": 196,35        "rate_usd_per_million": "32.0000000000",36        "amount_usd": "0.0062720000"37      }38    ]39  }40}

    回傳結果

    狀態碼狀態碼含義說明資料模型
    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