文字生成影像 API

使用 Meshy 的 AI 模型根據文字 prompt 生成影像。

文字生成影像用於製作影像。若要為影像中的內容製作 3D 模型，請使用 Image to 3D。若要根據照片製作可手持或可列印的物件，請使用 Creative Lab APIs。它們會先製作一張原型影像，然後據此建構 3D 模型，例如 Keychain、冰箱貼、Figure、燈具或鍵帽。

POST/openapi/v1/text-to-image

建立一個文字生成影像任務

建立一個文字生成影像任務。該任務在後台執行。關於任務通常需要多長時間，請參閱處理時間。

Request

POST

/openapi/v1/text-to-image

# Generate an image from a text prompt
curl https://api.meshy.ai/openapi/v1/text-to-image \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "ai_model": "nano-banana",
    "prompt": "A majestic dragon soaring through clouds at sunset",
    "aspect_ratio": "16:9"
  }'

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.1
- nano-banana-pro：Pro 模型，品質更高。需要 Pro 或更高級別的 plan。在較低級別的 plan 中，會回傳 402。
- gpt-image-2：OpenAI GPT Image 2
- gpt-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
generate_multi_view
Type
boolean
預設值 false
Description
是否生成從多個角度展示主體的多視角圖像。當該值為 true 時，不能傳送 aspect_ratio。同時傳送兩者會回傳 400。
Name
pose_mode
Type
string
Description
角色的姿勢，a-pose 或 t-pose。不設定則表示沒有姿勢。
姿勢的運作方式取決於 ai_model：
- nano-banana-2、nano-banana-2-lite 和 nano-banana-2-1：Meshy 保留你選擇的模型。圖像始終為 3:4，Meshy 會忽略 aspect_ratio。
- nano-banana 和 nano-banana-pro：Meshy 會使用 nano-banana-pro 生成圖像，因此任務的 ai_model 會被讀取為 nano-banana-pro。這需要 Pro 或更高級別的 plan。圖像始終為 3:4，Meshy 會忽略 aspect_ratio。
- GPT Image 模型（gpt-image-2、gpt-image-2-5-flare 和 gpt-image-2-5-sunburst）：Meshy 會保留你選擇的模型以及你的 aspect_ratio。
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 模型
nano-banana 系列模型（nano-banana、nano-banana-2、nano-banana-2-lite、nano-banana-2-1 和 nano-banana-pro）對 3:2 和 2:3 會回傳 400。
Name
remove_background
Type
boolean
預設值 false
Description
是否移除圖像的背景。true 會回傳一張透明的 RGBA PNG 圖像，這樣你就可以把主體放在任何背景上。

回傳值

回應的 result 欄位保存新建立的文字生成影像任務的 ID。

失敗模式

Name
400 - Bad Request
Description
請求無法執行。錯誤訊息會說明發現的問題。例如：
- 缺少參數：缺少必需的參數，例如 ai_model 或 prompt。
- 參數無效：ai_model 或 aspect_ratio 不是允許的值之一。
- 衝突：aspect_ratio 與 generate_multi_view: true 一起傳送。
修正請求後重新傳送。請參閱 Errors。
Name
401 - Unauthorized
Description
API 金鑰缺失或無效。請檢查 Authorization 請求標頭。
Name
402 - Payment Required
Description
帳戶無法執行此任務。例如：
- 免費 plan：建立任務需要付費 plan。請在訂閱設定中升級你的 plan，然後重試。
- 積分不足：帳戶沒有足夠的積分來執行此任務（Insufficient funds），或帳戶已達到積分上限。
- 需要特定 plan：請求使用了 nano-banana-pro，或在低於 Pro 的 plan 中使用了帶 nano-banana 的 pose_mode（Only Pro and above users can use nano-banana-pro，或 Only Pro and above users can use A/T pose feature (requires nano-banana-pro)）。
請檢查你的積分餘額和 plan，然後重試。
Name
429 - Too Many Requests
Description
你超出了速率限制。請稍候後重試。請參閱 Rate limits。

