API Ảnh sang ảnh

Chỉnh sửa và biến đổi hình ảnh trong ứng dụng của riêng bạn. Gửi hình ảnh tham chiếu và một prompt dạng văn bản, các mô hình AI của Meshy sẽ tạo ra một hình ảnh mới từ chúng.

Ảnh sang ảnh tạo ra hình ảnh. Để tạo mô hình 3D từ nội dung trong một hình ảnh, hãy sử dụng Ảnh sang 3D. Để tạo một vật thể mà bạn có thể cầm nắm hoặc in ra từ một bức ảnh, hãy sử dụng Creative Lab APIs. Chúng tạo ra một hình ảnh nguyên mẫu rồi dựng mô hình 3D từ đó, ví dụ như móc khóa, nam châm tủ lạnh, tượng, đèn hoặc nắp phím.

POST/openapi/v1/image-to-image

Tạo một tác vụ Ảnh sang ảnh

Tạo một tác vụ Ảnh sang ảnh. Tác vụ chạy ngầm. Để biết một tác vụ thường mất bao lâu, xem Thời gian xử lý.

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

Tham số

Name
ai_model
Type
string
Bắt buộc
Description
Mô hình AI tạo ra hình ảnh. Giá khác nhau tùy theo mô hình. Xem Giá.
Các giá trị khả dụng:
- nano-banana: mô hình tiêu chuẩn
- nano-banana-2: mạnh hơn nano-banana
- nano-banana-2-lite: phiên bản lite của nano-banana-2
- nano-banana-2-1: Nano Banana 2.1
- nano-banana-pro: mô hình Pro, có chất lượng cao hơn. Yêu cầu gói Pro trở lên. Trên gói thấp hơn, nó trả về 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
Bắt buộc
Description
Văn bản mô tả chỉnh sửa hoặc biến đổi cần áp dụng cho các hình ảnh tham chiếu.

Name
input_task_id
Type
string
Bắt buộc
Description
Bắt buộc trừ khi bạn gửi reference_image_urls. ID của một tác vụ Văn bản sang ảnh hoặc Ảnh sang ảnh mà hình ảnh của nó sẽ được dùng làm tham chiếu, kể cả các tác vụ đa góc nhìn. Tác vụ này phải là tác vụ bạn đã tạo bằng API và có trạng thái SUCCEEDED.
Meshy sử dụng mọi hình ảnh mà tác vụ đó đã tạo ra. Một tác vụ đơn ảnh cho một hình ảnh tham chiếu, còn một tác vụ đa góc nhìn cho một hình ảnh mỗi góc nhìn. Vì vậy, một ID tác vụ có thể lấp đầy nhiều trong số năm vị trí tham chiếu.
Tác vụ vẫn phải còn trong thời hạn lưu giữ tài nguyên. Sau khi hết hạn, ID của nó trả về 404.

Name
reference_image_urls
Type
array
Bắt buộc
Description
Bắt buộc trừ khi bạn gửi input_task_id. Một đến năm hình ảnh tham chiếu cần chỉnh sửa, mỗi hình là một URL công khai hoặc một Data URI, ví dụ data:image/jpeg;base64,<dữ liệu hình ảnh mã hóa base64 của bạn>. Một mảng rỗng, hoặc nhiều hơn năm hình ảnh, sẽ trả về 400. Nếu bạn gửi cả hai, Meshy sử dụng input_task_id.
Mỗi hình ảnh phải là một tệp .jpg, .jpeg, .png, hoặc .webp tối đa 20 MB, và ít nhất 32 pixel mỗi cạnh.

Name
generate_multi_view
Type
boolean
mặc định false
Description
Có tạo một hình ảnh đa góc nhìn thể hiện chủ thể từ nhiều góc độ hay không. Khi là true, bạn không thể gửi aspect_ratio. Gửi cả hai sẽ trả về 400.
Name
aspect_ratio
Type
string
mặc định 1:1
Description
Tỷ lệ khung hình của hình ảnh đầu ra. Các giá trị bạn có thể gửi phụ thuộc vào ai_model.
Các giá trị khả dụng:
- 1:1: vuông
- 16:9: cảnh rộng ngang
- 9:16: cảnh rộng dọc
- 4:3: ngang tiêu chuẩn
- 3:4: dọc tiêu chuẩn
- 3:2: ngang, chỉ dành cho các mô hình GPT Image
- 2:3: dọc, chỉ dành cho các mô hình GPT Image
Các mô hình GPT Image là gpt-image-2, gpt-image-2-5-flare, và gpt-image-2-5-sunburst. Với một mô hình nano-banana, 3:2 và 2:3 sẽ trả về 400.
Name
remove_background
Type
boolean
mặc định false
Description
Có loại bỏ nền hay không. Khi là true, Meshy trả về hình ảnh đầu ra dưới dạng PNG RGBA trong suốt, để bạn có thể đặt chủ thể lên bất kỳ nền nào.

