Menu docs

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

MethodPathFungsinya
POST/v1/images/generationsGambar baru dari prompt teks (body JSON)
POST/v1/images/editsMengubah 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
FieldWajibYang dilakukan Cent AI
modelyaModel gambar untuk gambar baru. Model chat atau nama yang tidak dikenal dijawab 404 model_not_found
promptyaDikirim ke model apa adanya
ntidakJumlah gambar, default 1. Saldo yang ditahan mencakup n gambar (lihat Biaya)
sizetidakDikirim apa adanya, misalnya 1024x1024. Ukuran yang ditolak model kembali sebagai error dari model
response_formattidakKosongkan 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
PartWajibYang dilakukan Cent AI
modelyaModel gambar yang mengedit, misalnya hunyuan-image-alpha-edit
promptyaDikirim ke model apa adanya
imageyaSatu berkas: PNG, JPEG, WebP, atau GIF. image kedua dijawab 400
masktidakSatu berkas dengan format yang sama
n, size, dan part teks laintidakDikirim 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"}
}
FieldArti
idId hasil, img_ diikuti 26 karakter. Dipakai untuk GET /v1/images/{id}
data[].b64_jsonGambar dalam base64. Tautan milik model tidak pernah diteruskan
usage.costBiaya request ini dalam USD, 9 desimal, sama dengan angka di halaman Requests

Nilai di atas menunjukkan bentuknya; harganya ada di halaman model.

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"}'
AturanRincian
Jawaban202 Accepted dengan Location: /v1/images/{id}, X-Cent-Image-Id, dan Preference-Applied: respond-async
PemeriksaanKey, model, body, dan saldo dicek dulu; bila ada masalah, jawabannya status error biasa dan tidak ada yang dijalankan
HasilPanggil GET /v1/images/{id} berkala, setiap beberapa detik, sampai status bernilai completed atau failed
BiayaDitagih setelah gambar tersimpan, hanya untuk gambar yang tersimpan. Gambar yang gagal tidak ditagih
MengulangPOST 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>
AturanRincian
Statusin_progress selama gambar dibuat, lalu completed dengan data dan usage, atau failed dengan kode dan pesan error dari jawaban yang gagal
Berapa lamaHasil disimpan 24 jam lalu dihapus. Sesudah itu id dijawab 404 not_found
Tautandata[].url adalah tautan bertanda tangan yang berlaku 10 menit; minta lagi untuk tautan baru
SiapaHanya key dari akun pemilik gambar itu. Key lain mendapat 404 not_found
BiayaGratis; 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 (unit image): harga tetap untuk tiap gambar yang Anda terima.
  • Per token (unit 1m_input_tokens dan 1m_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 menampilkan approx_per_image, biaya satu gambar 1K dari prompt pendek, dengan asumsinya di approx_assumption. Request tanpa area maupun size dikirim dengan area 1K.
LangkahYang terjadi pada saldo
Sebelum model dipanggilBiaya 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 sampaiHanya gambar yang Anda terima yang ditagih; sisa saldo yang ditahan dilepas
Request gagalSaldo yang ditahan dilepas penuh; request tidak dikenai biaya

Tagihan ada di usage.cost dan di halaman Requests dashboard. Lihat Biaya per request.

Error

StatusKodeKapan
400invalid_requestTanpa model atau prompt, response_format url, body JSON di edits, berkas bukan gambar, dua gambar
400upstream_errorModel menolak request, misalnya ukuran yang tidak didukungnya. Tidak ditagih
402insufficient_balanceSaldo tidak cukup untuk jumlah yang ditahan
403policy_violationModerasi milik model menolak prompt sebagai pelanggaran kebijakan. Tidak ditagih
404model_not_foundModel tidak dikenal, atau model chat di endpoint gambar
413request_too_largeBody lebih dari 32 MiB
503upstream_timeout, upstream_unavailableModel 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

  • modelstringwajib

  • nintegeropsional

    Number of images; no limit of its own beyond what the model accepts.

  • promptstringwajib

    Must not be empty.

  • response_format"b64_json"opsional

    Only b64_json is served; url is a 400.

  • sizestringopsional

    Passed to the model, for example 1024x1024; a size the model refuses is a 400.

Respons

  • 200The images as base64, or an error object 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 error object 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.