API Teks ke Gambar

Hasilkan gambar dari sebuah prompt teks dengan model AI milik Meshy.

Teks ke Gambar membuat gambar. Untuk membuat model 3D dari apa yang ada dalam sebuah gambar, gunakan Gambar ke 3D. Untuk membuat objek yang bisa Anda pegang atau cetak dari sebuah foto, gunakan Creative Lab APIs. API ini membuat gambar prototipe lalu membangun model 3D darinya, misalnya gantungan kunci, magnet kulkas, figur, lampu, atau keycap.

POST/openapi/v1/text-to-image

Membuat tugas Teks ke Gambar

Membuat tugas Teks ke Gambar. Tugas ini berjalan di latar belakang. Untuk mengetahui berapa lama biasanya tugas ini berjalan, lihat Waktu pemrosesan.

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
Wajib
Description
Model AI yang menghasilkan gambar. Harga berbeda-beda menurut model. Untuk harga, lihat Harga.
Nilai yang tersedia:
- nano-banana: model standar
- nano-banana-2: lebih mumpuni dibanding nano-banana
- nano-banana-2-lite: versi ringan dari nano-banana-2
- nano-banana-2-1: Nano Banana 2.1
- nano-banana-pro: model Pro, dengan kualitas lebih tinggi. Membutuhkan paket Pro atau yang lebih tinggi. Pada paket yang lebih rendah, akan 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
Wajib
Description
Teks yang menjelaskan gambar yang akan dihasilkan. Deskripsi yang detail memberikan hasil yang lebih baik.
Name
generate_multi_view
Type
boolean
default false
Description
Apakah akan menghasilkan gambar Multi-Tampilan yang menampilkan subjek dari beberapa sudut. Jika bernilai true, Anda tidak dapat mengirim aspect_ratio. Mengirim keduanya akan mengembalikan 400.
Name
pose_mode
Type
string
Description
Pose untuk karakter, a-pose atau t-pose. Kosongkan untuk tidak menggunakan pose.
Cara kerja pose bergantung pada ai_model:
- nano-banana-2, nano-banana-2-lite, dan nano-banana-2-1: Meshy mempertahankan model yang Anda pilih. Gambar selalu 3:4, dan Meshy mengabaikan aspect_ratio.
- nano-banana dan nano-banana-pro: Meshy menghasilkan gambar dengan nano-banana-pro, sehingga ai_model pada tugas akan terbaca kembali sebagai nano-banana-pro. Ini membutuhkan paket Pro atau yang lebih tinggi. Gambar selalu 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 mempertahankan model yang Anda pilih dan aspect_ratio Anda.
Name
aspect_ratio
Type
string
default 1:1
Description
Bentuk gambar. Nilai yang dapat Anda kirim bergantung pada ai_model.
Nilai yang tersedia:
- 1:1: persegi
- 16:9: lanskap layar lebar
- 9:16: potret layar lebar
- 4:3: lanskap standar
- 3:4: potret standar
- 3:2: lanskap, 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
default false
Description
Apakah akan menghapus latar belakang gambar. true mengembalikan PNG RGBA transparan, sehingga Anda dapat menempatkan subjek pada latar belakang apa pun.

Hasil

Kolom result pada respons menyimpan ID tugas Teks ke Gambar yang baru.

Mode kegagalan

Name
400 - Bad Request
Description
Permintaan tidak dapat dijalankan. Pesan kesalahan menunjukkan masalah apa yang ditemukan. Misalnya:
- Parameter hilang: Parameter yang wajib ada, seperti ai_model atau prompt, tidak disertakan.
- Parameter tidak valid: ai_model atau aspect_ratio bukan salah satu nilai yang diizinkan.
- Konflik: aspect_ratio dikirim bersama generate_multi_view: true.
Perbaiki permintaan, lalu kirim ulang. Lihat Kesalahan.
Name
401 - Unauthorized
Description
Kunci API hilang atau tidak valid. Periksa header Authorization.
Name
402 - Payment Required
Description
Akun tidak dapat menjalankan tugas ini. Misalnya:
- Paket gratis: Membuat tugas membutuhkan paket berbayar. Tingkatkan paket Anda di pengaturan langganan Anda, lalu coba lagi.
- Kredit tidak cukup: Akun tidak memiliki cukup kredit untuk tugas ini (Insufficient funds), atau akun telah mencapai batas kredit.
- Paket diperlukan: Permintaan menggunakan nano-banana-pro, atau pose_mode dengan nano-banana, pada paket 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)).
Periksa saldo kredit dan paket Anda, lalu coba lagi.
Name
429 - Too Many Requests
Description
Anda melampaui batas laju Anda. Tunggu, lalu coba lagi. Lihat Batas laju.

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

Get a Text to Image task

Mengembalikan tugas Teks ke Gambar berdasarkan 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 dari respons pembuatan.

