API Teks ke Gambar

Text to Image API adalah fitur yang memungkinkan Anda mengintegrasikan kemampuan pembuatan gambar AI milik Meshy ke dalam aplikasi Anda sendiri. Hasilkan gambar berkualitas tinggi dari prompt teks menggunakan model AI canggih kami.

Endpoint ini menghasilkan gambar. Jika tujuannya adalah objek yang dapat Anda pegang atau cetak — gantungan kunci, magnet kulkas, figur, lampu, atau keycap dari sebuah foto — gunakan Creative Lab APIs (gambar prototipe → bangun model 3D). Jika tujuannya adalah model 3D dari apa yang ada dalam gambar, gunakan Gambar ke 3D.

POST/openapi/v1/text-to-image

Create a Text to Image Task

Endpoint ini memungkinkan Anda membuat tugas Teks ke Gambar baru. Lihat The Text to Image Task Object untuk melihat properti apa saja yang termasuk dalam objek tugas Teks ke Gambar.

Tugas ini berjalan di latar belakang. Untuk mengetahui berapa lama biasanya proses ini berlangsung, lihat Processing Times.

Parameter

Name
ai_model
Type
string
Wajib
Description
ID model yang digunakan untuk pembuatan gambar.
Nilai yang tersedia:
- nano-banana: Model standar (3 kredit per gambar)
- nano-banana-2: Model seimbang dengan kemampuan lebih kuat dibandingkan standar (6 kredit per gambar)
- nano-banana-2-lite: Varian ringan dari nano-banana-2 (3 kredit per gambar)
- nano-banana-pro: Model Pro dengan kualitas yang ditingkatkan (9 kredit per gambar)
- gpt-image-2: OpenAI GPT Image 2, model gambar dengan fidelitas tinggi (9 kredit per gambar)
- gpt-image-2-5-flare: OpenAI GPT Image 2.5 (Flare), model gambar dengan fidelitas tinggi (9 kredit per gambar)
- gpt-image-2-5-sunburst: OpenAI GPT Image 2.5 (Sunburst), model gambar dengan fidelitas tinggi (9 kredit per gambar)
Name
prompt
Type
string
Wajib
Description
Deskripsi teks dari gambar yang ingin Anda buat. Berikan deskripsi yang rinci untuk hasil terbaik.
Name
generate_multi_view
Type
boolean
default false
Description
Jika diatur ke true, menghasilkan gambar Multi-Tampilan yang menampilkan subjek dari berbagai sudut.
Ketika generate_multi_view bernilai true, parameter aspect_ratio tidak dapat diatur.
Name
pose_mode
Type
string
Description
Tentukan mode pose untuk pembuatan karakter. Jika tidak disertakan, gambar akan dibuat tanpa preset pose apa pun.
Nilai yang tersedia: a-pose, t-pose
Dengan nano-banana, nano-banana-2, nano-banana-2-lite, dan nano-banana-pro, mengatur pose_mode akan menetapkan rasio aspek keluaran menjadi 3:4 dan setiap aspect_ratio yang Anda kirim akan diabaikan. nano-banana-2 dan nano-banana-2-lite tetap menggunakan model yang diminta. Dengan nano-banana atau nano-banana-pro, gambar dengan pose dihasilkan oleh nano-banana-pro (ai_model pada tugas akan terbaca kembali sebagai nano-banana-pro), yang memerlukan paket Pro atau di atasnya. Model GPT Image (gpt-image-2, gpt-image-2-5-flare, gpt-image-2-5-sunburst) tetap menggunakan model dan aspect_ratio yang diminta.
Name
aspect_ratio
Type
string
default 1:1
Description
Tentukan rasio aspek gambar yang dihasilkan. Nilai yang diizinkan 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 persegi
- 16:9: Lanskap layar lebar
- 9:16: Potret layar lebar
- 4:3: Lanskap standar
- 3:4: Potret standar
- 3:2: Lanskap (hanya didukung oleh model GPT Image)
- 2:3: Potret (hanya didukung oleh model GPT Image)
Name
remove_background
Type
boolean
default false
Description
Jika diatur ke true, gambar yang dihasilkan akan dikembalikan sebagai PNG RGBA transparan dengan latar belakang dihapus, sehingga Anda dapat menggabungkan subjek ke latar belakang apa pun.

Returns

Properti result dari respons berisi id tugas dari tugas Teks ke Gambar yang baru dibuat.

Failure Modes

