API Gambar ke Gambar

Edit dan ubah gambar dalam aplikasi Anda sendiri. Kirim gambar referensi dan prompt teks, dan model AI Meshy akan menghasilkan gambar baru darinya.

Gambar ke Gambar menghasilkan gambar. Untuk membuat model 3D dari apa yang ada dalam gambar, gunakan Gambar ke 3D. Untuk membuat objek yang bisa Anda pegang atau cetak dari sebuah foto, gunakan API Creative Lab. API ini membuat gambar prototipe lalu membangun model 3D darinya, misalnya gantungan kunci, magnet kulkas, figur, lampu, atau keycap.

POST/openapi/v1/image-to-image

Buat tugas Image to Image

Membuat tugas Image to Image. Tugas berjalan di latar belakang. Untuk informasi tentang berapa lama tugas biasanya berlangsung, lihat Processing times.

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
Wajib
Description
Model AI yang menghasilkan gambar. Harga berbeda-beda tergantung model. Lihat Harga.
Nilai yang tersedia:
- nano-banana: model standar
- nano-banana-2: lebih mumpuni dibanding nano-banana
- nano-banana-2-lite: versi lite dari nano-banana-2
- nano-banana-2-1: Nano Banana 2.1
- nano-banana-pro: model Pro, dengan kualitas lebih tinggi. Memerlukan paket Pro atau lebih tinggi. Pada paket yang lebih rendah, akan 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
Wajib
Description
Teks yang menjelaskan editan atau transformasi yang diterapkan pada gambar referensi.

Name
input_task_id
Type
string
Wajib
Description
Wajib diisi kecuali Anda mengirim reference_image_urls. ID dari tugas Text to Image atau Image to Image yang gambarnya akan digunakan sebagai referensi, termasuk tugas multi-tampilan. Tugas tersebut harus tugas yang Anda buat dengan API dan memiliki status SUCCEEDED.
Meshy menggunakan setiap gambar yang dihasilkan oleh tugas tersebut. Tugas gambar tunggal menghasilkan satu gambar referensi, dan tugas multi-tampilan menghasilkan satu per sudut pandang. Jadi satu ID tugas dapat mengisi beberapa dari lima slot referensi.
Tugas tersebut harus masih berada dalam periode retensi aset. Setelah masa berlakunya habis, ID-nya akan mengembalikan 404.

Name
reference_image_urls
Type
array
Wajib
Description
Wajib diisi kecuali Anda mengirim input_task_id. Satu hingga lima gambar referensi untuk diedit, masing-masing berupa URL publik atau Data URI, misalnya data:image/jpeg;base64,<data gambar berenkode base64 Anda>. Array kosong, atau lebih dari lima gambar, akan mengembalikan 400. Jika Anda mengirim keduanya, Meshy menggunakan input_task_id.
Setiap gambar harus berupa file .jpg, .jpeg, .png, atau .webp dengan ukuran maksimal 20 MB, dan minimal 32 piksel pada setiap sisinya.

Name
generate_multi_view
Type
boolean
default false
Description
Apakah akan menghasilkan gambar multi-tampilan yang menunjukkan subjek dari beberapa sudut. Jika true, Anda tidak dapat mengirim aspect_ratio. Mengirim keduanya akan mengembalikan 400.
Name
aspect_ratio
Type
string
default 1:1
Description
Rasio aspek gambar keluaran. Nilai yang dapat Anda kirim tergantung pada ai_model.
Nilai yang tersedia:
- 1:1: persegi
- 16:9: lanskap layar lebar
- 9:16: potret layar lebar
- 4:3: lanskap standar
- 3:4: potret standar
- 3:2: lanskap, hanya untuk model GPT Image
- 2:3: potret, hanya untuk 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 akan mengembalikan 400.
Name
remove_background
Type
boolean
default false
Description
Apakah akan menghapus latar belakang. Jika true, Meshy mengembalikan gambar keluaran sebagai PNG RGBA transparan, sehingga Anda dapat menempatkan subjek pada latar belakang apa pun.

