API Gambar ke Gambar

API Gambar ke Gambar adalah fitur yang memungkinkan Anda mengintegrasikan kemampuan pengeditan gambar AI dari Meshy ke dalam aplikasi Anda sendiri. Transformasikan dan edit gambar yang sudah ada menggunakan gambar referensi dan prompt teks dengan model AI kami yang canggih.

POST/openapi/v1/image-to-image

Create an Image to Image Task

Endpoint ini memungkinkan Anda membuat task Image to Image baru. Lihat The Image to Image Task Object untuk melihat properti apa saja yang disertakan dalam objek task Image to Image.

Parameter

  • Name
    ai_model
    Type
    string
    Wajib
    Description

    ID model yang digunakan untuk menghasilkan gambar.

    Nilai yang tersedia:

    • nano-banana: Model standar (3 kredit per gambar)
    • nano-banana-2: Model seimbang dengan kemampuan lebih kuat dibandingkan model 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)
    • gpt-image-2-5-flare: OpenAI GPT Image 2.5 (Flare), model edit gambar dengan fidelitas tinggi (12 kredit per gambar)
    • gpt-image-2-5-sunburst: OpenAI GPT Image 2.5 (Sunburst), model edit gambar dengan fidelitas tinggi (12 kredit per gambar)
  • Name
    prompt
    Type
    string
    Wajib
    Description

    Deskripsi teks tentang transformasi atau edit yang ingin Anda terapkan pada gambar referensi.

Hanya salah satu dari input_task_id atau reference_image_urls yang wajib diisi. Jika keduanya disediakan, input_task_id memiliki prioritas.

  • Name
    input_task_id
    Type
    string
    Wajib
    Description

    ID dari task pembuatan gambar yang telah selesai, yang gambar keluarannya akan digunakan sebagai gambar referensi. Task ini harus berupa salah satu dari task berikut: Text to Image atau Image to Image, termasuk varian multi-tampilan-nya. Selain itu, task tersebut harus dijalankan melalui API dan memiliki status SUCCEEDED.

    Semua gambar keluaran dari task sumber akan digunakan. Task dengan gambar tunggal menyumbang 1 gambar referensi; task multi-tampilan menyumbang satu gambar per tampilan yang dihasilkan, sehingga satu ID task dapat mengisi beberapa dari 5 slot referensi.

    Task sumber harus masih berada dalam periode retensi aset — setelah masa berlakunya habis, ID-nya akan mengembalikan 404.

  • Name
    reference_image_urls
    Type
    array
    Wajib
    Description

    Array berisi 1 hingga 5 gambar referensi yang digunakan untuk task pengeditan gambar. Saat ini kami mendukung format .jpg, .jpeg, dan .png.

    Ada dua cara untuk menyediakan setiap gambar:

    • URL yang dapat diakses secara publik: URL yang dapat diakses dari internet publik.
    • Data URI: Data URI gambar yang dienkode base64. Contoh data URI: data:image/jpeg;base64,<data gambar Anda yang dienkode base64>.
  • Name
    generate_multi_view
    Type
    boolean
    default false
    Description

    Jika disetel ke true, menghasilkan gambar multi-tampilan yang menampilkan subjek dari berbagai sudut.

    Ketika generate_multi_view disetel ke true, parameter aspect_ratio tidak dapat digunakan.

  • Name
    aspect_ratio
    Type
    string
    default 1:1
    Description

    Menentukan rasio aspek gambar keluaran. Nilai yang diperbolehkan 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, 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 persegi
    • 16:9: Lanskap layar lebar
    • 9:16: Potret layar lebar
    • 4:3: Lanskap standar
    • 3:4: Potret standar
    • 3:2: Lanskap (hanya didukung oleh model GPT Image)
    • 2:3: Potret (hanya didukung oleh model GPT Image)
  • Name
    remove_background
    Type
    boolean
    default false
    Description

    Jika disetel ke true, gambar keluaran dikembalikan sebagai PNG RGBA transparan dengan latar belakang dihapus, sehingga Anda dapat menggabungkan subjek ke latar belakang apa pun.

Hasil yang Dikembalikan

Properti result pada respons berisi id task dari task Image to Image yang baru dibuat.

Mode Kegagalan

  • Name
    400 - Bad Request
    Description

    Permintaan tidak dapat diterima. Penyebab umum:

    • Parameter hilang: Parameter yang wajib diisi (misalnya, ai_model, prompt) hilang, atau baik reference_image_urls maupun input_task_id tidak disediakan.
    • Task input tidak valid: input_task_id harus merujuk pada task Text to Image atau Image to Image (termasuk multi-tampilan) yang berstatus SUCCEEDED dan masih memiliki keluaran gambar. Task dengan tipe lain, yang belum berhasil, atau yang semua gambarnya telah kedaluwarsa akan ditolak.
    • Format gambar tidak valid: Satu atau lebih gambar referensi memiliki format yang tidak didukung.
    • URL tidak dapat diakses: 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 menjalankan task ini.

  • Name
    404 - Not Found
    Description

    input_task_id tidak merujuk pada task yang dimiliki oleh akun Anda. Task yang tidak ada dan task yang dimiliki akun lain akan mengembalikan respons yang sama.

  • Name
    429 - Too Many Requests
    Description

    Anda telah melampaui 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}"
    ]
  }'


 ## 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

Mengambil Tugas Image to Image

Endpoint ini memungkinkan Anda mengambil tugas Gambar ke Gambar dengan id tugas yang valid. Lihat The Image to Image Task Object untuk melihat properti apa saja yang termasuk dalam objek tugas Gambar ke Gambar.

Parameter

  • Name
    id
    Type
    path
    Description

    Pengenal unik untuk tugas Gambar ke Gambar yang akan diambil.

