API Teks ke Imej

Jana imej daripada prompt teks dengan model AI Meshy.

Teks ke Imej menghasilkan imej. Untuk membuat model 3D daripada apa yang terdapat dalam imej, gunakan Imej ke 3D. Untuk membuat objek yang anda boleh pegang atau cetak daripada foto, gunakan Creative Lab APIs. Ia menghasilkan imej prototaip dan kemudian membina model 3D daripadanya, contohnya rantai kunci, magnet peti sejuk, figura, lampu, atau keycap.

POST/openapi/v1/text-to-image

Cipta tugas Teks ke Imej

Mencipta tugas Teks ke Imej. Tugas ini berjalan di latar belakang. Untuk tempoh biasa tugas ini mengambil masa, lihat Masa pemprosesan.

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

Parameter

Name
ai_model
Type
string
Diperlukan
Description
Model AI yang menjana imej. Harga berbeza mengikut model. Untuk harga, lihat Harga.
Nilai yang tersedia:
- nano-banana: model standard
- nano-banana-2: lebih berkeupayaan daripada nano-banana
- nano-banana-2-lite: versi lite bagi nano-banana-2
- nano-banana-2-1: Nano Banana 2.1
- nano-banana-pro: model Pro, dengan kualiti lebih tinggi. Memerlukan pelan Pro atau lebih tinggi. Pada pelan yang lebih rendah, ia mengembalikan 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
Diperlukan
Description
Teks yang menerangkan imej yang hendak dijana. Penerangan yang terperinci memberikan hasil yang lebih baik.
Name
generate_multi_view
Type
boolean
lalai false
Description
Sama ada untuk menjana imej Berbilang Pandangan yang menunjukkan subjek dari beberapa sudut. Apabila ia true, anda tidak boleh menghantar aspect_ratio. Menghantar kedua-duanya mengembalikan 400.
Name
pose_mode
Type
string
Description
Pose untuk watak, a-pose atau t-pose. Tinggalkannya jika tiada pose.
Cara pose berfungsi bergantung pada ai_model:
- nano-banana-2, nano-banana-2-lite, dan nano-banana-2-1: Meshy mengekalkan model yang anda pilih. Imej sentiasa 3:4, dan Meshy mengabaikan aspect_ratio.
- nano-banana dan nano-banana-pro: Meshy menjana imej dengan nano-banana-pro, jadi ai_model tugas tersebut dibaca semula sebagai nano-banana-pro. Ini memerlukan pelan Pro atau lebih tinggi. Imej sentiasa 3:4, dan Meshy mengabaikan aspect_ratio.
- Model GPT Image (gpt-image-2, gpt-image-2-5-flare, dan gpt-image-2-5-sunburst): Meshy mengekalkan model yang anda pilih dan aspect_ratio anda.
Name
aspect_ratio
Type
string
lalai 1:1
Description
Bentuk imej. Nilai yang boleh anda hantar bergantung pada ai_model.
Nilai yang tersedia:
- 1:1: segi empat sama
- 16:9: landskap skrin lebar
- 9:16: potret skrin lebar
- 4:3: landskap standard
- 3:4: potret standard
- 3:2: landskap, hanya untuk model GPT Image
- 2:3: potret, hanya untuk model GPT Image
Model nano-banana (nano-banana, nano-banana-2, nano-banana-2-lite, nano-banana-2-1, dan nano-banana-pro) mengembalikan 400 untuk 3:2 dan 2:3.
Name
remove_background
Type
boolean
lalai false
Description
Sama ada untuk mengeluarkan latar belakang imej. true mengembalikan PNG RGBA lutsinar, supaya anda boleh meletakkan subjek pada sebarang latar belakang.

Pulangan

Medan result bagi respons menyimpan ID tugas Teks ke Imej yang baharu.

Mod kegagalan

Name
400 - Bad Request
Description
Permintaan tidak dapat dijalankan. Mesej ralat menyatakan masalah yang dikesan. Contohnya:
- Parameter hilang: Parameter yang diperlukan, seperti ai_model atau prompt, tiada.
- Parameter tidak sah: ai_model atau aspect_ratio bukan salah satu nilai yang dibenarkan.
- Konflik: aspect_ratio dihantar bersama generate_multi_view: true.
Betulkan permintaan, kemudian hantar semula. Lihat Ralat.
Name
401 - Unauthorized
Description
Kunci API hilang atau tidak sah. Semak header Authorization.
Name
402 - Payment Required
Description
Akaun tidak dapat menjalankan tugas ini. Contohnya:
- Pelan percuma: Mencipta tugas memerlukan pelan berbayar. Naik taraf pelan anda dalam tetapan langganan anda, kemudian cuba lagi.
- Kredit tidak mencukupi: Akaun tidak mempunyai kredit yang mencukupi untuk tugas ini (Insufficient funds), atau akaun telah mencapai had kredit.
- Pelan diperlukan: Permintaan menggunakan nano-banana-pro, atau pose_mode dengan nano-banana, pada pelan di bawah Pro (Only Pro and above users can use nano-banana-pro, atau Only Pro and above users can use A/T pose feature (requires nano-banana-pro)).
Semak baki kredit dan pelan anda, kemudian cuba lagi.
Name
429 - Too Many Requests
Description
Anda telah melebihi had kadar anda. Tunggu, kemudian cuba lagi. Lihat Had kadar.

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

