Text to Image API

Text to Image API เป็นฟีเจอร์ที่ช่วยให้คุณสามารถผสานรวมความสามารถในการสร้างรูปภาพด้วย AI ของ Meshy เข้ากับแอปพลิเคชันของคุณเองได้ สร้างรูปภาพคุณภาพสูงจากพรอมต์ข้อความโดยใช้โมเดล AI อันทรงพลังของเรา

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

POST/openapi/v1/text-to-image

สร้างงาน Text to Image

เอนด์พอยต์นี้ช่วยให้คุณสร้างงาน Text to Image ใหม่ได้ โปรดดู The Text to Image Task Object เพื่อดูว่าออบเจกต์งาน Text to Image มีพร็อพเพอร์ตี้ใดบ้าง

งานนี้จะทำงานในพื้นหลัง สำหรับระยะเวลาที่มักใช้ โปรดดู Processing Times

พารามิเตอร์

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
ระบุ pose 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 รูปภาพที่สร้างขึ้นจะถูกส่งคืนเป็น PNG แบบ RGBA โปร่งใสโดยมีการลบพื้นหลังออก เพื่อให้คุณสามารถนำตัวแบบไปประกอบกับพื้นหลังใดก็ได้

ผลลัพธ์ที่ส่งกลับ

พร็อพเพอร์ตี้ result ของการตอบกลับจะมี id ของงาน Text to Image ที่เพิ่งสร้างขึ้นใหม่

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

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 หรือ 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
คุณเกินการจำกัดอัตราของคุณแล้ว

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

Retrieve a Text to Image Task

เอนด์พอยต์นี้ช่วยให้คุณดึงข้อมูลงานข้อความเป็นรูปภาพโดยระบุ id ของงานที่ถูกต้อง ดู The Text to Image Task Object เพื่อดูว่ามีพร็อพเพอร์ตี้ใดบ้างที่รวมอยู่ในอ็อบเจกต์งานข้อความเป็นรูปภาพ

พารามิเตอร์

Name
id
Type
path
Description
ตัวระบุเฉพาะสำหรับงานข้อความเป็นรูปภาพที่ต้องการดึงข้อมูล

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

การตอบกลับประกอบด้วยอ็อบเจกต์งานข้อความเป็นรูปภาพ ตรวจสอบ ส่วน The Text to Image Task Object เพื่อดูรายละเอียด

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

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

เอนด์พอยต์นี้จะลบงานข้อความเป็นรูปภาพอย่างถาวร รวมถึงรูปภาพและข้อมูลทั้งหมดที่เกี่ยวข้อง การกระทำนี้ไม่สามารถย้อนกลับได้

พารามิเตอร์พาธ

Name
id
Type
path
Description
ID ของงานข้อความเป็นรูปภาพที่ต้องการลบ

สถานะของงาน

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

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

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

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

คืนค่า 200 OK เมื่อสำเร็จ หรือ 409 Conflict เมื่องานอยู่ในสถานะ IN_PROGRESS

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

List Text to Image Tasks

เอนด์พอยต์นี้ช่วยให้คุณสามารถดึงรายการงาน Text to Image ได้

พารามิเตอร์

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: เรียงตามเวลาที่สร้างจากมากไปน้อย

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

ส่งคืนรายการแบบแบ่งหน้าของ The Text to Image Task Objects

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

สตรีมงานข้อความเป็นรูปภาพ

เอนด์พอยต์นี้สตรีมการอัปเดตแบบเรียลไทม์สำหรับงานข้อความเป็นรูปภาพโดยใช้ 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=***"
  ]
}

The Text to Image Task Object

Text to Image Task object เป็นหน่วยงานที่ Meshy ใช้ติดตามเพื่อสร้างรูปภาพจากอินพุต text prompt ออบเจ็กต์นี้มีคุณสมบัติดังต่อไปนี้

Properties

Name
id
Type
string
Description
ตัวระบุที่ไม่ซ้ำกันสำหรับ task แม้ว่าเราจะใช้ k-sortable UUID สำหรับ task id เป็นรายละเอียดในการ implementation แต่คุณ ไม่ควร ตั้งสมมติฐานใดๆ เกี่ยวกับรูปแบบของ id
Name
type
Type
string
Description
ประเภทของ task การสร้างรูปภาพ สำหรับ Text to Image task ค่านี้จะเป็น text-to-image เสมอ
Name
ai_model
Type
string
Description
โมเดล AI ที่ใช้สำหรับ task นี้ ค่าที่เป็นไปได้คือ 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
สถานะของ task ค่าที่เป็นไปได้มีค่าใดค่าหนึ่งจาก PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED
Name
progress
Type
integer
Description
ความคืบหน้าของ task หาก task ยังไม่เริ่มต้น คุณสมบัตินี้จะเป็น 0 เมื่อ task สำเร็จแล้ว ค่านี้จะกลายเป็น 100
Name
created_at
Type
timestamp
Description
ไทม์สแตมป์ของเวลาที่สร้าง task หน่วยเป็นมิลลิวินาที
ไทม์สแตมป์แสดงถึงจำนวนมิลลิวินาทีที่ผ่านไปนับตั้งแต่วันที่ 1 มกราคม ค.ศ. 1970 UTC โดยเป็นไปตาม มาตรฐาน RFC 3339 ตัวอย่างเช่น วันศุกร์ที่ 1 กันยายน ค.ศ. 2023 เวลา 12:00:00 น. GMT จะแสดงเป็น 1693569600000 สิ่งนี้ใช้ กับไทม์สแตมป์ ทั้งหมด ใน Meshy API
Name
started_at
Type
timestamp
Description
ไทม์สแตมป์ของเวลาที่เริ่ม task หน่วยเป็นมิลลิวินาที หาก task ยังไม่เริ่มต้น คุณสมบัตินี้จะเป็น 0
Name
finished_at
Type
timestamp
Description
ไทม์สแตมป์ของเวลาที่ task เสร็จสิ้น หน่วยเป็นมิลลิวินาที หาก task ยังไม่เสร็จสิ้น คุณสมบัตินี้จะเป็น 0
Name
expires_at
Type
timestamp
Description
ไทม์สแตมป์ของเวลาที่ผลลัพธ์ของ task จะหมดอายุ หน่วยเป็นมิลลิวินาที
Name
preceding_tasks
Type
integer
Description
จำนวนของ task ที่อยู่ก่อนหน้า
ค่าของฟิลด์นี้มีความหมายก็ต่อเมื่อสถานะของ task เป็น PENDING
Name
image_urls
Type
array
Description
อาร์เรย์ของ URL ที่สามารถดาวน์โหลดได้ของรูปภาพที่สร้างขึ้น เมื่อเปิดใช้งาน generate_multi_view อาร์เรย์นี้จะมี URL รูปภาพสามรายการที่แสดงถึงมุมมองที่แตกต่างกัน มิฉะนั้นจะมี URL รูปภาพเพียงรายการเดียว
Name
task_error
Type
object
Description
รายละเอียดข้อผิดพลาดสำหรับ task ที่ล้มเหลว ดู ข้อผิดพลาด สำหรับข้อมูลอ้างอิงฉบับเต็มของออบเจ็กต์ task_error
Name
consumed_credits
Type
integer
Description
จำนวนเครดิตที่ใช้ไปโดย task นี้ มีค่าเมื่อสถานะของ task เป็น PENDING, IN_PROGRESS, หรือ SUCCEEDED จะคืนค่า 0 สำหรับ task ที่ FAILED (เครดิตจะถูกคืนเมื่อเกิดความล้มเหลว)

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
}