API Teks ke Imej

API Teks ke Imej adalah ciri yang membolehkan anda mengintegrasikan keupayaan penjanaan imej AI Meshy ke dalam aplikasi anda sendiri. Hasilkan imej berkualiti tinggi daripada arahan 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 baru. Rujuk kepada Objek Tugas Teks ke Imej untuk melihat sifat-sifat yang disertakan dengan objek tugas Teks ke Imej.

Parameter

  • Name
    ai_model
    Type
    string
    Diperlukan
    Description

    ID model yang akan digunakan untuk penjanaan imej.

    Nilai yang tersedia:

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

    Penerangan teks tentang imej yang anda ingin hasilkan. Jadilah deskriptif untuk hasil terbaik.

  • Name
    generate_multi_view
    Type
    boolean
    lalai false
    Description

    Apabila ditetapkan kepada true, menghasilkan imej berbilang pandangan yang menunjukkan subjek dari pelbagai sudut.

    Apabila generate_multi_view adalah true, parameter aspect_ratio tidak boleh ditetapkan.

  • Name
    pose_mode
    Type
    string
    Description

    Tentukan mode pose untuk penjanaan watak. Apabila diabaikan, imej dihasilkan tanpa sebarang tetapan pose.

    Nilai yang tersedia: a-pose, t-pose

  • Name
    aspect_ratio
    Type
    string
    lalai 1:1
    Description

    Tentukan nisbah aspek imej yang dihasilkan. 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: 1:1, 16:9, 9:16, 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 (tidak disokong oleh gpt-image-2)
    • 3:4: Potret standard (tidak disokong oleh gpt-image-2)
    • 3:2: Landskap (hanya disokong oleh gpt-image-2)
    • 2:3: Potret (hanya disokong oleh gpt-image-2)
  • Name
    remove_background
    Type
    boolean
    lalai false
    Description

    Apabila ditetapkan kepada true, imej yang dihasilkan dikembalikan sebagai PNG RGBA telus dengan latar belakang dibuang, jadi anda boleh menggabungkan subjek ke mana-mana latar belakang.

Pulangan

Sifat result dalam respons mengandungi id tugas yang baru dicipta untuk tugas Teks ke Imej.

Mod Kegagalan

  • Name
    400 - Bad Request
    Description

    Permintaan tidak boleh diterima. Punca biasa:

    • Parameter hilang: Parameter yang diperlukan (contohnya, ai_model, prompt) hilang.
    • Parameter tidak sah: ai_model atau aspect_ratio bukan salah satu nilai yang dibenarkan.
    • Konflik: generate_multi_view dan aspect_ratio tidak boleh digunakan 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.

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

Dapatkan Tugas Teks ke Imej

Endpoint ini membolehkan anda mendapatkan tugas Teks ke Imej dengan memberikan id tugas yang sah. Rujuk kepada Objek Tugas Teks ke Imej untuk melihat sifat-sifat yang disertakan dengan objek tugas Teks ke Imej.

Parameter

  • Name
    id
    Type
    path
    Description

    Pengenal pasti unik untuk tugas Teks ke Imej yang ingin diperoleh.

Pulangan

Respons mengandungi objek tugas Teks ke Imej. Semak bahagian Objek Tugas Teks ke Imej untuk butiran lanjut.

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

Respons

{
  "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 secara kekal tugas Teks ke Imej, termasuk semua imej dan data yang berkaitan. Tindakan ini tidak boleh dipulihkan.

Parameter Laluan

  • Name
    id
    Type
    path
    Description

    ID tugas Teks ke Imej untuk dipadam.

Pulangan

Mengembalikan 200 OK jika berjaya.

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

Senarai Tugas Teks ke Imej

Endpoint ini membolehkan anda mendapatkan senarai tugas 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 dibenarkan ialah 50 item.

  • Name
    sort_by
    Type
    string
    Description

    Medan untuk disusun. Nilai yang tersedia:

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

Pulangan

Mengembalikan senarai berpenomboran halaman bagi Objek Tugas Teks ke Imej.

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

Respons

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

Strim Tugas Teks ke Imej

Endpoint ini menstrim kemas kini masa nyata untuk tugas Teks ke Imej menggunakan Server-Sent Events (SSE).

Parameter

  • Name
    id
    Type
    path
    Description

    Pengenal pasti unik untuk tugas Teks ke Imej untuk distrim.

Pulangan

Mengembalikan strim Objek Tugas Teks ke Imej sebagai Server-Sent Events.

Untuk tugas PENDING atau IN_PROGRESS, strim 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 Tugas Teks ke Imej

Objek Tugas Teks ke Imej adalah unit kerja yang Meshy jejak untuk menjana imej daripada input prompt teks. Objek ini mempunyai sifat-sifat berikut:

Sifat-sifat

  • Name
    id
    Type
    string
    Description

    Pengenal pasti unik untuk tugas ini. Walaupun kami menggunakan UUID yang boleh diurutkan k untuk id tugas sebagai butiran pelaksanaan, anda tidak seharusnya membuat sebarang andaian tentang format id tersebut.

  • Name
    type
    Type
    string
    Description

    Jenis tugas penjanaan imej. Untuk tugas Teks ke Imej, ini akan sentiasa 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 menjana imej.

  • Name
    status
    Type
    string
    Description

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

  • Name
    progress
    Type
    integer
    Description

    Kemajuan tugas. Jika tugas belum dimulakan, sifat ini akan menjadi 0. Setelah tugas berjaya, ini akan menjadi 100.

  • Name
    created_at
    Type
    timestamp
    Description

    Cap masa apabila tugas 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 apabila tugas dimulakan, dalam milisaat. Jika tugas belum dimulakan, sifat ini akan menjadi 0.

  • Name
    finished_at
    Type
    timestamp
    Description

    Cap masa apabila tugas selesai, dalam milisaat. Jika tugas belum selesai, sifat ini akan menjadi 0.

  • Name
    expires_at
    Type
    timestamp
    Description

    Cap masa apabila hasil tugas tamat tempoh, dalam milisaat.

  • Name
    preceding_tasks
    Type
    integer
    Description

    Bilangan tugas terdahulu.

    Nilai medan ini bermakna hanya jika status tugas 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.

  • Name
    task_error
    Type
    object
    Description

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

  • Name
    consumed_credits
    Type
    integer
    Description

    Bilangan kredit yang digunakan oleh tugas ini. Hadir apabila status tugas adalah PENDING, IN_PROGRESS, atau SUCCEEDED. Mengembalikan 0 untuk tugas FAILED (kredit dikembalikan semula apabila gagal).

Contoh Objek Tugas Teks ke Imej

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