Panduan YupiAI Gateway

Model yang dipakai harus menghasilkan gambar. Cari Model ID di katalog model pada tab Gambar, atau lewat GET /v1/images/models.

modelstringwajib

Model ID gambar.

promptstringwajib

Deskripsi gambar, maksimal 32.000 karakter.

ninteger

Jumlah gambar, 1 sampai batas model (maksimal 10). Penyedia bisa mengembalikan lebih sedikit; yang ditagih hanya gambar yang diterima.

sizestring

Tier ukuran (512, 1K, 2K, 4K) atau piksel WIDTHxHEIGHT, misalnya 1536x1024. width dan height diterima sebagai bentuk lain dari size.

resolutionstring

512, 1K, 2K, atau 4K.

aspect_ratiostring

Rasio W:H, misalnya 16:9 atau 1:1.

qualitystring

auto, low, medium, high, xhigh, atau max, sesuai yang didukung model.

output_formatstring

png, jpeg, webp, atau svg.

output_compressioninteger

0 sampai 100, untuk jpeg dan webp.

backgroundstring

auto, transparent, atau opaque. transparent membutuhkan output_format png atau webp.

seedinteger

Untuk hasil yang bisa diulang, bila model mendukungnya.

input_referencesarray

Gambar referensi untuk edit lewat JSON: [{ "type": "image_url", "image_url": { "url": "https://..." } }]. URL harus https atau http publik, atau data URL base64.

streamboolean

Kirim gambar parsial lewat Server-Sent Events, hanya pada model yang mendukung streaming. Model lain menjawab biasa.

response_formatstring

Hanya b64_json. Gateway tidak menyimpan gambar, jadi tidak ada URL.

negative_prompt, guidance, stepsstring, number

Diteruskan ke penyedia model yang menerimanya; ditolak bila tidak ada yang menerima.

provider.optionsobject

Parameter khusus penyedia: { "<provider_slug>": { ... } }.

data[].b64_jsonstring

Gambar dalam base64.

data[].media_typestring

Format gambar, misalnya image/png.

usage.costnumber

Kredit yang ditagih untuk request ini.

usage.cost_detailsobject

billing_source, is_estimate, dan reserved_credits (kredit yang ditahan sebelum generasi).

usage.balanceobject

Saldo sebelum dan sesudah request.

x-yupiai-request-idheader

Id request, bisa dipakai di GET /v1/generation?id=.

provider_costnormal

Tagihan adalah biaya generasi yang dilaporkan penyedia, dalam kredit.

estimateestimasi

Biaya dari penyedia tidak tersedia. Tagihan dihitung dari tarif model dan tidak pernah melebihi kredit yang ditahan. is_estimate bernilai true.

not_billedgratis

Generasi gagal atau ditolak dan tidak ditagih. Kredit yang ditahan kembali penuh.

pendingsementara

Tagihan final belum ditetapkan. Nilai cost sementara; cek lagi lewat GET /v1/generation?id=.

Hanya model yang menerima gambar masukan. Di katalog, model ini tertulis bisa edit, beserta batas jumlah gambarnya.

modeltextwajib

Model ID yang bisa edit gambar.

prompttextwajib

Instruksi edit, maksimal 32.000 karakter.

imagefilewajib

Gambar yang diedit. Untuk beberapa gambar, ulangi field image[] (atau image). Batas jumlahnya mengikuti model, maksimal 16.

n, size, resolution, aspect_ratio, quality, output_format, output_compression, background, seedtext

Sama dengan POST /v1/images. Angka dikirim sebagai teks, misalnya n=2.

streamtext

true atau false, untuk model yang mendukung streaming.

response_formattext

Hanya b64_json.

negative_prompt, guidance, stepstext

Diteruskan ke penyedia model yang menerimanya.

modelstringwajib

Model ID video.

promptstring

Deskripsi video. Wajib, kecuali request membawa frame_images atau input_references.

durationinteger

Durasi dalam detik, salah satu yang didukung model. Bila kosong, gateway memakai default_duration model, jadi harga sudah pasti sebelum job berjalan.

resolutionstring

Misalnya 720p atau 1080p, sesuai model.

aspect_ratiostring

Misalnya 16:9 atau 9:16.

sizestring

