API Teks ke Imej

API Teks ke Imej ialah ciri yang membolehkan anda mengintegrasikan keupayaan penjanaan imej AI Meshy ke dalam aplikasi anda sendiri. Jana imej berkualiti tinggi daripada gesaan teks menggunakan model AI kami yang berkuasa.

POST/openapi/v1/text-to-image

Cipta Tugas Teks ke Imej

Endpoint ini membolehkan anda mencipta tugas Teks ke Imej yang baharu. Rujuk Objek Tugas Teks ke Imej untuk melihat sifat yang disertakan dengan objek tugas Teks ke Imej.

Parameter

  • Name
    ai_model
    Type
    string
    Diperlukan
    Description

    ID model yang digunakan untuk penjanaan imej.

    Nilai yang tersedia:

    • nano-banana: Model standard (3 kredit setiap imej)
    • nano-banana-2: Model seimbang dengan keupayaan yang lebih kuat daripada standard (6 kredit setiap imej)
    • nano-banana-pro: Model Pro dengan kualiti dipertingkatkan (9 kredit setiap imej)
    • gpt-image-2: OpenAI GPT Image 2, model imej ketepatan tinggi (9 kredit setiap imej)
    • gpt-image-2-5-flare: OpenAI GPT Image 2.5 (Flare), model imej ketepatan tinggi (9 kredit setiap imej)
    • gpt-image-2-5-sunburst: OpenAI GPT Image 2.5 (Sunburst), model imej ketepatan tinggi (9 kredit setiap imej)
  • Name
    prompt
    Type
    string
    Diperlukan
    Description

    Penerangan teks bagi imej yang ingin anda jana. Berikan penerangan yang jelas untuk hasil terbaik.

  • Name
    generate_multi_view
    Type
    boolean
    lalai false
    Description

    Apabila ditetapkan kepada true, akan menjana imej Berbilang Pandangan yang menunjukkan subjek dari pelbagai sudut.

    Apabila generate_multi_view bernilai true, parameter aspect_ratio tidak boleh ditetapkan.

  • Name
    pose_mode
    Type
    string
    Description

    Nyatakan pose_mode untuk penjanaan watak. Apabila diabaikan, imej akan dijana tanpa sebarang pratetap pose.

    Nilai yang tersedia: a-pose, t-pose

  • Name
    aspect_ratio
    Type
    string
    lalai 1:1
    Description

    Nyatakan nisbah aspek bagi imej yang dijana. Nilai yang dibenarkan 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 segi empat sama
    • 16:9: Landskap skrin lebar
    • 9:16: Potret skrin lebar
    • 4:3: Landskap standard
    • 3:4: Potret standard
    • 3:2: Landskap (hanya disokong oleh model GPT Image)
    • 2:3: Potret (hanya disokong oleh model GPT Image)
  • Name
    remove_background
    Type
    boolean
    lalai false
    Description

    Apabila ditetapkan kepada true, imej yang dijana dikembalikan sebagai PNG RGBA lutsinar dengan latar belakang dialih keluar, membolehkan anda menggabungkan subjek ke atas mana-mana latar belakang.

Nilai Pulangan

Sifat result bagi respons mengandungi id tugas bagi tugas Teks ke Imej yang baharu dicipta.

Mod Kegagalan

  • Name
    400 - Bad Request
    Description

    Permintaan tidak dapat diterima. Punca biasa:

    • Parameter hilang: Parameter yang diperlukan (contohnya, ai_model, prompt) tiada.
    • Parameter tidak sah: ai_model atau aspect_ratio bukan salah satu daripada nilai yang dibenarkan.
    • Konflik: generate_multi_view dan aspect_ratio tidak boleh digunakan secara serentak.
  • Name
    401 - Unauthorized
    Description

    Pengesahan gagal. Sila semak kunci API anda.

  • Name
    402 - Payment Required
    Description

    Kredit tidak mencukupi untuk melaksanakan tugas ini.

  • Name
    429 - Too Many Requests
    Description

    Anda telah melebihi had kadar 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

Retrieve a Text to Image Task

Endpoint ini membolehkan anda mendapatkan semula tugasan Teks ke Imej dengan id tugasan yang sah. Rujuk The Text to Image Task Object untuk melihat sifat-sifat yang disertakan dalam objek tugasan Teks ke Imej.

Parameter

  • Name
    id
    Type
    path
    Description

    Pengecam unik untuk tugasan Teks ke Imej yang hendak diambil.

Nilai Pulangan

Respons mengandungi objek tugasan Teks ke Imej. Semak bahagian The Text to Image Task Object untuk butiran lanjut.

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

Padam Tugas Teks ke Imej

Endpoint ini memadam tugas Teks ke Imej secara kekal, termasuk semua imej dan data yang berkaitan. Tindakan ini tidak boleh dibatalkan.

Parameter Laluan

  • Name
    id
    Type
    path
    Description

    ID tugas Teks ke Imej yang hendak dipadam.

Status Tugas

Tugas yang masih PENDING akan dipadam dan kredit yang digunakan pada masa penciptaan akan dikembalikan.

