API Gambar ke Gambar

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

POST/openapi/v1/image-to-image

Buat Tugas Gambar ke Gambar

endpoint ini memungkinkan Anda membuat tugas Gambar ke Gambar baru. Lihat Objek Tugas Gambar ke Gambar untuk melihat properti apa saja yang disertakan dalam objek tugas Gambar ke Gambar.

Parameter

  • Name
    ai_model
    Type
    string
    Wajib
    Description

    ID model yang digunakan untuk pembuatan gambar.

    Nilai yang tersedia:

    • nano-banana: Model standar (3 kredit per gambar)
    • nano-banana-2: Model seimbang dengan kemampuan yang lebih kuat daripada 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 tentang transformasi atau edit yang ingin Anda terapkan pada gambar referensi.

  • Name
    reference_image_urls
    Type
    array
    Wajib
    Description

    Array berisi 1 hingga 5 gambar referensi untuk digunakan dalam tugas pengeditan gambar. Saat ini kami 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 gambar yang dikodekan base64. 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 menampilkan subjek dari beberapa sudut.

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 beberapa gambar referensi bukan format yang didukung.
    • URL tidak dapat dijangkau: Satu atau beberapa reference_image_urls tidak dapat diunduh.
  • Name
    401 - Unauthorized
    Description

    autentikasi gagal. Harap periksa kunci API Anda.

  • Name
    402 - Payment Required
    Description

    kredit tidak mencukupi untuk menjalankan tugas ini.

  • 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}"
    ]
  }'

Response

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}
GET/openapi/v1/image-to-image/:id

Ambil Tugas Gambar ke Gambar

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

Parameter

  • Name
    id
    Type
    path
    Description

    Pengidentifikasi unik untuk tugas Gambar ke Gambar yang akan diambil.

Pengembalian

Respons berisi objek tugas Gambar ke Gambar. Periksa bagian Objek Tugas Gambar ke Gambar untuk detail.

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

Hapus Tugas Gambar ke Gambar

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

Parameter Path

  • Name
    id
    Type
    path
    Description

    ID tugas Gambar ke Gambar yang akan dihapus.

Pengembalian

Mengembalikan 200 OK saat berhasil.

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

// Returns 200 Ok on success.
GET/openapi/v1/image-to-image

Daftar Tugas Gambar ke Gambar

Endpoint ini memungkinkan Anda 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 mengurutkan. Nilai yang tersedia:

    • +created_at: Urutkan berdasarkan waktu pembuatan dalam urutan menaik.
    • -created_at: Urutkan berdasarkan waktu pembuatan dalam urutan menurun.

Mengembalikan

Mengembalikan daftar terpaginasi dari Objek Tugas Gambar ke Gambar.

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

    Pengidentifikasi unik untuk tugas Gambar ke Gambar yang akan dialirkan.

Mengembalikan

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

Untuk tugas PENDING atau IN_PROGRESS, stream respons hanya akan menyertakan bidang 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 Gambar ke Gambar

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

Properti

  • Name
    id
    Type
    string
    Description

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

  • Name
    type
    Type
    string
    Description

    Jenis tugas pembuatan gambar. Untuk tugas Gambar ke Gambar, ini akan selalu berupa image-to-image.

  • Name
    ai_model
    Type
    string
    Description

    Model AI yang digunakan untuk tugas ini. Nilai yang memungkinkan adalah nano-banana, nano-banana-2, nano-banana-pro, atau gpt-image-2.

  • Name
    prompt
    Type
    string
    Description

    Prompt teks yang digunakan untuk memandu transformasi gambar.

  • Name
    status
    Type
    string
    Description

    Status tugas. Nilai yang memungkinkan adalah salah satu dari PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

  • Name
    progress
    Type
    integer
    Description

    Progress tugas. Jika tugas belum dimulai, properti ini akan bernilai 0. Setelah tugas berhasil, ini akan menjadi 100.

  • Name
    created_at
    Type
    timestamp
    Description

    Stempel waktu saat tugas dibuat, dalam milidetik.

    Stempel waktu merepresentasikan jumlah milidetik yang berlalu sejak 1 Januari 1970 UTC, mengikuti standar RFC 3339. Misalnya, Jumat, 1 September 2023 12:00:00 PM GMT direpresentasikan 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 bernilai 0.

  • Name
    finished_at
    Type
    timestamp
    Description

    Stempel waktu saat tugas selesai, dalam milidetik. Jika tugas belum selesai, properti ini akan bernilai 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 bidang ini hanya bermakna jika status tugas adalah PENDING.

  • Name
    image_urls
    Type
    array
    Description

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

  • Name
    task_error
    Type
    object
    Description

    Detail kesalahan untuk tugas yang gagal. Lihat Kesalahan untuk referensi objek task_error lengkap.

  • Name
    consumed_credits
    Type
    integer
    Description

    Jumlah kredit yang dikonsumsi oleh tugas ini. Tersedia ketika status tugas adalah PENDING, IN_PROGRESS, atau SUCCEEDED. Mengembalikan 0 untuk tugas FAILED (kredit dikembalikan saat 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
}