API สำหรับรูปภาพเป็นรูปภาพ

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

POST/openapi/v1/image-to-image

Create an Image to Image Task

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

พารามิเตอร์

Name
ai_model
Type
string
จำเป็น
Description
ID ของโมเดลที่ใช้สำหรับการสร้างรูปภาพ
ค่าที่สามารถใช้ได้:
- nano-banana: โมเดลมาตรฐาน (3 เครดิตต่อรูปภาพ)
- nano-banana-2: โมเดลที่มีความสมดุล ความสามารถสูงกว่าโมเดลมาตรฐาน (6 เครดิตต่อรูปภาพ)
- nano-banana-pro: โมเดลระดับ Pro ที่มีคุณภาพสูงขึ้น (9 เครดิตต่อรูปภาพ)
- gpt-image-2: OpenAI GPT Image 2 โมเดลแก้ไขรูปภาพความคมชัดสูง (12 เครดิตต่อรูปภาพ)
- gpt-image-2-5-flare: OpenAI GPT Image 2.5 (Flare) โมเดลแก้ไขรูปภาพความคมชัดสูง (12 เครดิตต่อรูปภาพ)
- gpt-image-2-5-sunburst: OpenAI GPT Image 2.5 (Sunburst) โมเดลแก้ไขรูปภาพความคมชัดสูง (12 เครดิตต่อรูปภาพ)
Name
prompt
Type
string
จำเป็น
Description
คำอธิบายข้อความของการแปลงหรือแก้ไขที่คุณต้องการนำไปใช้กับรูปภาพอ้างอิง

ต้องระบุอย่างใดอย่างหนึ่งระหว่าง input_task_id หรือ reference_image_urls เท่านั้น หากระบุทั้งสองอย่าง input_task_id จะมีลำดับความสำคัญก่อน

Name
input_task_id
Type
string
จำเป็น
Description
ID ของงานสร้างรูปภาพที่เสร็จสมบูรณ์แล้ว ซึ่งรูปภาพผลลัพธ์ของงานนั้นจะถูกนำมาใช้เป็นรูปภาพอ้างอิง งานนี้ต้องเป็นหนึ่งในงานต่อไปนี้: ข้อความเป็นรูปภาพ หรือ รูปภาพเป็นรูปภาพ รวมถึงรูปแบบมุมมองหลายด้านของงานเหล่านั้นด้วย นอกจากนี้ งานนั้นต้องถูกรันผ่าน API และมีสถานะเป็น SUCCEEDED
รูปภาพผลลัพธ์ทั้งหมดของงานต้นทางจะถูกนำมาใช้ งานที่มีรูปภาพเดียวจะให้รูปภาพอ้างอิง 1 รูป ส่วนงานแบบมุมมองหลายด้านจะให้รูปภาพอ้างอิงต่อมุมมองที่สร้างขึ้น 1 รูป ดังนั้น task ID เดียวสามารถเติมเต็มช่องรูปภาพอ้างอิงได้หลายช่องจากทั้งหมด 5 ช่อง
งานต้นทางจะต้องยังอยู่ภายในระยะเวลาการเก็บรักษาแอสเซ็ต — เมื่อหมดอายุแล้ว ID ของงานนั้นจะคืนค่าเป็น 404

Name
reference_image_urls
Type
array
จำเป็น
Description
อาร์เรย์ของรูปภาพอ้างอิงจำนวน 1 ถึง 5 รูปที่ใช้สำหรับงานแก้ไขรูปภาพ ปัจจุบันรองรับรูปแบบ .jpg, .jpeg และ .png
มีสองวิธีในการระบุรูปภาพแต่ละรูป:
- URL ที่เข้าถึงได้แบบสาธารณะ: URL ที่สามารถเข้าถึงได้จากอินเทอร์เน็ตสาธารณะ
- Data URI: ข้อมูล URI ของรูปภาพที่เข้ารหัสแบบ base64 ตัวอย่างของ data URI: data:image/jpeg;base64,<your base64-encoded image data>

Name
generate_multi_view
Type
boolean
ค่าเริ่มต้น false
Description
เมื่อตั้งค่าเป็น true จะสร้างรูปภาพมุมมองหลายด้านที่แสดงเนื้อหาหลักจากหลายมุม
เมื่อ generate_multi_view เป็น true จะไม่สามารถตั้งค่าพารามิเตอร์ aspect_ratio ได้
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 ของงานรูปภาพเป็นรูปภาพที่สร้างขึ้นใหม่

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

