API Imej ke Imej

Sunting dan ubah imej dalam aplikasi anda sendiri. Hantar imej rujukan dan prompt teks, dan model AI Meshy akan menjana imej baharu daripadanya.

Imej ke Imej menghasilkan imej. Untuk menghasilkan model 3D daripada apa yang terdapat dalam imej, gunakan Imej ke 3D. Untuk menghasilkan objek yang boleh anda pegang atau cetak daripada foto, gunakan API Creative Lab. API ini menghasilkan imej prototaip dan kemudian membina model 3D daripadanya, contohnya rantai kunci, magnet peti sejuk, figura, lampu, atau keycap.

POST/openapi/v1/image-to-image

Create an Image to Image task

Mencipta tugas Imej ke Imej. Tugas berjalan di latar belakang. Untuk mengetahui tempoh biasa yang diperlukan oleh tugas, lihat Masa pemprosesan.

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

Parameter

Name
ai_model
Type
string
Diperlukan
Description
Model AI yang menjana imej. Harga berbeza mengikut model. Lihat Harga.
Nilai yang tersedia:
- nano-banana: model standard
- nano-banana-2: lebih berupaya daripada nano-banana
- nano-banana-2-lite: versi lite daripada nano-banana-2
- nano-banana-2-1: Nano Banana 2.1
- nano-banana-pro: model Pro, dengan kualiti lebih tinggi. Ia memerlukan pelan Pro atau lebih tinggi. Pada pelan yang lebih rendah, ia mengembalikan 402.
- gpt-image-2: OpenAI GPT Image 2
- gpt-image-2-5-flare: OpenAI GPT Image 2.5 (Flare)
- gpt-image-2-5-sunburst: OpenAI GPT Image 2.5 (Sunburst)
Name
prompt
Type
string
Diperlukan
Description
Teks yang menerangkan penyuntingan atau transformasi yang perlu digunakan pada imej rujukan.

Name
input_task_id
Type
string
Diperlukan
Description
Diperlukan kecuali anda menghantar reference_image_urls. ID tugas Teks ke Imej atau Imej ke Imej yang imejnya digunakan sebagai rujukan, termasuk tugas berbilang pandangan. Tugas tersebut mestilah tugas yang anda cipta menggunakan API dan mempunyai status SUCCEEDED.
Meshy menggunakan setiap imej yang dihasilkan oleh tugas tersebut. Tugas imej tunggal memberikan satu imej rujukan, dan tugas berbilang pandangan memberikan satu bagi setiap pandangan. Jadi satu ID tugas boleh mengisi beberapa daripada lima slot rujukan.
Tugas tersebut mestilah masih berada dalam tempoh pengekalan aset. Selepas tamat tempoh, ID-nya mengembalikan 404.

Name
reference_image_urls
Type
array
Diperlukan
Description
Diperlukan kecuali anda menghantar input_task_id. Satu hingga lima imej rujukan untuk disunting, setiap satu URL awam atau Data URI, contohnya data:image/jpeg;base64,<your base64-encoded image data>. Tatasusunan kosong, atau lebih daripada lima imej, mengembalikan 400. Jika anda menghantar kedua-duanya, Meshy menggunakan input_task_id.
Setiap imej mestilah fail .jpg, .jpeg, .png, atau .webp dengan saiz maksimum 20 MB, dan sekurang-kurangnya 32 piksel pada setiap sisi.

Name
generate_multi_view
Type
boolean
lalai false
Description
Sama ada untuk menjana imej berbilang pandangan yang menunjukkan subjek dari beberapa sudut. Apabila true, anda tidak boleh menghantar aspect_ratio. Menghantar kedua-duanya mengembalikan 400.
Name
aspect_ratio
Type
string
lalai 1:1
Description
Nisbah aspek imej output. Nilai yang boleh anda hantar bergantung pada ai_model.
Nilai yang tersedia:
- 1:1: 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 model GPT Image
- 2:3: potret, hanya model GPT Image
Model GPT Image adalah gpt-image-2, gpt-image-2-5-flare, dan gpt-image-2-5-sunburst. Dengan model nano-banana, 3:2 dan 2:3 mengembalikan 400.
Name
remove_background
Type
boolean
lalai false
Description
Sama ada untuk membuang latar belakang. Apabila true, Meshy mengembalikan imej output sebagai PNG RGBA lutsinar, supaya anda boleh meletakkan subjek pada sebarang latar belakang.

