Image to Image API

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

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

POST/openapi/v1/image-to-image

สร้างงาน Image to Image

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

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

พารามิเตอร์

Name
ai_model
Type
string
จำเป็น
Description
ID ของโมเดลที่จะใช้สำหรับการสร้างรูปภาพ
ค่าที่ใช้ได้:
- nano-banana: โมเดลมาตรฐาน (3 เครดิตต่อรูปภาพ)
- nano-banana-2: โมเดลที่สมดุล มีความสามารถสูงกว่ามาตรฐาน (6 เครดิตต่อรูปภาพ)
- nano-banana-2-lite: รุ่น Lite ของ nano-banana-2 (3 เครดิตต่อรูปภาพ)
- 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 จะมี priority สูงกว่า

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

Name
reference_image_urls
Type
array
จำเป็น
Description
อาร์เรย์ของรูปภาพอ้างอิง 1 ถึง 5 รูป ที่ใช้สำหรับงานแก้ไขรูปภาพ ปัจจุบันเรารองรับรูปแบบไฟล์ .jpg, .jpeg, .png และ .webp
ขนาดไฟล์สูงสุด: 20 MB ต่อรูปภาพ
มีสองวิธีในการระบุรูปภาพแต่ละรูป:
- URL ที่เข้าถึงได้แบบสาธารณะ: URL ที่สามารถเข้าถึงได้จากอินเทอร์เน็ตสาธารณะ
- Data URI: data 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-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 ของงาน Image to Image ที่สร้างขึ้นใหม่

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

Name
400 - Bad Request
Description
คำขอไม่ถูกต้อง สาเหตุที่พบบ่อย:
- ขาดพารามิเตอร์: พารามิเตอร์ที่จำเป็น (เช่น ai_model, prompt) ขาดหายไป หรือไม่ได้ระบุทั้ง reference_image_urls และ input_task_id
- งานอินพุตไม่ถูกต้อง: input_task_id ต้องอ้างอิงถึงงาน Text to Image หรือ Image to Image ที่มีสถานะ SUCCEEDED (รวมถึงแบบมุมมองหลายด้าน) และยังมีรูปภาพผลลัพธ์อยู่ งานประเภทอื่น งานที่ยังไม่สำเร็จ หรืองานที่รูปภาพหมดอายุไปทั้งหมดแล้ว จะถูกปฏิเสธ
- รูปแบบรูปภาพไม่ถูกต้อง: รูปภาพอ้างอิงหนึ่งรูปขึ้นไปไม่ใช่รูปแบบที่รองรับ
- URL ไม่สามารถเข้าถึงได้: ไม่สามารถดาวน์โหลด reference_image_urls หนึ่งรายการขึ้นไปได้
- รูปภาพมีขนาดใหญ่เกินไป: รูปภาพ reference_image_urls หนึ่งรูปขึ้นไปมีขนาดเกิน 20 MB
- พารามิเตอร์ไม่ถูกต้อง: 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 ติดตามเพื่อสร้างรูปภาพจากรูปภาพอ้างอิง (reference images) และ text prompt ที่ป้อนเข้ามา อ็อบเจกต์นี้มีคุณสมบัติดังต่อไปนี้

Properties

Name
id
Type
string
Description
ตัวระบุเฉพาะสำหรับ task นี้ แม้ว่าเราจะใช้ k-sortable UUID สำหรับ task id เป็นรายละเอียดการใช้งานจริง แต่คุณไม่ควรตั้งสมมติฐานใดๆ เกี่ยวกับรูปแบบของ id นี้
Name
type
Type
string
Description
ประเภทของ task การสร้างรูปภาพ สำหรับ task ประเภท Image to Image ค่านี้จะเป็น image-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
progress ของ task หาก task ยังไม่เริ่มดำเนินการ ค่านี้จะเป็น 0 เมื่อ task สำเร็จแล้ว ค่านี้จะกลายเป็น 100
Name
created_at
Type
timestamp
Description
ไทม์สแตมป์ของเวลาที่สร้าง task นี้ หน่วยเป็นมิลลิวินาที
ไทม์สแตมป์แสดงถึงจำนวนมิลลิวินาทีที่ผ่านไปนับตั้งแต่วันที่ 1 มกราคม 1970 UTC โดยเป็นไปตาม มาตรฐาน RFC 3339 ตัวอย่างเช่น วันศุกร์ที่ 1 กันยายน 2023 เวลา 12:00:00 PM 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
}