Docs / API
Gambar
POST /v1/images/generations dan /v1/images/edits dalam format OpenAI Images, harga per gambar atau per token, plus GET /v1/images/{id} untuk mengambil hasil lagi.
Terakhir diperbarui
Endpoint
| Method | Path | Fungsinya |
|---|---|---|
| POST | /v1/images/generations | Gambar baru dari prompt teks (body JSON) |
| POST | /v1/images/edits | Mengubah satu gambar yang Anda unggah, dipandu prompt (multipart/form-data) |
| GET | /v1/images/{id} | Mengambil hasil lagi selama 24 jam, sebagai tautan berumur pendek |
Endpoint ini mengikuti format OpenAI Images. Arahkan SDK OpenAI ke base URL https://api.cent-ai.dev/v1 lalu panggil images.generate atau images.edit.
Model gambar tampil di GET /v1/models dengan harganya di pricing.variants, dan di halaman model. Endpoint yang dilayani tiap model: hunyuan-image-alpha untuk gambar baru dan hunyuan-image-alpha-edit untuk edit; qwen-image-3.0-pro, wan2.7-image, dan wan2.7-image-pro untuk gambar baru dan edit; minimax-h3-image hanya untuk gambar baru dan ditagih per token, dengan perkiraan harga per gambar di halaman modelnya. Gambar dari kedua model Hunyuan memuat watermark teks kecil yang ditambahkan model; Cent AI tidak menambah atau menghapusnya.
Gambar baru
Request
POST https://api.cent-ai.dev/v1/images/generations
Authorization: Bearer cai_<secret>
Content-Type: application/json
| Field | Wajib | Yang dilakukan Cent AI |
|---|---|---|
model | ya | Model gambar untuk gambar baru. Model chat atau nama yang tidak dikenal dijawab 404 model_not_found |
prompt | ya | Dikirim ke model apa adanya |
n | tidak | Jumlah gambar, default 1. Saldo yang ditahan mencakup n gambar (lihat Biaya) |
size | tidak | Dikirim apa adanya, misalnya 1024x1024. Ukuran yang ditolak model kembali sebagai error dari model |
response_format | tidak | Kosongkan atau kirim b64_json. url dijawab 400 invalid_request |
Field lain diteruskan ke model tanpa diubah. Cent AI tidak menambah filter konten sendiri; prompt yang ditolak model mendapat error dari model (400 upstream_error atau 403 policy_violation) dan tidak ditagih.
Contoh
curl https://api.cent-ai.dev/v1/images/generations \
-H "Authorization: Bearer $CENT_AI_KEY" \
-H "Content-Type: application/json" \
--max-time 630 \
-d '{"model":"hunyuan-image-alpha","prompt":"A lighthouse at dawn, watercolor","size":"1024x1024"}'
Mengedit gambar
Request
POST https://api.cent-ai.dev/v1/images/edits
Authorization: Bearer cai_<secret>
Content-Type: multipart/form-data
| Part | Wajib | Yang dilakukan Cent AI |
|---|---|---|
model | ya | Model gambar yang mengedit, misalnya hunyuan-image-alpha-edit |
prompt | ya | Dikirim ke model apa adanya |
image | ya | Satu berkas: PNG, JPEG, WebP, atau GIF. image kedua dijawab 400 |
mask | tidak | Satu berkas dengan format yang sama |
n, size, dan part teks lain | tidak | Dikirim ke model apa adanya |
Body wajib multipart/form-data, seperti yang dikirim SDK OpenAI; body JSON dijawab 400 invalid_request. Seluruh body paling besar 32 MiB; lebih besar dari itu dijawab 413 request_too_large. Model bisa mengembalikan ukuran yang berbeda dari yang Anda minta.
Contoh
curl https://api.cent-ai.dev/v1/images/edits \
-H "Authorization: Bearer $CENT_AI_KEY" \
--max-time 630 \
-F model=hunyuan-image-alpha-edit \
-F prompt="Make the sky orange" \
-F image=@photo.png
Respons
Kedua endpoint menjawab dengan bentuk yang sama:
{
"id": "img_01JC8Z3V6Q4N2T7R5W9X0Y1A2B",
"created": 1792051200,
"data": [{"b64_json": "iVBORw0KGgo…"}],
"usage": {"cost": "0.150000000"}
}
| Field | Arti |
|---|---|
id | Id hasil, img_ diikuti 26 karakter. Dipakai untuk GET /v1/images/{id} |
data[].b64_json | Gambar dalam base64. Tautan milik model tidak pernah diteruskan |
usage.cost | Biaya request ini dalam USD, 9 desimal, sama dengan angka di halaman Requests |
Nilai di atas menunjukkan bentuknya; harganya ada di halaman model.
Menunggu gambar
Satu gambar bisa memakan beberapa menit. Cent AI menunggu model sampai 600 detik.
- Bila model menjawab dalam 15 detik, Anda menerima status biasa: 200 dengan gambar, atau status error.
- Sesudah 15 detik Cent AI mengirim status 200 dengan
Content-Type: application/json, lalu satu spasi tiap 15 detik sampai body JSON. Spasi sebelum JSON itu sah, jadi SDK OpenAI dan parser JSON membaca body seperti biasa. Spasi ini menjaga koneksi agar tidak diputus proxy karena diam. - Bila request gagal sesudah status itu terkirim, statusnya tetap 200 dan body-nya berisi error:
{"error": {"message": "The model did not respond in time. Try again shortly.", "type": "server_error", "param": null, "code": "upstream_timeout"}}
Periksa error, atau data yang tidak ada, sebelum membaca data. Request yang gagal tidak pernah ditagih.
Atur timeout klien minimal 630 detik: timeout=630 di SDK Python, timeout: 630_000 di SDK Node, --max-time 630 untuk curl.
Bila koneksi putus
Koneksi yang lama terbuka bisa diputus di tengah jalan, oleh jaringan Anda atau proxy, saat gambar masih dibuat. Setiap jawaban untuk request yang diterima membawa header X-Cent-Image-Id berisi id gambar, sejak byte pertama. Bila putusnya terjadi di tengah jalan, misalnya timeout proxy, sementara Cent AI tetap menyelesaikan gambar, GET /v1/images/{id} mengembalikannya selama 24 jam (lihat di bawah). Bila putusnya sampai ke Cent AI sebelum gambar siap, request berhenti, tidak ditagih, dan GET menjawab failed. Untuk gambar yang memakan beberapa menit, pakai mode async. Mengirim request yang sama lagi membuat dan menagih gambar baru.
Mode async
Tambahkan header Prefer: respond-async ke POST /v1/images/generations atau /v1/images/edits untuk langsung mendapat id tanpa menunggu di koneksi yang terbuka:
curl -i https://api.cent-ai.dev/v1/images/generations \
-H "Authorization: Bearer $CENT_AI_KEY" \
-H "Content-Type: application/json" \
-H "Prefer: respond-async" \
-d '{"model": "hunyuan-image-alpha", "prompt": "a red bicycle by a white wall"}'
| Aturan | Rincian |
|---|---|
| Jawaban | 202 Accepted dengan Location: /v1/images/{id}, X-Cent-Image-Id, dan Preference-Applied: respond-async |
| Pemeriksaan | Key, model, body, dan saldo dicek dulu; bila ada masalah, jawabannya status error biasa dan tidak ada yang dijalankan |
| Hasil | Panggil GET /v1/images/{id} berkala, setiap beberapa detik, sampai status bernilai completed atau failed |
| Biaya | Ditagih setelah gambar tersimpan, hanya untuk gambar yang tersimpan. Gambar yang gagal tidak ditagih |
| Mengulang | POST kedua adalah gambar baru dan tagihan baru; untuk mengecek request, pakai GET dengan id-nya |
Tanpa header itu jawabannya sinkron seperti di atas, sesuai yang diharapkan SDK OpenAI. Jawaban 200 tanpa Preference-Applied berarti request berjalan sinkron: baca body-nya seperti di atas.
Status dan hasil gambar
GET https://api.cent-ai.dev/v1/images/img_01JC8Z3V6Q4N2T7R5W9X0Y1A2B
Authorization: Bearer cai_<secret>
| Aturan | Rincian |
|---|---|
| Status | in_progress selama gambar dibuat, lalu completed dengan data dan usage, atau failed dengan kode dan pesan error dari jawaban yang gagal |
| Berapa lama | Hasil disimpan 24 jam lalu dihapus. Sesudah itu id dijawab 404 not_found |
| Tautan | data[].url adalah tautan bertanda tangan yang berlaku 10 menit; minta lagi untuk tautan baru |
| Siapa | Hanya key dari akun pemilik gambar itu. Key lain mendapat 404 not_found |
| Biaya | Gratis; rate limit key yang biasa tetap berlaku |
Pakai ini sesudah mode async, atau bila koneksi putus sebelum body sampai.
Biaya
Model gambar tidak termasuk paket budget. Tiap model dihargai dengan salah satu dari dua cara, terlihat di pricing.variants:
- Per gambar (
unitimage): harga tetap untuk tiap gambar yang Anda terima. - Per token (
unit1m_input_tokensdan1m_output_tokens): tarif per 1M token teks masuk, gambar masuk, dan keluar, ditagih dari token yang dilaporkan model untuk tiap request. Hanya keluaran gambar yang Anda terima yang ditagih. Model ini juga menampilkanapprox_per_image, biaya satu gambar 1K dari prompt pendek, dengan asumsinya diapprox_assumption. Request tanpaareamaupunsizedikirim denganarea1K.
| Langkah | Yang terjadi pada saldo |
|---|---|
| Sebelum model dipanggil | Biaya terbesar request ditahan: harga × n untuk model per gambar; untuk model per token, token keluar terbanyak per gambar untuk area yang diminta × n, ditambah token masuk terbanyak. Saldo kurang dijawab 402 insufficient_balance dan model tidak dipanggil |
| Gambar sampai | Hanya gambar yang Anda terima yang ditagih; sisa saldo yang ditahan dilepas |
| Request gagal | Saldo yang ditahan dilepas penuh; request tidak dikenai biaya |
Tagihan ada di usage.cost dan di halaman Requests dashboard. Lihat Biaya per request.
Error
| Status | Kode | Kapan |
|---|---|---|
| 400 | invalid_request | Tanpa model atau prompt, response_format url, body JSON di edits, berkas bukan gambar, dua gambar |
| 400 | upstream_error | Model menolak request, misalnya ukuran yang tidak didukungnya. Tidak ditagih |
| 402 | insufficient_balance | Saldo tidak cukup untuk jumlah yang ditahan |
| 403 | policy_violation | Moderasi milik model menolak prompt sebagai pelanggaran kebijakan. Tidak ditagih |
| 404 | model_not_found | Model tidak dikenal, atau model chat di endpoint gambar |
| 413 | request_too_large | Body lebih dari 32 MiB |
| 503 | upstream_timeout, upstream_unavailable | Model tidak menjawab dalam 600 detik, atau tidak ada gambar yang kembali. Tidak ditagih |
Sesudah 15 detik pertama, error ini datang dengan status 200 seperti di atas. Lihat Error.
Kontrak
POST/v1/images/generations
Image generation (OpenAI Images format)
Autentikasi · Key API (Bearer atau x-api-key)
Body request
modelstringwajibnintegeropsionalNumber of images; no limit of its own beyond what the model accepts.
promptstringwajibMust not be empty.
response_format"b64_json"opsionalOnly b64_json is served; url is a 400.
sizestringopsionalPassed to the model, for example 1024x1024; a size the model refuses is a 400.
Respons
- 200The images as base64, or an
errorobject when the request failed after the early 200 header. - 202Accepted with
Prefer: respond-async; the image is made and billed in the background. - 400Error in the OpenAI shape.
- 401Error in the OpenAI shape.
- 402Error in the OpenAI shape.
- 403Error in the OpenAI shape.
- 404Error in the OpenAI shape.
- 413Error in the OpenAI shape.
- 429Error in the OpenAI shape that may be retried after Retry-After.ulangi
- 500Error in the OpenAI shape.
- 501The endpoint is not open yet; not billed and the model is never called.
- 503Error in the OpenAI shape that may be retried after Retry-After.ulangi
Header respons
LocationPreference-AppliedRetry-AfterX-Cent-Image-Idx-request-id
POST/v1/images/edits
Image editing (OpenAI Images format)
Autentikasi · Key API (Bearer atau x-api-key)
Respons
- 200The images as base64, or an
errorobject when the request failed after the early 200 header. - 202Accepted with
Prefer: respond-async; the image is made and billed in the background. - 400Error in the OpenAI shape.
- 401Error in the OpenAI shape.
- 402Error in the OpenAI shape.
- 403Error in the OpenAI shape.
- 404Error in the OpenAI shape.
- 413Error in the OpenAI shape.
- 429Error in the OpenAI shape that may be retried after Retry-After.ulangi
- 500Error in the OpenAI shape.
- 501The endpoint is not open yet; not billed and the model is never called.
- 503Error in the OpenAI shape that may be retried after Retry-After.ulangi
Header respons
LocationPreference-AppliedRetry-AfterX-Cent-Image-Idx-request-id
GET/v1/images/{id}
Image status and result
Autentikasi · Key API (Bearer atau x-api-key)
Respons
- 200The request's status, with the stored images once completed.
- 401Error in the OpenAI shape.
- 404Error in the OpenAI shape.
- 429Error in the OpenAI shape that may be retried after Retry-After.ulangi
- 501The endpoint is not open yet; not billed and the model is never called.
- 503Error in the OpenAI shape that may be retried after Retry-After.ulangi
Header respons
Retry-Afterx-request-id
Dibuat dari kontrak OpenAPI.