Hasil

Kolom result pada respons memuat ID dari tugas Image to Image yang baru.

Mode kegagalan

Name
400 - Bad Request
Description
Permintaan tidak dapat dijalankan. Pesan kesalahan menyebutkan masalah apa yang ditemukan. Contohnya:
- Parameter hilang: Parameter wajib, seperti ai_model atau prompt, tidak ada, atau baik reference_image_urls maupun input_task_id tidak dikirim.
- Tugas input tidak valid: input_task_id tidak mengarah ke tugas yang dapat digunakan. Tugas tersebut harus berupa tugas Text to Image atau Image to Image dengan status SUCCEEDED, termasuk multi-tampilan, yang masih memiliki keluaran gambar. Meshy menolak tugas dari tipe lain, tugas yang belum berhasil, dan tugas yang semua gambarnya sudah kedaluwarsa.
- Format gambar tidak valid: Satu atau beberapa gambar referensi tidak dalam format yang didukung.
- URL tidak dapat dijangkau: Meshy tidak dapat mengunduh satu atau beberapa gambar reference_image_urls.
- Gambar terlalu besar: Satu atau beberapa gambar reference_image_urls berukuran lebih dari 20 MB.
- Gambar terlalu kecil: Satu atau beberapa gambar reference_image_urls memiliki sisi lebih pendek dari 32 piksel.
- Parameter tidak valid: aspect_ratio bukan salah satu nilai yang didukung oleh ai_model yang dipilih.
- Konflik: Permintaan mengirim aspect_ratio bersama generate_multi_view: true.
Perbaiki permintaan, lalu kirim ulang. Lihat Kesalahan.
Name
401 - Unauthorized
Description
Kunci API hilang atau tidak valid. Periksa header Authorization.
Name
402 - Payment Required
Description
Akun tidak dapat menjalankan tugas ini. Contohnya:
- Paket gratis: Membuat tugas memerlukan paket berbayar. Tingkatkan paket Anda di pengaturan langganan Anda, lalu coba lagi.
- Kredit tidak cukup: Akun tidak memiliki cukup kredit untuk tugas ini, atau akun telah mencapai batas kredit.
- Paket diperlukan: Permintaan menggunakan nano-banana-pro pada paket di bawah Pro.
Periksa saldo kredit dan paket Anda, lalu coba lagi.
Name
404 - Not Found
Description
input_task_id tidak cocok dengan tugas mana pun di akun Anda. Tugas yang tidak ada dan tugas yang dimiliki akun lain mengembalikan respons yang sama. Periksa ID-nya.
Name
429 - Too Many Requests
Description
Anda melebihi batas laju Anda. Tunggu, lalu coba lagi. Lihat Batas laju.

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

Dapatkan tugas Gambar ke Gambar

Mengembalikan tugas Gambar ke Gambar berdasarkan 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 dari respons pembuatan.

Returns

Objek tugas Gambar ke Gambar.

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

Hapus tugas Gambar ke Gambar

Menghapus tugas Gambar ke Gambar secara permanen, termasuk gambar dan datanya. Anda tidak dapat membatalkan penghapusan 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 path

Name
id
Type
path
Description
ID tugas yang akan dihapus.

Status tugas

Menghapus tugas PENDING akan mengembalikan kredit yang digunakan saat Anda membuatnya.

Tugas IN_PROGRESS tidak dapat dihapus. Permintaan akan mengembalikan 409 Conflict, dan tugas tersebut akan terus berjalan. Meshy tidak mengembalikan kredit untuk tugas yang sudah dimulai, jadi menghapusnya akan membuat Anda kehilangan kredit sekaligus hasilnya. Tunggu hingga tugas tersebut mencapai status SUCCEEDED, FAILED, atau CANCELED, lalu hapus.

Menghapus tugas dengan status akhir (SUCCEEDED, FAILED, atau CANCELED) tidak akan mengembalikan kreditnya.

