API Teks ke Imej

API Teks ke Imej ialah ciri yang membolehkan anda mengintegrasikan keupayaan penjanaan imej AI Meshy ke dalam aplikasi anda sendiri. Jana imej berkualiti tinggi daripada gesaan teks menggunakan model AI kami yang berkuasa.

Endpoint ini menghasilkan imej. Jika matlamatnya ialah objek yang boleh anda pegang atau cetak — rantai kunci, magnet peti sejuk, figura, lampu atau keycap daripada foto — gunakan Creative Lab APIs (imej prototaip → bina model 3D). Jika matlamatnya ialah model 3D bagi apa yang terdapat dalam gambar, gunakan Imej ke 3D.

POST/openapi/v1/text-to-image

Create a Text to Image Task

Endpoint ini membolehkan anda mencipta tugas Teks ke Imej yang baharu. Rujuk The Text to Image Task Object untuk melihat sifat yang disertakan dengan objek tugas Teks ke Imej.

Tugas ini berjalan di latar belakang. Untuk mengetahui berapa lama biasanya ia mengambil masa, lihat Processing Times.

Parameter

Name
ai_model
Type
string
Diperlukan
Description
ID model yang digunakan untuk penjanaan imej.
Nilai yang tersedia:
- nano-banana: Model standard (3 kredit setiap imej)
- nano-banana-2: Model seimbang dengan keupayaan yang lebih kuat berbanding standard (6 kredit setiap imej)
- nano-banana-2-lite: Varian lite bagi nano-banana-2 (3 kredit setiap imej)
- nano-banana-pro: Model Pro dengan kualiti yang dipertingkatkan (9 kredit setiap imej)
- gpt-image-2: OpenAI GPT Image 2, model imej berketepatan tinggi (9 kredit setiap imej)
- gpt-image-2-5-flare: OpenAI GPT Image 2.5 (Flare), model imej berketepatan tinggi (9 kredit setiap imej)
- gpt-image-2-5-sunburst: OpenAI GPT Image 2.5 (Sunburst), model imej berketepatan tinggi (9 kredit setiap imej)
Name
prompt
Type
string
Diperlukan
Description
Keterangan teks bagi imej yang ingin anda jana. Berikan penerangan yang terperinci untuk hasil terbaik.
Name
generate_multi_view
Type
boolean
lalai false
Description
Apabila ditetapkan kepada true, menjana imej Berbilang Pandangan yang menunjukkan subjek daripada pelbagai sudut.
Apabila generate_multi_view ditetapkan kepada true, parameter aspect_ratio tidak boleh ditetapkan.
Name
pose_mode
Type
string
Description
Nyatakan pose_mode untuk penjanaan watak. Apabila diabaikan, imej dijana tanpa sebarang pratetap pose.
Nilai yang tersedia: a-pose, t-pose
Dengan nano-banana, nano-banana-2, nano-banana-2-lite dan nano-banana-pro, menetapkan pose_mode akan menetapkan nisbah bidang output kepada 3:4 dan sebarang aspect_ratio yang anda hantar akan diabaikan. nano-banana-2 dan nano-banana-2-lite mengekalkan model yang diminta. Dengan nano-banana atau nano-banana-pro, imej berpose dijana oleh nano-banana-pro (ai_model tugas tersebut akan dibaca semula sebagai nano-banana-pro), yang memerlukan pelan Pro atau ke atas. Model GPT Image (gpt-image-2, gpt-image-2-5-flare, gpt-image-2-5-sunburst) mengekalkan model dan aspect_ratio yang diminta.
Name
aspect_ratio
Type
string
lalai 1:1
Description
Nyatakan nisbah bidang bagi imej yang dijana. Nilai yang dibenarkan bergantung pada ai_model yang dipilih:
- 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
Nilai yang tersedia:
- 1:1: Format 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 disokong oleh model GPT Image)
- 2:3: Potret (hanya disokong oleh model GPT Image)
Name
remove_background
Type
boolean
lalai false
Description
Apabila ditetapkan kepada true, imej yang dijana dikembalikan sebagai PNG RGBA lutsinar dengan latar belakang dibuang, supaya anda boleh menggabungkan subjek ke atas mana-mana latar belakang.