Name
400 - Bad Request
Description
Permintaan tidak dapat diterima. Penyebab umum:
- Parameter hilang: Parameter yang diperlukan (misalnya, ai_model, prompt) hilang.
- Parameter tidak valid: ai_model atau aspect_ratio bukan salah satu nilai yang diizinkan.
- Konflik: generate_multi_view dan aspect_ratio tidak dapat digunakan secara bersamaan.
Name
401 - Unauthorized
Description
Autentikasi gagal. Silakan periksa kunci API Anda.
Name
402 - Payment Required
Description
Penyebab umum:
- Kredit tidak cukup: Akun Anda tidak memiliki kredit yang cukup untuk melakukan tugas ini (Insufficient funds).
- Paket diperlukan: nano-banana-pro, atau pose_mode dengan nano-banana, memerlukan paket Pro atau di atasnya (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 melampaui batas laju 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

Mengambil Tugas Teks ke Gambar

Endpoint ini memungkinkan Anda untuk mengambil tugas Teks ke Gambar berdasarkan id tugas yang valid. Lihat The Text to Image Task Object untuk melihat properti apa saja yang disertakan dalam objek tugas Teks ke Gambar.

Parameter

Name
id
Type
path
Description
Pengenal unik untuk tugas Teks ke Gambar yang akan diambil.

Hasil Pengembalian

Respons berisi objek tugas Teks ke Gambar. Lihat bagian The Text to Image Task Object untuk detailnya.

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

Hapus Tugas Teks ke Gambar

Endpoint ini menghapus permanen tugas Teks ke Gambar, termasuk semua gambar dan data yang terkait. Tindakan ini tidak dapat dibatalkan.

Parameter Path

Name
id
Type
path
Description
ID dari tugas Teks ke Gambar yang akan dihapus.

Status Tugas

Tugas yang masih berstatus PENDING akan dihapus dan kredit yang terpakai saat pembuatan akan dikembalikan.

Tugas yang sudah berstatus IN_PROGRESS tidak dapat dihapus: permintaan akan ditolak dengan 409 Conflict dan tugas tetap berjalan. Kredit untuk tugas yang sudah mulai dikerjakan oleh worker tidak dapat dikembalikan, sehingga menghapusnya di tengah proses akan membuat Anda kehilangan kredit sekaligus hasilnya. Tunggu hingga mencapai status SUCCEEDED, FAILED, atau CANCELED, baru kemudian hapus.

Tugas dengan status akhir (SUCCEEDED, FAILED, atau CANCELED) akan dihapus tanpa pengembalian kredit.

Returns

Mengembalikan 200 OK jika berhasil, atau 409 Conflict ketika tugas 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

Daftar Tugas Teks ke Gambar

Endpoint ini memungkinkan Anda untuk mengambil daftar tugas Teks ke Gambar.

Parameter

Name
page_num
Type
integer
Description
Nomor halaman untuk paginasi. Dimulai dan defaultnya adalah 1.
Name
page_size
Type
integer
Description
Batas ukuran halaman. Defaultnya adalah 10 item. Maksimum yang diizinkan adalah 100 item.
Name
sort_by
Type
string
Description
Kolom untuk pengurutan. Nilai yang tersedia:
- +created_at: Urutkan berdasarkan waktu pembuatan secara ascending.
- -created_at: Urutkan berdasarkan waktu pembuatan secara descending.

Returns

Mengembalikan daftar berpaginasi dari The Text to Image Task Objects.

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

Stream a Text to Image Task

Endpoint ini melakukan streaming pembaruan secara real-time untuk tugas Teks ke Gambar menggunakan Server-Sent Events (SSE).

Parameter

Name
id
Type
path
Description
Pengidentifikasi unik untuk tugas Teks ke Gambar yang akan di-stream.

Returns

Mengembalikan aliran (stream) The Text to Image Task Objects sebagai Server-Sent Events.

Untuk tugas dengan status PENDING atau IN_PROGRESS, response stream hanya akan menyertakan kolom 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 Task Text to Image

Objek Task Text to Image adalah unit kerja yang dilacak oleh Meshy untuk menghasilkan gambar dari input text prompt. Objek ini memiliki properti berikut:

Properti

Name
id
Type
string
Description
Pengenal unik untuk task ini. Meskipun kami menggunakan k-sortable UUID untuk id task sebagai detail implementasi, Anda tidak boleh membuat asumsi apa pun tentang format id tersebut.
Name
type
Type
string
Description
Jenis task pembuatan gambar. Untuk task Text to Image, nilai ini selalu text-to-image.
Name
ai_model
Type
string
Description
Model AI yang digunakan untuk task ini. Nilai yang mungkin adalah 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
Teks prompt yang digunakan untuk menghasilkan gambar.
Name
status
Type
string
Description
Status task. Nilai yang mungkin adalah salah satu dari PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Progress task. Jika task belum dimulai, properti ini akan bernilai 0. Setelah task berhasil, nilainya akan menjadi 100.
Name
created_at
Type
timestamp
Description
Stempel waktu saat task dibuat, dalam milidetik.
Stempel waktu merepresentasikan jumlah milidetik yang berlalu sejak 1 Januari 1970 UTC, mengikuti standar RFC 3339. Misalnya, Jumat, 1 September 2023 pukul 12:00:00 PM GMT direpresentasikan sebagai 1693569600000. Hal ini berlaku untuk semua stempel waktu di Meshy API.
Name
started_at
Type
timestamp
Description
Stempel waktu saat task dimulai, dalam milidetik. Jika task belum dimulai, properti ini akan bernilai 0.
Name
finished_at
Type
timestamp
Description
Stempel waktu saat task selesai, dalam milidetik. Jika task belum selesai, properti ini akan bernilai 0.
Name
expires_at
Type
timestamp
Description
Stempel waktu saat hasil task kedaluwarsa, dalam milidetik.
Name
preceding_tasks
Type
integer
Description
Jumlah task yang mendahului.
Nilai bidang ini hanya bermakna jika status task adalah PENDING.
Name
image_urls
Type
array
Description
Array URL yang dapat diunduh untuk gambar yang dihasilkan. Saat generate_multi_view diaktifkan, array ini berisi tiga URL gambar yang mewakili sudut pandang berbeda. Jika tidak, array ini berisi satu URL gambar.
Name
task_error
Type
object
Description
Detail kesalahan untuk task yang gagal. Lihat Kesalahan untuk referensi lengkap objek task_error.
Name
consumed_credits
Type
integer
Description
Jumlah kredit yang dikonsumsi oleh task ini. Muncul saat status task adalah PENDING, IN_PROGRESS, atau SUCCEEDED. Mengembalikan 0 untuk task FAILED (kredit dikembalikan jika 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
}