Image to Image API

Image to Image API là một tính năng cho phép bạn tích hợp khả năng chỉnh sửa ảnh bằng AI của Meshy vào ứng dụng của riêng mình. Biến đổi và chỉnh sửa các ảnh hiện có bằng cách sử dụng ảnh tham chiếu và các prompt văn bản với các mô hình AI mạnh mẽ của chúng tôi.

endpoint này tạo ra ảnh. Nếu mục tiêu là một vật thể bạn có thể cầm nắm hoặc in ra — một móc khóa, nam châm tủ lạnh, tượng, đèn hoặc keycap từ một bức ảnh — hãy sử dụng Creative Lab APIs (ảnh prototype → xây dựng mô hình 3D). Nếu mục tiêu là một mô hình 3D của vật thể trong bức ảnh, hãy sử dụng Ảnh sang 3D.

POST/openapi/v1/image-to-image

Create an Image to Image Task

Endpoint này cho phép bạn tạo một tác vụ Ảnh sang ảnh mới. Tham khảo The Image to Image Task Object để xem các thuộc tính nào được bao gồm trong đối tượng tác vụ Ảnh sang ảnh.

Tác vụ chạy ngầm trong nền. Để biết thời gian xử lý thường mất bao lâu, xem Processing Times.

Tham số

Name
ai_model
Type
string
Bắt buộc
Description
ID của mô hình sử dụng để tạo ảnh.
Các giá trị khả dụng:
- nano-banana: Mô hình tiêu chuẩn (3 tín dụng mỗi ảnh)
- nano-banana-2: Mô hình cân bằng với khả năng mạnh hơn mô hình tiêu chuẩn (6 tín dụng mỗi ảnh)
- nano-banana-2-lite: Phiên bản nhẹ của nano-banana-2 (3 tín dụng mỗi ảnh)
- nano-banana-pro: Mô hình Pro với chất lượng nâng cao (9 tín dụng mỗi ảnh)
- gpt-image-2: OpenAI GPT Image 2, một mô hình chỉnh sửa ảnh độ trung thực cao (12 tín dụng mỗi ảnh)
- gpt-image-2-5-flare: OpenAI GPT Image 2.5 (Flare), một mô hình chỉnh sửa ảnh độ trung thực cao (12 tín dụng mỗi ảnh)
- gpt-image-2-5-sunburst: OpenAI GPT Image 2.5 (Sunburst), một mô hình chỉnh sửa ảnh độ trung thực cao (12 tín dụng mỗi ảnh)
Name
prompt
Type
string
Bắt buộc
Description
Mô tả bằng văn bản về sự biến đổi hoặc chỉnh sửa bạn muốn áp dụng cho các ảnh tham chiếu.

Chỉ một trong hai input_task_id hoặc reference_image_urls là bắt buộc. Nếu cả hai đều được cung cấp, input_task_id sẽ được ưu tiên.

Name
input_task_id
Type
string
Bắt buộc
Description
ID của một tác vụ tạo ảnh đã hoàn thành mà các ảnh đầu ra của nó sẽ được dùng làm ảnh tham chiếu. Tác vụ này phải là một trong các loại tác vụ sau: Văn bản sang ảnh hoặc Ảnh sang ảnh, bao gồm cả các biến thể đa góc nhìn của chúng. Ngoài ra, nó phải được chạy qua API và có trạng thái SUCCEEDED.
Tất cả các ảnh đầu ra của tác vụ nguồn đều được sử dụng. Một tác vụ đơn ảnh đóng góp 1 ảnh tham chiếu; một tác vụ đa góc nhìn đóng góp một ảnh cho mỗi góc nhìn được tạo ra, do đó một ID tác vụ duy nhất có thể lấp đầy nhiều trong số 5 vị trí ảnh tham chiếu.
Tác vụ nguồn vẫn phải nằm trong thời gian lưu giữ tài nguyên — một khi hết hạn, ID của nó sẽ trả về 404.

Name
reference_image_urls
Type
array
Bắt buộc
Description
Một mảng từ 1 đến 5 ảnh tham chiếu để sử dụng cho tác vụ chỉnh sửa ảnh. Hiện tại chúng tôi hỗ trợ các định dạng .jpg, .jpeg, .png, và .webp.
Kích thước tệp tối đa: 20 MB mỗi ảnh.
Có hai cách để cung cấp mỗi ảnh:
- URL truy cập công khai: Một URL có thể truy cập từ internet công cộng.
- Data URI: Một data URI được mã hóa base64 của ảnh. Ví dụ về một data URI: data:image/jpeg;base64,<dữ liệu ảnh được mã hóa base64 của bạn>.

