API Gambar ke Gambar

API Gambar ke Gambar adalah fitur yang memungkinkan Anda untuk mengintegrasikan kemampuan pengeditan gambar AI dari Meshy ke dalam aplikasi Anda sendiri. Transformasi dan edit gambar yang ada menggunakan gambar referensi dan petunjuk teks dengan model AI kami yang kuat.

POST/openapi/v1/image-to-image

Membuat Tugas Gambar ke Gambar

Endpoint ini memungkinkan Anda untuk membuat tugas Gambar ke Gambar baru. Lihat Objek Tugas Gambar ke Gambar untuk melihat properti yang disertakan dengan objek tugas Gambar ke Gambar.

Parameter

Name
ai_model
Type
string
Wajib
Description
ID model yang akan digunakan untuk pembuatan gambar.
Nilai yang tersedia:
- nano-banana: Model standar (3 kredit per gambar)
- nano-banana-2: Model seimbang dengan kemampuan lebih kuat dari standar (6 kredit per gambar)
- nano-banana-pro: Model pro dengan kualitas yang ditingkatkan (9 kredit per gambar)
- gpt-image-2: OpenAI GPT Image 2, model edit gambar dengan fidelitas tinggi (12 kredit per gambar)
Name
prompt
Type
string
Wajib
Description
Deskripsi teks dari transformasi atau edit yang ingin Anda terapkan pada gambar referensi.
Name
reference_image_urls
Type
array
Wajib
Description
Array dari 1 hingga 5 gambar referensi yang akan digunakan untuk tugas pengeditan gambar. Kami saat ini mendukung format .jpg, .jpeg, dan .png.
Ada dua cara untuk menyediakan setiap gambar:
- URL yang dapat diakses publik: URL yang dapat diakses dari internet publik.
- Data URI: Data URI yang dikodekan base64 dari gambar. Contoh Data URI: data:image/jpeg;base64,<your base64-encoded image data>.
Name
generate_multi_view
Type
boolean
default false
Description
Ketika diatur ke true, menghasilkan gambar multi-tampilan yang menunjukkan subjek dari berbagai sudut.
Ketika generate_multi_view adalah true, parameter aspect_ratio tidak dapat diatur.
Name
aspect_ratio
Type
string
default 1:1
Description
Tentukan rasio aspek dari gambar keluaran. Nilai yang diizinkan tergantung 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 persegi
- 16:9: Lanskap layar lebar
- 9:16: Potret layar lebar
- 4:3: Lanskap standar (tidak didukung oleh gpt-image-2)
- 3:4: Potret standar (tidak didukung oleh gpt-image-2)
- 3:2: Lanskap (hanya didukung oleh gpt-image-2)
- 2:3: Potret (hanya didukung oleh gpt-image-2)
Name
remove_background
Type
boolean
default false
Description
Ketika diatur ke true, gambar keluaran dikembalikan sebagai PNG RGBA transparan dengan latar belakang dihapus, sehingga Anda dapat menggabungkan subjek ke latar belakang mana pun.

Mengembalikan

Properti result dari respons berisi id tugas dari tugas Gambar ke Gambar yang baru dibuat.

Mode Kegagalan

Name
400 - Bad Request
Description
Permintaan tidak dapat diterima. Penyebab umum:
- Parameter hilang: Parameter yang diperlukan (misalnya, ai_model, prompt, reference_image_urls) hilang.
- Format gambar tidak valid: Satu atau lebih gambar referensi bukan format yang didukung.
- URL tidak dapat dijangkau: Satu atau lebih reference_image_urls tidak dapat diunduh.
- Parameter tidak valid: aspect_ratio bukan salah satu nilai yang diizinkan untuk ai_model yang dipilih.
- Konflik: generate_multi_view dan aspect_ratio tidak dapat digunakan secara bersamaan.
Name
401 - Unauthorized
Description
Autentikasi gagal. Silakan periksa kunci API Anda.
Name
402 - Payment Required
Description
Kredit tidak mencukupi untuk melakukan tugas ini.
Name
429 - Too Many Requests
Description
Anda telah melebihi batas laju 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

Mengambil Tugas Gambar ke Gambar

Endpoint ini memungkinkan Anda untuk mengambil tugas Gambar ke Gambar dengan memberikan id tugas yang valid. Lihat Objek Tugas Gambar ke Gambar untuk melihat properti mana yang disertakan dengan objek tugas Gambar ke Gambar.

Parameter

Name
id
Type
path
Description
Pengenal unik untuk tugas Gambar ke Gambar yang akan diambil.

Mengembalikan

Respon berisi objek tugas Gambar ke Gambar. Periksa bagian Objek Tugas Gambar ke Gambar untuk detailnya.

Permintaan

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

Respon

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

Menghapus Tugas Gambar ke Gambar