Dapatkan tugas Teks ke Imej

Mengembalikan tugas Teks ke Imej mengikut ID-nya.

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

Parameter

Name
id
Type
path
Description
ID tugas daripada respons create.

Pulangan

Objek tugas Teks ke Imej.

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

Padam tugas Teks ke Imej

Memadam tugas Teks ke Imej secara kekal, termasuk imej dan datanya. Anda tidak boleh membatalkan tindakan padam ini.

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

Parameter laluan

Name
id
Type
path
Description
ID tugas yang hendak dipadam.

Status tugas

Memadam tugas PENDING akan memulangkan kredit yang digunakan semasa anda mencipta tugas tersebut.

Tugas IN_PROGRESS tidak boleh dipadam. Permintaan tersebut akan memulangkan 409 Conflict, dan tugas tersebut terus berjalan. Meshy tidak memulangkan kredit untuk tugas yang telah bermula, jadi memadamnya akan menyebabkan anda kehilangan kedua-dua kredit dan hasilnya. Tunggu sehingga ia mencapai SUCCEEDED, FAILED, atau CANCELED, kemudian padamkannya.

Memadam tugas yang berada dalam status akhir (SUCCEEDED, FAILED, atau CANCELED) tidak memulangkan kreditnya.

Pulangan

200 OK apabila tugas berjaya dipadam, atau 409 Conflict apabila tugas berstatus IN_PROGRESS.

GET/openapi/v1/text-to-image

Senaraikan tugas Teks ke Imej

Mengembalikan senarai tugas Teks ke Imej dan Imej ke Imej anda. Medan type setiap tugas menunjukkan yang mana satu antara kedua-duanya.

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

Parameter

Name
page_num
Type
integer
Description
Nombor halaman yang hendak dikembalikan. Bermula pada dan lalai kepada 1.
Name
page_size
Type
integer
Description
Bilangan tugas setiap halaman, sehingga 100. Lalai kepada 10.
Name
sort_by
Type
string
Description
Susunan isihan.
Nilai yang tersedia:
- +created_at: paling lama dahulu
- -created_at: paling baharu dahulu

Pulangan

Senarai tugas yang dipaparkan secara berhalaman, dalam format yang sama seperti objek tugas Teks ke Imej.

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

Alir Tugas Teks ke Imej

Mengalirkan kemas kini tugas Teks ke Imej sebagai 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=***"
  ]
}

Parameter

Name
id
Type
path
Description
ID tugas daripada respons create.

Nilai Pulangan

Aliran objek tugas Teks ke Imej sebagai Server-Sent Events.

Setiap peristiwa (event) membawa objek tugas yang lengkap, dalam bentuk yang sama seperti yang dikembalikan oleh endpoint Get. Semasa tugas berstatus PENDING atau IN_PROGRESS, medan keputusannya belum lagi mempunyai nilai.

Objek tugas Text to Image

Objek tugas Text to Image menerangkan satu penjanaan imej daripada prompt teks. Ia menyimpan status, progress, dan URL imej apabila tugas berjaya.

Ciri-ciri

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 tugas. Anggap ia sebagai rentetan legap, dan jangan bergantung pada formatnya.
Name
type
Type
string
Description
Jenis tugas, sentiasa text-to-image.
Name
ai_model
Type
string
Description
Model AI yang digunakan oleh tugas.
Nilai yang mungkin:
- 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 teks yang anda gunakan untuk mencipta tugas.
Name
status
Type
string
Description
Status tugas, salah satu daripada PENDING, IN_PROGRESS, SUCCEEDED, FAILED, atau CANCELED.
Name
progress
Type
integer
Description
Sejauh mana tugas telah selesai, sebagai peratusan. Ia adalah 0 sehingga tugas bermula dan 100 apabila ia berjaya.
Name
created_at
Type
timestamp
Description
Masa tugas dicipta, dalam milisaat Unix.
Name
started_at
Type
timestamp
Description
Masa tugas bermula, dalam milisaat Unix. Tiada sehingga tugas bermula.
Name
finished_at
Type
timestamp
Description
Masa tugas selesai, dalam milisaat Unix. Tiada sehingga tugas selesai.
Name
expires_at
Type
timestamp
Description
Masa hasil tugas tamat tempoh, dalam milisaat Unix. Tiada sehingga tugas selesai.
Name
preceding_tasks
Type
integer
Description
Bilangan tugas yang mendahului tugas ini dalam baris gilir. Nilai ini hanya bermakna semasa tugas berstatus PENDING. Medan ini ditinggalkan apabila nilainya 0.
Name
image_urls
Type
array
Description
URL muat turun untuk imej yang dijana. Dengan generate_multi_view: true, tatasusunan ini menyimpan satu URL bagi setiap pandangan, biasanya tiga. Jika Meshy tidak dapat mengasingkan setiap pandangan, ia memulangkan lebih sedikit, dan tugas masih berjaya. Jika tidak, ia menyimpan satu URL.
Name
task_error
Type
object
Description
Butiran ralat apabila tugas gagal. Ia adalah null melainkan statusnya FAILED. Lihat Ralat.
Name
consumed_credits
Type
integer
Description
Bilangan kredit yang digunakan oleh tugas. Hadir apabila status adalah PENDING, IN_PROGRESS, atau SUCCEEDED. Ia adalah 0 untuk tugas FAILED, kerana Meshy memulangkan semula kredit apabila tugas gagal.