影像生成影像 API
在您自己的應用程式中編輯和轉換圖像。傳送參考圖像和文字 prompt，Meshy 的 AI 模型將據此生成一張新圖像。
影像生成影像用於生成影像。如果要根據影像製作 3D 模型，請使用 影象生成 3D。如果要根據照片製作可以手持或列印的實體物品，請使用 Creative Lab APIs。它們會先生成一張原型影像，然後基於該影像建構 3D 模型，例如鑰匙扣、冰箱貼、Q 版手辦、燈具或 keycap。
創建影像生成影像任務
創建一個影像生成影像任務。任務會在後台執行。關於任務通常需要多長時間，請參閱處理時間。
Request
# Transform a reference image with a text prompt
curl https://api.meshy.ai/openapi/v1/image-to-image \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
"ai_model": "nano-banana",
"prompt": "Transform this into a cyberpunk style artwork",
"reference_image_urls": [
"<your publicly accessible image url or base64-encoded data URI>"
]
}'
## Using data URI example
curl https://api.meshy.ai/openapi/v1/image-to-image \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
"ai_model": "nano-banana",
"prompt": "Transform this into a cyberpunk style artwork",
"reference_image_urls": [
"data:image/png;base64,${YOUR_BASE64_ENCODED_IMAGE_DATA}"
]
}'
## Chaining from a previous task, instead of passing image URLs
curl https://api.meshy.ai/openapi/v1/image-to-image \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
"ai_model": "nano-banana",
"prompt": "Transform this into a cyberpunk style artwork",
"input_task_id": "<your Text to Image or Image to Image task id>"
}'
Response
{
"result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}
參數
- Name
- ai_model
- Type
- string
- 必選
- Description
用於生成影像的 AI 模型。不同模型的價格不同。請參閱 Pricing。
可用值：
nano-banana：標準模型nano-banana-2：比nano-banana更強大nano-banana-2-lite：nano-banana-2的精簡版本nano-banana-2-1：Nano Banana 2.1nano-banana-pro：Pro 模型，品質更高。需要 Pro 或更高等級的 plan。在較低等級的 plan 上使用會返回402。gpt-image-2：OpenAI GPT Image 2gpt-image-2-5-flare：OpenAI GPT Image 2.5（Flare）gpt-image-2-5-sunburst：OpenAI GPT Image 2.5（Sunburst）
- Name
- prompt
- Type
- string
- 必選
- Description
描述要對參考圖片套用的編輯或轉換的文字。
- Name
- input_task_id
- Type
- string
- 必選
- Description
除非你傳送
reference_image_urls，否則此項為必填。一個文字生成影像或影像生成影像任務的 ID，其生成的圖片將作為參考，包括多視圖任務。該任務必須是你透過 API 創建、且狀態為SUCCEEDED的任務。Meshy 會使用該任務生成的每一張圖片。單圖任務提供一張參考圖片，多視圖任務則為每個視角提供一張。因此一個任務 ID 就可以填滿五個參考位中的多個。
該任務還必須處於資產保留期之內。過期後，其 ID 將返回
404。
- Name
- reference_image_urls
- Type
- array
- 必選
- Description
除非你傳送
input_task_id，否則此項為必填。一到五張要編輯的參考圖片，每張圖片為一個公開可存取的 URL 或 data URI，例如data:image/jpeg;base64,<your base64-encoded image data>。空陣列或超過五張圖片都會返回400。如果兩者都傳送，Meshy 將使用input_task_id。每張圖片必須是
.jpg、.jpeg、.png或.webp格式，大小不超過 20 MB，且每邊至少 32 像素。
- Name
- generate_multi_view
- Type
- boolean
- 預設值 false
- Description
是否生成展示主體多個角度的多視圖影像。為
true時，不能傳送aspect_ratio。同時傳送兩者會返回400。
- Name
- aspect_ratio
- Type
- string
- 預設值 1:1
- Description
輸出圖片的寬高比。可傳送的值取決於
ai_model。可用值：
1:1：正方形16:9：寬螢幕橫向9:16：寬螢幕縱向4:3：標準橫向3:4：標準縱向3:2：橫向，僅限 GPT Image 模型2:3：縱向，僅限 GPT Image 模型
GPT Image 模型包括
gpt-image-2、gpt-image-2-5-flare和gpt-image-2-5-sunburst。使用nano-banana模型時，3:2和2:3會返回400。
- Name
- remove_background
- Type
- boolean
- 預設值 false
- Description
是否移除背景。為
true時，Meshy 會將輸出圖片以透明 RGBA PNG 格式返回，這樣你可以將主體放置在任意背景上。
返回值
回應中的 result 欄位包含新建的影像生成影像任務的 ID。
失敗模式
- Name
400 - Bad Request- Description
請求無法執行。錯誤訊息會說明發現了什麼問題。例如：
- 缺少參數：缺少必填參數，例如
ai_model或prompt，或者reference_image_urls和input_task_id都未傳送。 - 輸入任務無效：
input_task_id未指向可用的任務。該任務必須是狀態為SUCCEEDED的文字生成影像或影像生成影像任務（包括多視圖任務），且仍有圖片輸出。Meshy 會拒絕其他類型的任務、尚未成功的任務，以及圖片已全部過期的任務。 - 圖片格式無效：一張或多張參考圖片的格式不受支援。
- URL 無法存取：Meshy 無法下載一張或多張
reference_image_urls圖片。 - 圖片過大：一張或多張
reference_image_urls圖片超過 20 MB。 - 圖片過小：一張或多張
reference_image_urls圖片的邊長小於 32 像素。 - 參數無效：
aspect_ratio不是所選ai_model支援的值之一。 - 衝突：請求同時傳送了
aspect_ratio和generate_multi_view: true。
請修正請求後重新傳送。請參閱 Errors。
- 缺少參數：缺少必填參數，例如
- Name
401 - Unauthorized- Description
API 金鑰缺失或無效。請檢查
Authorization請求標頭。
- Name
402 - Payment Required- Description
該帳戶無法執行此任務。例如：
- 免費 plan：建立任務需要付費 plan。請在你的 訂閱設定中升級你的 plan，然後重試。
- 積分不足：帳戶沒有足夠的積分來執行此任務，或帳戶已達到積分限額。
- 需要更高級 plan：請求使用了
nano-banana-pro，但目前 plan 低於 Pro。
請檢查你的積分餘額和 plan，然後重試。
- Name
404 - Not Found- Description
input_task_id與你帳戶中的任何任務都不匹配。不存在的任務和屬於其他帳戶的任務會返回相同的回應。請檢查該 ID。
- Name
429 - Too Many Requests- Description
你超出了速率限制。請稍候後重試。請參閱速率限制。
取得影像生成影像任務
透過 ID 返回一個影像生成影像任務。
Request
curl https://api.meshy.ai/openapi/v1/image-to-image/018a210d-8ba4-705c-b111-1f1776f7f578 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response
{
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "image-to-image",
"ai_model": "nano-banana",
"prompt": "Transform this into a cyberpunk style artwork",
"status": "SUCCEEDED",
"progress": 100,
"created_at": 1692771650657,
"started_at": 1692771667037,
"finished_at": 1692771669037,
"expires_at": 1692771679037,
"image_urls": [
"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/image.png?Expires=***"
]
}
刪除一個影像生成影像任務
永久刪除一個影像生成影像任務，包括其圖像和資料。刪除操作無法復原。
Request
curl --request DELETE \
--url https://api.meshy.ai/openapi/v1/image-to-image/018a210d-8ba4-705c-b111-1f1776f7f578 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response
// 200 OK on success, with an empty body.
//
// 409 Conflict when the task is IN_PROGRESS. The task keeps running:
{
"message": "Task is IN_PROGRESS and cannot be deleted. Credits for a task the worker has already started are not refundable; wait for it to reach SUCCEEDED, FAILED or CANCELED, then delete it."
}
路徑參數
- Name
- id
- Type
- path
- Description
要刪除的任務的 ID。
任務狀態
刪除一個 PENDING 任務會退還建立該任務時所使用的積分。
IN_PROGRESS 的任務無法被刪除。該請求會回傳 409 Conflict，
並且任務會繼續執行。Meshy 不會為已經開始的任務退款，
因此刪除它會讓你同時失去積分和結果。請等待它
達到 SUCCEEDED、FAILED 或 CANCELED 狀態，然後再刪除它。
刪除處於最終狀態（SUCCEEDED、FAILED 或 CANCELED）的任務
不會退還其積分。
回傳值
任務被刪除時回傳 200 OK，當任務為
IN_PROGRESS 時回傳 409 Conflict。
列出影像生成影像任務
返回你的影像生成影像和文字生成影像任務列表。每個任務的 type 欄位會說明它屬於這兩者中的哪一種。
Request
curl https://api.meshy.ai/openapi/v1/image-to-image?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response
[
{
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "image-to-image",
"ai_model": "nano-banana",
"prompt": "Transform this into a cyberpunk style artwork",
"status": "SUCCEEDED",
"progress": 100,
"created_at": 1692771650657,
"started_at": 1692771667037,
"finished_at": 1692771669037,
"expires_at": 1692771679037,
"image_urls": [
"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/image.png?Expires=***"
]
}
]
參數
- Name
- page_num
- Type
- integer
- Description
要返回的頁碼。起始值與預設值皆為
1。
- Name
- page_size
- Type
- integer
- Description
每頁的任務數量，最多為
100。預設為10。
- Name
- sort_by
- Type
- string
- Description
排序方式。
可選值：
+created_at：最舊的排在最前-created_at：最新的排在最前
返回值
一個分頁的任務物件清單，格式與影像生成影像任務物件相同。
流式取得 Image to Image 任務
以伺服器發送事件（SSE）的形式流式傳輸 Image to Image 任務的更新。
Request
curl -N https://api.meshy.ai/openapi/v1/image-to-image/018a210d-8ba4-705c-b111-1f1776f7f578/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response Stream
// Error event example
event: error
data: {
"status_code": 404,
"message": "Task not found"
}
// Message event examples illustrate task progress.
// These examples are shortened. Each event holds the full task object.
event: message
data: {
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"progress": 0,
"status": "PENDING"
}
event: message
data: {
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "image-to-image",
"ai_model": "nano-banana",
"prompt": "Transform this into a cyberpunk style artwork",
"status": "SUCCEEDED",
"progress": 100,
"created_at": 1692771650657,
"started_at": 1692771667037,
"finished_at": 1692771669037,
"expires_at": 1692771679037,
"image_urls": [
"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/image.png?Expires=***"
]
}
參數
- Name
- id
- Type
- path
- Description
建立回應中回傳的任務 ID。
回傳
以伺服器發送事件形式回傳的 Image to Image 任務物件 串流。
每個事件都包含完整的任務物件，其結構與 Get endpoint 回傳的相同。當任務處於 PENDING 或 IN_PROGRESS 狀態時，其結果欄位尚無值。
影像生成影像任務物件
一個影像生成影像任務物件描述了一張根據參考圖像和文字 prompt 生成的圖像。它保存了任務的狀態、進度，以及任務成功後生成的圖像。
屬性
Example Image to Image Task Object
{
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "image-to-image",
"ai_model": "nano-banana",
"prompt": "Transform this into a cyberpunk style artwork",
"status": "SUCCEEDED",
"progress": 100,
"created_at": 1692771650657,
"started_at": 1692771667037,
"finished_at": 1692771669037,
"expires_at": 1692771679037,
"image_urls": [
"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/image.png?Expires=***"
],
"task_error": null,
"consumed_credits": 3
}
- Name
- id
- Type
- string
- Description
任務 ID。請將其視為一個不透明的字串，不要依賴其格式。
- Name
- type
- Type
- string
- Description
任務類型，固定為
image-to-image。
- Name
- ai_model
- Type
- string
- Description
任務所使用的 AI 模型。
可選值：
nano-banananano-banana-2nano-banana-2-litenano-banana-2-1nano-banana-progpt-image-2gpt-image-2-5-flaregpt-image-2-5-sunburst
- Name
- prompt
- Type
- string
- Description
指導此次編輯的文字 prompt。
- Name
- status
- Type
- string
- Description
任務狀態，取值為
PENDING、IN_PROGRESS、SUCCEEDED、FAILED或CANCELED之一。
- Name
- progress
- Type
- integer
- Description
任務完成的百分比。任務開始前為
0，成功後為100。
- Name
- created_at
- Type
- timestamp
- Description
任務建立時間，以 Unix 毫秒表示。
- Name
- started_at
- Type
- timestamp
- Description
任務開始時間，以 Unix 毫秒表示。在任務開始前不存在該欄位。
- Name
- finished_at
- Type
- timestamp
- Description
任務完成時間，以 Unix 毫秒表示。在任務完成前不存在該欄位。
- Name
- expires_at
- Type
- timestamp
- Description
任務結果的過期時間，以 Unix 毫秒表示。在任務完成前不存在該欄位。
- Name
- preceding_tasks
- Type
- integer
- Description
排在此任務之前的任務數量。該值僅在任務處於
PENDING狀態時才有意義。當值為0時，該欄位會被省略。
- Name
- image_urls
- Type
- array
- Description
生成圖像的下載連結。當
generate_multi_view: true時，每個視角對應一個連結，通常為三個。如果 Meshy 無法分離出每個視角，傳回的連結會更少，但任務仍視為成功。否則，它只包含一個連結。
- Name
- task_error
- Type
- object
- Description
任務失敗時的錯誤詳情。除非狀態為
FAILED，否則該值為null。請參閱 錯誤。
- Name
- consumed_credits
- Type
- integer
- Description
任務消耗的積分數量。當狀態為
PENDING、IN_PROGRESS或SUCCEEDED時會顯示該欄位。對於FAILED的任務，該值為0，因為 Meshy 會在任務失敗時退還積分。