Nilai Pulangan

Sifat result bagi respons mengandungi id tugas bagi tugas Teks ke Imej yang baharu dicipta.

Mod Kegagalan

Name
400 - Bad Request
Description
Permintaan tidak dapat diterima. Punca biasa:
- Parameter hilang: Parameter yang diperlukan (contohnya, ai_model, prompt) tiada.
- Parameter tidak sah: ai_model atau aspect_ratio bukan salah satu nilai yang dibenarkan.
- Konflik: generate_multi_view dan aspect_ratio tidak boleh digunakan serentak.
Name
401 - Unauthorized
Description
Pengesahan gagal. Sila semak kunci API anda.
Name
402 - Payment Required
Description
Punca biasa:
- Kredit tidak mencukupi: Akaun anda tidak mempunyai kredit yang mencukupi untuk menjalankan tugas ini (Insufficient funds).
- Pelan diperlukan: nano-banana-pro, atau pose_mode dengan nano-banana, memerlukan pelan Pro atau ke atas (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)).
Name
429 - Too Many Requests
Description
Anda telah melebihi had kadar anda.

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

Dapatkan Semula Tugas Teks ke Imej

Endpoint ini membolehkan anda mendapatkan semula tugas Teks ke Imej dengan id tugas yang sah. Rujuk The Text to Image Task Object untuk melihat ciri-ciri yang disertakan dalam objek tugas Teks ke Imej.

Parameter

Name
id
Type
path
Description
Pengecam unik untuk tugas Teks ke Imej yang hendak didapatkan semula.

Pulangan

Respons mengandungi objek tugas Teks ke Imej. Semak bahagian The Text to Image Task Object untuk maklumat lanjut.

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

Padam Tugasan Teks ke Imej

Endpoint ini memadam secara kekal tugasan Teks ke Imej, termasuk semua imej dan data yang berkaitan. Tindakan ini tidak boleh dibalikkan.

Parameter Laluan

Name
id
Type
path
Description
ID tugasan Teks ke Imej yang hendak dipadam.

Status Tugasan

Tugasan yang masih PENDING akan dipadam dan kredit yang digunakan semasa penciptaan akan dikembalikan.

Tugasan yang sudah IN_PROGRESS tidak boleh dipadam: permintaan akan ditolak dengan 409 Conflict dan tugasan akan terus berjalan. Kredit untuk tugasan yang sudah mula diproses oleh worker tidak boleh dikembalikan, jadi memadamnya semasa ia sedang berjalan akan menyebabkan anda kehilangan kredit dan hasilnya sekali. Tunggu sehingga ia mencapai status SUCCEEDED, FAILED atau CANCELED, kemudian padamkannya.

Tugasan dalam status terminal (SUCCEEDED, FAILED atau CANCELED) dipadam tanpa sebarang bayaran balik.

Pulangan

Mengembalikan 200 OK apabila berjaya, atau 409 Conflict apabila tugasan berstatus 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

Senaraikan Tugas Teks ke Imej

Endpoint ini membolehkan anda mendapatkan senarai tugas Teks ke Imej.

Parameter

Name
page_num
Type
integer
Description
Nombor halaman untuk penomboran halaman. Bermula dan lalai pada 1.
Name
page_size
Type
integer
Description
Had saiz halaman. Lalai 10 item. Maksimum yang dibenarkan ialah 100 item.
Name
sort_by
Type
string
Description
Medan untuk disusun mengikut. Nilai yang tersedia:
- +created_at: Susun mengikut masa penciptaan secara menaik.
- -created_at: Susun mengikut masa penciptaan secara menurun.