Return

Respons berisi objek tugas Gambar ke Gambar. Periksa bagian The Image to Image Task Object untuk detailnya.

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

Menghapus Tugas Gambar ke Gambar

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

Parameter Path

  • Name
    id
    Type
    path
    Description

    ID dari tugas Gambar ke Gambar yang akan dihapus.

Status Tugas

Tugas yang masih berstatus PENDING akan dihapus dan kredit yang digunakan saat pembuatan akan dikembalikan.

Tugas yang sudah berstatus IN_PROGRESS tidak dapat dihapus: permintaan akan ditolak dengan 409 Conflict dan tugas tetap berjalan. Kredit untuk tugas yang sudah mulai dikerjakan oleh worker tidak dapat dikembalikan, sehingga menghapusnya di tengah proses akan membuat Anda kehilangan kredit sekaligus hasilnya. Tunggu hingga statusnya mencapai SUCCEEDED, FAILED, atau CANCELED, baru kemudian hapus.

Tugas dengan status akhir (SUCCEEDED, FAILED, atau CANCELED) akan dihapus tanpa pengembalian kredit.

Returns

Mengembalikan 200 OK jika berhasil, atau 409 Conflict jika tugas masih 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

List Image to Image Tasks

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

Parameter

  • Name
    page_num
    Type
    integer
    Description

    Nomor halaman untuk paginasi. Dimulai dan defaultnya adalah 1.

  • Name
    page_size
    Type
    integer
    Description

    Batas ukuran halaman. Defaultnya adalah 10 item. Maksimum yang diizinkan adalah 100 item.

  • Name
    sort_by
    Type
    string
    Description

    Kolom untuk pengurutan. Nilai yang tersedia:

    • +created_at: Urutkan berdasarkan waktu pembuatan secara ascending.
    • -created_at: Urutkan berdasarkan waktu pembuatan secara descending.

Returns

Mengembalikan daftar berpaginasi dari The Image to Image Task Objects.

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

Streaming Task Gambar ke Gambar

Endpoint ini melakukan streaming pembaruan secara real-time untuk task Gambar ke Gambar menggunakan Server-Sent Events (SSE).

Parameter

  • Name
    id
    Type
    path
    Description

    Pengidentifikasi unik untuk task Gambar ke Gambar yang akan di-streaming.

Return

Mengembalikan aliran (stream) dari The Image to Image Task Objects sebagai Server-Sent Events.

Untuk task dengan status PENDING atau IN_PROGRESS, aliran respons hanya akan menyertakan kolom 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=***"
  ]
}

The Image to Image Task Object

Objek Image to Image Task adalah unit kerja yang dilacak oleh Meshy untuk menghasilkan sebuah gambar dari gambar referensi dan input prompt teks. Objek ini memiliki properti berikut:

Properties

  • Name
    id
    Type
    string
    Description

    Pengidentifikasi unik untuk task. Meskipun kami menggunakan UUID yang dapat diurutkan secara k-sortable untuk id task sebagai detail implementasi, Anda tidak boleh membuat asumsi apa pun tentang format id tersebut.

  • Name
    type
    Type
    string
    Description

    Jenis task pembuatan gambar. Untuk task Image to Image, nilainya akan selalu image-to-image.

  • Name
    ai_model
    Type
    string
    Description

    Model AI yang digunakan untuk task ini. Nilai yang mungkin adalah nano-banana, nano-banana-2, 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 gambar.

  • Name
    status
    Type
    string
    Description

    Status task. Nilai yang mungkin adalah salah satu dari PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

  • Name
    progress
    Type
    integer
    Description

    Progress dari task. Jika task belum dimulai, properti ini akan bernilai 0. Setelah task berhasil, nilai ini akan menjadi 100.

  • Name
    created_at
    Type
    timestamp
    Description

    Stempel waktu saat task dibuat, dalam milidetik.

    Stempel waktu merepresentasikan jumlah milidetik yang berlalu sejak 1 Januari 1970 UTC, mengikuti standar RFC 3339. Sebagai contoh, Jumat, 1 September 2023 pukul 12:00:00 PM GMT direpresentasikan sebagai 1693569600000. Hal ini berlaku untuk semua stempel waktu di Meshy API.

  • Name
    started_at
    Type
    timestamp
    Description

    Stempel waktu saat task dimulai, dalam milidetik. Jika task belum dimulai, properti ini akan bernilai 0.

  • Name
    finished_at
    Type
    timestamp
    Description

    Stempel waktu saat task selesai, dalam milidetik. Jika task belum selesai, properti ini akan bernilai 0.

  • Name
    expires_at
    Type
    timestamp
    Description

    Stempel waktu saat hasil task kedaluwarsa, dalam milidetik.

  • Name
    preceding_tasks
    Type
    integer
    Description

    Jumlah task yang mendahului.

    Nilai kolom ini hanya bermakna jika status task adalah PENDING.

  • Name
    image_urls
    Type
    array
    Description

    Sebuah array berisi URL yang dapat diunduh untuk gambar yang dihasilkan. Ketika generate_multi_view diaktifkan, array ini berisi tiga URL gambar yang merepresentasikan sudut pandang yang berbeda. Jika tidak, array ini berisi satu URL gambar.

  • Name
    task_error
    Type
    object
    Description

    Detail kesalahan untuk task yang gagal. Lihat Errors untuk referensi lengkap objek task_error.

  • Name
    consumed_credits
    Type
    integer
    Description

    Jumlah kredit yang dikonsumsi oleh task ini. Muncul saat status task adalah PENDING, IN_PROGRESS, atau SUCCEEDED. Mengembalikan 0 untuk task FAILED (kredit dikembalikan jika terjadi kegagalan).

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
}