Returns

Objek tugas Teks ke Gambar.

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

Hapus task Teks ke Gambar

Menghapus task Teks ke Gambar secara permanen, termasuk gambar dan datanya. Anda tidak dapat membatalkan penghapusan 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 path

Name
id
Type
path
Description
ID dari task yang akan dihapus.

Status task

Menghapus task PENDING akan mengembalikan kredit yang digunakan saat Anda membuatnya.

Task IN_PROGRESS tidak dapat dihapus. Permintaan akan mengembalikan 409 Conflict, dan task tersebut tetap berjalan. Meshy tidak mengembalikan kredit untuk task yang sudah dimulai, sehingga menghapusnya akan membuat Anda kehilangan baik kredit maupun hasilnya. Tunggu hingga task mencapai status SUCCEEDED, FAILED, atau CANCELED, lalu hapus task tersebut.

Menghapus task dengan status akhir (SUCCEEDED, FAILED, atau CANCELED) tidak mengembalikan kreditnya.

Returns

200 OK ketika task berhasil dihapus, atau 409 Conflict ketika task berstatus IN_PROGRESS.

GET/openapi/v1/text-to-image

Mendapatkan Daftar Tugas Teks ke Gambar

Mengembalikan daftar tugas Teks ke Gambar dan Gambar ke Gambar Anda. Kolom type pada setiap tugas menunjukkan termasuk jenis yang mana dari keduanya.

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
Nomor halaman yang akan dikembalikan. Dimulai dari dan secara default 1.
Name
page_size
Type
integer
Description
Jumlah tugas per halaman, hingga 100. Defaultnya adalah 10.
Name
sort_by
Type
string
Description
Urutan pengurutan.
Nilai yang tersedia:
- +created_at: yang terlama terlebih dahulu
- -created_at: yang terbaru terlebih dahulu

Hasil Kembalian

Daftar objek tugas yang dipaginasi, dalam format yang sama seperti objek tugas Teks ke Gambar.

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

Stream a Text to Image task

Melakukan streaming pembaruan tugas Teks ke Gambar 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 dari respons pembuatan.

Returns

Sebuah stream objek tugas Teks ke Gambar sebagai Server-Sent Events.

Setiap event memuat objek tugas secara lengkap, dengan bentuk yang sama seperti yang dikembalikan oleh endpoint Get. Selama tugas berstatus PENDING atau IN_PROGRESS, kolom hasilnya belum memiliki nilai.

Objek task Text to Image

Objek task Text to Image menjelaskan satu pembuatan gambar dari prompt teks. Objek ini menyimpan status, progress, dan URL gambar ketika task berhasil.

Properties

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 task. Perlakukan sebagai string buram, dan jangan bergantung pada formatnya.
Name
type
Type
string
Description
Jenis task, selalu text-to-image.
Name
ai_model
Type
string
Description
Model AI yang digunakan oleh task.
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 membuat task.
Name
status
Type
string
Description
Status task, salah satu dari PENDING, IN_PROGRESS, SUCCEEDED, FAILED, atau CANCELED.
Name
progress
Type
integer
Description
Seberapa banyak task telah selesai, dalam persentase. Nilainya 0 hingga task dimulai dan 100 ketika berhasil.
Name
created_at
Type
timestamp
Description
Waktu task dibuat, dalam milidetik Unix.
Name
started_at
Type
timestamp
Description
Waktu task dimulai, dalam milidetik Unix. Tidak ada sampai task dimulai.
Name
finished_at
Type
timestamp
Description
Waktu task selesai, dalam milidetik Unix. Tidak ada sampai task selesai.
Name
expires_at
Type
timestamp
Description
Waktu hasil task kedaluwarsa, dalam milidetik Unix. Tidak ada sampai task selesai.
Name
preceding_tasks
Type
integer
Description
Jumlah task yang berada di depan task ini dalam antrean. Nilai ini hanya berarti selama task berstatus PENDING. Bidang ini tidak disertakan ketika nilainya 0.
Name
image_urls
Type
array
Description
URL unduhan untuk gambar yang dihasilkan. Dengan generate_multi_view: true, array ini menyimpan satu URL per tampilan, biasanya tiga. Jika Meshy tidak dapat memisahkan setiap tampilan, Meshy mengembalikan lebih sedikit, dan task tetap berhasil. Jika tidak, array ini menyimpan satu URL.
Name
task_error
Type
object
Description
Detail kesalahan ketika task gagal. Nilainya null kecuali statusnya FAILED. Lihat Kesalahan.
Name
consumed_credits
Type
integer
Description
Jumlah kredit yang digunakan oleh task. Ada ketika status PENDING, IN_PROGRESS, atau SUCCEEDED. Nilainya 0 untuk task FAILED, karena Meshy mengembalikan kredit ketika task gagal.