API Văn bản sang ảnh

API Văn bản sang ảnh là một tính năng cho phép bạn tích hợp các 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 ảnh chất lượng cao từ lời nhắc văn bản bằng các mô hình AI mạnh mẽ của chúng tôi.

POST/openapi/v1/text-to-image

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

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 Đối tượng tác vụ Văn bản sang ảnh để xem những thuộc tính nào được bao gồm trong đối tượng tác vụ Văn bản sang ảnh.

Tham số

Name
ai_model
Type
string
Bắt buộc
Description
ID của mô hình dùng để tạo ảnh.
Giá trị khả dụng:
- nano-banana: Mô hình tiêu chuẩn (3 tín dụng cho mỗi ảnh)
- nano-banana-2: Mô hình cân bằng với năng lực mạnh hơn tiêu chuẩn (6 tín dụng cho mỗi ảnh)
- nano-banana-pro: Mô hình Pro với chất lượng được nâng cao (9 tín dụng cho mỗi ảnh)
- gpt-image-2: OpenAI GPT Image 2, một mô hình ảnh độ trung thực cao với hỗ trợ tỷ lệ khung hình bị giới hạn (9 tín dụng cho mỗi ảnh)
Name
prompt
Type
string
Bắt buộc
Description
Mô tả bằng văn bản về ảnh bạn muốn tạo. Hãy mô tả chi tiế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, tạo một ảnh đa góc nhìn hiển thị chủ thể từ nhiều góc.
Khi generate_multi_view là true, tham số aspect_ratio không thể được đặt.
Name
pose_mode
Type
string
Description
Chỉ định pose mode cho việc tạo nhân vật. Khi bỏ qua, ảnh được tạo mà không có bất kỳ preset tư thế nào.
Giá trị khả dụng: a-pose, t-pose
Name
aspect_ratio
Type
string
mặc định 1:1
Description
Chỉ định tỷ lệ khung hình của ả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-pro: 1:1, 16:9, 9:16, 4:3, 3:4
- gpt-image-2: chỉ 1:1, 3:2, 2:3
Giá trị khả dụng:
- 1:1: Định dạng vuông
- 16:9: Khổ ngang màn hình rộng (không được hỗ trợ bởi gpt-image-2)
- 9:16: Khổ dọc màn hình rộng (không được hỗ trợ bởi gpt-image-2)
- 4:3: Khổ ngang tiêu chuẩn (không được hỗ trợ bởi gpt-image-2)
- 3:4: Khổ dọc tiêu chuẩn (không được hỗ trợ bởi gpt-image-2)
- 3:2: Khổ ngang (chỉ được hỗ trợ bởi gpt-image-2)
- 2:3: Khổ dọc (chỉ được hỗ trợ bởi gpt-image-2)

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ụ Văn bản sang ảnh mới được tạo.

Các trường hợp 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ố: Thiếu một tham số bắt buộc (ví dụ: ai_model, prompt).
- 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
Không đủ tín dụng để thực hiện tác vụ này.
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/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

Truy xuất một tác vụ Văn bản sang ảnh

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

Tham số

Name
id
Type
path
Description
Mã định danh duy nhất của tác vụ Văn bản sang ảnh cần truy xuất.

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ả ả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ả về

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

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

// Returns 200 Ok on success.

GET/openapi/v1/text-to-image

Liệt kê các tác vụ Văn bản sang ảnh

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 được phép là 50 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 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 được phân trang của Các đố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 luồng tác vụ Văn bản sang ảnh

endpoint này truyền luồng các cập nhật theo thời gian thực cho một tác vụ 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 tác vụ Văn bản sang ảnh cần truyền luồng.

Giá trị trả về

Trả về một luồng Các đối tượng tác vụ Văn bản 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/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 tác vụ Văn bản sang ảnh

Đối tượng tác vụ 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 có các thuộc tính sau:

Thuộc tính

Name
id
Type
string
Description
Mã đị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 cho id tác 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 tác vụ tạo ảnh. Đối với các tác vụ 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 tác 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 để tạo ả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 PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
progress 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 khi tác vụ đượ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 PM GMT được biểu diễn là 1693569600000. Điều này áp dụng cho tất cả dấu thời gian trong Meshy API.
Name
started_at
Type
timestamp
Description
Dấu thời gian khi tác vụ 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 khi tác vụ hoàn tất, tính bằng mili giây. Nếu tác vụ chưa hoàn tất, thuộc tính này sẽ là 0.
Name
expires_at
Type
timestamp
Description
Dấu thời gian khi 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 nếu 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 tới các ảnh đã 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ứa một URL ả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ố tín dụng được tác vụ này tiêu thụ. Có mặt khi trạng thái tác vụ là PENDING, IN_PROGRESS, hoặc SUCCEEDED. Trả về 0 cho các tác vụ 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
}