> For the complete documentation index, see [llms.txt](https://docs.apismart.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.apismart.ai/documentation/zh-tw/api-zhi-nan/tu-pian-sheng-cheng-api.md). # 圖片生成 API 了解如何使用 ApiSmart 透過文字提示、參考圖片、多圖輸入、連續生成、串流以及本地檔案上傳來生成和編輯圖片。 使用 Image Generation API，搭配支援的 ApiSmart 圖像模型來建立和轉換圖片。 此 API 支援 **文字生成圖片、圖片生成圖片、多張參考圖片、序列式圖片生成、串流輸出，以及本地圖片上傳**. ### 🖼️ 端點 **方法：** `POST` **端點：** `/v1/images/generations` **完整 URL：** `https://gw.apismart.ai/v1/images/generations` 目前的圖片模型： `doubao-seedream-5-0` ### 🔑 驗證 請將你的 ApiSmart API 金鑰包含在 `Authorization` 標頭中： ```http Authorization: Bearer ``` 對於 JSON 請求，還要包含： ```http Content-Type: application/json ``` ### ⏱️ 請求逾時 圖片生成預設為同步。 連線會保持開啟，直到圖片生成完成並回傳結果。 單張圖片通常大約需要 **20–40 秒**。高解析度生成、多張參考圖片或序列生成可能需要更久。 請將你的用戶端逾時設定至少為： `90 秒` 如果你的用戶端過早斷線，生成可能仍會完成並產生費用，即使你的應用程式沒有收到結果。 ### 🚀 文字生成圖片 傳送文字提示詞以生成圖片： ```bash curl https://gw.apismart.ai/v1/images/generations \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "model": "doubao-seedream-5-0", "prompt": "A mountain village at sunrise, watercolor style, vertical composition", "size": "2K", "watermark": false }' ``` 這個 `prompt` 描述你想生成的圖片。 ### 📐 圖片尺寸 這個 `size` 參數支援兩種格式。 #### 解析度預設值 可用預設值： * `2K` * `3K` * `4K` 使用預設值時，你可以在提示詞中描述所需的構圖或長寬比。 例如： > 一個電影感的海岸城市在日落時分，橫向 16:9 構圖 #### 精確像素尺寸 你也可以提供精確尺寸： `x` 例如： `2048x2048` 精確尺寸必須同時滿足以下兩項： * 總像素數： `3,686,400` 至 `16,777,216` * 長寬比：介於 `1:16` 與 `16:1` 不要在同一個 `size` 值中同時組合解析度預設值和精確像素尺寸。 ### 🔄 圖片生成圖片 若要使用現有圖片作為參考，請使用 `image`: ```bash curl https://gw.apismart.ai/v1/images/generations \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "model": "doubao-seedream-5-0", "prompt": "將這張圖片轉換成水彩畫", "image": "https://example.com/input.jpg", "size": "2048x2048" }' ``` 參考圖片必須符合支援的圖片輸入需求。 ### 🧩 多張參考圖片 你可以使用陣列提供多張圖片。 最多支援 **14 張參考圖片** 。 ```bash curl https://gw.apismart.ai/v1/images/generations \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "model": "doubao-seedream-5-0", "prompt": "將第一張圖片中的角色與第二張圖片中的環境結合", "image": [ "https://example.com/character.png", "https://example.com/scene.jpg" ], "size": "2K" }' ``` 這可用於角色參考、產品組合或視覺構圖等工作流程。 ### 🖼️ 序列式圖片生成 當你想要從單次請求生成多張相關圖片時，請使用序列生成。 ```bash curl https://gw.apismart.ai/v1/images/generations \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "model": "doubao-seedream-5-0", "prompt": "建立一組四張極簡儀表板設計系列", "size": "2K", "sequential_image_generation": "auto", "sequential_image_generation_options": { "max_images": 4 } }' ``` 設定： `sequential_image_generation: "auto"` 以啟用序列生成。 `max_images` 接受從 `1` 至 `15`. 輸入和生成圖片的總數不得超過支援的合併上限。 ### 🌊 串流圖片輸出 圖片生成也支援 SSE 串流。 設定： ```json { "stream": true } ``` 範例： ```bash curl https://gw.apismart.ai/v1/images/generations \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -N \ -d '{ "model": "doubao-seedream-5-0", "prompt": "建立一個極簡產品設計系列", "size": "2K", "sequential_image_generation": "auto", "sequential_image_generation_options": { "max_images": 6 }, "stream": true }' ``` 這個 `-N` 選項可防止 curl 緩衝串流輸出。 若要了解 ApiSmart 回應模式，請參閱 [**回應模式**](/documentation/zh-tw/api-zhi-nan/hui-ying-mo-shi.md). ### 📤 上傳本地圖片 若要上傳本地圖片檔而不是使用公開圖片 URL，請使用 Image Edits 端點： **方法：** `POST` **端點：** `/v1/images/edits` 範例： ```bash curl https://gw.apismart.ai/v1/images/edits \ -H "Authorization: Bearer " \ -F model="doubao-seedream-5-0" \ -F image="@character.png" \ -F prompt="將角色放入賽博龐克環境中" \ -F size="2K" \ -F response_format="url" ``` 此端點使用 multipart form data，而非 JSON 請求本文。 每個上傳的圖片檔大小不得超過 **10 MB**，且最多 **14 張參考圖片** 。 ### ⚙️ 參數 | 參數 | 型別 | 必填 | 說明 | | ------------------------------------- | -------------- | :-: | -------------------------------------- | | `model` | string | 是 | 圖片模型 ID。目前 `doubao-seedream-5-0`. | | `prompt` | string | 是 | 圖片生成指令。支援中文與英文。 | | `image` | string / array | 否 | 參考圖片 URL 或 URL 陣列。最多 14 張圖片。 | | `size` | string | 否 | `2K`, `3K`, `4K`，或精確尺寸，例如 `2048x2048`. | | `response_format` | string | 否 | 回應格式。目前 `url`. | | `watermark` | boolean | 否 | 控制 AI 生成浮水印。預設： `true`. | | `sequential_image_generation` | string | 否 | 使用 `"auto"` 以啟用序列式圖片生成。 | | `sequential_image_generation_options` | object | 否 | 序列生成選項，包括 `max_images`. | | `tools` | array | 否 | 可選工具，例如在支援時可使用網頁搜尋。 | | `stream` | boolean | 否 | 設定為 `true` 以啟用 SSE 串流。預設： `false`. | | `output_format` | string | 否 | `png` 或 `jpeg`。預設： `jpeg`. | | `seed` | integer | 否 | 隨機種子。 | | `optimize_prompt_options` | object | 否 | 可選的提示詞最佳化設定。 | ### 📋 參考圖片需求 參考圖片必須符合以下需求： | 需求 | 限制 | | --------- | -------------------------- | | 支援格式 | JPEG、PNG、WebP、BMP、TIFF、GIF | | 最大檔案大小 | 每張圖片 10 MB | | 最小寬度 / 高度 | 大於 14 px | | 最大總像素數 | 36,000,000 | | 支援的長寬比 | `1:16` 至 `16:1` | | 最多參考圖片數 | 14 | | 輸入 + 生成圖片 | 最多 15 | 超過這些限制的請求可能會被拒絕。 ### 📦 成功回應 成功回應可能如下： ```json { "created": 1714000000, "data": [ { "url": "https://cdn.example.com/generated-image.jpg", "size": "2048x2048" } ], "usage": { "generated_images": 1, "output_tokens": 16384, "total_tokens": 16384 } } ``` 重要的回應欄位包括： * `data[].url` — 生成的圖片 URL * `data[].size` — 生成圖片尺寸 * `usage.generated_images` — 回應中報告的生成圖片數量 生成端點直接回傳的圖片 URL 是暫時性的。請將重要圖片儲存到你自己的儲存空間。 ### 💰 計費 目前圖片生成按每張生成圖片計費。 每 `doubao-seedream-5-0`: `$0.04 / 張` 最終費用取決於 **實際送達且已去重計費的圖片結果數量**. 對於 URL 回應，送達的圖片數量通常以 `data[]`. 中返回的有效圖片結果為準。 有關計費詳情，請參閱 [**模型定價與計費**](/documentation/zh-tw/mo-xing-yu-jia-ge/mo-xing-jia-ge-yu-ji-fei.md). ### 🕘 查看最近生成的圖片 你可以使用以下方式取得最近成功的圖片生成紀錄： `GET /v1/images` 範例： ```bash curl "https://gw.apismart.ai/v1/images?page=1&page_size=20" \ -H "Authorization: Bearer " ``` 支援的查詢參數： | 參數 | 預設 | 說明 | | ----------- | ---: | ------------ | | `page` | `1` | 頁碼 | | `page_size` | `20` | 每頁紀錄數，最多 100 | 歷史紀錄可能包含如下資訊： * 生成 ID * 模型 ID * 生成的圖片 URL * 圖片數量 * 解析度 * 費用 * 建立時間 * 儲存狀態 僅可查詢最近 **7 天** 的圖片歷史。 請將重要的生成圖片儲存到你自己的儲存空間，不要依賴歷史可用性。 ### ⚠️ 常見問題 #### API 金鑰無效 `401 invalid_api_key` 確認你的 API 金鑰有效，且請求包含： ```http Authorization: Bearer ``` #### 模型不可用 `403 model_not_allowed` 此圖片模型目前未對你的 API 金鑰或帳號啟用。 #### 不支援的模型 `403 model_not_image_capable` 所選模型不支援圖片生成端點。 #### 參數無效 一個 `400` 回應可能表示 JSON 無效、不支援的參數，或圖片設定無效。 請檢查請求本文、圖片限制，以及 `size` 值中同時組合解析度預設值和精確像素尺寸。 #### 請求逾時 圖片生成可能比一般文字請求需要更久。 請將你的用戶端逾時至少設定為 **90 秒** ，並避免只因用戶端逾時就立刻重試請求。 ### ✅ 在送出請求前 請確認： * 你的 API 金鑰有效且已啟用 * 你的帳號餘額充足 * 模型 ID 正確 * 端點與圖片工作流程相符 * 參考圖片符合支援的限制 * `size` 使用的是預設值或精確尺寸 * 你的用戶端逾時至少為 90 秒 * 你了解此請求可能生成多少張圖片 ### ➡️ 下一步 接著查看： * [**模型與模型 ID**](/documentation/zh-tw/mo-xing-yu-jia-ge/mo-xing-yu-mo-xing-id.md) — 找出支援的模型 ID * [**模型定價與計費**](/documentation/zh-tw/mo-xing-yu-jia-ge/mo-xing-jia-ge-yu-ji-fei.md) — 了解圖片生成費用 * [**回應模式**](/documentation/zh-tw/api-zhi-nan/hui-ying-mo-shi.md) — 了解同步與串流回應 * [**使用紀錄與費用**](/documentation/zh-tw/api-shi-yong-liang/shi-yong-ji-lu-yu-cheng-ben.md) — 檢視請求層級的使用量與費用 * [**HTTP 狀態碼與 API 錯誤**](/documentation/zh-tw/yi-nan-pai-jie/http-zhuang-tai-ma-yu-api-cuo-wu.md) — 排除 API 故障