Name
400 - Bad Request
Description
คำขอไม่สามารถยอมรับได้ สาเหตุที่พบบ่อย:
- ขาดพารามิเตอร์: พารามิเตอร์ที่จำเป็น (เช่น ai_model, prompt) หายไป หรือไม่ได้ระบุทั้ง reference_image_urls และ input_task_id
- งานอินพุตไม่ถูกต้อง: input_task_id ต้องอ้างอิงถึงงานข้อความเป็นรูปภาพหรือรูปภาพเป็นรูปภาพที่มีสถานะ SUCCEEDED (รวมถึงมุมมองหลายด้าน) ที่ยังมีรูปภาพผลลัพธ์อยู่ งานประเภทอื่น งานที่ยังไม่สำเร็จ หรืองานที่รูปภาพทั้งหมดหมดอายุแล้วจะถูกปฏิเสธ
- รูปแบบรูปภาพไม่ถูกต้อง: รูปภาพอ้างอิงหนึ่งรูปหรือมากกว่านั้นไม่ใช่รูปแบบที่รองรับ
- URL ไม่สามารถเข้าถึงได้: ไม่สามารถดาวน์โหลด reference_image_urls หนึ่งรายการหรือมากกว่านั้นได้
- พารามิเตอร์ไม่ถูกต้อง: aspect_ratio ไม่ใช่หนึ่งในค่าที่อนุญาตสำหรับ ai_model ที่เลือก
- ขัดแย้งกัน: ไม่สามารถใช้ generate_multi_view และ aspect_ratio พร้อมกันได้
Name
401 - Unauthorized
Description
การยืนยันตัวตนล้มเหลว โปรดตรวจสอบ API คีย์ของคุณ
Name
402 - Payment Required
Description
เครดิตไม่เพียงพอสำหรับการดำเนินงานนี้
Name
404 - Not Found
Description
input_task_id ไม่ได้อ้างอิงถึงงานที่เป็นของบัญชีของคุณ งานที่ไม่มีอยู่จริงและงานที่เป็นของบัญชีอื่นจะให้ผลลัพธ์การตอบกลับเดียวกัน
Name
429 - Too Many Requests
Description
คุณได้เกินขีดจำกัดการจำกัดอัตราแล้ว

Request

POST

/openapi/v1/image-to-image

# Transform a reference image with a text prompt
curl https://api.meshy.ai/openapi/v1/image-to-image \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "ai_model": "nano-banana",
    "prompt": "Transform this into a cyberpunk style artwork",
    "reference_image_urls": [
      "<your publicly accessible image url or base64-encoded data URI>"
    ]
  }'


 ## Using Data URI example
curl https://api.meshy.ai/openapi/v1/image-to-image \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "ai_model": "nano-banana",
    "prompt": "Transform this into a cyberpunk style artwork",
    "reference_image_urls": [
      "data:image/png;base64,${YOUR_BASE64_ENCODED_IMAGE_DATA}"
    ]
  }'


 ## Chaining from a previous task, instead of passing image URLs
curl https://api.meshy.ai/openapi/v1/image-to-image \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "ai_model": "nano-banana",
    "prompt": "Transform this into a cyberpunk style artwork",
    "input_task_id": "<your Text to Image or Image to Image task id>"
  }'

Response

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}

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

ดึงข้อมูล Image to Image Task

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

พารามิเตอร์

Name
id
Type
path
Description
ตัวระบุที่ไม่ซ้ำกันสำหรับ Image to Image task ที่ต้องการดึงข้อมูล

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

การตอบกลับประกอบด้วย Image to Image task object ดูรายละเอียดได้ที่ส่วน The Image to Image Task Object

Request

GET

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

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

Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "image-to-image",
  "ai_model": "nano-banana",
  "prompt": "Transform this into a cyberpunk style artwork",
  "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/image-to-image/:id

ลบงาน Image to Image

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

พารามิเตอร์เส้นทาง

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/image-to-image/018a210d-8ba4-705c-b111-1f1776f7f578

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

List Image to Image Tasks

เอนด์พอยต์นี้ช่วยให้คุณสามารถดึงรายการงาน รูปภาพเป็นรูปภาพ ได้

พารามิเตอร์

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 Image to Image Task Objects

Request

GET

/openapi/v1/image-to-image

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

Response

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "image-to-image",
    "ai_model": "nano-banana",
    "prompt": "Transform this into a cyberpunk style artwork",
    "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/image-to-image/:id/stream

สตรีมงาน Image to Image

เอนด์พอยต์นี้จะสตรีมข้อมูลอัปเดตแบบเรียลไทม์สำหรับงานรูปภาพเป็นรูปภาพโดยใช้ Server-Sent Events (SSE)

พารามิเตอร์

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

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

ส่งกลับสตรีมของ The Image to Image Task Objects ในรูปแบบ Server-Sent Events

สำหรับงานที่มีสถานะ PENDING หรือ IN_PROGRESS สตรีมการตอบกลับจะมีเฉพาะฟิลด์ progress และ status ที่จำเป็นเท่านั้น

Request

GET

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

curl -N https://api.meshy.ai/openapi/v1/image-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": "image-to-image",
  "ai_model": "nano-banana",
  "prompt": "Transform this into a cyberpunk style artwork",
  "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 Image to Image Task Object

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

คุณสมบัติ

Name
id
Type
string
Description
ตัวระบุที่ไม่ซ้ำกันสำหรับ task แม้ว่าเราจะใช้ k-sortable UUID สำหรับ task id เป็นรายละเอียดในการนำไปใช้งาน แต่คุณ ไม่ควร ตั้งสมมติฐานใดๆ เกี่ยวกับรูปแบบของ id
Name
type
Type
string
Description
ประเภทของ task การสร้างรูปภาพ สำหรับ Image to Image task ค่านี้จะเป็น image-to-image เสมอ
Name
ai_model
Type
string
Description
โมเดล AI ที่ใช้สำหรับ task นี้ ค่าที่เป็นไปได้คือ 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
สถานะของ 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 Image to Image Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "image-to-image",
  "ai_model": "nano-banana",
  "prompt": "Transform this into a cyberpunk style artwork",
  "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
}