Piksel WIDTHxHEIGHT, misalnya 1280x720.

frame_imagesarray

Frame awal atau akhir: [{ "type": "image_url", "image_url": { "url": "..." }, "frame_type": "first_frame" }]. first_frame atau last_frame, masing-masing sekali.

input_referencesarray

Referensi gambar, video, atau audio (image_url, video_url, audio_url).

generate_audioboolean

Minta audio, pada model yang bisa menghasilkannya.

seedinteger

Untuk hasil yang bisa diulang, bila model mendukungnya.

previous_job_idstring

Melanjutkan video milik Anda yang sudah completed, dari model yang sama.

provider.optionsobject

Parameter khusus penyedia.

pending

Job sudah diterima dan menunggu diproses.

in_progress

Video sedang dibuat.

completed

Selesai. unsigned_urls berisi URL unduhan. usage muncul setelah tagihan final; bila belum ada, cek lagi sebentar kemudian.

failed

Gagal. Field error berisi alasannya.

cancelled

Dibatalkan penyedia.

expired

Tidak selesai dalam batas waktu penyedia.

Model gambar: capabilities (image_generation, image_editing, streaming), supported_parameters, dan pricing dalam kredit per unit.

Model video: capabilities, supported_durations, default_duration, supported_resolutions, supported_aspect_ratios, generate_audio, dan pricing_skus dalam kredit.

endpoint per kemampuan

text

/v1/chat/completions, /v1/messages, /v1/responses

image_generation

POST /v1/images

image_editing

POST /v1/images/edits, atau POST /v1/images dengan input_references

video_generation

POST /v1/videos

speech_generation

POST /v1/audio/speech

transcription

POST /v1/audio/transcriptions

audio_input, audio_output

/v1/chat/completions dengan input_audio, atau modalities ["text", "audio"]

status · code

400 · unsupported_capability

Model tidak menghasilkan output yang diminta, misalnya model teks di /v1/images atau model tanpa gambar masukan di /v1/images/edits.

400 · unsupported_parameter

Parameter tidak dikenal atau tidak didukung model (termasuk mask). error.param menyebut namanya.

400 · invalid_parameter

Nilai parameter tidak valid, misalnya durasi yang tidak didukung atau jumlah gambar di atas batas model.

400 · missing_required_parameter

model, prompt, atau image tidak dikirim.

400 · invalid_image_typeedits

File bukan PNG, JPEG, atau WebP.

400 · invalid_multipartedits

Body multipart/form-data rusak atau terlalu banyak field.

413 · request_too_large

Body terlalu besar. Untuk edits, total unggahan maksimal 20 MB.

415 · unsupported_media_typeedits

Body bukan multipart/form-data.

402 · insufficient_quota

Saldo tidak cukup untuk kredit yang harus ditahan.

404 · not_foundvideo

Job tidak ada pada akun ini.

409 · idempotent_replay

Idempotency-Key sudah dipakai untuk request gambar yang sama.

409 · idempotency_key_reused

Idempotency-Key sudah dipakai untuk request dengan isi berbeda.

409 · idempotent_request_in_progressvideo

Request dengan key itu masih diproses. Ulangi sesuai retry-after.

409 · generation_not_readyvideo

Video belum selesai; pantau status dulu.

410 · content_expiredvideo

File video sudah tidak tersedia di penyedia.

429 · rate_limit_exceeded

Terlalu banyak request atau polling. Ikuti header retry-after.

429 · provider_rate_limited

Penyedia sedang membatasi request. Tidak ada kredit yang dipotong.

502 · generation_failed

Penyedia tidak mengembalikan hasil. Tidak ditagih kecuali penyedia menagih generasinya.

502 / 504 · provider_error, provider_timeout

Penyedia gagal atau tidak menjawab. Bila penyedia mungkin masih bekerja, kredit tetap ditahan sampai hasilnya pasti, lalu dikembalikan bila tidak ditagih.

503 · provider_unavailable, model_pricing_unavailable

Model sementara tidak bisa dilayani. Ulangi beberapa saat lagi.

Model harus menghasilkan suara. Daftar model, pilihan suara, dan tarifnya ada di GET /v1/audio/models atau katalog model pada tab Audio.

modelstringwajib

Model ID text-to-speech.

inputstringwajib

