Image to Image API

แก้ไขและแปลงรูปภาพในแอปพลิเคชันของคุณเอง ส่งรูปภาพอ้างอิงและ prompt ข้อความ แล้วโมเดล AI ของ Meshy จะสร้างรูปภาพใหม่จากรูปภาพเหล่านั้น

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

POST/openapi/v1/image-to-image

สร้างงาน Image to Image

สร้างงาน Image to Image งานนี้จะทำงานอยู่เบื้องหลัง สำหรับระยะเวลาที่งานมักใช้ ดูที่ เวลาในการประมวลผล

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

พารามิเตอร์

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
input_task_id
Type
string
จำเป็น
Description
จำเป็นต้องระบุ เว้นแต่คุณจะส่ง reference_image_urls คือ ID ของงาน Text to Image หรือ Image to Image ที่จะใช้รูปภาพของงานนั้นเป็นข้อมูลอ้างอิง รวมถึงงานแบบมุมมองหลายด้านด้วย งานนั้นต้องเป็นงานที่คุณสร้างด้วย API และมีสถานะ SUCCEEDED
Meshy ใช้รูปภาพทุกรูปที่งานนั้นสร้างขึ้น งานแบบรูปภาพเดียวจะให้รูปภาพอ้างอิงหนึ่งรูป และงานแบบมุมมองหลายด้านจะให้หนึ่งรูปต่อหนึ่งมุมมอง ดังนั้น ID ของงานเดียวอาจเติมเต็มช่องรูปภาพอ้างอิงได้หลายช่องจากทั้งหมดห้าช่อง
งานนั้นต้องยังอยู่ภายในระยะเวลาการเก็บรักษาแอสเซ็ต หลังจากหมดอายุแล้ว ID ของงานจะคืนค่า 404

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

Name
generate_multi_view
Type
boolean
ค่าเริ่มต้น false
Description
ว่าจะสร้างรูปภาพมุมมองหลายด้านที่แสดงหัวเรื่องจากหลายมุมหรือไม่ เมื่อเป็น true คุณจะส่ง aspect_ratio ไม่ได้ การส่งทั้งสองอย่างจะคืนค่า 400
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 เท่านั้น
โมเดล GPT Image ได้แก่ gpt-image-2, gpt-image-2-5-flare, และ gpt-image-2-5-sunburst หากใช้โมเดล nano-banana ค่า 3:2 และ 2:3 จะคืนค่า 400
Name
remove_background
Type
boolean
ค่าเริ่มต้น false
Description
ว่าจะลบพื้นหลังหรือไม่ เมื่อเป็น true Meshy จะคืนรูปภาพผลลัพธ์เป็น 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 รวมถึงงานแบบมุมมองหลายด้าน ซึ่งยังมีรูปภาพผลลัพธ์อยู่ Meshy จะปฏิเสธงานประเภทอื่น งานที่ยังไม่สำเร็จ และงานที่รูปภาพหมดอายุไปหมดแล้ว
- รูปแบบรูปภาพไม่ถูกต้อง: รูปภาพอ้างอิงหนึ่งรูปขึ้นไปไม่ได้อยู่ในรูปแบบที่รองรับ
- URL ไม่สามารถเข้าถึงได้: Meshy ไม่สามารถดาวน์โหลดรูปภาพ reference_image_urls หนึ่งรูปขึ้นไปได้
- รูปภาพมีขนาดใหญ่เกินไป: รูปภาพ reference_image_urls หนึ่งรูปขึ้นไปมีขนาดเกิน 20 MB
- รูปภาพมีขนาดเล็กเกินไป: รูปภาพ reference_image_urls หนึ่งรูปขึ้นไปมีด้านที่สั้นกว่า 32 พิกเซล
- พารามิเตอร์ไม่ถูกต้อง: aspect_ratio ไม่ใช่ค่าใดค่าหนึ่งที่ ai_model ที่เลือกรองรับ
- ความขัดแย้ง: คำขอส่ง aspect_ratio พร้อมกับ generate_multi_view: true
แก้ไขคำขอ แล้วส่งใหม่อีกครั้ง ดู ข้อผิดพลาด
Name
401 - Unauthorized
Description
API คีย์ขาดหายไปหรือไม่ถูกต้อง ตรวจสอบส่วนหัว Authorization
Name
402 - Payment Required
Description
บัญชีนี้ไม่สามารถเรียกใช้งานนี้ได้ ตัวอย่างเช่น:
- แพลนฟรี: การสร้างงานต้องใช้แพลนแบบชำระเงิน อัปเกรดแพลนของคุณในการตั้งค่าการสมัครสมาชิก แล้วลองใหม่
- เครดิตไม่เพียงพอ: บัญชีนี้ไม่มีเครดิตเพียงพอสำหรับงานนี้ หรือบัญชีถึงขีดจำกัดเครดิตแล้ว
- ต้องใช้แพลนที่กำหนด: คำขอใช้ nano-banana-pro ในแพลนที่ต่ำกว่า Pro
ตรวจสอบยอดเครดิตคงเหลือและแพลนของคุณ แล้วลองใหม่
Name
404 - Not Found
Description
input_task_id ไม่ตรงกับงานใด ๆ ในบัญชีของคุณ งานที่ไม่มีอยู่จริงและงานที่เป็นของบัญชีอื่นจะคืนค่าการตอบกลับเดียวกัน ตรวจสอบ ID
Name
429 - Too Many Requests
Description
คุณเกินขีดจำกัดอัตราการเรียกใช้งานแล้ว รอสักครู่ แล้วลองใหม่ ดู การจำกัดอัตรา

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

ดึงข้อมูลงาน Image to Image

คืนค่างาน Image to Image ตามรหัส (ID) ของงานนั้น

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=***"
  ]
}

พารามิเตอร์

Name
id
Type
path
Description
รหัสงานจากการตอบกลับของการสร้าง

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

อ็อบเจ็กต์งาน Image to Image

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

ลบงาน Image to Image

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

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

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

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

สถานะของงาน

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

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

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

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

200 OK เมื่อลบงานสำเร็จ หรือ 409 Conflict เมื่อสถานะของงานเป็น IN_PROGRESS

GET/openapi/v1/image-to-image

แสดงรายการงาน Image to Image

คืนค่ารายการงาน Image to Image และ Text to Image ของคุณ โดยฟิลด์ type ของแต่ละงานจะบอกว่าเป็นงานประเภทใดในสองประเภทนี้

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=***"
    ]
  }
]

พารามิเตอร์

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: ใหม่สุดก่อน

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

รายการออบเจ็กต์งานแบบแบ่งหน้า ในรูปแบบเดียวกับ ออบเจ็กต์งาน Image to Image

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

สตรีมงาน Image to Image

สตรีมการอัปเดตของงาน Image to Image ในรูปแบบ Server-Sent Events (SSE)

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.
// 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": "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=***"
  ]
}

พารามิเตอร์

Name
id
Type
path
Description
ไอดีของงานจากการตอบกลับของการสร้าง

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

สตรีมของ Image to Image task objects ในรูปแบบ Server-Sent Events

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

The Image to Image task object

Image to Image task object อธิบายถึงรูปภาพหนึ่งที่สร้างขึ้นจากรูปภาพอ้างอิงและ prompt ข้อความ โดยจะเก็บสถานะ progress และรูปภาพเมื่องานสำเร็จ

คุณสมบัติ

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,
  "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
ประเภทของงาน ซึ่งจะเป็น image-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 จะคืนเครดิตให้เมื่องานล้มเหลว