Edit Image

Gambaran Umum

Membuat gambar yang telah diedit atau diperluas berdasarkan gambar asli dan sebuah prompt.

Endpoint ini mendukung keduanya:

alur unggah multipart/form-data yang kompatibel dengan OpenAI seperti yang didokumentasikan di bawah
permintaan JSON yang menyediakan image_url, image_urls, atau referensi images resmi untuk keluarga image-to-image yang didukung

gpt-image-2 didukung di sini. Model ini menerima unggahan image multipart, image_url / image_urls JSON, dan referensi images[] resmi (image_url atau file_id), dengan maksimal 16 gambar sumber. Buat nilai file_id melalui /v1/files terlebih dahulu. Atur async: true untuk mengembalikan tugas terlebih dahulu; model edit FLUX/BFL resmi juga menggunakan alur polling tugas yang sama.

Edit gpt-image-2 tidak menerima resolution; gunakan size untuk dimensi output. background menerima auto atau opaque; transparent tidak didukung. Untuk edit multi-gambar atau latensi tinggi, lebih 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 edit gambar. 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: maksimal 5 untuk grok-imagine-image-2.0, dan maksimal 3 untuk grok-imagine-image serta versi lama grok-imagine-image-pro. Permintaan dengan gambar sumber lebih banyak dari yang diterima model akan gagal dalam validasi input dengan 400 too_many_images.

input_fidelity bukan bagian dari bidang yang didukung TokenLab saat ini untuk gpt-image-2; hilangkan bidang tersebut atau permintaan akan mengembalikan 400 unsupported_parameter.

Isi Permintaan

Timeout permintaan sinkron: Beberapa permintaan gambar mengembalikan gambar akhir secara langsung dan menunggu pembuatan selesai. Permintaan beresolusi tinggi atau berkualitas tinggi dapat memakan waktu hampir satu menit atau lebih, jadi atur timeout klien HTTP Anda setidaknya ke 120s. Jika respons pembuatan menyertakan status: "pending", task_id, atau poll_url, ikuti poll_url yang dikembalikan sebagai gantinya.

URL gambar jarak jauh: ketika input multipart diperlukan, TokenLab mengambil image_url, image_urls, atau images[].image_url JSON dan mengirimkan byte sebagai bagian image multipart. URL harus berupa http/https publik, tanpa kredensial atau fragmen yang disematkan, dan tidak boleh mengarah ke localhost, IP privat, atau rentang IP yang dicadangkan; setiap pengalihan (redirect) diperiksa kembali. Payload yang diambil harus berupa gambar PNG, JPEG, atau WebP yang valid. Batasannya adalah 50 MiB per gambar, total 200 MiB untuk gambar yang diambil melalui URL dalam satu permintaan, timeout pengambilan 30s, dan maksimal 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.

imagefile

Gambar sumber multipart. Ulangi image untuk memberikan beberapa sumber GPT Image. File harus berupa PNG, JPEG, atau WebP, maksimal 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 3 untuk model edit xAI lainnya.

promptstringwajib

Deskripsi teks dari edit yang diinginkan.

maskfile | object

Gambar tambahan yang area transparan penuhnya menunjukkan di mana gambar 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 edit gambar yang sama.

modelstringwajib

Model yang digunakan untuk edit gambar. Gunakan gpt-image-2 untuk edit GPT Image, atau model edit gambar terkini lainnya yang dikembalikan oleh GET /v1/models?recommended_for=image.

nintegerbawaan: 1

Jumlah gambar yang akan dihasilkan (1-10, tergantung model).

sizestring

Ukuran gambar yang dihasilkan. Untuk gpt-image-2, gunakan auto atau WIDTHxHEIGHT; dimensi harus kelipatan 16, tepi 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 sebagai resolution. Tingkat yang tidak didukung oleh model, atau tingkat yang berbeda dari resolution, akan mengembalikan 400 dengan kode invalid_image_size_contract. Bentuk yang disarankan adalah aspect_ratio dengan resolution.

response_formatstring

Bagaimana gambar dikembalikan: url atau b64_json.

Dihilangkan: ketika model mengembalikan byte gambar, setiap gambar ada di data[].b64_json, dan juga di data[].url saat TokenLab menyimpannya. Ketika model mengembalikan tautan, setiap gambar ada di data[].url.
url: setiap gambar hanya ada di data[].url.
b64_json: setiap gambar hanya ada di data[].b64_json sebagai data Base64.

Tautan adalah URL hasil media TokenLab. Tautan tersebut tetap valid selama 30 hari. Lihat Retensi data.

asyncbooleanbawaan: false

Atur ke true dengan gpt-image-2 atau model edit FLUX/BFL resmi untuk mengembalikan tugas sebelum gambar akhir siap. Edit asinkron yang selesai mengembalikan URL terlepas dari response_format yang diminta; gunakan permintaan sinkron jika Anda memerlukan b64_json.

