Generasi gambar (OpenAI Images API)

POST /v1/images/generations menghasilkan gambar dalam format OpenAI Images API: Anda mengirim permintaan dan mendapatkan gambar kembali dalam respons yang sama. Ini adalah adaptor di atas antrean yang sama dengan POST /api/media/generate: model, harga, pemeriksaan saldo, failover pemasok, dan biaya digunakan bersama, sehingga generasi yang sama dikenai biaya yang sama pada kedua alamat.

curl https://getvibeapi.com/v1/images/generations \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"nano-banana","prompt":"a red bicycle on a bridge","n":1,"size":"1024x1024"}'

Respons (HTTP 200):

{
  "created": 1792706400,
  "data": [{ "url": "https://getvibeapi.com/media/r/…/0.png" }]
}

Teruskan kunci sebagai Authorization: Bearer sk-pv-… atau x-api-key. OpenAI SDK resmi dapat digunakan apa adanya:

from openai import OpenAI

client = OpenAI(base_url="https://getvibeapi.com/v1", api_key="sk-pv-...", timeout=600)
image = client.images.generate(model="nano-banana", prompt="a red bicycle on a bridge", size="1024x1024")
print(image.data[0].url)

Kolom yang tidak dikenal, serta background, style, output_format, output_compression, moderation, stream dan partial_images, ditolak dengan 400 berdasarkan namanya, bukan diabaikan secara diam-diam — jika tidak, Anda akan membayar gambar yang tidak Anda minta. Model yang memerlukan gambar sumber (pengeditan, peningkatan resolusi, inpainting) tidak berfungsi pada alamat ini, karena tidak ada cara untuk mengirim gambar di sini; gunakan POST /api/media/generate.

Permintaan tetap terbuka hingga tugas selesai, selama maksimal 300 detik. Waktu median adalah 15 hingga 85 detik bergantung pada model; generasi individual pada model paling lambat memerlukan 3–4 menit. Atur batas waktu klien Anda ke setidaknya 300 detik (default OpenAI SDK adalah 600).

• Setiap respons, termasuk kesalahan setelah tugas dibuat, membawa header x-pv-media-job-id dengan id tugas.
• Jika tugas tidak selesai dalam 300 detik, jawabannya adalah 504 dengan cause: image_generation_timeout dan id tugas di dalam pesan. Generasi tetap berjalan: ambil hasilnya dari GET /api/media/jobs/{id}.
• Jika koneksi terputus (batas waktu aplikasi, jaringan), tugas tetap diselesaikan. GET /v1/images/generations?limit=20 (hingga 100) mencantumkan gambar terbaru untuk kunci ini beserta status, tautan, dan jumlah yang dibebankan cost_rub.

Tidak ada biaya yang dikenakan saat pengiriman. Hanya generasi yang berhasil diselesaikan yang dikenai biaya, dengan harga yang sama seperti di /api/media-catalog dan dalam kutipan POST /api/media/price. Generasi yang gagal mengembalikan 502 dengan pesan "Tidak ada biaya yang dikenakan" dan tidak dikenai biaya apa pun. Jumlah yang dibebankan dikembalikan dalam header x-pv-cost-rub. Jika saldo tidak dapat menutupi biaya generasi, jawabannya adalah 402 sebelum tugas apa pun dimulai.

Aplikasi apa pun yang dapat menghasilkan gambar melalui penyedia yang kompatibel dengan OpenAI dapat digunakan. Menggunakan Cherry Studio sebagai contoh:

1. Tambahkan penyedia bertipe OpenAI dengan alamat API https://getvibeapi.com (aplikasi menambahkan /v1 sendiri) dan kunci sk-pv-… Anda.
2. Tambahkan model secara manual menggunakan id dari https://getvibeapi.com/api/media-catalog (hanya entri dengan kind: "image"), misalnya nano-banana atau gpt-image-2. Daftar model aplikasi menampilkan model teks; model media tidak ada di dalamnya.
3. Lakukan generasi dari fitur melukis / generasi gambar aplikasi, bukan dari chat biasa. Chat mengirim permintaan ke /v1/chat/completions, yang tidak mendukung model gambar.
4. Jika aplikasi memungkinkan Anda mengatur batas waktu permintaan, atur ke setidaknya 300 detik. Gambar yang menyerah untuk dibuat oleh aplikasi tercantum di GET /v1/images/generations. Mencoba lagi dari aplikasi membuat generasi baru yang dikenai biaya secara terpisah.

Mode yang mengedit gambar yang diunggah dalam aplikasi semacam itu disebut /v1/images/edits, dan juga tersedia di sini (lihat di bawah).

POST /v1/images/edits menerima permintaan OpenAI SDK (multipart/form-data: file di image, atau beberapa file di image[], dengan prompt, model, size, quality dan response_format) atau JSON dengan images: [{"image_url": "…"}]. Cara kerjanya sama seperti generasi di atas: respons yang sama, waktu tunggu yang sama, x-pv-media-job-id yang sama, dan harga yang sama seperti POST /api/media/generate dengan gambar sumber; edit yang gagal tidak dikenai biaya. Mode edit model dipilih dari katalog. mask ditolak dengan 400 unsupported_parameter, dan model yang tidak menerima gambar sumber ditolak dengan model_cannot_edit. Untuk edit bertopeng, gunakan POST /api/media/generate dan lakukan polling pada GET /api/media/jobs/{id} — lihat panduan generasi asinkron. Video tidak dibuat secara sinkron: /v1/video/generations dan /v1/videos juga merespons dengan 410 (detail).

Di katalog dan kode baru, gunakan nano-banana-pro. Untuk memigrasikan klien async yang sudah ada, nilai gemini-3-pro-image masih diterima hanya di field model pada request /api/media/generate dan mengarah ke public model yang sama. Nilai ini tidak dipublikasikan di discovery atau pricing.