Giá trị trả về

Trường result trong phản hồi chứa ID của tác vụ Ảnh sang ảnh mới.

Các chế độ lỗi

Name
400 - Bad Request
Description
Yêu cầu không thể chạy. Thông báo lỗi cho biết vấn đề mà nó phát hiện. Ví dụ:
- Thiếu tham số: Một tham số bắt buộc, chẳng hạn như ai_model hoặc prompt, bị thiếu, hoặc không có cả reference_image_urls lẫn input_task_id được gửi.
- Tác vụ đầu vào không hợp lệ: input_task_id không trỏ đến một tác vụ có thể sử dụng được. Nó phải là một tác vụ Văn bản sang ảnh hoặc Ảnh sang ảnh SUCCEEDED, kể cả đa góc nhìn, mà vẫn còn hình ảnh đầu ra. Meshy từ chối một tác vụ thuộc loại khác, một tác vụ chưa thành công, và một tác vụ mà tất cả hình ảnh của nó đã hết hạn.
- Định dạng hình ảnh không hợp lệ: Một hoặc nhiều hình ảnh tham chiếu không ở định dạng được hỗ trợ.
- URL không thể truy cập: Meshy không thể tải xuống một hoặc nhiều hình ảnh reference_image_urls.
- Hình ảnh quá lớn: Một hoặc nhiều hình ảnh reference_image_urls vượt quá 20 MB.
- Hình ảnh quá nhỏ: Một hoặc nhiều hình ảnh reference_image_urls có một cạnh ngắn hơn 32 pixel.
- Tham số không hợp lệ: aspect_ratio không phải là một trong các giá trị mà ai_model đã chọn hỗ trợ.
- Xung đột: Yêu cầu gửi aspect_ratio cùng với generate_multi_view: true.
Hãy sửa yêu cầu, sau đó gửi lại. Xem Lỗi.
Name
401 - Unauthorized
Description
khóa API bị thiếu hoặc không hợp lệ. Kiểm tra tiêu đề Authorization.
Name
402 - Payment Required
Description
Tài khoản không thể chạy tác vụ này. Ví dụ:
- Gói miễn phí: Tạo một tác vụ yêu cầu gói trả phí. Hãy nâng cấp gói của bạn trong cài đặt đăng ký, sau đó thử lại.
- Không đủ tín dụng: Tài khoản không có đủ tín dụng cho tác vụ này, hoặc tài khoản đã đạt đến giới hạn tín dụng.
- Yêu cầu gói: Yêu cầu sử dụng nano-banana-pro trên một gói thấp hơn Pro.
Hãy kiểm tra số dư tín dụng và gói của bạn, sau đó thử lại.
Name
404 - Not Found
Description
input_task_id không khớp với tác vụ nào trong tài khoản của bạn. Một tác vụ không tồn tại và một tác vụ thuộc về tài khoản khác trả về cùng một phản hồi. Hãy kiểm tra ID.
Name
429 - Too Many Requests
Description
Bạn đã vượt quá giới hạn tốc độ của mình. Hãy chờ, sau đó thử lại. Xem Giới hạn tốc độ.

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

Lấy một tác vụ Ảnh sang ảnh

Trả về một tác vụ Ảnh sang ảnh theo ID của nó.

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

Tham số

Name
id
Type
path
Description
ID của tác vụ từ phản hồi tạo tác vụ.

Giá trị trả về

Đối tượng tác vụ Ảnh sang ảnh.

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

Xóa một tác vụ Ảnh sang ảnh

Xóa vĩnh viễn một tác vụ Ảnh sang ảnh, bao gồm các hình ảnh và dữ liệu của nó. Bạn không thể hoàn tác việc xóa.

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

Tham số đường dẫn

Name
id
Type
path
Description
ID của tác vụ cần xóa.

Trạng thái tác vụ

Xóa một tác vụ PENDING sẽ hoàn lại tín dụng đã sử dụng khi bạn tạo tác vụ đó.

Một tác vụ IN_PROGRESS không thể bị xóa. Yêu cầu sẽ trả về 409 Conflict, và tác vụ vẫn tiếp tục chạy. Meshy không hoàn lại tín dụng cho một tác vụ đã bắt đầu, vì vậy việc xóa nó sẽ khiến bạn mất cả tín dụng lẫn kết quả. Hãy đợi cho đến khi tác vụ đạt trạng thái SUCCEEDED, FAILED, hoặc CANCELED, rồi mới xóa.

Xóa một tác vụ ở trạng thái cuối cùng (SUCCEEDED, FAILED, hoặc CANCELED) sẽ không hoàn lại tín dụng.