userstring

Pengidentifikasi unik yang mewakili pengguna akhir Anda untuk pemantauan penyalahgunaan.

Respons

createdinteger

Stempel waktu Unix saat gambar dibuat.

dataarray

Array gambar yang dihasilkan.

Setiap objek berisi:

url (string): URL hasil media TokenLab dari gambar yang diedit, valid selama 30 hari. Tidak ada jika response_format adalah b64_json. Jika response_format dihilangkan, bidang ini tidak ada jika TokenLab tidak dapat menyimpan gambar.
b64_json (string): Data gambar Base64. Ada jika response_format adalah b64_json, atau jika dihilangkan dan model mengembalikan byte gambar.

Respons Tugas Asinkron

Atur async: true dengan gpt-image-2 atau model edit FLUX/BFL resmi 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 completed atau failed.

Tugas edit asinkron hanya mengembalikan URL gambar akhir. Jika Anda memerlukan data gambar b64_json mentah, gunakan permintaan sinkron.

Penagihan mungkin mencadangkan jumlah estimasi saat tugas dibuat. Tugas yang selesai ditagih berdasarkan penggunaan aktual, dan tugas yang gagal atau kehabisan waktu akan dibatalkan 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

Response

{
  "created": 1706000000,
  "data": [
    {
      "url": "https://..."
    }
  ]
}

Catatan

Kegagalan pengambilan gambar jarak jauh dikembalikan sebagai kesalahan input sebelum pembuatan dimulai. URL yang tidak dapat dijangkau, timeout, 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]. Untuk aset privat atau yang dilindungi header, unggah file image multipart secara langsung atau buat referensi /v1/files.

Hy Image 3.5 Preview membuat gambar persegi 1024 piksel dari teks dan mengedit gambar referensi menggunakan instruksi tertulis. Model ini berguna untuk merancang visual dan menyempurnakan komposisi.

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

AuthorizationBearer <token>

Autentikasi API Key. Buat atau kelola API key di Dashboard > API > API Keys.

Lokasi: header

Header

X-TokenLab-Delivery-Policy?string

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"

Body permintaan

model?string

Model yang digunakan untuk edit gambar. Kirimkan ini secara eksplisit.

prompt?string

image_url*string

URL gambar sumber tunggal. Dipertahankan untuk kompatibilitas TokenLab; gunakan images untuk bentuk JSON resmi.

Formaturi

n?integer

Rentang1 <= value

quality?string

size?string

aspect_ratio?string

resolution?string

response_format?string

background?string

Nilai yang tersedia

"transparent"
"opaque"
"auto"

output_format?string

Nilai yang tersedia

"png"
"jpeg"
"webp"

output_compression?integer

Rentang0 <= value <= 100

compression?integer

Rentang0 <= value <= 100

moderation?string

Nilai yang tersedia

"auto"
"low"

async?boolean

Mengembalikan tugas sebelum gambar yang diedit siap untuk model yang mendukung eksekusi async publik.

stream?boolean

Flag streaming gambar yang dicadangkan. Rute edit publik saat ini menolak true.

user?string

image_urls?array<>

Beberapa URL gambar sumber. Edit GPT Image menerima hingga 16 gambar sumber; edit xAI Grok Imagine Image 2.0 menerima paling banyak 5 gambar sumber; model edit xAI Grok Imagine lainnya menerima paling banyak 3.

Item1 <= items <= 16

images?array<|>

Referensi gambar JSON resmi untuk edit gambar. Berikan tepat satu dari image_url atau file_id untuk setiap item. Edit GPT Image menerima hingga 16 gambar sumber; edit xAI Grok Imagine Image 2.0 menerima paling banyak 5 gambar sumber; model edit xAI Grok Imagine lainnya menerima paling banyak 3.

Item1 <= items <= 16

mask?|

Referensi mask JSON opsional untuk edit gambar. Berikan tepat satu dari image_url atau file_id. Permintaan multipart juga dapat mengirim mask sebagai bagian file.

[key: string]?any

Edit Image

Gambaran Umum

Isi Permintaan

Respons

Respons Tugas Asinkron

Catatan

Otorisasi

Header

Body permintaan

Respons

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

Edit Image

Gambaran UmumCopy Anchor Link

Isi PermintaanCopy Anchor Link

ResponsCopy Anchor Link

Respons Tugas AsinkronCopy Anchor Link

CatatanCopy Anchor Link

OtorisasiCopy Anchor Link

HeaderCopy Anchor Link

Body permintaanCopy Anchor Link

ResponsCopy Anchor Link

200application/json

400application/json

401application/json

413application/json

500application/json

503application/json

Gambaran Umum

Isi Permintaan

Respons

Respons Tugas Asinkron

Catatan

Otorisasi

Header

Body permintaan

Respons

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`