ข้อความเป็นรูปภาพ API

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

POST/openapi/v1/text-to-image

สร้างงาน Text to Image

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

พารามิเตอร์

  • Name
    ai_model
    Type
    string
    จำเป็น
    Description

    ID ของโมเดลที่จะใช้สำหรับการสร้างรูปภาพ

    ค่าที่ใช้ได้:

    • nano-banana: โมเดลมาตรฐาน (3 เครดิตต่อรูปภาพ)
    • nano-banana-2: โมเดลที่มีความสมดุลและมีความสามารถสูงกว่ามาตรฐาน (6 เครดิตต่อรูปภาพ)
    • 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

  • Name
    aspect_ratio
    Type
    string
    ค่าเริ่มต้น 1:1
    Description

    ระบุอัตราส่วนภาพของรูปภาพที่สร้างขึ้น ค่าที่อนุญาตขึ้นอยู่กับ ai_model ที่เลือก:

    • nano-banana, nano-banana-2, 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

    เครดิตไม่เพียงพอสำหรับการทำงานนี้

  • 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

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

พารามิเตอร์

  • Name
    id
    Type
    path
    Description

    ตัวระบุเฉพาะสำหรับงาน Text to Image ที่ต้องการเรียกดู

ค่าที่ส่งคืน

การตอบกลับประกอบด้วยออบเจ็กต์งาน Text to Image ตรวจสอบรายละเอียดได้ที่ส่วน 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

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

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

Path Parameters

  • Name
    id
    Type
    path
    Description

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

สถานะของงาน

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

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

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

Returns

ส่งคืน 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

    ตัวระบุเฉพาะสำหรับงานข้อความเป็นรูปภาพที่ต้องการสตรีม

สิ่งที่ส่งกลับ

ส่งกลับสตรีมของ The Text to Image Task Objects ในรูปแบบ 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 อ็อบเจกต์นี้มีคุณสมบัติดังต่อไปนี้

คุณสมบัติ

  • Name
    id
    Type
    string
    Description

    ตัวระบุที่ไม่ซ้ำกันสำหรับงาน แม้ว่าเราจะใช้ k-sortable UUID สำหรับ id ของงานเป็นรายละเอียดการใช้งานภายใน คุณไม่ควรตั้งสมมติฐานใดๆ เกี่ยวกับรูปแบบของ id

  • Name
    type
    Type
    string
    Description

    ประเภทของงานสร้างรูปภาพ สำหรับงาน Text to Image ค่านี้จะเป็น text-to-image เสมอ

  • Name
    ai_model
    Type
    string
    Description

    โมเดล AI ที่ใช้สำหรับงานนี้ ค่าที่เป็นไปได้คือ nano-banana, nano-banana-2, 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

    ไทม์สแตมป์ของเวลาที่สร้างงาน หน่วยเป็นมิลลิวินาที

    ไทม์สแตมป์แสดงถึงจำนวนมิลลิวินาทีที่ผ่านไปนับตั้งแต่วันที่ 1 มกราคม 1970 UTC โดยเป็นไปตาม มาตรฐาน RFC 3339 ตัวอย่างเช่น วันศุกร์ที่ 1 กันยายน 2023 เวลา 12:00:00 PM GMT จะแสดงเป็น 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 จะคืนค่า 0 สำหรับงานที่เป็น 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
}