Name
generate_multi_view
Type
boolean
mặc định false
Description
Khi được đặt là true, tạo ra một ảnh đa góc nhìn hiển thị đối tượng từ nhiều góc độ khác nhau.
Khi generate_multi_view là true, tham số aspect_ratio không thể được thiết lập.
Name
aspect_ratio
Type
string
mặc định 1:1
Description
Chỉ định tỷ lệ khung hình của ảnh đầu ra. Các giá trị được phép tùy thuộc vào ai_model được chọn:
- 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
Các giá trị khả dụng:
- 1:1: Định dạng vuông
- 16:9: Màn hình rộng ngang
- 9:16: Màn hình rộng dọc
- 4:3: Ngang tiêu chuẩn
- 3:4: Dọc tiêu chuẩn
- 3:2: Ngang (chỉ được hỗ trợ bởi các mô hình GPT Image)
- 2:3: Dọc (chỉ được hỗ trợ bởi các mô hình GPT Image)
Name
remove_background
Type
boolean
mặc định false
Description
Khi được đặt là true, ảnh đầu ra được trả về dưới dạng PNG RGBA trong suốt với nền đã bị loại bỏ, cho phép bạn ghép đối tượng lên bất kỳ nền nào.

Giá trị trả về

Thuộc tính result của phản hồi chứa id tác vụ của tác vụ Ảnh sang ảnh vừa được tạo.

Các chế độ lỗi

Name
400 - Bad Request
Description
Yêu cầu không được chấp nhận. Các nguyên nhân phổ biến:
- Thiếu tham số: Một tham số bắt buộc (ví dụ: ai_model, prompt) bị thiếu, hoặc không có reference_image_urls lẫn input_task_id nào được cung cấp.
- Tác vụ đầu vào không hợp lệ: input_task_id phải tham chiếu đến một tác vụ Văn bản sang ảnh hoặc Ảnh sang ảnh có trạng thái SUCCEEDED (bao gồm cả đa góc nhìn) và vẫn còn ảnh đầu ra. Một tác vụ thuộc loại khác, một tác vụ chưa thành công, hoặc một tác vụ mà tất cả ảnh của nó đã hết hạn sẽ bị từ chối.
- Định dạng ảnh không hợp lệ: Một hoặc nhiều ảnh tham chiếu không thuộc các định dạng được hỗ trợ.
- URL không thể truy cập: Một hoặc nhiều reference_image_urls không thể tải xuống.
- Ảnh quá lớn: Một hoặc nhiều ảnh trong reference_image_urls vượt quá 20 MB.
- Tham số không hợp lệ: aspect_ratio không phải là một trong các giá trị được phép cho ai_model đã chọn.
- Xung đột: generate_multi_view và aspect_ratio không thể được sử dụng đồng thời.
Name
401 - Unauthorized
Description
Xác thực thất bại. Vui lòng kiểm tra khóa API của bạn.
Name
402 - Payment Required
Description
Không đủ tín dụng để thực hiện tác vụ này.
Name
404 - Not Found
Description
input_task_id không tham chiếu đến một tác vụ thuộc sở hữu của tài khoản 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 đều trả về cùng một phản hồi.
Name
429 - Too Many Requests
Description
Bạn đã vượt quá giới hạn tốc độ.

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

Retrieve an Image to Image Task

Endpoint này cho phép bạn truy xuất một tác vụ Ảnh sang ảnh với một id tác vụ hợp lệ. Tham khảo Đối tượng tác vụ Ảnh sang ảnh để xem những thuộc tính nào được bao gồm trong đối tượng tác vụ Ảnh sang ảnh.

Tham số

Name
id
Type
path
Description
Định danh duy nhất của tác vụ Ảnh sang ảnh cần truy xuất.

Giá trị trả về

Phản hồi chứa đối tượng tác vụ Ảnh sang ảnh. Xem phần Đối tượng tác vụ Ảnh sang ảnh để biết chi tiết.

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

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

Endpoint này sẽ xóa vĩnh viễn một tác vụ Ảnh sang ảnh, bao gồm tất cả hình ảnh và dữ liệu liên quan. Hành động này không thể hoàn tác.

Tham số đường dẫn

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

Trạng thái tác vụ

Một tác vụ vẫn đang ở trạng thái PENDING sẽ được xóa và số tín dụng đã tiêu tốn tại thời điểm tạo sẽ được hoàn lại.

Một tác vụ đã ở trạng thái IN_PROGRESS thì không thể xóa: yêu cầu sẽ bị từ chối với mã 409 Conflict và tác vụ vẫn tiếp tục chạy. Tín dụng cho một tác vụ mà worker đã bắt đầu xử lý sẽ không được hoàn lại, vì vậy việc xóa nó giữa chừng 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, sau đó mới xóa.

Một tác vụ ở trạng thái kết thúc (SUCCEEDED, FAILED hoặc CANCELED) sẽ được xóa mà không được hoàn tín dụng.

Kết quả trả về

Trả về 200 OK khi thành công, hoặc 409 Conflict khi tác vụ đang ở trạng thái 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

Danh sách các tác vụ Ảnh sang ảnh