Teks yang diucapkan, maksimal 10.000 karakter per request. Pecah teks yang lebih panjang.

voicestring

ID suara. Model yang punya daftar suara (voices di GET /v1/audio/models) hanya menerima suara dari daftar itu. Sebagian penyedia mewajibkan voice.

response_formatstring

mp3 atau pcm. Bila tidak dikirim, penyedia memakai pcm. OpenAI SDK tidak mengirim field ini secara default, jadi tulis response_format secara eksplisit.

speednumber

0.25 sampai 4. Hanya dipakai model yang mendukungnya; model lain mengabaikannya.

input_referencesarray

Kloning suara, khusus model dengan voice_cloning: satu part input_audio berisi sampel suara (base64 atau data URI, maksimal 15 MB) dan paling banyak satu part text berisi transkripnya.

provider.optionsobject

Parameter khusus penyedia, dikelompokkan per slug penyedia, misalnya gaya bicara. Maksimal 8 KB.

multipart/form-data dengan field file (maksimal 25 MB), atau JSON dengan input_audio (body maksimal 16 MB).

modelstringwajib

Model ID transkripsi.

filefilemultipart

Satu file audio, maksimal 25 MB. Format dibaca dari isi file; nama file dan tipe MIME dari klien diabaikan.

input_audioobjectJSON

{ "data": base64, "format": "wav" }. Data URI juga diterima. Format dibaca dari isi audio, jadi format yang salah tulis tetap terkirim dengan benar.

languagestring

Kode ISO-639-1, misalnya id atau en. Bila kosong, penyedia mendeteksi bahasa sendiri.

temperaturenumber

0 sampai 1.

response_formatstring

json (default) atau verbose_json. verbose_json menambah language, duration, segments, dan words bila penyedia mendukungnya. text, srt, dan vtt tidak didukung penyedia.

timestamp_granularitiesarray

word dan/atau segment. Hanya berlaku dengan verbose_json. Di multipart, kirim sebagai timestamp_granularities[].

promptstring

Diterima agar kode OpenAI SDK tetap jalan, tetapi tidak diteruskan karena penyedia mengabaikannya.

provider.optionsobjectJSON

Parameter khusus penyedia per slug, misalnya diarisasi pembicara.

usage.cost_details.billing_source

provider_costnormal

Tagihan adalah biaya yang dilaporkan penyedia untuk request itu, dalam kredit.

estimateestimasi

Biaya dari penyedia tidak pernah tersedia. Tagihan dihitung dari durasi atau jumlah karakter yang diukur penyedia dan tarif model, tidak pernah melebihi kredit yang ditahan, dan ditandai is_estimate true.

not_billedgratis

Request gagal atau ditolak penyedia tanpa biaya. Kredit yang ditahan kembali penuh.

pendingsementara

Biaya final belum tercatat. Cek lagi lewat GET /v1/generation?id=.

Model teks ke suara dan transkripsi yang bisa dipanggil API key Anda: type, endpoint, voices, voice_cloning, response_formats atau input_formats, dan pricing dalam kredit per satuan. Tambahkan ?type=speech atau ?type=transcription untuk menyaring.

status · code

400 · unsupported_capability

Model tidak melayani endpoint ini, misalnya model transkripsi di /v1/audio/speech, atau model chat tanpa output audio yang diminta menjawab dengan suara.

400 · unsupported_parameter

Parameter tidak didukung, misalnya response_format wav di speech, srt di transkripsi, instructions, stream_format, atau stream pada transkripsi. error.param menyebut namanya.

400 · invalid_parameter

Nilai tidak valid: voice di luar daftar model, speed, language, temperature, timestamp_granularities tanpa verbose_json, atau output audio di chat tanpa stream: true.

400 · missing_required_parameter

model, input, file, atau input_audio tidak dikirim.

400 · invalid_audio

Isi file bukan audio yang dikenali, atau base64 rusak.

400 · unsupported_audio_formattranskripsi

File audio dikenali tetapi formatnya tidak diterima penyedia transkripsi, misalnya AIFF.

400 · invalid_multipart

Body multipart rusak, field teks berisi file, atau terlalu banyak field.

413 · request_too_large

Upload lebih dari 25 MB, body JSON lebih dari 16 MB, atau sampel suara lebih dari 15 MB.