Nilai pulangan

Medan result bagi respons menyimpan ID tugas Imej ke Imej yang baharu.

Mod kegagalan

Name
400 - Bad Request
Description
Permintaan tidak dapat dijalankan. Mesej ralat menyatakan masalah yang ditemui. Contohnya:
- Parameter hilang: Parameter yang diperlukan, seperti ai_model atau prompt, tiada, atau kedua-dua reference_image_urls dan input_task_id tidak dihantar.
- Tugas input tidak sah: input_task_id tidak menunjuk kepada tugas yang boleh digunakan. Ia mestilah tugas Teks ke Imej atau Imej ke Imej yang SUCCEEDED, termasuk berbilang pandangan, yang masih mempunyai output imej. Meshy menolak tugas jenis lain, tugas yang belum berjaya, dan tugas yang semua imejnya telah tamat tempoh.
- Format imej tidak sah: Satu atau lebih imej rujukan tidak dalam format yang disokong.
- URL tidak boleh dicapai: Meshy tidak dapat memuat turun satu atau lebih imej reference_image_urls.
- Imej terlalu besar: Satu atau lebih imej reference_image_urls melebihi 20 MB.
- Imej terlalu kecil: Satu atau lebih imej reference_image_urls mempunyai sisi yang lebih pendek daripada 32 piksel.
- Parameter tidak sah: aspect_ratio bukan salah satu nilai yang disokong oleh ai_model yang dipilih.
- Konflik: Permintaan menghantar aspect_ratio bersama generate_multi_view: true.
Betulkan permintaan, kemudian hantar semula. Lihat Ralat.
Name
401 - Unauthorized
Description
Kunci API tiada atau tidak sah. Semak pengepala Authorization.
Name
402 - Payment Required
Description
Akaun tidak dapat menjalankan tugas ini. Contohnya:
- Pelan percuma: Mencipta tugas memerlukan pelan berbayar. Naik taraf pelan anda dalam tetapan langganan anda, kemudian cuba semula.
- Kredit tidak mencukupi: Akaun tidak mempunyai kredit yang mencukupi untuk tugas ini, atau akaun telah mencapai had kredit.
- Pelan diperlukan: Permintaan menggunakan nano-banana-pro pada pelan di bawah Pro.
Semak baki kredit dan pelan anda, kemudian cuba semula.
Name
404 - Not Found
Description
input_task_id tidak sepadan dengan mana-mana tugas dalam akaun anda. Tugas yang tidak wujud dan tugas yang kepunyaan akaun lain mengembalikan respons yang sama. Semak ID tersebut.
Name
429 - Too Many Requests
Description
Anda telah melebihi had kadar anda. Tunggu, kemudian cuba semula. Lihat Had kadar.

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

Dapatkan tugas Imej ke Imej

Mengembalikan tugas Imej ke Imej mengikut ID-nya.

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=***"
  ]
}

Parameter

Name
id
Type
path
Description
ID tugas daripada respons penciptaan.

Hasil Kembali

Objek tugas Imej ke Imej.

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

Padam tugas Imej ke Imej

Memadam secara kekal tugas Imej ke Imej, termasuk imej dan datanya. Anda tidak boleh membatalkan tindakan padam ini.

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

Parameter laluan

Name
id
Type
path
Description
ID tugas yang hendak dipadam.

Status tugas

Memadam tugas PENDING akan memulangkan kredit yang digunakan semasa anda mencipta tugas tersebut.

Tugas IN_PROGRESS tidak boleh dipadam. Permintaan akan mengembalikan 409 Conflict, dan tugas tersebut akan terus berjalan. Meshy tidak memulangkan kredit bagi tugas yang telah bermula, jadi memadamnya akan menyebabkan anda rugi kredit dan juga hasilnya. Tunggu sehingga ia mencapai status SUCCEEDED, FAILED, atau CANCELED, kemudian padamkannya.

Memadam tugas yang berada dalam status akhir (SUCCEEDED, FAILED, atau CANCELED) tidak akan memulangkan kreditnya.

Pulangan

200 OK apabila tugas berjaya dipadam, atau 409 Conflict apabila tugas berstatus IN_PROGRESS.

GET/openapi/v1/image-to-image

Senaraikan tugas Imej ke Imej