Endpoint này cho phép bạn lấy về danh sách các tác vụ Ảnh sang ảnh.

Tham số

Name
page_num
Type
integer
Description
Số trang dùng cho phân trang. Bắt đầu và mặc định là 1.
Name
page_size
Type
integer
Description
Giới hạn kích thước trang. Mặc định là 10 mục. Tối đa cho phép là 100 mục.
Name
sort_by
Type
string
Description
Trường dùng để sắp xếp. Các giá trị khả dụng:
- +created_at: Sắp xếp theo thời gian tạo tăng dần.
- -created_at: Sắp xếp theo thời gian tạo giảm dần.

Kết quả trả về

Trả về một danh sách được phân trang của 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

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

Endpoint này stream các cập nhật theo thời gian thực cho một tác vụ Ảnh sang ảnh bằng Server-Sent Events (SSE).

Tham số

Name
id
Type
path
Description
Định danh duy nhất của tác vụ Ảnh sang ảnh cần stream.

Giá trị trả về

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

Đối với các tác vụ ở trạng thái PENDING hoặc IN_PROGRESS, luồng phản hồi sẽ chỉ bao gồm các trường progress và status cần thiết.

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

Đối tượng Image to Image Task là một đơn vị công việc mà Meshy theo dõi để tạo ra một hình ảnh từ hình ảnh tham chiếu và đầu vào text prompt. Đối tượng này có các thuộc tính sau:

Thuộc tính

Name
id
Type
string
Description
Định danh duy nhất cho tác vụ. Mặc dù chúng tôi sử dụng UUID có thể sắp xếp theo k (k-sortable UUID) cho id tác vụ như là chi tiết triển khai, bạn không nên đưa ra bất kỳ giả định nào về định dạng của id.
Name
type
Type
string
Description
Loại tác vụ tạo hình ảnh. Đối với tác vụ Image to Image, giá trị này luôn là image-to-image.
Name
ai_model
Type
string
Description
Mô hình AI được sử dụng cho tác vụ này. Các giá trị có thể là nano-banana, nano-banana-2, nano-banana-2-lite, nano-banana-pro, gpt-image-2, gpt-image-2-5-flare, hoặc gpt-image-2-5-sunburst.
Name
prompt
Type
string
Description
Prompt văn bản được sử dụng để định hướng việc biến đổi hình ảnh.
Name
status
Type
string
Description
Trạng thái của tác vụ. Các giá trị có thể là một trong các giá trị PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Tiến độ của tác vụ. Nếu tác vụ chưa bắt đầu, thuộc tính này sẽ là 0. Khi tác vụ đã thành công, giá trị này sẽ trở thành 100.
Name
created_at
Type
timestamp
Description
Dấu thời gian cho biết thời điểm tác vụ được tạo, tính bằng mili giây.
Dấu thời gian đại diện cho số mili giây đã trôi qua kể từ ngày 1 tháng 1 năm 1970 UTC, tuân theo tiêu chuẩn RFC 3339. Ví dụ, Thứ Sáu, ngày 1 tháng 9 năm 2023, 12:00:00 CH GMT được biểu diễn là 1693569600000. Điều này áp dụng cho tất cả các dấu thời gian trong Meshy API.
Name
started_at
Type
timestamp
Description
Dấu thời gian cho biết thời điểm tác vụ được bắt đầu, tính bằng mili giây. Nếu tác vụ chưa bắt đầu, thuộc tính này sẽ là 0.
Name
finished_at
Type
timestamp
Description
Dấu thời gian cho biết thời điểm tác vụ hoàn thành, tính bằng mili giây. Nếu tác vụ chưa hoàn thành, thuộc tính này sẽ là 0.
Name
expires_at
Type
timestamp
Description
Dấu thời gian cho biết thời điểm kết quả tác vụ hết hạn, tính bằng mili giây.
Name
preceding_tasks
Type
integer
Description
Số lượng tác vụ đứng trước.
Giá trị của trường này chỉ có ý nghĩa khi trạng thái tác vụ là PENDING.
Name
image_urls
Type
array
Description
Một mảng các URL có thể tải xuống của các hình ảnh đã tạo. Khi generate_multi_view được bật, mảng này chứa ba URL hình ảnh đại diện cho các góc nhìn khác nhau. Nếu không, nó chứa một URL hình ảnh duy nhất.
Name
task_error
Type
object
Description
Chi tiết lỗi cho các tác vụ thất bại. Xem Lỗi để biết tham chiếu đầy đủ về đối tượng task_error.
Name
consumed_credits
Type
integer
Description
Số lượng tín dụng đã tiêu thụ bởi tác vụ này. Có mặt khi trạng thái tác vụ là PENDING, IN_PROGRESS, hoặc SUCCEEDED. Trả về 0 đối với các tác vụ FAILED (tín dụng được hoàn lại khi thất bại).

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
}