lowpoly 將於 2026年10月30日 下線。 請在這些日期前切換模型，以免請求出錯。

文字生成影像 API

文字生成影像 API 是一項功能，可讓您將 Meshy 的 AI 影像生成能力整合到您自己的應用程式中。使用我們強大的 AI 模型，根據文字提示生成高品質影像。

此 endpoint 生成的是影像。如果您的目標是一個可以握持或列印的實體物品——例如根據照片生成 Keychain、冰箱貼、Q 版手辦、燈具或鍵帽——請使用 Creative Lab APIs（原型影像 → 建構 3D 模型）。如果您的目標是生成圖片中物體的 3D 模型，請使用 Image to 3D。

POST/openapi/v1/text-to-image

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

此 endpoint 允許您創建一個新的文字生成影像任務。請參閱 文字生成影像任務物件 以了解文字生成影像任務物件包含哪些屬性。

該任務在背景執行。有關通常所需的時間，請參閱 處理時間。

參數

  • Name
    ai_model
    Type
    string
    必選
    Description

    用於圖像生成的模型 ID。

    可用值：

    • nano-banana：標準模型（每張圖像 3 積分）
    • nano-banana-2：平衡模型，能力強於標準模型（每張圖像 6 積分）
    • nano-banana-2-lite：nano-banana-2 的輕量版本（每張圖像 3 積分）
    • nano-banana-pro：具有增強品質的專業模型（每張圖像 9 積分）
    • gpt-image-2：OpenAI GPT Image 2，一款高保真圖像模型（每張圖像 9 積分）
    • gpt-image-2-5-flare：OpenAI GPT Image 2.5（Flare），一款高保真圖像模型（每張圖像 9 積分）
    • gpt-image-2-5-sunburst：OpenAI GPT Image 2.5（Sunburst），一款高保真圖像模型（每張圖像 9 積分）
  • Name
    prompt
    Type
    string
    必選
    Description

    您想要生成的圖像的文字描述。描述越詳細，效果越好。

  • Name
    generate_multi_view
    Type
    boolean
    預設值 false
    Description

    當設置為 true 時，將生成一張展示主體多個角度的多視圖圖像。

    當 generate_multi_view 為 true 時，不能設置 aspect_ratio 參數。

  • Name
    pose_mode
    Type
    string
    Description

    指定用於角色生成的姿勢 mode。如果省略，則生成的圖像不套用任何姿勢預設。

    可用值：a-pose、t-pose

    當使用 nano-banana、nano-banana-2、nano-banana-2-lite 和 nano-banana-pro 時，設置 pose_mode 會將輸出的寬高比固定為 3:4，您傳送的任何 aspect_ratio 都會被忽略。nano-banana-2 和 nano-banana-2-lite 會保留所請求的模型。對於 nano-banana 或 nano-banana-pro，帶姿勢的圖像將由 nano-banana-pro 生成（任務的 ai_model 讀取回來時為 nano-banana-pro），這需要 Pro 方案或更高方案。GPT Image 系列模型（gpt-image-2、gpt-image-2-5-flare、gpt-image-2-5-sunburst）會保留所請求的模型和 aspect_ratio。

  • Name
    aspect_ratio
    Type
    string
    預設值 1:1
    Description

    指定生成圖像的寬高比。可用值取決於所選的 ai_model：

    • nano-banana、nano-banana-2、nano-banana-2-lite、nano-banana-pro：1:1、16:9、9:16、4:3、3:4
    • gpt-image-2、gpt-image-2-5-flare、gpt-image-2-5-sunburst：1:1、16:9、9:16、4:3、3:4、3:2、2:3

    可用值：

    • 1:1：正方形
    • 16:9：寬螢幕橫向
    • 9:16：寬螢幕縱向
    • 4:3：標準橫向
    • 3:4：標準縱向
    • 3:2：橫向（僅 GPT Image 系列模型支援）
    • 2:3：縱向（僅 GPT Image 系列模型支援）
  • Name
    remove_background
    Type
    boolean
    預設值 false
    Description

    當設置為 true 時，生成的圖像將以透明 RGBA PNG 格式返回，背景已被移除，因此您可以將主體合成到任何背景上。

返回值

回應的 result 屬性包含新創建的文字生成影像任務的任務 id。

失敗模式

  • Name
    400 - Bad Request
    Description

    請求無法被接受。常見原因：

    • 缺少參數：缺少必需的參數（例如 ai_model、prompt）。
    • 參數無效：ai_model 或 aspect_ratio 不是允許的值之一。
    • 衝突：generate_multi_view 和 aspect_ratio 不能同時使用。
  • Name
    401 - Unauthorized
    Description

    身份驗證失敗。請檢查您的 API 金鑰。

  • Name
    402 - Payment Required
    Description

    常見原因：

    • 積分不足：您的帳戶沒有足夠的積分來執行此任務（Insufficient funds）。
    • 需要特定方案：nano-banana-pro，或在 nano-banana 中使用 pose_mode，需要 Pro 方案或更高方案（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)）。
  • Name
    429 - Too Many Requests
    Description

    您已超出速率限制。

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"
}
GET/openapi/v1/text-to-image/:id

