API Imej ke Imej

API Imej ke Imej ialah ciri yang membolehkan anda mengintegrasikan keupayaan penyuntingan imej AI Meshy ke dalam aplikasi anda sendiri. Ubah bentuk dan sunting imej sedia ada menggunakan imej rujukan dan gesaan teks dengan model AI kami yang berkuasa.

POST/openapi/v1/image-to-image

Cipta Tugasan Imej ke Imej

Endpoint ini membolehkan anda mencipta tugasan Imej ke Imej baharu. Rujuk Objek Tugasan Imej ke Imej untuk melihat sifat yang disertakan dengan objek tugasan Imej ke Imej.

Parameter

  • Name
    ai_model
    Type
    string
    Diperlukan
    Description

    ID model untuk digunakan bagi 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 dipertingkat (9 kredit setiap imej)
    • gpt-image-2: OpenAI GPT Image 2, model suntingan imej berketepatan tinggi (12 kredit setiap imej)
  • Name
    prompt
    Type
    string
    Diperlukan
    Description

    Penerangan teks tentang transformasi atau suntingan yang anda mahu gunakan pada imej rujukan.

  • Name
    reference_image_urls
    Type
    array
    Diperlukan
    Description

    Array 1 hingga 5 imej rujukan untuk digunakan bagi tugasan penyuntingan imej. Pada masa ini kami menyokong format .jpg, .jpeg, dan .png.

    Terdapat dua cara untuk menyediakan setiap imej:

    • URL yang boleh diakses secara awam: URL yang boleh diakses daripada internet awam.
    • Data URI: Data URI imej yang dikodkan base64. Contoh Data URI: data:image/jpeg;base64,<your base64-encoded image data>.
  • Name
    generate_multi_view
    Type
    boolean
    lalai false
    Description

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

Pulangan

Sifat result dalam respons mengandungi id tugasan bagi tugasan Imej ke Imej yang baru dicipta.

Mod Kegagalan

  • Name
    400 - Bad Request
    Description

    Permintaan tidak dapat diterima. Punca biasa:

    • Parameter hilang: Parameter yang diperlukan (cth., ai_model, prompt, reference_image_urls) tiada.
    • Format imej tidak sah: Satu atau lebih imej rujukan bukan format yang disokong.
    • URL tidak dapat dicapai: Satu atau lebih reference_image_urls tidak dapat dimuat turun.
  • Name
    401 - Unauthorized
    Description

    Pengesahan gagal. Sila semak kunci API anda.

  • Name
    402 - Payment Required
    Description

    Kredit tidak mencukupi untuk melaksanakan tugasan ini.

  • Name
    429 - Too Many Requests
    Description

    Anda telah melebihi had kadar anda.

Request

POST
/openapi/v1/image-to-image
# Transform a reference image with a text prompt
curl https://api.meshy.ai/openapi/v1/image-to-image \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "ai_model": "nano-banana",
    "prompt": "Transform this into a cyberpunk style artwork",
    "reference_image_urls": [
      "<your publicly accessible image url or base64-encoded data URI>"
    ]
  }'


 ## Using Data URI example
curl https://api.meshy.ai/openapi/v1/image-to-image \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "ai_model": "nano-banana",
    "prompt": "Transform this into a cyberpunk style artwork",
    "reference_image_urls": [
      "data:image/png;base64,${YOUR_BASE64_ENCODED_IMAGE_DATA}"
    ]
  }'

Response

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}
GET/openapi/v1/image-to-image/:id

Dapatkan Tugasan Imej ke Imej

endpoint ini membolehkan anda mendapatkan tugasan Imej ke Imej dengan id tugasan yang sah. Rujuk Objek Tugasan Imej ke Imej untuk melihat properties yang disertakan dengan objek tugasan Imej ke Imej.

Parameter

  • Name
    id
    Type
    path
    Description

    Pengecam unik untuk tugasan Imej ke Imej yang ingin didapatkan.

Pulangan

Respons mengandungi objek tugasan Imej ke Imej. Semak bahagian Objek Tugasan Imej ke Imej untuk butiran.

Request

GET
/openapi/v1/image-to-image/018a210d-8ba4-705c-b111-1f1776f7f578
curl https://api.meshy.ai/openapi/v1/image-to-image/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "image-to-image",
  "ai_model": "nano-banana",
  "prompt": "Transform this into a cyberpunk style artwork",
  "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/image-to-image/:id

