API Imej ke Imej

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

Endpoint ini menghasilkan imej. Jika matlamatnya ialah objek yang boleh anda pegang atau cetak — rantai kunci, magnet peti sejuk, figura, lampu atau penutup kekunci daripada foto — gunakan Creative Lab APIs (imej prototaip → bina model 3D). Jika matlamatnya ialah model 3D bagi apa yang terdapat dalam gambar, gunakan Imej ke 3D.

POST/openapi/v1/image-to-image

Create an Image to Image Task

Endpoint ini membolehkan anda mencipta tugas Imej ke Imej yang baharu. Rujuk The Image to Image Task Object untuk melihat sifat-sifat yang disertakan dengan objek tugas Imej ke Imej.

Tugas ini berjalan di latar belakang. Untuk tempoh biasa yang diperlukan, lihat Processing Times.

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 lebih kuat berbanding standard (6 kredit setiap imej)
- nano-banana-2-lite: Varian ringan bagi nano-banana-2 (3 kredit setiap imej)
- nano-banana-pro: Model Pro dengan kualiti yang dipertingkatkan (9 kredit setiap imej)
- gpt-image-2: OpenAI GPT Image 2, model penyuntingan imej berketepatan tinggi (12 kredit setiap imej)
- gpt-image-2-5-flare: OpenAI GPT Image 2.5 (Flare), model penyuntingan imej berketepatan tinggi (12 kredit setiap imej)
- gpt-image-2-5-sunburst: OpenAI GPT Image 2.5 (Sunburst), model penyuntingan imej berketepatan tinggi (12 kredit setiap imej)
Name
prompt
Type
string
Diperlukan
Description
Penerangan teks tentang transformasi atau suntingan yang anda ingin kenakan pada imej rujukan.

Hanya satu daripada input_task_id atau reference_image_urls yang diperlukan. Jika kedua-duanya disediakan, input_task_id diberi keutamaan.

Name
input_task_id
Type
string
Diperlukan
Description
ID tugas penjanaan imej yang telah selesai, yang imej outputnya hendak digunakan sebagai imej rujukan. Tugas ini mestilah salah satu daripada tugas berikut: Teks ke Imej atau Imej ke Imej, termasuk varian Berbilang Pandangan masing-masing. Selain itu, ia mestilah telah dijalankan melalui API dan mempunyai status SUCCEEDED.
Semua imej output tugas sumber digunakan. Tugas imej tunggal menyumbang 1 imej rujukan; tugas berbilang pandangan menyumbang satu bagi setiap pandangan yang dijana, jadi satu ID tugas boleh mengisi beberapa daripada 5 slot rujukan.
Tugas sumber mestilah masih dalam tempoh pengekalan aset — sebaik sahaja ia tamat tempoh, ID-nya akan memulangkan 404.

Name
reference_image_urls
Type
array
Diperlukan
Description
Satu tatasusunan sebanyak 1 hingga 5 imej rujukan untuk digunakan bagi tugas penyuntingan imej. Kami kini menyokong format .jpg, .jpeg, .png, dan .webp.
Saiz fail maksimum: 20 MB setiap imej.
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 daripada pelbagai sudut.
Apabila generate_multi_view ialah true, parameter aspect_ratio tidak boleh ditetapkan.
Name
aspect_ratio
Type
string
lalai 1:1
Description
Nyatakan nisbah bidang imej output. Nilai yang dibenarkan bergantung pada ai_model yang dipilih:
- nano-banana, nano-banana-2, nano-banana-2-lite, 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 output dipulangkan sebagai PNG RGBA telus dengan latar belakang dibuang, supaya anda boleh menggabungkan subjek ke atas sebarang latar belakang.

Pulangan

Sifat result bagi respons mengandungi id tugas bagi tugas Imej 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, atau sama ada reference_image_urls atau input_task_id tidak disediakan.
- Tugas input tidak sah: input_task_id mestilah merujuk kepada tugas Teks ke Imej atau Imej ke Imej yang berstatus SUCCEEDED (termasuk Berbilang Pandangan) dan masih mempunyai output imej. Tugas daripada jenis lain, tugas yang belum berjaya, atau tugas yang semua imejnya telah tamat tempoh akan ditolak.
- Format imej tidak sah: Satu atau lebih imej rujukan tidak dalam format yang disokong.
- URL tidak dapat dicapai: Satu atau lebih reference_image_urls tidak dapat dimuat turun.
- Imej terlalu besar: Satu atau lebih imej reference_image_urls melebihi 20 MB.
- Parameter tidak sah: aspect_ratio bukan salah satu nilai yang dibenarkan bagi ai_model yang dipilih.
- 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
404 - Not Found
Description
input_task_id tidak merujuk kepada tugas yang dimiliki oleh akaun anda. Tugas yang tidak wujud dan tugas milik akaun lain akan memulangkan respons yang sama.
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}"
    ]
  }'


 ## Chaining from a previous task, instead of passing image URLs
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",
    "input_task_id": "<your Text to Image or Image to Image task id>"
  }'