Pengembalian

200 OK ketika tugas berhasil dihapus, atau 409 Conflict ketika tugas sedang IN_PROGRESS.

GET/openapi/v1/image-to-image

Daftar tugas Image to Image

Mengembalikan daftar tugas Image to Image dan Text to Image Anda. Field type pada setiap tugas menunjukkan termasuk yang mana dari keduanya.

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
Nomor halaman yang akan dikembalikan. Dimulai dari dan default-nya 1.
Name
page_size
Type
integer
Description
Jumlah tugas per halaman, hingga 100. Default-nya 10.
Name
sort_by
Type
string
Description
Urutan pengurutan.
Nilai yang tersedia:
- +created_at: terlama lebih dulu
- -created_at: terbaru lebih dulu

Returns

Daftar objek tugas yang dipaginasi, dalam format yang sama dengan objek tugas Image to Image.

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

Stream Tugas Image to Image

Melakukan streaming pembaruan tugas Gambar ke Gambar 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 dari respons pembuatan (create).

Returns

Sebuah stream dari objek tugas Gambar ke Gambar sebagai Server-Sent Events.

Setiap event menyimpan objek tugas secara lengkap, dalam bentuk yang sama seperti yang dikembalikan oleh endpoint Get. Selama tugas berstatus PENDING atau IN_PROGRESS, field hasilnya belum memiliki nilai.

Objek tugas Image to Image

Objek tugas Image to Image menggambarkan satu gambar yang dihasilkan dari gambar referensi dan sebuah prompt teks. Objek ini menyimpan status, progress, dan gambar saat tugas berhasil.

Properti

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. Perlakukan sebagai string opaque, dan jangan bergantung pada formatnya.
Name
type
Type
string
Description
Tipe tugas, selalu image-to-image.
Name
ai_model
Type
string
Description
Model AI yang digunakan oleh tugas.
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 proses edit.
Name
status
Type
string
Description
Status tugas, salah satu dari PENDING, IN_PROGRESS, SUCCEEDED, FAILED, atau CANCELED.
Name
progress
Type
integer
Description
Seberapa banyak bagian tugas yang telah selesai, dalam persentase. Nilainya 0 sampai tugas dimulai dan 100 saat tugas berhasil.
Name
created_at
Type
timestamp
Description
Waktu tugas dibuat, dalam milidetik Unix.
Name
started_at
Type
timestamp
Description
Waktu tugas dimulai, dalam milidetik Unix. Tidak ada sampai tugas dimulai.
Name
finished_at
Type
timestamp
Description
Waktu tugas selesai, dalam milidetik Unix. Tidak ada sampai tugas selesai.
Name
expires_at
Type
timestamp
Description
Waktu hasil tugas kedaluwarsa, dalam milidetik Unix. Tidak ada sampai tugas selesai.
Name
preceding_tasks
Type
integer
Description
Jumlah tugas yang berada di depan tugas ini dalam antrean. Nilai ini hanya berarti selama tugas berstatus PENDING. Bidang ini tidak disertakan saat nilainya 0.
Name
image_urls
Type
array
Description
URL unduhan untuk gambar yang dihasilkan. Dengan generate_multi_view: true, properti ini menyimpan satu URL per sudut pandang, biasanya tiga. Jika Meshy tidak dapat memisahkan setiap sudut pandang, properti ini mengembalikan lebih sedikit URL, dan tugas tetap berhasil. Selain itu, properti ini menyimpan satu URL.
Name
task_error
Type
object
Description
Detail kesalahan saat tugas gagal. Nilainya null kecuali statusnya FAILED. Lihat Kesalahan.
Name
consumed_credits
Type
integer
Description
Jumlah kredit yang digunakan oleh tugas. Tersedia saat statusnya PENDING, IN_PROGRESS, atau SUCCEEDED. Nilainya 0 untuk tugas FAILED, karena Meshy mengembalikan kredit saat tugas gagal.