API Teks ke Gambar

API Teks ke Gambar adalah fitur yang memungkinkan Anda untuk mengintegrasikan kemampuan pembuatan gambar AI dari Meshy ke dalam aplikasi Anda sendiri. Hasilkan gambar berkualitas tinggi dari teks prompt menggunakan model AI kami yang kuat.

POST/openapi/v1/text-to-image

Membuat Tugas Teks ke Gambar

Endpoint ini memungkinkan Anda untuk membuat tugas Teks ke Gambar baru. Lihat Objek Tugas Teks ke Gambar untuk melihat properti apa saja yang termasuk dalam objek tugas Teks ke Gambar.

Parameter

  • Name
    ai_model
    Type
    string
    Wajib
    Description

    ID model yang akan digunakan untuk pembuatan gambar.

    Nilai yang tersedia:

    • nano-banana: Model standar (3 kredit per gambar)
    • nano-banana-2: Model seimbang dengan kemampuan lebih kuat dari 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)
  • Name
    prompt
    Type
    string
    Wajib
    Description

    Deskripsi teks dari gambar yang ingin Anda buat. Berikan deskripsi yang jelas untuk hasil terbaik.

  • Name
    generate_multi_view
    Type
    boolean
    default false
    Description

    Ketika diatur ke true, menghasilkan gambar multi-tampilan yang menunjukkan subjek dari berbagai sudut.

    Ketika generate_multi_view adalah true, parameter aspect_ratio tidak dapat diatur.

  • Name
    pose_mode
    Type
    string
    Description

    Tentukan mode pose untuk pembuatan karakter. Jika tidak disebutkan, gambar dibuat tanpa preset pose apa pun.

    Nilai yang tersedia: a-pose, t-pose

  • Name
    aspect_ratio
    Type
    string
    default 1:1
    Description

    Tentukan rasio aspek dari gambar yang dihasilkan. Nilai yang diizinkan tergantung 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: 1:1, 16:9, 9:16, 3:2, 2:3

    Nilai yang tersedia:

    • 1:1: Format persegi
    • 16:9: Layar lebar lanskap
    • 9:16: Layar lebar potret
    • 4:3: Lanskap standar (tidak didukung oleh gpt-image-2)
    • 3:4: Potret standar (tidak didukung oleh gpt-image-2)
    • 3:2: Lanskap (hanya didukung oleh gpt-image-2)
    • 2:3: Potret (hanya didukung oleh gpt-image-2)
  • Name
    remove_background
    Type
    boolean
    default false
    Description

    Ketika diatur ke true, gambar yang dihasilkan dikembalikan sebagai PNG RGBA transparan dengan latar belakang dihapus, sehingga Anda dapat menggabungkan subjek ke latar belakang apa pun.

Mengembalikan

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

Mode Kegagalan

  • 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 bersamaan.
  • Name
    401 - Unauthorized
    Description

    Autentikasi gagal. Silakan periksa kunci API Anda.

  • Name
    402 - Payment Required
    Description

    Kredit tidak mencukupi untuk melakukan tugas ini.

  • Name
    429 - Too Many Requests
    Description

    Anda telah melebihi batas laju Anda.

Permintaan

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

Respons