Response

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}

GET/openapi/v1/image-to-image/:id

Dapatkan Semula Tugasan Imej ke Imej

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

Parameter

Name
id
Type
path
Description
Pengenal unik untuk tugasan Imej ke Imej yang hendak didapatkan semula.

Pulangan

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

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 Tugasan Imej ke Imej

Endpoint ini memadamkan tugasan Imej ke Imej secara kekal, termasuk semua imej dan data yang berkaitan. Tindakan ini tidak boleh diterbalikkan.

Parameter Laluan

Name
id
Type
path
Description
ID bagi tugasan Imej ke Imej yang hendak dipadamkan.

Status Tugasan

Tugasan yang masih PENDING akan dipadamkan dan kredit yang digunakan semasa ia dicipta akan dikembalikan.

Tugasan yang sudah pun IN_PROGRESS tidak boleh dipadamkan: permintaan akan ditolak dengan 409 Conflict dan tugasan itu akan terus berjalan. Kredit bagi tugasan yang telah mula diproses oleh worker tidak boleh dikembalikan, jadi memadamkannya semasa berjalan akan menyebabkan anda kehilangan kredit dan juga hasilnya. Tunggu sehingga ia mencapai status SUCCEEDED, FAILED atau CANCELED, kemudian padamkannya.

Tugasan yang berada dalam status akhir (SUCCEEDED, FAILED atau CANCELED) akan dipadamkan tanpa sebarang bayaran balik.

Nilai Pulangan

Memulangkan 200 OK jika berjaya, atau 409 Conflict apabila tugasan tersebut berstatus IN_PROGRESS.

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

// 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/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 100 item.
Name
sort_by
Type
string
Description
Medan untuk disusun mengikut. Nilai yang tersedia:
- +created_at: Susun mengikut masa penciptaan secara menaik.
- -created_at: Susun mengikut masa penciptaan secara menurun.

Pulangan

Mengembalikan senarai bernomboran 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

Alirkan Tugas Imej ke Imej

Endpoint ini mengalirkan 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 hendak dialirkan.

Pemulangan

Memulangkan aliran Objek Tugas Imej ke Imej sebagai Server-Sent Events.

Untuk tugas PENDING atau IN_PROGRESS, aliran respons hanya akan mengandungi 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 Tugas Image to Image

Objek Tugas Image to Image ialah unit kerja yang dijejaki oleh Meshy untuk menjana imej daripada imej rujukan dan input prompt teks. Objek ini mempunyai sifat-sifat berikut:

Sifat-sifat

Name
id
Type
string
Description
Pengenal unik untuk tugas tersebut. Walaupun kami menggunakan UUID yang boleh diisih secara-k (k-sortable) sebagai butiran pelaksanaan untuk id tugas, anda tidak sepatutnya membuat sebarang andaian tentang format id tersebut.
Name
type
Type
string
Description
Jenis tugas penjanaan imej. Untuk tugas Imej ke Imej, nilai ini sentiasa image-to-image.
Name
ai_model
Type
string
Description
Model AI yang digunakan untuk tugas ini. Nilai yang mungkin ialah nano-banana, nano-banana-2, nano-banana-2-lite, 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 memandu transformasi imej.
Name
status
Type
string
Description
Status tugas tersebut. Nilai yang mungkin ialah salah satu daripada PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Progress tugas tersebut. Jika tugas belum bermula lagi, sifat ini akan bernilai 0. Sebaik sahaja tugas berjaya, ia akan menjadi 100.
Name
created_at
Type
timestamp
Description
Cap masa bila tugas tersebut 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 tugas tersebut dimulakan, dalam milisaat. Jika tugas belum bermula lagi, sifat ini akan bernilai 0.
Name
finished_at
Type
timestamp
Description
Cap masa bila tugas tersebut selesai, dalam milisaat. Jika tugas belum selesai lagi, sifat ini akan bernilai 0.
Name
expires_at
Type
timestamp
Description
Cap masa bila hasil tugas tersebut akan luput, dalam milisaat.
Name
preceding_tasks
Type
integer
Description
Bilangan tugas terdahulu.
Nilai medan ini hanya bermakna jika status tugas ialah 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 berbeza. Jika tidak, ia mengandungi satu URL imej sahaja.
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 ialah PENDING, IN_PROGRESS, atau SUCCEEDED. Mengembalikan 0 untuk tugas FAILED (kredit dikembalikan 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
}