API Văn bản sang ảnh

Tạo ảnh từ một prompt văn bản bằng các mô hình AI của Meshy.

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

POST/openapi/v1/text-to-image

Tạo một tác vụ Văn bản sang ảnh

Tạo một tác vụ Văn bản sang ảnh. Tác vụ này 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/text-to-image

# Generate an image from a text prompt
curl https://api.meshy.ai/openapi/v1/text-to-image \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "ai_model": "nano-banana",
    "prompt": "A majestic dragon soaring through clouds at sunset",
    "aspect_ratio": "16:9"
  }'

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 ảnh. Giá khác nhau tùy theo mô hình. Về giá, 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 nhẹ của nano-banana-2
- nano-banana-2-1: Nano Banana 2.1
- nano-banana-pro: mô hình Pro, với chất lượng cao hơn. Yêu cầu gói Pro trở lê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ả ảnh cần tạo. Một mô tả chi tiết sẽ cho kết quả tốt hơn.
Name
generate_multi_view
Type
boolean
mặc định false
Description
Có tạo ảnh Đa góc nhìn hiển thị chủ thể từ nhiều góc độ hay không. Khi giá trị này là true, bạn không thể gửi aspect_ratio. Gửi cả hai sẽ trả về 400.
Name
pose_mode
Type
string
Description
Tư thế cho nhân vật, a-pose hoặc t-pose. Bỏ trống nếu không dùng tư thế.
Cách tư thế hoạt động phụ thuộc vào ai_model:
- nano-banana-2, nano-banana-2-lite, và nano-banana-2-1: Meshy giữ nguyên mô hình bạn đã chọn. Ảnh luôn có tỷ lệ 3:4, và Meshy bỏ qua aspect_ratio.
- nano-banana và nano-banana-pro: Meshy tạo ảnh bằng nano-banana-pro, nên ai_model của tác vụ sẽ được trả về là nano-banana-pro. Điều này yêu cầu gói Pro trở lên. Ảnh luôn có tỷ lệ 3:4, và Meshy bỏ qua aspect_ratio.
- Các mô hình GPT Image (gpt-image-2, gpt-image-2-5-flare, và gpt-image-2-5-sunburst): Meshy giữ nguyên mô hình bạn đã chọn và aspect_ratio của bạn.
Name
aspect_ratio
Type
string
mặc định 1:1
Description
Hình dạng của ảnh. 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: ngang rộng
- 9:16: dọc rộng
- 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 nano-banana (nano-banana, nano-banana-2, nano-banana-2-lite, nano-banana-2-1, và nano-banana-pro) trả về 400 cho 3:2 và 2:3.
Name
remove_background
Type
boolean
mặc định false
Description
Có xóa phông nền của ảnh hay không. true trả về một PNG RGBA trong suốt, nhờ đó bạn có thể đặt chủ thể lên bất kỳ phông nền nào.

Giá trị trả về

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

Các trường hợp 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 đề đã 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.
- Tham số không hợp lệ: ai_model hoặc aspect_ratio không phải là một trong các giá trị được phép.
- Xung đột: aspect_ratio được gửi cùng với generate_multi_view: true.
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í: Việc tạo tác vụ yêu cầu gói trả phí. 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 (Insufficient funds), hoặc tài khoản đã đạt giới hạn tín dụng.
- Yêu cầu gói: Yêu cầu sử dụng nano-banana-pro, hoặc pose_mode với nano-banana, trên gói thấp hơn Pro (Only Pro and above users can use nano-banana-pro, hoặc Only Pro and above users can use A/T pose feature (requires nano-banana-pro)).
Kiểm tra số dư tín dụng và gói của bạn, sau đó thử lại.
Name
429 - Too Many Requests
Description
Bạn đã vượt quá giới hạn tốc độ. Hãy đợi, rồi thử lại. Xem Giới hạn tốc độ.

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

Lấy tác vụ Văn bản sang ảnh

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

Request

GET

/openapi/v1/text-to-image/018a210d-8ba4-705c-b111-1f1776f7f578

curl https://api.meshy.ai/openapi/v1/text-to-image/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "text-to-image",
  "ai_model": "nano-banana",
  "prompt": "A majestic dragon soaring through clouds at sunset",
  "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ụ Văn bản sang ảnh.

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

Xóa một tác vụ Văn bản sang ảnh

Xóa vĩnh viễn một tác vụ Văn bản sang ảnh, bao gồm 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/text-to-image/018a210d-8ba4-705c-b111-1f1776f7f578

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/text-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 số tín dụng đã 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 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/text-to-image

List Text to Image tasks

Trả về danh sách các tác vụ Văn bản sang ảnh và Ảnh 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/text-to-image

curl https://api.meshy.ai/openapi/v1/text-to-image?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "text-to-image",
    "ai_model": "nano-banana",
    "prompt": "A majestic dragon soaring through clouds at sunset",
    "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

Giá trị trả về

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

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

Stream một task Văn bản sang ảnh

Truyền trực tuyến các cập nhật của task Văn bản sang ảnh dưới dạng Server-Sent Events (SSE).

Request

GET

/openapi/v1/text-to-image/018a210d-8ba4-705c-b111-1f1776f7f578/stream

curl -N https://api.meshy.ai/openapi/v1/text-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": "text-to-image",
  "ai_model": "nano-banana",
  "prompt": "A majestic dragon soaring through clouds at sunset",
  "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 task từ phản hồi tạo task.

Giá trị trả về

Một luồng đối tượng task Văn bản sang ảnh dưới dạng Server-Sent Events.

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

Đối tượng tác vụ Text to Image

Một đối tượng tác vụ Text to Image mô tả một lần tạo ảnh từ một prompt văn bản. Nó lưu trữ trạng thái, progress, và các URL ảnh khi tác vụ thành công.

Thuộc tính

Example Text to Image Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "text-to-image",
  "ai_model": "nano-banana",
  "prompt": "A majestic dragon soaring through clouds at sunset",
  "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 coi đây là một chuỗi không minh bạch (opaque string), và đừng phụ thuộc vào định dạng của nó.
Name
type
Type
string
Description
Loại tác vụ, luôn là text-to-image.
Name
ai_model
Type
string
Description
Mô hình AI mà tác vụ đã sử dụng.
Các giá trị có thể có:
- 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 bạn đã dùng để tạo tác vụ.
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ẽ không xuất hiện khi giá trị là 0.
Name
image_urls
Type
array
Description
Các URL tải xuống cho những ảnh đã tạo. Với generate_multi_view: true, mảng này chứa 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 URL hơn, và tác vụ vẫn thành công. Nếu không, nó sẽ chứa một URL duy nhất.
Name
task_error
Type
object
Description
Thông tin chi tiết về 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ố 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 tác vụ FAILED, vì Meshy sẽ hoàn lại tín dụng khi tác vụ thất bại.