415 · unsupported_media_typetranskripsi

Body bukan multipart/form-data atau JSON.

402 · insufficient_quota

Saldo tidak cukup untuk kredit yang harus ditahan.

403 · model_not_found, model_not_permitted

Model tidak terdaftar, tidak aktif, atau di luar tier Anda.

409 · idempotent_replay

Idempotency-Key sudah dipakai untuk request yang sama. Gateway tidak menyimpan audio atau transkrip; kirim key baru.

409 · idempotency_key_reused

Idempotency-Key sudah dipakai untuk request dengan isi berbeda.

429 · rate_limit_exceeded, provider_rate_limited

Terlalu banyak request, di gateway atau di penyedia. Ikuti header retry-after. Tidak ada kredit yang dipotong.

502 · generation_failed

Penyedia menjawab tanpa audio atau tanpa transkrip. Tidak ditagih kecuali penyedia menagihnya.

502 / 504 · provider_error, provider_timeout

Penyedia gagal atau tidak menjawab. Bila penyedia mungkin sudah memproses, kredit tetap ditahan sampai hasilnya pasti, lalu dikembalikan bila tidak ditagih.

503 · provider_unavailable, model_pricing_unavailable

Model sementara tidak bisa dilayani, atau tarifnya belum tersinkron. Ulangi beberapa saat lagi.

Dua satuan

Token

Dihitung provider dengan tokenizer model. Empat kelas: input baru, tulis cache, baca cache, dan output (termasuk reasoning). Gateway tidak mengubah angka token.

Kredit

Satuan saldo. Nilai dan pemakaian kredit dapat berbeda tergantung model yang digunakan serta pola penggunaan masing-masing user. Pemakaian dihitung berdasarkan jumlah token yang diproses dan harga atau multiplier token pada setiap model. Multiplier di katalog dinyatakan dalam kredit per token. Semua nominal di API dalam kredit.

provider_costnormal

Provider melaporkan biaya request. Tagihan adalah biaya itu dalam kredit (contoh di atas: 7.790). Selisih terhadap harga tabel dicatat sebagai pricing_adjustment_credits (−10).

token_fallbackestimasi

Provider tidak melaporkan biaya yang kredibel. Tagihan adalah harga tabel, maksimal sebesar kredit yang di-hold. is_estimate bernilai true; nilai final ada di GET /v1/generation.

complimentarygratis

Paket free trial pada model free-trial. Semua kelas kredit 0; token tetap dicatat.

Field usage berikut ada di response non-streaming dan di chunk terakhir response streaming.

usage

prompt_tokensnumber

Total token input, termasuk token cache.

completion_tokensnumber

Total token output, termasuk token reasoning.

total_tokensnumber

prompt_tokens + completion_tokens.

prompt_tokens_details.cached_tokensnumber

Token input yang dibaca dari cache.

prompt_tokens_details.cache_write_tokensnumber

Token input yang ditulis ke cache. Tidak semua provider melaporkannya.

completion_tokens_details.reasoning_tokensnumber

Token reasoning, bagian dari completion_tokens. Hanya ada jika provider melaporkannya.

costnumber

Total kredit yang ditagih. Menggantikan field cost provider yang berdenominasi USD.

cost_detailsobject

Kredit per kelas token, pricing_adjustment_credits, billing_source, dan is_estimate. Lihat Token vs kredit.

balance.beforenumber

Saldo tepat sebelum request ini menahan kredit.

balance.afternumber

before dikurangi cost. Berbeda dari saldo di ledger hanya jika request lain milik Anda settlement di antaranya.

balance.reserved_creditsnumber

Kredit yang ditahan untuk request ini. Dilepas saat settlement.

x-yupiai-request-idselalu

ID request gateway (UUID), ada di setiap response sukses termasuk streaming. Dipakai di GET /v1/generation?id=.

x-yupiai-costnon-streaming

Total kredit sebagai string desimal. Tidak ada pada response streaming karena biaya belum diketahui saat header dikirim.

Autentikasi dengan API key di header Authorization: Bearer, x-api-key, atau api-key. Tidak ada parameter.

data

total_creditsnumber

Total kredit pada siklus pembelian saat ini.

total_usagenumber

Kredit yang sudah keluar dari siklus ini, termasuk yang sedang ditahan.