Tugas yang sudah IN_PROGRESS tidak boleh dipadam: permintaan akan ditolak dengan 409 Conflict dan tugas tersebut terus berjalan. Kredit bagi tugas yang pekerja telah mula proses tidak boleh dikembalikan, jadi memadamnya semasa ia berjalan akan menyebabkan anda kehilangan kredit dan juga hasilnya. Tunggu sehingga ia mencapai SUCCEEDED, FAILED atau CANCELED, kemudian padamkannya.

Tugas dalam keadaan akhir (SUCCEEDED, FAILED atau CANCELED) akan dipadam tanpa bayaran balik.

Pulangan

Mengembalikan 200 OK apabila berjaya, atau 409 Conflict apabila 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

Senaraikan Tugasan Teks ke Imej

Endpoint ini membolehkan anda mendapatkan senarai tugasan Teks ke Imej.

Parameter

  • Name
    page_num
    Type
    integer
    Description

    Nombor halaman untuk penomboran halaman. Bermula dan lalai kepada 1.

  • Name
    page_size
    Type
    integer
    Description

    Had saiz halaman. Lalai kepada 10 item. Maksimum yang dibenarkan ialah 100 item.

  • Name
    sort_by
    Type
    string
    Description

    Medan untuk disusun. Nilai yang tersedia:

    • +created_at: Susun mengikut masa penciptaan secara menaik.
    • -created_at: Susun mengikut masa penciptaan secara menurun.

Pulangan

Mengembalikan senarai berpenomboran halaman bagi 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 menstrim kemas kini masa nyata untuk tugas Teks ke Imej menggunakan Server-Sent Events (SSE).

Parameter

  • Name
    id
    Type
    path
    Description

    Pengecam unik untuk tugas Teks ke Imej yang hendak distrim.

Pulangan

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

Untuk tugas PENDING atau IN_PROGRESS, aliran respons hanya akan menyertakan medan 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 Tugasan Teks ke Imej

Objek Tugasan Teks ke Imej adalah unit kerja yang dijejaki oleh Meshy untuk menjana imej daripada input prompt teks. Objek ini mempunyai ciri-ciri berikut:

Ciri-ciri

  • Name
    id
    Type
    string
    Description

    Pengecam unik untuk tugasan. Walaupun kami menggunakan UUID k-sortable untuk id tugasan sebagai perincian pelaksanaan, anda tidak patut membuat sebarang andaian tentang format id tersebut.

  • Name
    type
    Type
    string
    Description

    Jenis tugasan penjanaan imej. Untuk tugasan Teks ke Imej, ini sentiasa text-to-image.

  • Name
    ai_model
    Type
    string
    Description

    Model AI yang digunakan untuk tugasan ini. Nilai yang mungkin ialah 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 menjana imej tersebut.

  • Name
    status
    Type
    string
    Description

    Status tugasan. Nilai yang mungkin ialah salah satu daripada PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

  • Name
    progress
    Type
    integer
    Description

    Progress bagi tugasan. Jika tugasan belum bermula lagi, ciri ini akan menjadi 0. Setelah tugasan berjaya, ini akan menjadi 100.

  • Name
    created_at
    Type
    timestamp
    Description

    Cap masa bila tugasan dicipta, dalam milisaat.

    Cap masa mewakili bilangan milisaat yang berlalu sejak 1 Januari 1970 UTC, mengikut piawaian RFC 3339. Sebagai contoh, Jumaat, 1 September 2023 12:00:00 PM GMT diwakili sebagai 1693569600000. Ini terpakai kepada semua cap masa dalam Meshy API.

  • Name
    started_at
    Type
    timestamp
    Description

    Cap masa bila tugasan dimulakan, dalam milisaat. Jika tugasan belum bermula lagi, ciri ini akan menjadi 0.

  • Name
    finished_at
    Type
    timestamp
    Description

    Cap masa bila tugasan selesai, dalam milisaat. Jika tugasan belum selesai lagi, ciri ini akan menjadi 0.

  • Name
    expires_at
    Type
    timestamp
    Description

    Cap masa bila hasil tugasan akan luput, dalam milisaat.

  • Name
    preceding_tasks
    Type
    integer
    Description

    Bilangan tugasan yang mendahului.

    Nilai medan ini hanya bermakna jika status tugasan adalah PENDING.

  • Name
    image_urls
    Type
    array
    Description

    Satu array URL yang boleh dimuat turun untuk imej yang dijana. Apabila generate_multi_view diaktifkan, array ini mengandungi tiga URL imej yang mewakili sudut pandangan yang berbeza. Jika tidak, ia mengandungi satu URL imej sahaja.

  • Name
    task_error
    Type
    object
    Description

    Butiran ralat untuk tugasan yang gagal. Lihat Ralat untuk rujukan penuh objek task_error.

  • Name
    consumed_credits
    Type
    integer
    Description

    Bilangan kredit yang digunakan oleh tugasan ini. Hadir apabila status tugasan adalah PENDING, IN_PROGRESS, atau SUCCEEDED. Mengembalikan 0 untuk tugasan FAILED (kredit dikembalikan semula apabila 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
}