Pulangan

Mengembalikan senarai berhalaman Objek Tugas Teks ke Imej.

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

Alirkan Tugas Text to Image

Endpoint ini mengalirkan kemas kini masa nyata untuk tugas Teks ke Imej menggunakan Server-Sent Events (SSE).

Parameter

Name
id
Type
path
Description
Pengenal unik untuk tugas Teks ke Imej yang hendak dialirkan.

Pulangan

Mengembalikan aliran Objek Tugas Text to Image sebagai Server-Sent Events.

Untuk tugas PENDING atau IN_PROGRESS, aliran respons hanya akan mengandungi medan progress dan status yang diperlukan.

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

Objek Tugas Text to Image

Objek Tugas Text to Image adalah unit kerja yang dijejaki oleh Meshy untuk menjana imej daripada input prompt teks. Objek ini mempunyai ciri-ciri berikut:

Ciri-ciri

Name
id
Type
string
Description
Pengecam unik untuk tugas tersebut. Walaupun kami menggunakan UUID k-sortable untuk id tugas sebagai perincian pelaksanaan, anda tidak seharusnya membuat sebarang andaian tentang format id tersebut.
Name
type
Type
string
Description
Jenis tugas penjanaan imej. Untuk tugas Text to Image, ini akan sentiasa menjadi text-to-image.
Name
ai_model
Type
string
Description
Model AI yang digunakan untuk tugas ini. Nilai yang mungkin ialah nano-banana, nano-banana-2, nano-banana-2-lite, nano-banana-pro, gpt-image-2, gpt-image-2-5-flare, atau gpt-image-2-5-sunburst.
Name
prompt
Type
string
Description
Prompt teks yang digunakan untuk menjana imej tersebut.
Name
status
Type
string
Description
Status tugas. Nilai yang mungkin ialah salah satu daripada PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Progress tugas. Jika tugas belum bermula lagi, ciri ini akan menjadi 0. Setelah tugas berjaya, ini akan menjadi 100.
Name
created_at
Type
timestamp
Description
Cap masa bila tugas dicipta, dalam milisaat.
Cap masa mewakili bilangan milisaat yang berlalu sejak 1 Januari 1970 UTC, mengikut piawaian RFC 3339. Contohnya, Jumaat, 1 September 2023 12:00:00 PM GMT diwakili sebagai 1693569600000. Ini terpakai kepada semua cap masa dalam Meshy API.
Name
started_at
Type
timestamp
Description
Cap masa bila tugas bermula, dalam milisaat. Jika tugas belum bermula lagi, ciri ini akan menjadi 0.
Name
finished_at
Type
timestamp
Description
Cap masa bila tugas selesai, dalam milisaat. Jika tugas belum selesai lagi, ciri ini akan menjadi 0.
Name
expires_at
Type
timestamp
Description
Cap masa bila hasil tugas tamat tempoh, dalam milisaat.
Name
preceding_tasks
Type
integer
Description
Bilangan tugas yang mendahului.
Nilai medan ini hanya bermakna jika status tugas ialah PENDING.
Name
image_urls
Type
array
Description
Satu array URL yang boleh dimuat turun bagi imej yang dijana. Apabila generate_multi_view diaktifkan, array ini mengandungi tiga URL imej yang mewakili sudut pandangan yang berbeza. Jika tidak, ia mengandungi satu URL imej sahaja.
Name
task_error
Type
object
Description
Butiran ralat untuk tugas yang gagal. Lihat Ralat untuk rujukan penuh objek task_error.
Name
consumed_credits
Type
integer
Description
Bilangan kredit yang digunakan oleh tugas ini. Hadir apabila status tugas ialah PENDING, IN_PROGRESS, atau SUCCEEDED. Mengembalikan 0 untuk tugas FAILED (kredit akan dikembalikan apabila gagal).

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
}