Endpoint ini secara permanen menghapus tugas Gambar ke Gambar, termasuk semua gambar dan data terkait. Tindakan ini tidak dapat dibatalkan.

Parameter Jalur

Name
id
Type
path
Description
ID dari tugas Gambar ke Gambar yang akan dihapus.

Mengembalikan

Mengembalikan 200 OK jika berhasil.

Permintaan

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

Respon

// Returns 200 Ok on success.

GET/openapi/v1/image-to-image

Daftar Tugas Gambar ke Gambar

Endpoint ini memungkinkan Anda untuk mengambil daftar tugas Gambar ke Gambar.

Parameter

Name
page_num
Type
integer
Description
Nomor halaman untuk paginasi. Dimulai dan default ke 1.
Name
page_size
Type
integer
Description
Batas ukuran halaman. Default ke 10 item. Maksimum yang diizinkan adalah 50 item.
Name
sort_by
Type
string
Description
Bidang untuk diurutkan. Nilai yang tersedia:
- +created_at: Urutkan berdasarkan waktu pembuatan dalam urutan naik.
- -created_at: Urutkan berdasarkan waktu pembuatan dalam urutan turun.

Mengembalikan

Mengembalikan daftar dengan paginasi dari Objek Tugas Gambar ke Gambar.

Permintaan

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

Respon

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

Streaming Tugas Gambar ke Gambar

Endpoint ini mengalirkan pembaruan real-time untuk tugas Gambar ke Gambar menggunakan Server-Sent Events (SSE).

Parameter

Name
id
Type
path
Description
Pengenal unik untuk tugas Gambar ke Gambar yang akan di-stream.

Mengembalikan

Mengembalikan aliran Objek Tugas Gambar ke Gambar sebagai Server-Sent Events.

Untuk tugas PENDING atau IN_PROGRESS, aliran respons hanya akan menyertakan bidang progress dan status yang diperlukan.

Permintaan

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

Aliran Respons

// 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 Gambar ke Gambar

Objek Tugas Gambar ke Gambar adalah unit kerja yang dilacak oleh Meshy untuk menghasilkan gambar dari gambar referensi dan input teks prompt. Objek ini memiliki properti sebagai berikut:

Properti

Name
id
Type
string
Description
Pengidentifikasi unik untuk tugas. Meskipun kami menggunakan UUID yang dapat diurutkan secara k untuk id tugas sebagai detail implementasi, Anda tidak boleh membuat asumsi apa pun tentang format id tersebut.
Name
type
Type
string
Description
Jenis tugas pembuatan gambar. Untuk tugas Gambar ke Gambar, ini akan selalu menjadi image-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
Teks prompt yang digunakan untuk memandu transformasi gambar.
Name
status
Type
string
Description
Status dari tugas. Nilai yang mungkin adalah salah satu dari PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Progress dari tugas. Jika tugas belum dimulai, properti ini akan menjadi 0. Setelah tugas berhasil, ini akan menjadi 100.
Name
created_at
Type
timestamp
Description
Stempel waktu saat tugas dibuat, dalam milidetik.
Stempel waktu mewakili jumlah milidetik yang berlalu sejak 1 Januari 1970 UTC, mengikuti standar RFC 3339. Sebagai contoh, Jumat, 1 September 2023 12:00:00 PM GMT diwakili sebagai 1693569600000. Ini berlaku untuk semua stempel waktu di Meshy API.
Name
started_at
Type
timestamp
Description
Stempel waktu saat tugas dimulai, dalam milidetik. Jika tugas belum dimulai, properti ini akan menjadi 0.
Name
finished_at
Type
timestamp
Description
Stempel waktu saat tugas selesai, dalam milidetik. Jika tugas belum selesai, properti ini akan menjadi 0.
Name
expires_at
Type
timestamp
Description
Stempel waktu saat hasil tugas kedaluwarsa, dalam milidetik.
Name
preceding_tasks
Type
integer
Description
Jumlah tugas sebelumnya.
Nilai dari bidang ini hanya bermakna jika status tugas adalah PENDING.
Name
image_urls
Type
array
Description
Sebuah array dari URL yang dapat diunduh ke gambar yang dihasilkan. Ketika generate_multi_view diaktifkan, array ini berisi tiga URL gambar yang mewakili sudut pandang yang berbeda. Jika tidak, ini berisi satu URL gambar.
Name
task_error
Type
object
Description
Detail kesalahan untuk tugas yang gagal. Lihat Kesalahan untuk referensi lengkap objek task_error.
Name
consumed_credits
Type
integer
Description
Jumlah kredit yang dikonsumsi oleh tugas ini. Ada ketika status tugas adalah PENDING, IN_PROGRESS, atau SUCCEEDED. Mengembalikan 0 untuk tugas FAILED (kredit dikembalikan pada kegagalan).

Contoh Objek Tugas Gambar ke Gambar

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