取得文字生成影像任務

此 endpoint 允許你根據有效的任務 id 取得文字生成影像任務。 請參閱文字生成影像任務物件以查看文字生成影像任務物件所包含的屬性。

參數

  • Name
    id
    Type
    path
    Description

    要取得的文字生成影像任務的唯一識別碼。

回傳值

回應中包含文字生成影像任務物件。詳情請查看 文字生成影像任務物件部分。

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=***"
  ]
}
DELETE/openapi/v1/text-to-image/:id

刪除文字生成影像任務

此 endpoint 將永久刪除一個文字生成影像任務，包括所有相關的影像和資料。此操作不可逆轉。

路徑參數

  • Name
    id
    Type
    path
    Description

    要刪除的文字生成影像任務的 ID。

任務狀態

仍處於 PENDING 狀態的任務可以被刪除，建立時消耗的積分將被退還。

已處於 IN_PROGRESS 狀態的任務無法被刪除：該請求會被拒絕並返回 409 Conflict，任務將繼續執行。工作程序已經開始處理的任務所消耗的 積分不可退還，因此在執行過程中刪除該任務只會讓您同時損失 積分和結果。請等待任務到達 SUCCEEDED、FAILED 或 CANCELED 狀態後再刪除它。

處於終止狀態（SUCCEEDED、FAILED 或 CANCELED）的任務會被刪除， 且不會退還積分。

返回

成功時返回 200 OK；當任務處於 IN_PROGRESS 狀態時返回 409 Conflict。

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 is left 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."
}
GET/openapi/v1/text-to-image

列出文字生成影像任務

此 endpoint 允許你取得文字生成影像任務的清單。

參數

  • Name
    page_num
    Type
    integer
    Description

    用於分頁的頁碼。起始值與預設值為 1。

  • Name
    page_size
    Type
    integer
    Description

    每頁數量限制。預設為 10 項。最大允許值為 100 項。

  • Name
    sort_by
    Type
    string
    Description

    用於排序的欄位。可用值：

    • +created_at：依建立時間升冪排序。
    • -created_at：依建立時間降冪排序。

回傳

回傳一個分頁的文字生成影像任務物件清單。

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=***"
    ]
  }
]
GET/openapi/v1/text-to-image/:id/stream

流式傳輸文字生成圖像任務

此 endpoint 使用 Server-Sent Events（SSE）為文字生成圖像任務流式傳輸即時更新。

參數

  • Name
    id
    Type
    path
    Description

    要流式傳輸的文字生成圖像任務的唯一識別碼。

回傳值

以 Server-Sent Events 的形式回傳 文字生成圖像任務物件 的串流。

對於 PENDING 或 IN_PROGRESS 狀態的任務，回應串流將僅包含必要的 progress 和 status 欄位。

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.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
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=***"
  ]
}

文字生成影像任務物件

文字生成影像任務物件是 Meshy 用於追蹤根據文本 prompt 輸入生成圖像的工作單元。 該物件具有以下屬性：

屬性

  • Name
    id
    Type
    string
    Description

    任務的唯一識別碼。雖然我們在實作細節上使用 k-可排序的 UUID 作為任務 id，但你不應對 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-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

    任務的 progress。如果任務尚未開始，該屬性將為 0。一旦任務成功，該值將變為 100。

  • Name
    created_at
    Type
    timestamp
    Description

    任務建立時間的時間戳，以毫秒為單位。

    時間戳表示自 1970 年 1 月 1 日 UTC 起經過的毫秒數，遵循 RFC 3339 標準。 例如，格林威治標準時間 2023 年 9 月 1 日星期五下午 12:00:00 表示為 1693569600000。這適用於 Meshy API 中的所有時間戳。

  • Name
    started_at
    Type
    timestamp
    Description

    任務開始時間的時間戳，以毫秒為單位。如果任務尚未開始，該屬性將為 0。

  • Name
    finished_at
    Type
    timestamp
    Description

    任務完成時間的時間戳，以毫秒為單位。如果任務尚未完成，該屬性將為 0。

  • Name
    expires_at
    Type
    timestamp
    Description

    任務結果過期時間的時間戳，以毫秒為單位。

  • Name
    preceding_tasks
    Type
    integer
    Description

    前置任務的數量。

    僅當任務狀態為 PENDING 時，該欄位的值才有意義。

  • Name
    image_urls
    Type
    array
    Description

    指向生成的圖像的可下載 URL 陣列。啟用 generate_multi_view 時，此陣列包含代表不同觀察角度的三個圖像 URL；否則，它只包含一個圖像 URL。

  • Name
    task_error
    Type
    object
    Description

    失敗任務的錯誤詳情。完整的 task_error 物件參考請參閱 錯誤。

  • Name
    consumed_credits
    Type
    integer
    Description

    此任務消耗的積分數量。當任務狀態為 PENDING、IN_PROGRESS 或 SUCCEEDED 時存在該欄位。對於 FAILED 任務，回傳 0（失敗時積分會被退還）。

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,
  "preceding_tasks": 0,
  "image_urls": [
    "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/image.png?Expires=***"
  ],
  "task_error": {

    "message": ""

  },

  "consumed_credits": 3
}