Giá trị trả về

200 OK khi tác vụ được xóa, hoặc 409 Conflict khi tác vụ đang ở trạng thái IN_PROGRESS.

GET/openapi/v1/image-to-image

Liệt kê các tác vụ Ảnh sang ảnh

Trả về danh sách các tác vụ Ảnh sang ảnh và Văn bản sang ảnh của bạn. Trường type của mỗi tác vụ cho biết đó là loại nào trong hai loại này.

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

Tham số

Name
page_num
Type
integer
Description
Số trang cần trả về. Bắt đầu từ và mặc định là 1.
Name
page_size
Type
integer
Description
Số lượng tác vụ trên mỗi trang, tối đa 100. Mặc định là 10.
Name
sort_by
Type
string
Description
Thứ tự sắp xếp.
Các giá trị khả dụng:
- +created_at: cũ nhất trước
- -created_at: mới nhất trước

Kết quả trả về

Một danh sách phân trang các đối tượng tác vụ, theo cùng định dạng với đối tượng tác vụ Ảnh sang ảnh.

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

Stream một tác vụ Ảnh sang ảnh

Stream các cập nhật của một tác vụ Ảnh sang ảnh dưới dạng 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=***"
  ]
}

Tham số

Name
id
Type
path
Description
ID tác vụ từ phản hồi tạo tác vụ.

Giá trị trả về

Một luồng đối tượng tác vụ Ảnh sang ảnh dưới dạng Server-Sent Events.

Mỗi sự kiện chứa toàn bộ đối tượng tác vụ, theo cùng cấu trúc mà endpoint Get trả về. Trong khi tác vụ đang ở trạng thái PENDING hoặc IN_PROGRESS, các trường kết quả của nó chưa có giá trị.

Đối tượng tác vụ Ảnh sang ảnh

Một đối tượng tác vụ Ảnh sang ảnh mô tả một hình ảnh được tạo ra từ các hình ảnh tham chiếu và một prompt văn bản. Nó lưu giữ trạng thái, progress, và các hình ảnh khi tác vụ thành công.

Thuộc tính

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
ID của tác vụ. Hãy xem đây là một chuỗi không minh bạch, và đừng dựa vào định dạng của nó.
Name
type
Type
string
Description
Loại tác vụ, luôn là image-to-image.
Name
ai_model
Type
string
Description
Mô hình AI mà tác vụ đã sử dụng.
Các giá trị khả dụng:
- 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 văn bản định hướng việc chỉnh sửa.
Name
status
Type
string
Description
Trạng thái của tác vụ, là một trong các giá trị PENDING, IN_PROGRESS, SUCCEEDED, FAILED, hoặc CANCELED.
Name
progress
Type
integer
Description
Mức độ hoàn thành của tác vụ, tính theo phần trăm. Giá trị là 0 cho đến khi tác vụ bắt đầu và 100 khi tác vụ thành công.
Name
created_at
Type
timestamp
Description
Thời điểm tác vụ được tạo, tính bằng mili-giây Unix.
Name
started_at
Type
timestamp
Description
Thời điểm tác vụ bắt đầu, tính bằng mili-giây Unix. Không có cho đến khi tác vụ bắt đầu.
Name
finished_at
Type
timestamp
Description
Thời điểm tác vụ kết thúc, tính bằng mili-giây Unix. Không có cho đến khi tác vụ kết thúc.
Name
expires_at
Type
timestamp
Description
Thời điểm kết quả của tác vụ hết hạn, tính bằng mili-giây Unix. Không có cho đến khi tác vụ kết thúc.
Name
preceding_tasks
Type
integer
Description
Số lượng tác vụ đứng trước tác vụ này trong hàng đợi. Giá trị này chỉ có ý nghĩa khi tác vụ đang ở trạng thái PENDING. Trường này sẽ bị bỏ qua khi giá trị là 0.
Name
image_urls
Type
array
Description
Các URL tải xuống cho những hình ảnh được tạo ra. Với generate_multi_view: true, nó lưu giữ một URL cho mỗi góc nhìn, thường là ba. Nếu Meshy không thể tách riêng từng góc nhìn, nó sẽ trả về ít hơn, và tác vụ vẫn thành công. Nếu không, nó lưu giữ một URL duy nhất.
Name
task_error
Type
object
Description
Chi tiết lỗi khi tác vụ thất bại. Giá trị là null trừ khi trạng thái là FAILED. Xem Lỗi.
Name
consumed_credits
Type
integer
Description
Số lượng tín dụng mà tác vụ đã sử dụng. Có mặt khi trạng thái là PENDING, IN_PROGRESS, hoặc SUCCEEDED. Giá trị là 0 đối với một tác vụ FAILED, vì Meshy sẽ hoàn lại tín dụng khi một tác vụ thất bại.