Text to Image API

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

POST/openapi/v1/text-to-image

Membuat Task Teks ke Gambar

Endpoint ini memungkinkan Anda membuat task Teks ke Gambar baru. Lihat The Text to Image Task Object untuk mengetahui properti apa saja yang terdapat pada objek task Teks ke Gambar.

Parameter

  • Name
    ai_model
    Type
    string
    Wajib
    Description

    ID model yang digunakan untuk menghasilkan gambar.

    Nilai yang tersedia:

    • nano-banana: Model standar (3 kredit per gambar)
    • nano-banana-2: Model seimbang dengan kemampuan lebih kuat dibanding model standar (6 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 hasilkan. Buatlah deskripsi yang detail untuk hasil terbaik.

  • Name
    generate_multi_view
    Type
    boolean
    default false
    Description

    Jika diatur ke true, akan 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 dihasilkan tanpa preset pose apa pun.

    Nilai yang tersedia: a-pose, t-pose

  • Name
    aspect_ratio
    Type
    string
    default 1:1
    Description

    Tentukan rasio aspek gambar yang dihasilkan. Nilai yang diperbolehkan bergantung pada ai_model yang dipilih:

    • nano-banana, nano-banana-2, 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 yang dihilangkan, sehingga Anda dapat menyusun subjek ke latar belakang apa pun.

Returns

Properti result pada respons berisi id task dari task 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) tidak disertakan.
    • Parameter tidak valid: ai_model atau aspect_ratio bukan salah satu dari nilai yang diperbolehkan.
    • 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

    Kredit tidak cukup untuk melakukan task ini.

  • Name
    429 - Too Many Requests
    Description

    Anda telah melebihi 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 Task Text to Image

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

Parameter

  • Name
    id
    Type
    path
    Description

    Pengenal unik untuk task Teks ke Gambar yang ingin diambil.

Nilai yang Dikembalikan

Respons berisi objek task 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

Menghapus Tugas Teks ke Gambar

Endpoint ini menghapus permanen sebuah tugas Teks ke Gambar, termasuk semua gambar dan data 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 digunakan pada 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 tugas mencapai status SUCCEEDED, FAILED, atau CANCELED, lalu hapus.

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

Hasil

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 mengambil daftar tugas Teks ke Gambar.

Parameter

  • Name
    page_num
    Type
    integer
    Description

    Nomor halaman untuk paginasi. Dimulai dan default-nya adalah 1.

  • Name
    page_size
    Type
    integer
    Description

    Batas ukuran halaman. Default-nya adalah 10 item. Maksimum yang diizinkan adalah 100 item.

  • Name
    sort_by
    Type
    string
    Description

    Kolom untuk mengurutkan. 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

Streaming Tugas Text to Image

Endpoint ini melakukan streaming pembaruan secara real-time untuk tugas Text to Image menggunakan Server-Sent Events (SSE).

Parameter

  • Name
    id
    Type
    path
    Description

    Pengenal unik untuk tugas Text to Image yang akan di-streaming.

Returns

Mengembalikan stream dari The Text to Image Task Objects sebagai Server-Sent Events.

Untuk tugas dengan status PENDING atau IN_PROGRESS, response stream hanya akan menyertakan field 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

    Pengidentifikasi unik untuk task. Meskipun kami menggunakan UUID yang dapat diurutkan secara-k (k-sortable) 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 akan 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-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 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 dari task. Jika task belum dimulai, properti ini akan bernilai 0. Setelah task berhasil, nilai ini 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 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

    Sebuah array berisi URL yang dapat diunduh untuk gambar yang dihasilkan. Ketika generate_multi_view diaktifkan, array ini berisi tiga URL gambar yang mewakili sudut pandang yang berbeda. Jika tidak, array ini hanya 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
}