remaining_creditsnumber

Saldo yang bisa dipakai. total_credits dikurangi total_usage.

reserved_creditsnumber

Bagian total_usage yang ditahan untuk request yang belum settlement.

pending_requestsnumber

Jumlah request yang masih menahan kredit.

tierstring

Paket aktif: free_trial, starter, pro, business, atau user (tanpa paket).

expires_atstring | null

Akhir masa aktif paket, ISO 8601.

cycle_started_atstring | null

Awal siklus pembelian saat ini.

is_expiredboolean

true jika masa aktif sudah lewat. Endpoint ini tetap bisa dibaca; inference ditolak dengan 403.

Autentikasi dengan API key yang ingin diperiksa, di header Authorization: Bearer, x-api-key, atau api-key. Tidak ada parameter.

data

idstring

ID key (UUID). Nilai untuk parameter api_key di /v1/usage.

labelstring

Nama key yang diberikan di Dashboard.

key_prefixstring

12 karakter pertama key. Key lengkap tidak pernah dikembalikan.

created_atstring

Waktu key dibuat, ISO 8601.

limitnull

Selalu null. Tidak ada batas pengeluaran per key; batasnya adalah saldo akun.

limit_resetnull

Selalu null.

limit_remainingnumber

Kredit yang masih bisa dipakai key ini: saldo akun, atau 0 jika paket kedaluwarsa.

usagenumber

Kredit yang dipakai key ini sepanjang masa. Request yang di-refund tidak dihitung.

usage_dailynumber

Kredit sejak 00:00 UTC hari ini.

usage_weeklynumber

Kredit sejak Senin 00:00 UTC minggu ini.

usage_monthlynumber

Kredit sejak tanggal 1 pukul 00:00 UTC bulan ini.

is_free_tierboolean

true jika akun tidak memiliki paket berbayar (starter, pro, business).

balancenumber

Saldo akun saat ini. Sama dengan remaining_credits di /v1/credits.

tierstring

Paket aktif akun pemilik key.

expires_atstring | null

Akhir masa aktif paket, ISO 8601.

is_expiredboolean

true jika masa aktif sudah lewat.

requestsnumber

Jumlah request key ini sepanjang masa. requests_daily, requests_weekly, dan requests_monthly memakai jendela yang sama dengan usage_*.

last_used_atstring | null

Waktu settlement request terakhir key ini. null jika belum pernah dipakai.

Default 30 hari terakhir. Hanya request yang sudah settlement yang dihitung. Request yang ditolak sebelum reservasi (key tidak valid, kredit habis, model tidak ada) tidak tercatat.

fromstringopsional

Awal rentang, ISO 8601 atau YYYY-MM-DD (UTC). Default 30 hari sebelum to.

tostringopsional

Akhir rentang. Nilai YYYY-MM-DD mencakup hari itu secara penuh. Default sekarang. Rentang maksimal 93 hari.

datestringopsional

Satu hari UTC (YYYY-MM-DD). Mengabaikan from dan to.

modelstringopsional

Satu Model ID, misalnya yupiai-glm5.2.

providerstringopsional

Satu provider sesuai nama yang dilaporkan upstream, misalnya Anthropic.

api_keystring (UUID)opsional

Satu key milik Anda, memakai id dari GET /v1/key. Key milik akun lain menghasilkan 404.

summary

requestsnumber

Request yang sudah settlement dalam rentang waktu.

successful_requestsnumber

Request dengan outcome completed.

failed_requestsnumber

Request dengan outcome error (ditolak provider setelah reservasi).

cancelled_requestsnumber

Request dengan outcome cancelled (stream diputus client).

unknown_requestsnumber

Request yang settlement-nya dilakukan proses pemulihan tanpa mengetahui akhirnya.

streamed_requestsnumber

Request dengan stream: true.

prompt_tokensnumber

Total token input, termasuk token cache.

cached_tokensnumber

Token input yang dibaca dari cache.

cache_write_tokensnumber

Token input yang ditulis ke cache.

completion_tokensnumber

Total token output, termasuk token reasoning.

reasoning_tokensnumber

Token reasoning, bagian dari completion_tokens.

total_tokensnumber

prompt_tokens + completion_tokens.

creditsnumber

