API Ảnh sang ảnh

API Ảnh sang ảnh là một tính năng cho phép bạn tích hợp khả năng chỉnh sửa hình ảnh AI của Meshy vào ứng dụng của riêng bạn. Chuyển đổi và chỉnh sửa hình ảnh hiện có bằng cách sử dụng hình ảnh tham chiếu và lời nhắc 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

Tạo một Nhiệm vụ Ảnh sang ảnh

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

Tham số

Name
ai_model
Type
string
Bắt buộc
Description
ID của mô hình để sử dụng cho việc tạo ảnh.
Các giá trị có sẵn:
- 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ô 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ả 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.
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 nhiệm 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 có thể 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 mã hóa base64 của ảnh. Ví dụ về một Data URI: data:image/jpeg;base64,<your base64-encoded image data>.
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 hiển thị đối tượng từ nhiều góc độ.
Khi generate_multi_view là true, tham số aspect_ratio không thể được đặt.
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 đã chọn:
- nano-banana, nano-banana-2, nano-banana-pro: 1:1, 16:9, 9:16, 4:3, 3:4
- gpt-image-2: 1:1, 16:9, 9:16, 3:2, 2:3
Các giá trị có sẵn:
- 1:1: Định dạng vuông
- 16:9: Cảnh rộng màn hình ngang
- 9:16: Cảnh rộng màn hình dọc
- 4:3: Cảnh tiêu chuẩn ngang (không được hỗ trợ bởi gpt-image-2)
- 3:4: Cảnh tiêu chuẩn dọc (không được hỗ trợ bởi gpt-image-2)
- 3:2: Cảnh ngang (chỉ được hỗ trợ bởi gpt-image-2)
- 2:3: Cảnh dọc (chỉ được hỗ trợ bởi gpt-image-2)
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 loại bỏ, để bạn có thể ghép đối tượng lên bất kỳ nền nào.

Trả về

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

Chế độ thất bại

Name
400 - Bad Request
Description
Yêu cầu không chấp nhận đượ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, reference_image_urls) bị thiếu.
- Định dạng ảnh không hợp lệ: Một hoặc nhiều ảnh tham chiếu không phải là đị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.
- Tham số không hợp lệ: aspect_ratio không phải là một trong những 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 nhiệm vụ này.
Name
429 - Too Many Requests
Description
Bạn đã vượt quá giới hạn tốc độ của mình.

Yêu cầu

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

Phản hồi

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}

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

Truy xuất một Nhiệm vụ Ảnh sang ảnh

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

Tham số

Name
id
Type
path
Description
Định danh duy nhất cho nhiệm vụ Ảnh sang ảnh cần truy xuất.

Trả về

Phản hồi chứa đối tượng nhiệm vụ Ảnh sang ảnh. Kiểm tra phần Đối tượng Nhiệm vụ Ảnh sang ảnh để biết chi tiết.

Yêu cầu

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

Phản hồi

{
  "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 xóa vĩnh viễn một tác vụ Ảnh sang ảnh, bao gồm tất cả các hình ảnh và dữ liệu liên quan. Hành động này không thể đảo ngượ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ả về

Trả về 200 OK khi thành công.

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

// Returns 200 Ok on success.

GET/openapi/v1/image-to-image

Danh sách Nhiệm vụ Ảnh sang ảnh

Endpoint này cho phép bạn truy xuất danh sách các nhiệm vụ Ảnh sang ảnh.

Tham số

Name
page_num
Type
integer
Description
Số trang 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à 50 mục.
Name
sort_by
Type
string
Description
Trường để sắp xếp. Các giá trị có sẵn:
- +created_at: Sắp xếp theo thời gian tạo theo thứ tự tăng dần.
- -created_at: Sắp xếp theo thời gian tạo theo thứ tự giảm dần.

Trả về

Trả về danh sách phân trang của Các Đối tượng Nhiệm vụ Ảnh sang ảnh.

Yêu cầu

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

Phản hồi

[
  {
    "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

Truyền tải một tác vụ Ảnh sang ảnh

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

Tham số

Name
id
Type
path
Description
Định danh duy nhất cho tác vụ Ảnh sang ảnh cần truyền tải.

Trả về

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

Đối với các tác vụ 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 Nhiệm vụ Ảnh sang Ảnh

Đối tượng Nhiệm vụ Ảnh sang Ảnh 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 prompt văn bản. Đối tượng có các thuộc tính sau:

Thuộc tính

Name
id
Type
string
Description
Định danh duy nhất cho nhiệm vụ. Mặc dù chúng tôi sử dụng UUID có thể sắp xếp k cho id nhiệm vụ 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 nhiệm vụ tạo hình ảnh. Đối với các nhiệm vụ Ảnh sang Ảnh, điều này sẽ luôn là image-to-image.
Name
ai_model
Type
string
Description
Mô hình AI được sử dụng cho nhiệm vụ này. Các giá trị có thể là nano-banana, nano-banana-2, nano-banana-pro, hoặc gpt-image-2.
Name
prompt
Type
string
Description
Prompt văn bản được sử dụng để hướng dẫn quá trình chuyển đổi hình ảnh.
Name
status
Type
string
Description
Trạng thái của nhiệm vụ. Các giá trị có thể là một trong PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Tiến độ của nhiệm vụ. Nếu nhiệm vụ chưa bắt đầu, thuộc tính này sẽ là 0. Khi nhiệm vụ đã thành công, điều này sẽ trở thành 100.
Name
created_at
Type
timestamp
Description
Dấu thời gian khi nhiệm vụ đượ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 12:00:00 PM 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 nhiệm vụ bắt đầu, tính bằng mili giây. Nếu nhiệm 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 khi nhiệm vụ kết thúc, tính bằng mili giây. Nếu nhiệm vụ chưa kết thúc, thuộc tính này sẽ là 0.
Name
expires_at
Type
timestamp
Description
Dấu thời gian khi kết quả nhiệm vụ hết hạn, tính bằng mili giây.
Name
preceding_tasks
Type
integer
Description
Số lượng nhiệm vụ trước đó.
Giá trị của trường này chỉ có ý nghĩa nếu trạng thái nhiệm 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 được tạo ra. Khi generate_multi_view được kích hoạ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 nhiệm vụ thất bại. Xem Lỗi để tham khảo đầy đủ đối tượng task_error.
Name
consumed_credits
Type
integer
Description
Số lượng tín dụng đã tiêu thụ bởi nhiệm vụ này. Có mặt khi trạng thái nhiệm vụ là PENDING, IN_PROGRESS, hoặc SUCCEEDED. Trả về 0 cho các nhiệm vụ FAILED (tín dụng được hoàn lại khi thất bại).

Ví dụ Đối tượng Nhiệm vụ Ảnh sang Ảnh

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