API Teks ke Gambar

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

POST/openapi/v1/text-to-image

Buat Tugas Teks ke Gambar

Endpoint ini memungkinkan Anda membuat tugas Teks ke Gambar baru. Lihat Objek Tugas Teks ke Gambar untuk melihat properti yang disertakan dengan 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 daripada 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 fidelitas tinggi dengan dukungan rasio aspek terbatas (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

    Jika diatur ke true, menghasilkan gambar multi-tampilan yang menampilkan subjek dari beberapa sudut.

    Jika generate_multi_view adalah true, parameter aspect_ratio tidak dapat diatur.

  • Name
    pose_mode
    Type
    string
    Description

    Tentukan mode pose untuk pembuatan karakter. Jika dihilangkan, 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 gambar yang dihasilkan. Nilai yang diizinkan 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: hanya 1:1, 3:2, 2:3

    Nilai yang tersedia:

    • 1:1: Format persegi
    • 16:9: Lanskap layar lebar (tidak didukung oleh gpt-image-2)
    • 9:16: Potret layar lebar (tidak didukung oleh gpt-image-2)
    • 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)

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 wajib (misalnya, ai_model, prompt) tidak ada.
    • 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. Harap periksa kunci API Anda.

  • Name
    402 - Payment Required
    Description

    Kredit tidak mencukupi untuk melakukan tugas ini.

  • 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

Ambil Tugas Teks ke Gambar

Endpoint ini memungkinkan Anda mengambil tugas Teks ke Gambar dengan id tugas yang valid. Lihat Objek Tugas Teks ke Gambar untuk mengetahui properti apa saja yang disertakan dalam objek tugas Teks ke Gambar.

Parameter

  • Name
    id
    Type
    path
    Description

    Pengidentifikasi unik untuk tugas Teks ke Gambar yang akan diambil.

Mengembalikan

Respons berisi objek tugas Teks ke Gambar. Periksa bagian Objek Tugas Teks ke Gambar 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 secara permanen tugas Teks ke Gambar, termasuk semua gambar dan data terkait. Tindakan ini tidak dapat dibatalkan.

Parameter Path

  • Name
    id
    Type
    path
    Description

    ID tugas Teks ke Gambar yang akan dihapus.

Pengembalian

Mengembalikan 200 OK jika berhasil.

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

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

    Field untuk mengurutkan berdasarkan. Nilai yang tersedia:

    • +created_at: Urutkan berdasarkan waktu pembuatan dalam urutan menaik.
    • -created_at: Urutkan berdasarkan waktu pembuatan dalam urutan menurun.

Mengembalikan

Mengembalikan daftar terpaginasi dari Objek Tugas Teks ke Gambar.

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

Endpoint ini melakukan streaming pembaruan 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-streaming.

Mengembalikan

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

Untuk tugas PENDING atau IN_PROGRESS, stream respons 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 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 berikut:

Properties

  • Name
    id
    Type
    string
    Description

    Pengidentifikasi unik untuk tugas. Meskipun kami menggunakan UUID k-sortable untuk id tugas sebagai detail implementasi, Anda tidak boleh membuat asumsi apa pun tentang format id tersebut.

  • Name
    type
    Type
    string
    Description

    Jenis tugas pembuatan gambar. Untuk tugas Teks ke Gambar, nilainya akan selalu 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 tugas. Jika tugas belum dimulai, properti ini akan bernilai 0. Setelah tugas berhasil, nilainya akan menjadi 100.

  • Name
    created_at
    Type
    timestamp
    Description

    Stempel waktu saat tugas 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. Ini berlaku untuk semua stempel waktu di Meshy API.

  • Name
    started_at
    Type
    timestamp
    Description

    Stempel waktu saat tugas dimulai, dalam milidetik. Jika tugas belum dimulai, properti ini akan bernilai 0.

  • Name
    finished_at
    Type
    timestamp
    Description

    Stempel waktu saat tugas selesai, dalam milidetik. Jika tugas belum selesai, properti ini akan bernilai 0.

  • Name
    expires_at
    Type
    timestamp
    Description

    Stempel waktu saat hasil tugas kedaluwarsa, dalam milidetik.

  • Name
    preceding_tasks
    Type
    integer
    Description

    Jumlah tugas sebelumnya.

    Nilai bidang ini hanya bermakna jika status tugas adalah PENDING.

  • Name
    image_urls
    Type
    array
    Description

    Array URL yang dapat diunduh untuk gambar yang dihasilkan. Ketika generate_multi_view diaktifkan, array ini berisi tiga URL gambar yang merepresentasikan sudut pandang berbeda. Jika tidak, array ini berisi satu URL gambar.

  • Name
    task_error
    Type
    object
    Description

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

  • Name
    consumed_credits
    Type
    integer
    Description

    Jumlah kredit yang dikonsumsi oleh tugas ini. Hadir ketika status tugas adalah PENDING, IN_PROGRESS, atau SUCCEEDED. Mengembalikan 0 untuk tugas FAILED (kredit dikembalikan saat 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
}