Total kredit yang ditagih.

average_credits_per_requestnumber

credits dibagi requests.

cost_detailsobject

Total kredit per kelas token (input_credits, cache_write_credits, cache_read_credits, output_credits, pricing_adjustment_credits) serta estimated_requests dan complimentary_requests.

average_latency_msnumber | null

Rata-rata waktu dari request dikirim ke provider sampai response selesai.

field lain

from, tostring

Rentang yang dipakai, ISO 8601, setelah default diterapkan.

filtersobject

model, provider, dan api_key yang diterapkan. null jika tidak difilter.

pendingobject

Request yang masih menahan kredit dalam rentang ini: requests dan reserved_credits. Belum masuk summary.

Baris diurutkan dari tanggal terbaru. Field usage adalah kredit. Key digabung kecuali difilter dengan api_key.

data[]

datestring

Hari UTC, YYYY-MM-DD.

modelstring

Model ID.

provider_namestring | null

Provider yang melayani request. null untuk request sebelum kolom ini ada.

requestsnumber

Jumlah request yang settlement.

prompt_tokens, completion_tokens, reasoning_tokens, cached_tokens, cache_write_tokensnumber

Total token per kelas, sama dengan summary di /v1/usage.

usagenumber

Total kredit untuk hari, model, dan provider tersebut.

Parameter id menerima header x-yupiai-request-id (ada di setiap response), field id response Chat Completions (gen-...), atau id response non-streaming Anthropic (msg_...) dan Responses (resp_...).

data

idstring

ID request gateway. Sama dengan header x-yupiai-request-id.

generation_idstring | null

ID generasi di sisi provider (gen-...). null jika request gagal sebelum diterima provider.

api_keystring

ID key yang dipakai.

model, provider_namestring

Model ID dan provider yang melayani request.

statusstring

pending, settled, atau refunded. Selama pending, total_cost dan cost_details bernilai null.

outcomestring | null

completed, cancelled, error, atau unknown. Field cancelled bernilai true untuk outcome cancelled.

streamed, latencyboolean | null, number | null

Request streaming atau tidak, dan durasi dalam milidetik dari dikirim ke provider sampai response selesai.

tokens_prompt, tokens_completionnumber | null

Token input total dan token output, sesuai laporan provider.

native_tokens_cached, native_tokens_cache_write, native_tokens_reasoningnumber | null

Token baca cache, tulis cache, dan reasoning.

total_costnumber | null

Kredit yang ditagih.

cost_detailsobject | null

Kredit per kelas token, pricing_adjustment_credits, billing_source, dan is_estimate. Sama dengan response inference.

reserved_creditsnumber

Kredit yang ditahan saat request dimulai.

balance_before, balance_afternumber | null

Saldo tepat sebelum hold dan tepat setelah settlement, dari ledger.

is_complimentary, is_refunded, billing_review_requiredboolean

Request free trial, request yang di-refund admin, dan request yang sedang ditinjau tim YupiAI.

status · code

401 · missing_api_key

Tidak ada API key di header Authorization, x-api-key, atau api-key.

401 · invalid_api_key

Prefix bukan yupi_ai_ (atau rk_live_ lama), key tidak ditemukan, key dicabut (revoked), atau akun dinonaktifkan. Pesan menyebutkan alasannya.

402 · insufficient_quotainference

Saldo tidak cukup untuk menahan kredit request. Tidak ada yang dipotong.

403 · subscription_expiredinference

Masa aktif paket sudah lewat. Endpoint pembacaan tetap menjawab 200 dengan is_expired: true.

400 · invalid_queryusage, activity

from, to, atau date tidak valid; rentang lebih dari 93 hari; to tidak lebih akhir dari from; atau model, provider, api_key bukan pengenal yang valid. error.param menyebut parameternya.

400 · missing_required_parametergeneration

Parameter id kosong.

404 · not_foundusage, generation

api_key atau id tidak ada pada akun ini.

429 · rate_limit_exceeded

Endpoint pembacaan dibatasi 30 request per menit per akun dan mengirim header retry-after: 10. Inference memakai limiter terpisah.

502 · gateway_unavailable

Ledger tidak dapat dihubungi. Ulangi beberapa detik kemudian. Endpoint pembacaan tidak menjawab dengan angka nol.