{
  "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 dengan memberikan id tugas yang valid. Lihat Objek Tugas Teks ke Gambar untuk melihat properti apa saja yang disertakan dengan objek tugas Teks ke Gambar.

Parameter

  • Name
    id
    Type
    path
    Description

    Pengenal unik untuk tugas Teks ke Gambar yang akan diambil.

Mengembalikan

Respon berisi objek tugas Teks ke Gambar. Periksa bagian Objek Tugas Teks ke Gambar untuk detailnya.

Permintaan

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

Respon

{
  "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 secara permanen menghapus tugas Teks ke Gambar, termasuk semua gambar dan data yang terkait. Tindakan ini tidak dapat dibatalkan.

Parameter Jalur

  • Name
    id
    Type
    path
    Description

    ID dari tugas Teks ke Gambar yang akan dihapus.

Mengembalikan

Mengembalikan 200 OK jika berhasil.

Permintaan

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

Respons

// Returns 200 Ok on success.
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 default ke 1.

  • Name
    page_size
    Type
    integer
    Description

    Batas ukuran halaman. Default ke 10 item. Maksimum yang diizinkan adalah 50 item.

  • Name
    sort_by
    Type
    string
    Description

    Bidang untuk mengurutkan. Nilai yang tersedia:

    • +created_at: Urutkan berdasarkan waktu pembuatan dalam urutan naik.
    • -created_at: Urutkan berdasarkan waktu pembuatan dalam urutan turun.

Mengembalikan

Mengembalikan daftar berisi paginasi dari Objek Tugas Teks ke Gambar.

Permintaan

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

Respon

[
  {
    "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 Teks ke Gambar

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

Parameter

  • Name
    id
    Type
    path
    Description

    Pengenal unik untuk tugas Teks ke Gambar yang akan di-stream.

Mengembalikan

Mengembalikan aliran Objek Tugas Teks ke Gambar sebagai Server-Sent Events.

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

Permintaan

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

Aliran Respons

// 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 Teks ke Gambar

Objek Tugas Teks ke Gambar adalah unit kerja yang dilacak oleh Meshy untuk menghasilkan gambar dari input prompt teks. Objek ini memiliki properti sebagai berikut:

Properti

  • Name
    id
    Type
    string
    Description

    Pengidentifikasi unik untuk tugas. Meskipun kami menggunakan UUID yang dapat diurutkan secara k untuk id tugas sebagai detail implementasi, Anda tidak boleh membuat asumsi apapun tentang format id tersebut.

  • Name
    type
    Type
    string
    Description

    Jenis tugas pembuatan gambar. Untuk tugas Teks ke Gambar, ini akan selalu menjadi text-to-image.

  • Name
    ai_model
    Type
    string
    Description

    Model AI yang digunakan untuk tugas ini. Nilai yang mungkin adalah nano-banana, nano-banana-2, nano-banana-pro, atau gpt-image-2.

  • Name
    prompt
    Type
    string
    Description

    Prompt teks yang digunakan untuk menghasilkan gambar.

  • Name
    status
    Type
    string
    Description

    Status tugas. Nilai yang mungkin adalah salah satu dari PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

  • Name
    progress
    Type
    integer
    Description

    Progress dari tugas. Jika tugas belum dimulai, properti ini akan menjadi 0. Setelah tugas berhasil, ini akan menjadi 100.

  • Name
    created_at
    Type
    timestamp
    Description

    Stempel waktu ketika tugas dibuat, dalam milidetik.

    Stempel waktu mewakili jumlah milidetik yang berlalu sejak 1 Januari 1970 UTC, mengikuti standar RFC 3339. Sebagai contoh, Jumat, 1 September 2023 12:00:00 PM GMT diwakili sebagai 1693569600000. Ini berlaku untuk semua stempel waktu di Meshy API.

  • Name
    started_at
    Type
    timestamp
    Description

    Stempel waktu ketika tugas dimulai, dalam milidetik. Jika tugas belum dimulai, properti ini akan menjadi 0.

  • Name
    finished_at
    Type
    timestamp
    Description

    Stempel waktu ketika tugas selesai, dalam milidetik. Jika tugas belum selesai, properti ini akan menjadi 0.

  • Name
    expires_at
    Type
    timestamp
    Description

    Stempel waktu ketika hasil tugas kedaluwarsa, dalam milidetik.

  • Name
    preceding_tasks
    Type
    integer
    Description

    Jumlah tugas sebelumnya.

    Nilai dari bidang ini hanya berarti jika status tugas adalah PENDING.

  • Name
    image_urls
    Type
    array
    Description

    Sebuah array URL yang dapat diunduh ke gambar yang dihasilkan. Ketika generate_multi_view diaktifkan, array ini berisi tiga URL gambar yang mewakili sudut pandang yang berbeda. Jika tidak, ini berisi satu URL gambar.

  • Name
    task_error
    Type
    object
    Description

    Detail kesalahan untuk tugas yang gagal. Lihat Kesalahan untuk referensi lengkap objek task_error.

  • Name
    consumed_credits
    Type
    integer
    Description

    Jumlah kredit yang dikonsumsi oleh tugas ini. Ada ketika status tugas adalah PENDING, IN_PROGRESS, atau SUCCEEDED. Mengembalikan 0 untuk tugas FAILED (kredit dikembalikan saat gagal).

Contoh Objek Tugas Teks ke Gambar

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