Text to Image API

สร้างรูปภาพจาก prompt ข้อความด้วยโมเดล AI ของ Meshy

ข้อความเป็นรูปภาพใช้สร้าง รูปภาพ หากต้องการสร้างโมเดล 3D จากสิ่งที่อยู่ในรูปภาพ ให้ใช้ รูปภาพเป็น 3D หากต้องการสร้างวัตถุที่คุณสามารถถือหรือพิมพ์ได้จากภาพถ่าย ให้ใช้ Creative Lab APIs ซึ่งจะสร้างภาพต้นแบบขึ้นมาก่อน แล้วจึงสร้างโมเดล 3D จากภาพนั้น เช่น พวงกุญแจ แม่เหล็กติดตู้เย็น ฟิกเกอร์ โคมไฟ หรือปุ่มคีย์แคป

POST/openapi/v1/text-to-image

Create a Text to Image task

สร้างงานข้อความเป็นรูปภาพ งานจะทำงานในเบื้องหลัง สำหรับระยะเวลาที่งานมักใช้ ดูที่ Processing times

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 ที่ใช้สร้างรูปภาพ ราคาแตกต่างกันไปตามโมเดล สำหรับราคา ดูที่ ราคา
ค่าที่ใช้ได้:
- 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 ขึ้นไป หากใช้แพลนที่ต่ำกว่า จะได้รับ 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 ขึ้นไป รูปภาพจะเป็น 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) จะส่งค่า 400 กลับมาสำหรับ 3:2 และ 2:3
Name
remove_background
Type
boolean
ค่าเริ่มต้น false
Description
กำหนดว่าจะลบพื้นหลังของรูปภาพหรือไม่ true จะส่งคืนไฟล์ PNG แบบ RGBA ที่โปร่งใส ทำให้คุณสามารถวางตัวแบบไว้บนพื้นหลังใดก็ได้

ค่าที่ส่งกลับ

ฟิลด์ result ของการตอบกลับเก็บ ID ของงานข้อความเป็นรูปภาพใหม่

รูปแบบความล้มเหลว

Name
400 - Bad Request
Description
คำขอไม่สามารถทำงานได้ ข้อความแสดงข้อผิดพลาดจะระบุว่าพบปัญหาใด ตัวอย่างเช่น:
- ขาดพารามิเตอร์: พารามิเตอร์ที่จำเป็น เช่น ai_model หรือ prompt ขาดหายไป
- พารามิเตอร์ไม่ถูกต้อง: ai_model หรือ aspect_ratio ไม่ใช่หนึ่งในค่าที่อนุญาต
- ความขัดแย้ง: ส่ง aspect_ratio มาพร้อมกับ generate_multi_view: true
แก้ไขคำขอ แล้วส่งใหม่อีกครั้ง ดูที่ ข้อผิดพลาด
Name
401 - Unauthorized
Description
API คีย์ขาดหายไปหรือไม่ถูกต้อง ตรวจสอบส่วนหัว Authorization
Name
402 - Payment Required
Description
บัญชีไม่สามารถเรียกใช้งานนี้ได้ ตัวอย่างเช่น:
- แพลนฟรี: การสร้างงานต้องใช้แพลนแบบชำระเงิน อัปเกรดแพลนของคุณได้ที่การตั้งค่าการสมัครสมาชิก แล้วลองใหม่อีกครั้ง
- เครดิตไม่เพียงพอ: บัญชีไม่มีเครดิตเพียงพอสำหรับงานนี้ (Insufficient funds) หรือบัญชีถึงขีดจำกัดเครดิตแล้ว
- ต้องใช้แพลนที่กำหนด: คำขอใช้ nano-banana-pro หรือ pose_mode ร่วมกับ nano-banana บนแพลนที่ต่ำกว่า 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
คุณเกินการจำกัดอัตราของคุณแล้ว รอสักครู่ แล้วลองใหม่อีกครั้ง ดูที่ การจำกัดอัตรา

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

รับ task ข้อความเป็นรูปภาพ

คืนค่า task ข้อความเป็นรูปภาพตาม ID ของ task นั้น

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 ของ task จากการตอบกลับตอนสร้าง

ค่าที่คืนกลับ

ออบเจ็กต์ task ข้อความเป็นรูปภาพ

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

ลบ Task ข้อความเป็นรูปภาพ

ลบ Task ข้อความเป็นรูปภาพอย่างถาวร รวมถึงรูปภาพและข้อมูลของ Task นั้น คุณไม่สามารถยกเลิกการลบได้

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."
}

Path parameters

Name
id
Type
path
Description
ID ของ Task ที่ต้องการลบ

สถานะของ Task

การลบ Task ที่อยู่ในสถานะ PENDING จะคืนเครดิตที่ใช้ไปตอนสร้าง Task นั้น

Task ที่อยู่ในสถานะ IN_PROGRESS ไม่สามารถลบได้ คำขอจะส่งกลับ 409 Conflict และ Task จะยังคงทำงานต่อไป Meshy ไม่คืนเครดิตสำหรับ Task ที่เริ่มทำงานไปแล้ว ดังนั้นการลบ Task นี้จะทำให้คุณเสียทั้งเครดิตและผลลัพธ์ รอให้ Task เข้าสู่สถานะ SUCCEEDED, FAILED, หรือ CANCELED ก่อน แล้วจึงค่อยลบ

การลบ Task ที่อยู่ในสถานะสุดท้าย (SUCCEEDED, FAILED, หรือ CANCELED) จะไม่คืนเครดิต

ผลลัพธ์ที่ได้

200 OK เมื่อ Task ถูกลบสำเร็จ หรือ 409 Conflict เมื่อ Task อยู่ในสถานะ IN_PROGRESS

GET/openapi/v1/text-to-image

List Text to Image tasks

แสดงรายการงาน ข้อความเป็นรูปภาพ และ รูปภาพเป็นรูปภาพ ของคุณ โดยฟิลด์ 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
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

สตรีมงาน Text to Image

สตรีมการอัปเดตของงาน Text to Image ในรูปแบบ Server-Sent Events (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
รหัสงาน (task ID) จากการตอบกลับตอนสร้าง

ผลลัพธ์ที่ได้

สตรีมของ อ็อบเจกต์งาน Text to Image ในรูปแบบ Server-Sent Events

แต่ละอีเวนต์จะมีอ็อบเจกต์งานแบบเต็ม ในรูปแบบเดียวกับที่เอนด์พอยต์ Get ส่งคืน ขณะที่งานยังอยู่ในสถานะ PENDING หรือ IN_PROGRESS ฟิลด์ผลลัพธ์ของงานนั้นจะยังไม่มีค่า

The Text to Image task object

อ็อบเจ็กต์งาน 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
รหัสงาน ให้ถือว่าเป็นสตริงที่ไม่มีความหมายตายตัว และอย่าอ้างอิงรูปแบบของมัน
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
รายละเอียดข้อผิดพลาดเมื่องานล้มเหลว จะเป็น null ยกเว้นเมื่อสถานะเป็น FAILED ดูที่ ข้อผิดพลาด
Name
consumed_credits
Type
integer
Description
จำนวนเครดิตที่งานนี้ใช้ไป จะปรากฏเมื่อสถานะเป็น PENDING, IN_PROGRESS, หรือ SUCCEEDED และจะเป็น 0 สำหรับงานที่ FAILED เนื่องจาก Meshy จะคืนเครดิตเมื่องานล้มเหลว