Padam Tugas Imej ke Imej

endpoint ini memadamkan tugas Imej 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 Imej ke Imej yang hendak dipadamkan.

Pulangan

Mengembalikan 200 OK apabila berjaya.

Request

DELETE
/openapi/v1/image-to-image/018a210d-8ba4-705c-b111-1f1776f7f578
curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/image-to-image/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// Returns 200 Ok on success.
GET/openapi/v1/image-to-image

Senaraikan Tugas Imej ke Imej

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

  • Name
    sort_by
    Type
    string
    Description

    Medan untuk diisih mengikut. Nilai tersedia:

    • +created_at: Isih mengikut masa penciptaan dalam tertib menaik.
    • -created_at: Isih mengikut masa penciptaan dalam tertib menurun.

Pulangan

Mengembalikan senarai bernombor halaman bagi Objek Tugas Imej ke Imej.

Request

GET
/openapi/v1/image-to-image
curl https://api.meshy.ai/openapi/v1/image-to-image?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "image-to-image",
    "ai_model": "nano-banana",
    "prompt": "Transform this into a cyberpunk style artwork",
    "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/image-to-image/:id/stream

Strimkan Tugas Imej ke Imej

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

Parameter

  • Name
    id
    Type
    path
    Description

    Pengecam unik untuk tugas Imej ke Imej yang akan distrim.

Pulangan

Mengembalikan strim Objek Tugas Imej 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/image-to-image/018a210d-8ba4-705c-b111-1f1776f7f578/stream
curl -N https://api.meshy.ai/openapi/v1/image-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": "image-to-image",
  "ai_model": "nano-banana",
  "prompt": "Transform this into a cyberpunk style artwork",
  "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 Imej ke Imej

Objek Tugasan Imej ke Imej ialah unit kerja yang dijejaki oleh Meshy untuk menjana imej daripada input imej rujukan dan prompt teks. Objek ini mempunyai sifat berikut:

Sifat

  • Name
    id
    Type
    string
    Description

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

  • Name
    type
    Type
    string
    Description

    Jenis tugasan penjanaan imej. Untuk tugasan Imej ke Imej, ini akan sentiasa menjadi image-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, atau gpt-image-2.

  • Name
    prompt
    Type
    string
    Description

    Prompt teks yang digunakan untuk memandu transformasi imej.

  • 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 tugasan. Jika tugasan belum bermula, sifat ini akan menjadi 0. Setelah tugasan berjaya, ini akan menjadi 100.

  • Name
    created_at
    Type
    timestamp
    Description

    Cap masa ketika tugasan dicipta, dalam milisaat.

    Cap masa mewakili bilangan milisaat yang telah 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 ketika tugasan dimulakan, dalam milisaat. Jika tugasan belum bermula, sifat ini akan menjadi 0.

  • Name
    finished_at
    Type
    timestamp
    Description

    Cap masa ketika tugasan selesai, dalam milisaat. Jika tugasan belum selesai, sifat ini akan menjadi 0.

  • Name
    expires_at
    Type
    timestamp
    Description

    Cap masa ketika hasil tugasan tamat tempoh, dalam milisaat.

  • Name
    preceding_tasks
    Type
    integer
    Description

    Bilangan tugasan yang mendahului.

    Nilai medan ini hanya bermakna jika status tugasan ialah PENDING.

  • Name
    image_urls
    Type
    array
    Description

    Satu tatasusunan URL yang boleh dimuat turun untuk imej yang dijana. Apabila generate_multi_view didayakan, tatasusunan 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 tugasan yang gagal. Lihat Ralat untuk rujukan objek task_error penuh.

  • Name
    consumed_credits
    Type
    integer
    Description

    Bilangan kredit yang digunakan oleh tugasan ini. Hadir apabila status tugasan ialah PENDING, IN_PROGRESS, atau SUCCEEDED. Mengembalikan 0 untuk tugasan FAILED (kredit dibayar balik apabila gagal).

Example Image to Image Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "image-to-image",
  "ai_model": "nano-banana",
  "prompt": "Transform this into a cyberpunk style artwork",
  "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
}