Gambar
Edit Gambar
Edit gambar berdasarkan prompt dan gambar sumber
Gambaran Umum
Membuat gambar yang diedit atau diperluas berdasarkan gambar asli dan prompt.
Endpoint ini mendukung keduanya:
- alur unggah
multipart/form-datayang kompatibel dengan OpenAI seperti yang didokumentasikan di bawah ini - permintaan JSON yang menyediakan
image_url,image_urls, atau referensiimagesresmi untuk famili image-to-image yang didukung
gpt-image-2 didukung di sini. Model ini menerima unggahan multipart image, JSON image_url / image_urls, dan referensi images[] resmi (image_url atau file_id), hingga 16 gambar sumber. Buat nilai file_id melalui /v1/files terlebih dahulu. Atur async: true untuk mengembalikan tugas terlebih dahulu; setiap model yang mencantumkan async di antara parameter yang didukungnya, seperti gpt-image-2 dan model edit FLUX, menggunakan alur polling tugas yang sama.
Pengeditan gpt-image-2 tidak menerima resolution; gunakan size untuk dimensi output. background menerima auto atau opaque; transparent tidak didukung. Untuk pengeditan multi-gambar atau berlatensi tinggi, disarankan menggunakan async: true dan melakukan polling pada tugas yang dikembalikan.
Permintaan gambar referensi Nano Banana (nano-banana-2, nano-banana-2.1, nano-banana-2-lite, dan nano-banana-pro) diekspos pada /v1/images/generations dengan operation: "image-to-image" dan image_urls, bukan pada endpoint /v1/images/edits ini. Permintaan edit gambar untuk nano-banana-2, nano-banana-2.1, nano-banana-2-lite, dan nano-banana-pro juga menggunakan /v1/images/generations, dengan operation: "image-edit".
gemini-3.1-flash-image, gemini-nano-banana-2.1, gemini-3.1-flash-lite-image, dan gemini-3-pro-image menggunakan endpoint ini untuk image-edit. Permintaan image-to-image mereka menggunakan /v1/images/generations dengan operation: "image-to-image".
Model edit gambar xAI Grok Imagine menerima jumlah gambar sumber yang terbatas: grok-imagine-image-2.0 menerima maksimal 5, dan grok-imagine-image menerima maksimal 3. Permintaan dengan gambar sumber lebih banyak dari yang diterima model akan gagal pada validasi input dengan 400 too_many_images. Permintaan image-to-image mereka juga menggunakan endpoint ini.
Detail masing-masing model (GET /v1/models/{model}, lihat Dapatkan Model) menyediakan endpoint untuk setiap operasi dalam tokenlab.request_format_summary.request_endpoint_by_operation, serta bidang dan batasan yang diterima dalam tokenlab.request_format_details.operation_constraints. Operasi yang dikirim ke endpoint yang salah akan mengembalikan 400 unsupported_endpoint.
input_fidelity bukan bagian dari bidang yang saat ini didukung TokenLab untuk gpt-image-2; hilangkan parameter ini atau permintaan akan mengembalikan 400 unsupported_parameter.
Body Permintaan
Batas waktu permintaan sinkron: Beberapa permintaan gambar mengembalikan gambar akhir secara inline dan menunggu hingga pembuatan selesai. Permintaan resolusi tinggi atau kualitas tinggi dapat memakan waktu hampir satu menit atau lebih lama, jadi atur batas waktu klien HTTP Anda setidaknya 120s. Jika respons pembuatan menyertakan status: "pending", task_id, atau poll_url, lakukan polling pada GET /v1/tasks/{task_id} sebagai gantinya.
URL gambar jarak jauh: saat input multipart diperlukan, TokenLab mengambil JSON image_url, image_urls, atau images[].image_url dan mengirimkan byte tersebut sebagai bagian multipart image. URL harus berupa http/https publik, tanpa kredensial atau fragmen yang disematkan, dan tidak boleh mengarah ke localhost, rentang IP privat, atau yang dicadangkan; setiap pengalihan diperiksa kembali. Payload yang diambil harus berupa gambar PNG, JPEG, atau WebP asli. Batasannya adalah 50 MiB per gambar, total 200 MiB untuk gambar yang diambil melalui URL dalam satu permintaan, batas waktu pengambilan 30s, dan hingga 3 pengalihan.
Untuk permintaan JSON, berikan tepat satu dari image_url, image_urls, atau images. Setiap objek images[] harus berisi tepat satu dari image_url atau file_id. Batas agregat 200 MiB mencakup semua gambar sumber dan mask.
Gambar sumber multipart. Ulangi image untuk menyediakan beberapa sumber GPT Image. File harus berformat PNG, JPEG, atau WebP, hingga 16 gambar sumber dan masing-masing 50 MiB. Model edit xAI Grok Imagine menggunakan bidang input yang sama tetapi membatasi gambar sumber: maksimal 5 untuk grok-imagine-image-2.0 dan maksimal 3 untuk model edit xAI lainnya.
Deskripsi teks dari pengeditan yang diinginkan, hingga 32.000 karakter. Wajib diisi untuk setiap model yang mencantumkan prompt dalam detailnya. Alat tanpa prompt, seperti stability-upscale-fast, dipanggil tanpa prompt.
Gambar tambahan yang area sepenuhnya transparan menandakan bagian mana dari gambar yang harus diedit. Harus berupa file PNG yang valid, kurang dari 50 MiB, dan memiliki dimensi yang sama dengan image.
Untuk permintaan JSON, mask juga dapat berupa objek dengan tepat satu dari image_url atau file_id; nilai file_id harus berasal dari /v1/files dan tetap terikat pada konfigurasi image-edit yang sama.
Model yang digunakan untuk pengeditan gambar. Gunakan gpt-image-2 untuk pengeditan GPT Image, atau model edit gambar saat ini lainnya yang dikembalikan oleh GET /v1/models?recommended_for=image.
1Jumlah gambar yang akan dibuat (1-10, bergantung pada model).
Ukuran gambar yang dihasilkan. Untuk gpt-image-2, gunakan auto atau WIDTHxHEIGHT; dimensi harus kelipatan 16, sisi terpanjang maksimal 3840px, rasio panjang/pendek maksimal 3:1, dan total piksel antara 655,360 dan 8,294,400.
Untuk gemini-3.1-flash-image, gemini-nano-banana-2.1, gemini-3-pro-image, dan gemini-3.1-flash-lite-image, size menerima ukuran output dari tabel ukuran model atau tingkat resolusi: 1K, 2K, atau 4K. TokenLab mengirimkan tingkat resolusi sebagai resolution. Tingkat resolusi yang tidak didukung model, atau tingkat resolusi yang berbeda dari resolution, mengembalikan 400 dengan kode invalid_image_size_contract. Bentuk yang disarankan adalah aspect_ratio dengan resolution.
Bagaimana gambar dikembalikan: url atau b64_json.
- Ditiadakan: ketika model mengembalikan byte gambar, setiap gambar ada di
data[].b64_json, dan juga didata[].urlketika TokenLab menyimpannya. Ketika model mengembalikan tautan, setiap gambar ada didata[].url. url: setiap gambar hanya ada didata[].url.b64_json: setiap gambar hanya ada didata[].b64_jsonsebagai data Base64.
Tautan adalah URL hasil media TokenLab. Tautan tersebut tetap valid selama 30 hari. Lihat Retensi data.
falseAtur ke true untuk mengembalikan tugas sebelum gambar akhir siap. Hanya model yang mencantumkan async di antara parameter yang didukung yang menerimanya, misalnya gpt-image-2; untuk model lainnya, permintaan mengembalikan 400 unsupported_async_mode. Pengeditan asinkron yang selesai mengembalikan URL terlepas dari response_format yang diminta; gunakan permintaan sinkron ketika Anda memerlukan b64_json.
Pengenal unik yang mewakili pengguna akhir Anda untuk pemantauan penyalahgunaan.
Respons
Timestamp Unix saat gambar dibuat.
Array gambar yang dihasilkan.
Setiap objek berisi:
url(string): URL hasil media TokenLab dari gambar yang diedit, valid selama 30 hari. Tidak ada jikaresponse_formatberupab64_json. Ketikaresponse_formatditiadakan, nilai ini tidak ada jika TokenLab tidak dapat menyimpan gambar.b64_json(string): Data gambar Base64. Ada ketikaresponse_formatberupab64_json, atau ketika ditiadakan dan model mengembalikan byte gambar.
Jumlah token (input_tokens, output_tokens, total_tokens, dan detailnya) untuk model dengan harga berbasis token seperti gpt-image-2, jika tersedia.
Respons Tugas Asinkron
Atur async: true pada model yang mendukungnya untuk membuat tugas alih-alih menunggu gambar yang diedit dalam permintaan. Respons mencakup status: "pending", task_id, dan poll_url. Lakukan polling pada /v1/tasks/{task_id} hingga tugas mencapai status completed atau failed.
Tugas edit asinkron hanya mengembalikan URL gambar akhir. Jika Anda memerlukan data gambar b64_json mentah, gunakan permintaan sinkron.
Penagihan dapat mencadangkan perkiraan jumlah biaya saat tugas dibuat. Tugas yang selesai ditagihkan berdasarkan penggunaan sebenarnya, dan tugas yang gagal atau kehabisan waktu akan dilepaskan atau dikembalikan dananya.
Permintaan
curl -X POST "https://api.tokenlab.sh/v1/images/edits" \
-H "Authorization: Bearer sk-your-api-key" \
-F "model=gpt-image-2" \
-F "image=@sunlit_lounge.png" \
-F "mask=@mask.png" \
-F "prompt=A sunlit indoor lounge area with a pool" \
-F "n=1" \
-F "size=1024x1024"Respons
{
"created": 1706000000,
"data": [
{
"url": "https://..."
}
]
}Catatan
Kegagalan pengambilan gambar jarak jauh dikembalikan sebagai kesalahan input sebelum pembuatan dimulai. URL yang tidak dapat dijangkau, batas waktu habis, respons 403/404, host privat/internal, kredensial atau fragmen dalam URL, konten non-gambar, format yang tidak didukung, dan pelanggaran batas ukuran akan mengembalikan 400 atau 413 dan mengidentifikasi input image_url / image_urls[n]. Kodenya adalah invalid_image_url, unsupported_image_content_type, too_many_images, atau, dengan 413, image_too_large atau image_input_too_large. Untuk aset privat atau yang dilindungi header, unggah file multipart image secara langsung atau buat referensi /v1/files.
Kirim header Idempotency-Key untuk mencoba kembali permintaan dengan aman setelah batas waktu habis; lihat Mencoba kembali dengan aman menggunakan kunci idempotensi.
Hy Image 3.5 Preview mengedit gambar referensi berdasarkan instruksi tertulis. Model ini hanya menerima size 1024x1024 dan n 1:
{
"model": "hy-image-v3.5-preview",
"prompt": "Change the table to pale blue",
"image_url": "https://example.com/reference.png",
"size": "1024x1024",
"n": 1,
"response_format": "url"
}Otorisasi
BearerAuth Autentikasi API Key. Buat atau kelola API key di Dashboard > API > API Keys.
Lokasi: header
Header
Kebijakan Pengiriman per-permintaan. Menggantikan default API key dan Workspace. Secara otomatis mencoba TokenLab Verified terlebih dahulu dan dapat beralih satu kali ke Official saja sebelum output, penerimaan permintaan, atau pembuatan sumber daya persisten.
Nilai yang tersedia
- "auto"
- "verified"
- "official"
Kunci opsional yang membuat permintaan gambar aman untuk dicoba ulang jika permintaan tersebut membuat tugas. Kirim nilai unik baru, seperti UUID, untuk setiap permintaan. Percobaan ulang dengan kunci dan body yang sama kemudian akan mengembalikan tugas tersebut dan tidak akan membuat, mengirim, atau mengenakan biaya untuk tugas kedua. Untuk permintaan yang mengembalikan gambar secara langsung, percobaan ulang dengan kunci yang sama dapat mengembalikan status tugas alih-alih gambar, atau 409 dengan idempotent_response_not_replayable. Body yang berbeda dengan kunci yang sudah diterima akan ditolak; kode status dan kode error untuk kasus tersebut tidak dijamin. Kunci yang lebih panjang dari 255 karakter akan diabaikan, dan permintaan tersebut tidak akan memiliki perlindungan idempotensi. Lihat Retry safely with an idempotency key.
1 <= length <= 255Respons
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json