Text to Image API

Text to Image API là một tính năng cho phép bạn tích hợp khả năng tạo ảnh bằng AI của Meshy vào ứng dụng của riêng bạn. Tạo ra những hình ảnh chất lượng cao từ các prompt văn bản bằng 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ể mà bạn có thể cầm nắm hoặc in ra — một chiếc 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 → dựng mô hình 3D). Nếu mục tiêu là một mô hình 3D của những gì có trong bức ảnh, hãy sử dụng Image to 3D.

POST/openapi/v1/text-to-image

Create a Text to Image Task

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

Tác vụ chạy 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 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, mạnh hơn mô hình tiêu chuẩn (6 tín dụng mỗi ảnh)
- nano-banana-2-lite: Biến thể 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 ảnh có độ trung thực cao (9 tín dụng mỗi ảnh)
- gpt-image-2-5-flare: OpenAI GPT Image 2.5 (Flare), một mô hình ảnh có độ trung thực cao (9 tín dụng mỗi ảnh)
- gpt-image-2-5-sunburst: OpenAI GPT Image 2.5 (Sunburst), một mô hình ảnh có độ trung thực cao (9 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ề hình ảnh bạn muốn tạo. Hãy mô tả càng chi tiết càng tốt để có kết quả tốt nhất.
Name
generate_multi_view
Type
boolean
mặc định false
Description
Khi được đặt thành true, sẽ tạo ra một hình ảnh đa góc nhìn thể hiện chủ thể từ nhiều góc độ khác nhau.
Khi generate_multi_view là true, tham số aspect_ratio không thể được đặt.
Name
pose_mode
Type
string
Description
Chỉ định mode tư thế cho việc tạo nhân vật. Khi bị bỏ qua, hình ảnh sẽ được tạo mà không có bất kỳ mẫu tư thế dựng sẵn nào.
Các giá trị khả dụng: a-pose, t-pose
Với nano-banana, nano-banana-2, nano-banana-2-lite và nano-banana-pro, việc đặt pose_mode sẽ cố định tỷ lệ khung hình đầu ra thành 3:4 và bất kỳ aspect_ratio nào bạn gửi đều sẽ bị bỏ qua. nano-banana-2 và nano-banana-2-lite vẫn giữ nguyên mô hình đã yêu cầu. Với nano-banana hoặc nano-banana-pro, một hình ảnh có tư thế sẽ được tạo bởi nano-banana-pro (trường ai_model của tác vụ sẽ trả về là nano-banana-pro), yêu cầu gói Pro trở lên. Các mô hình GPT Image (gpt-image-2, gpt-image-2-5-flare, gpt-image-2-5-sunburst) vẫn giữ nguyên mô hình và aspect_ratio đã yêu cầu.
Name
aspect_ratio
Type
string
mặc định 1:1
Description
Chỉ định tỷ lệ khung hình của hình ảnh được tạo. Các giá trị được phép phụ thuộc vào ai_model đã 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 ảnh rộng, ngang
- 9:16: Màn ả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 thành true, hình ảnh được tạo sẽ được trả về dưới dạng PNG RGBA trong suốt với nền đã được loại bỏ, cho phép bạn ghép chủ thể vào bất kỳ nền nào.

Giá trị trả về

Thuộc tính result trong phản hồi chứa id của tác vụ Văn bản 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.
- 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: 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
Các nguyên nhân phổ biến:
- Không đủ tín dụng: Tài khoản của bạn không có đủ tín dụng để thực hiện tác vụ này (Insufficient funds).
- Yêu cầu gói: nano-banana-pro, hoặc pose_mode với nano-banana, yêu cầu gói Pro trở lên (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)).
Name
429 - Too Many Requests
Description
Bạn đã vượt quá giới hạn tốc độ.

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

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

Lấy thông tin một tác vụ Văn bản sang ảnh

Endpoint này cho phép bạn lấy thông tin một tác vụ Văn bản sang ảnh khi biết id hợp lệ của tác vụ. Tham khảo Đối tượng tác vụ Văn bản sang ảnh để xem các thuộc tính có trong đối tượng tác vụ Văn bản sang ảnh.

Tham số

Name
id
Type
path
Description
Định danh duy nhất của tác vụ Văn bản sang ảnh cần lấy thông tin.

Giá trị trả về

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

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

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

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

Endpoint này xóa vĩnh viễn một tác vụ Văn bản 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ụ Văn bản sang ảnh cần xóa.

Trạng thái tác vụ

Một tác vụ vẫn còn ở 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ể bị 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 chờ cho đến khi nó đạt trạng thái SUCCEEDED, FAILED hoặc CANCELED, sau đó mới xóa.

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

Giá trị 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/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 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/text-to-image

List Text to Image Tasks

Endpoint này cho phép bạn truy xuất danh sách các tác vụ Văn bản 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à 100 mục.
Name
sort_by
Type
string
Description
Trườ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.

Giá trị trả về

Trả về một danh sách phân trang của Đối tượng Tác vụ Văn bản sang ảnh.

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

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

Truyền trực tiếp Task Văn bản sang ảnh

Endpoint này truyền trực tiếp các cập nhật theo thời gian thực cho một task Văn bản sang ảnh bằng Server-Sent Events (SSE).

Tham số

Name
id
Type
path
Description
Mã định danh duy nhất của task Văn bản sang ảnh cần truyền trực tiếp.

Giá trị trả về

Trả về một luồng Đối tượng Task Văn bản sang ảnh dưới dạng Server-Sent Events.

Đối với các task ở 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/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.
// 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": "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=***"
  ]
}

Đối tượng Task Văn bản sang ảnh

Đối tượng Task Văn bản sang ảnh là một đơn vị công việc mà Meshy theo dõi để tạo ảnh từ đầu vào prompt văn bản. Đố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) làm chi tiết triển khai cho id của task, 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 Văn bản sang ảnh, giá trị này sẽ luôn là text-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-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 để tạo ả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 trình (progress) 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 cho biết thời điểm task được tạo, tính bằng mili giây.
Dấu thời gian biểu thị 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 CH GMT được biểu thị 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 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 cho biết thời điểm task 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 cho biết thời điểm 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 task đứng trước.
Giá trị của trường này chỉ có ý nghĩa khi trạng thái của 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. 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, nó 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 đố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. Xuất hiện khi trạng thái của task là PENDING, IN_PROGRESS, hoặc SUCCEEDED. Trả về 0 đối với các task FAILED (tín dụng được hoàn lại khi thất bại).

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