GET/openapi/v1/text-to-image/:id

取得文字生成影像任務

透過任務 ID 回傳對應的文字生成影像任務。

Request

GET

/openapi/v1/text-to-image/018a210d-8ba4-705c-b111-1f1776f7f578

curl https://api.meshy.ai/openapi/v1/text-to-image/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "text-to-image",
  "ai_model": "nano-banana",
  "prompt": "A majestic dragon soaring through clouds at sunset",
  "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。

回傳值

文字生成影像任務物件。

DELETE/openapi/v1/text-to-image/:id

刪除文字生成影像任務

永久刪除一個文字生成影像任務，包括其圖像和資料。刪除後無法復原。

Request

DELETE

/openapi/v1/text-to-image/018a210d-8ba4-705c-b111-1f1776f7f578

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/text-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。

GET/openapi/v1/text-to-image

列出文字生成影像任務

返回你的文字生成影像和影像生成影像任務列表。每個任務的 type 欄位表示它屬於這兩者中的哪一種。

Request

GET

/openapi/v1/text-to-image

curl https://api.meshy.ai/openapi/v1/text-to-image?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "text-to-image",
    "ai_model": "nano-banana",
    "prompt": "A majestic dragon soaring through clouds at sunset",
    "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 開始，預設為 1。
Name
page_size
Type
integer
Description
每頁的任務數量，最多為 100。預設為 10。
Name
sort_by
Type
string
Description
排序方式。
可用值：
- +created_at：最舊的排在最前
- -created_at：最新的排在最前

返回值

一個分頁的任務物件清單，格式與文字生成影像任務物件相同。

GET/openapi/v1/text-to-image/:id/stream

串流傳輸文字生成影像任務

以伺服器發送事件（SSE）的形式串流傳輸文字生成影像任務的更新。

Request

GET

/openapi/v1/text-to-image/018a210d-8ba4-705c-b111-1f1776f7f578/stream

curl -N https://api.meshy.ai/openapi/v1/text-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": "text-to-image",
  "ai_model": "nano-banana",
  "prompt": "A majestic dragon soaring through clouds at sunset",
  "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。

以伺服器發送事件形式返回的文字生成影像任務物件串流。

每個事件都包含完整的任務物件，其結構與 Get endpoint 返回的結構相同。當任務處於 PENDING 或 IN_PROGRESS 狀態時，其結果欄位尚無取值。

Text to Image 任務物件

Text to Image 任務物件描述了一次根據文字 prompt 生成影像的任務。它儲存了任務的狀態、progress，以及任務成功時的影像 URL。

屬性

Example Text to Image Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "text-to-image",
  "ai_model": "nano-banana",
  "prompt": "A majestic dragon soaring through clouds at sunset",
  "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
任務類型，始終為 text-to-image。
Name
ai_model
Type
string
Description
任務使用的 AI 模型。
可能的取值：
- nano-banana
- nano-banana-2
- nano-banana-2-lite
- nano-banana-2-1
- nano-banana-pro
- gpt-image-2
- gpt-image-2-5-flare
- gpt-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
生成影像的下載 URL。當 generate_multi_view: true 時，陣列中包含每個視圖對應的一個 URL，通常為三個。如果 Meshy 無法分離出每個視圖，回傳的數量會更少，但任務仍會成功。否則，陣列中僅包含一個 URL。
Name
task_error
Type
object
Description
任務失敗時的錯誤詳情。除非狀態為 FAILED，否則為 null。參見錯誤。
Name
consumed_credits
Type
integer
Description
任務消耗的積分數量。當狀態為 PENDING、IN_PROGRESS 或 SUCCEEDED 時存在。對於 FAILED 的任務，該值為 0，因為 Meshy 會在任務失敗時退還積分。