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 bạn. Chuyển đổi và chỉnh sửa các hình ảnh hiện có bằng cách sử dụng hình ảnh tham chiếu và câu lệnh văn bản với các mô hình AI mạnh mẽ của chúng tôi.

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 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
ai_model
Type
string
Bắt buộc
Description
ID của mô hình được 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 tiêu chuẩn (6 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 có độ 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 có độ 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 có độ 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ự chuyển đổi hoặc chỉnh sửa mà bạn muốn áp dụng cho các ảnh tham chiếu.

Chỉ cần một trong hai trường 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 sử 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 thông qua API và có trạng thái là 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ụ một ả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 phải vẫn còn nằm trong thời gian lưu giữ tài nguyên — 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 gồm 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, và .png.
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 được từ internet công cộng.
- Data URI: Một data URI mã hóa base64 của ảnh. Ví dụ về một data URI: data:image/jpeg;base64,<dữ liệu ảnh mã hóa base64 của bạn>.

Name
generate_multi_view
Type
boolean
mặc định false
Description
Khi được đặt thành true, tạo ra một ảnh đa góc nhìn thể hiện chủ thể từ nhiều góc độ.
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 phụ thuộc vào ai_model được chọn:
- 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
Các giá trị khả dụng:
- 1:1: Định dạng vuông
- 16:9: Ngang màn hình rộng
- 9:16: Dọc màn hình rộng
- 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 thành true, ảnh đầu ra được trả về dưới dạng PNG RGBA trong suốt với nền đã được xóa, để bạn có thể ghép chủ thể lên bất kỳ nền nào.

Kết quả trả về

Thuộc tính result của phản hồi chứa id 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 (bao gồm cả đa góc nhìn) có trạng thái SUCCEEDED và vẫn còn ảnh đầu ra. Bất kỳ tác vụ nào thuộc loại khác, chưa thành công, hoặc có tất cả ảnh đã hết hạn đều 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 đị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 được.
- Tham số không hợp lệ: aspect_ratio không phải là một trong các giá trị được phép đối với 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 sẽ 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 độ của mình.

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

Đối tượng Task Image to Image

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

Thuộc tính

Name
id
Type
string
Description
Mã định danh duy nhất cho task. Mặc dù chúng tôi sử dụng UUID có thể sắp xếp theo k (k-sortable UUID) cho id của task như một 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 task tạo ảnh. Đối với task 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 task này. Các giá trị có thể là nano-banana, nano-banana-2, 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 ảnh.
Name
status
Type
string
Description
Trạng thái của task. 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 task. Nếu task chưa bắt đầu, thuộc tính này sẽ là 0. Khi task đã thành công, giá trị này sẽ trở thành 100.
Name
created_at
Type
timestamp
Description
Dấu thời gian khi task được tạo, tính bằng mili giây.
Một 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, theo tiêu chuẩn RFC 3339. Ví dụ, thứ Sáu, ngày 1 tháng 9 năm 2023 lúc 12:00:00 chiều 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 khi task được bắt đầu, tính bằng mili giây. Nếu task chưa được bắt đầu, thuộc tính này sẽ là 0.
Name
finished_at
Type
timestamp
Description
Dấu thời gian khi task được hoàn thành, tính bằng mili giây. Nếu task 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 khi kết quả của task hết hạn, tính bằng mili giây.
Name
preceding_tasks
Type
integer
Description
Số lượng các task đứng trước.
Giá trị của trường này chỉ có ý nghĩa khi trạng thái task 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 ảnh được tạo ra. Khi generate_multi_view được bật, mảng này chứa ba URL ảnh đại diện cho các góc nhìn khác nhau. Nếu không, mảng này chỉ chứa một URL ảnh duy nhất.
Name
task_error
Type
object
Description
Chi tiết lỗi cho các task thất bại. Xem Lỗi để biết đầy đủ tham chiếu về đối tượng task_error.
Name
consumed_credits
Type
integer
Description
Số lượng tín dụng đã tiêu thụ bởi task này. Có mặt khi trạng thái task là PENDING, IN_PROGRESS, hoặc SUCCEEDED. Trả về 0 đối với các task FAILED (tín dụng sẽ đượ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
}