Mengembalikan senarai tugas Imej ke Imej dan Teks ke Imej anda. Medan type setiap tugas menunjukkan yang mana satu antara kedua-duanya.

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=***"
    ]
  }
]

Parameter

Name
page_num
Type
integer
Description
Nombor halaman yang hendak dikembalikan. Bermula pada dan lalai kepada 1.
Name
page_size
Type
integer
Description
Bilangan tugas setiap halaman, sehingga 100. Lalai kepada 10.
Name
sort_by
Type
string
Description
Susunan isihan.
Nilai yang tersedia:
- +created_at: paling lama dahulu
- -created_at: paling baharu dahulu

Returns

Senarai bernombor halaman bagi objek tugas, dalam format yang sama seperti objek tugas Imej ke Imej.

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

Alir tugas Imej ke Imej

Mengalirkan kemas kini tugas Imej ke Imej sebagai Server-Sent Events (SSE).

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.
// These examples are shortened. Each event holds the full task object.
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=***"
  ]
}

Parameter

Name
id
Type
path
Description
ID tugas daripada respons penciptaan.

Nilai Pulangan

Satu aliran objek tugas Imej ke Imej sebagai Server-Sent Events.

Setiap peristiwa (event) memegang objek tugas yang lengkap, dalam bentuk yang sama seperti yang dikembalikan oleh endpoint Get. Semasa tugas itu PENDING atau IN_PROGRESS, medan hasilnya belum lagi mempunyai nilai.

Objek tugas Imej ke Imej

Objek tugas Imej ke Imej menerangkan satu imej yang dijana daripada imej rujukan dan prompt teks. Ia menyimpan status, progress, dan imej apabila tugas berjaya.

Ciri-ciri

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,
  "image_urls": [
    "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/image.png?Expires=***"
  ],
  "task_error": null,

  "consumed_credits": 3
}

Name
id
Type
string
Description
ID tugas. Anggap ia sebagai rentetan legap, dan jangan bergantung pada formatnya.
Name
type
Type
string
Description
Jenis tugas, sentiasa image-to-image.
Name
ai_model
Type
string
Description
Model AI yang digunakan oleh tugas tersebut.
Nilai yang tersedia:
- nano-banana
- nano-banana-2
- nano-banana-2-lite
- nano-banana-2-1
- nano-banana-pro
- gpt-image-2
- gpt-image-2-5-flare
- gpt-image-2-5-sunburst
Name
prompt
Type
string
Description
Prompt teks yang memandu penyuntingan.
Name
status
Type
string
Description
Status tugas, salah satu daripada PENDING, IN_PROGRESS, SUCCEEDED, FAILED, atau CANCELED.
Name
progress
Type
integer
Description
Sejauh mana tugas telah selesai, dalam peratusan. Ia adalah 0 sehingga tugas bermula dan 100 apabila ia berjaya.
Name
created_at
Type
timestamp
Description
Masa tugas dicipta, dalam milisaat Unix.
Name
started_at
Type
timestamp
Description
Masa tugas bermula, dalam milisaat Unix. Tiada sehingga tugas bermula.
Name
finished_at
Type
timestamp
Description
Masa tugas selesai, dalam milisaat Unix. Tiada sehingga tugas selesai.
Name
expires_at
Type
timestamp
Description
Masa hasil tugas tamat tempoh, dalam milisaat Unix. Tiada sehingga tugas selesai.
Name
preceding_tasks
Type
integer
Description
Bilangan tugas yang mendahului tugas ini dalam baris gilir. Nilai ini hanya bermakna semasa tugas berstatus PENDING. Medan ini ditinggalkan apabila nilainya 0.
Name
image_urls
Type
array
Description
URL muat turun untuk imej yang dijana. Dengan generate_multi_view: true, ia menyimpan satu URL bagi setiap pandangan, biasanya tiga. Jika Meshy tidak dapat memisahkan setiap pandangan, ia mengembalikan lebih sedikit, dan tugas tetap berjaya. Jika tidak, ia menyimpan satu URL.
Name
task_error
Type
object
Description
Butiran ralat apabila tugas gagal. Ia adalah null kecuali status adalah FAILED. Lihat Ralat.
Name
consumed_credits
Type
integer
Description
Bilangan kredit yang digunakan oleh tugas. Hadir apabila status adalah PENDING, IN_PROGRESS, atau SUCCEEDED. Ia adalah 0 untuk tugas FAILED, kerana Meshy memulangkan kredit apabila tugas gagal.