Dokumentasi seamless.ai.id

Mulai dalam empat langkah

1. Minta API key ke operator (pendaftaran mandiri belum dibuka).
2. Simpan API key pertama Anda: key hanya ditampilkan sekali.
3. Isi saldo dengan QRIS dari dashboard, lalu coba model di Playground dashboard tanpa menulis kode.
4. Ikuti panduan untuk alat Anda: curl, Python (SDK OpenAI), JavaScript / TypeScript (SDK OpenAI), LangChain, n8n.

Model yang tersedia: 3 model chat, 1 model embedding. Harga, konteks, dan kemampuan setiap model ada di daftar model, juga sebagai JSON di /pricing.

Saldo dalam rupiah: isi, tahan, tagih

1. Isi saldo. Top-up dibayar dengan QRIS dari aplikasi bank atau e-wallet apa pun; saldo bertambah begitu pembayaran diterima dan kuitansi terbit. Jumlah minimum dan maksimum, bonus yang berlaku, dan cara PPN dihitung tampil di dashboard sebelum Anda membayar dan di halaman harga.
2. Tahan. Sebelum request diteruskan ke provider, gateway menahan batas atas biayanya dari saldo: seluruh body dihitung seolah setiap byte satu token prompt, ditambah max_tokens token jawaban (tanpa max_tokens, batas bawaan model), dengan harga tertinggi yang bisa berlaku selama request berjalan. Kalau saldo yang tersedia tidak cukup, request ditolak sebelum dikirim. Mengisi max_tokens membuat yang ditahan lebih kecil.
3. Tagih. Setelah jawaban selesai, yang ditagih adalah token yang dilaporkan provider dengan harga provider yang menjawab, dan sisa yang ditahan kembali ke saldo. Tagihan tidak pernah melebihi yang ditahan. Request yang gagal sebelum ada isi jawaban tidak ditagih. Kalau provider tidak melaporkan jumlah token (misalnya stream dihentikan sebelum laporan pemakaian), jumlahnya diperkirakan dari ukuran prompt dan jawaban yang sudah terkirim; untuk penalaran yang tidak terlihat (thinking model Anthropic) yang ditagih adalah seluruh batas jawaban.

Model berharga Gratis tidak memakai saldo. Harga token ditulis per 1 juta token; model pembuat gambar, transkripsi suara, dan teks ke suara dihargai per gambar, per jam audio, atau per 1 juta karakter, dan sebagian model rerank per 1.000 pencarian (lihat di bawah). Saldo, yang sedang ditahan, pemakaian per hari, dan daftar request tampil di dashboard atau lewat GET /v1/balance, /v1/usage, dan /v1/requests. Isi prompt dan jawaban (termasuk audio, transkrip, dan gambar yang dibuat) tidak pernah kami simpan, hanya metadata (model, jumlah token, gambar, detik audio, karakter, atau pencarian, biaya). Satu-satunya pengecualian adalah Batch API: file JSONL yang Anda unggah ke /v1/files dan hasil setiap barisnya kami simpan sampai Anda menghapusnya (DELETE /v1/files/{id}) atau masa simpannya habis.

API key dan scope

Setiap key memegang satu atau beberapa scope:

• Key pertama dari pendaftaran memegang ketiganya. Untuk aplikasi, buat key sendiri yang hanya ber-scope inference (dashboard, atau POST /v1/keys dengan key admin), supaya key yang bocor tidak bisa mengubah akun.
• Key bisa diberi batas belanja per bulan (WIB) atau seumur key, dan routing default (misalnya hanya provider yang tidak melatih model dengan prompt).
• Key hanya tampil sekali saat dibuat; gateway menyimpan hash-nya saja. Key yang dicabut langsung berhenti bekerja.
• Tim: akun bisa punya anggota (pemilik, admin, developer, penagihan) dengan key masing-masing, dan admin bisa memberi developer anggaran rupiah per bulan untuk semua key-nya bersama-sama (panel Anggota di dashboard); request yang melewatinya ditolak sebelum dikirim (lihat batas).

Responses API

POST /v1/responses menerima format Responses API OpenAI untuk setiap model chat, jadi SDK dan framework agent yang memanggil responses.create bisa memakai model mana pun di sini. Gateway menerjemahkannya ke chat completions: routing, fallback, harga, saldo yang ditahan, dan tagihannya sama persis dengan request chat yang sama, dan usage di jawaban adalah token yang ditagih.

• Tanpa penyimpanan: jawaban tidak disimpan di server. Kirim seluruh percakapan di input, termasuk item output jawaban sebelumnya. previous_response_id, conversation, prompt, store: true, dan background: true ditolak 400; tanpa store, jawaban menulis "store": false.
• Input: teks, item message (peran user, assistant, system, atau developer, yang dikirim sebagai system; bagian input_text, output_text, dan input_image berupa URL atau data URL ke model dengan badge input gambar), function_call, dan function_call_output (teks). Item reasoning jawaban sebelumnya diterima tetapi tidak dikirim ulang ke model. File (input_file, file_id), item_reference, dan item tool bawaan ditolak.
• Tool: hanya tool function, dengan tool_choice none, auto, required, atau satu fungsi. Tool bawaan (web search, file search, code interpreter, image generation, MCP, computer, shell) tidak dijual dan ditolak 400 unsupported_value.
• Format dan penalaran: text.format (text, json_object, json_schema), text.verbosity, dan reasoning.effort diteruskan seperti di chat. Diabaikan karena tidak mengubah jawaban maupun tagihan: reasoning.summary, include: ["reasoning.encrypted_content"], max_tool_calls, dan stream_options.include_obfuscation; metadata hanya dikembalikan di jawaban.
• Jawaban: item reasoning (teks penalaran, kalau model mengirimnya), message, dan function_call. max_output_tokens membatasi jawaban dan saldo yang ditahan; jawaban yang terpotong berstatus incomplete. Stream mengirim event response.created sampai response.completed; stream yang putus diakhiri response.failed dan tetap ditagih untuk bagian yang sudah terkirim, seperti chat.

Batas

• Request per menit dan request bersamaan per key ditetapkan operator. Kalau tercapai: 429 rate_limit_exceeded dengan header Retry-After, yang diulang otomatis oleh SDK OpenAI.
• Saldo, batas belanja key, anggaran anggota: request yang bisa melewatinya ditolak sebelum dikirim, 429 insufficient_quota dengan x-should-retry: false (SDK OpenAI tidak mengulangnya); code-nya insufficient_quota, key_spend_limit_reached, atau member_budget_reached, dan pesannya menyebut sisa dan kapan diperbarui.
• Ukuran request: body yang terlalu besar dijawab 413 request_too_large.
• Konteks dan jawaban: panjang konteks dan batas jawaban setiap model tertulis di halaman modelnya.

Error

Setiap error berformat OpenAI:

{"error": {"message": "…", "type": "invalid_request_error", "param": "model", "code": "model_not_found"}}

Kondisi setiap model sekarang, riwayat 90 hari, dan insiden yang diumumkan ada di halaman status. Setiap jawaban membawa header x-request-id; sebutkan saat menghubungi operator.

Memilih provider dan membatasi harga

Satu model bisa dilayani beberapa provider dengan harga dan kebijakan data masing-masing (tertulis di halaman model). Tanpa pengaturan, gateway memilih sendiri dan pindah ke provider lain kalau satu gagal. Request ditagih dengan harga provider yang menjawab, paling tinggi harga "hingga" model itu. Pengaturannya dikirim di body sebagai gateway.routing (SDK Python dan LangChain: extra_body):

• order: provider yang dicoba lebih dulu; only: hanya provider ini; exclude: jangan provider ini; fallback: false: paling banyak satu percobaan.
• data_policy: "no_training" (provider tidak melatih model dengan prompt) atau "zero_retention" (provider tidak menyimpan apa pun).
• max_price: {"input_idr_per_mtok": 5000, "output_idr_per_mtok": 15000}, rupiah utuh per 1 juta token. Provider di atas batas tidak dipakai; kalau tidak ada yang muat, request ditolak 400 price_above_max sebelum saldo ditahan. Hanya untuk harga per token: request ke model pembuat gambar atau transkripsi yang membawa max_price, atau dikirim dengan key yang routing default-nya memuat max_price, ditolak 400 max_price_not_applicable.
• sort: "latency": provider tercepat (waktu ke token pertama) lebih dulu.

Harga "mulai" di halaman model hanya dijamin dengan only (atau order + fallback: false) ke provider termurah, atau max_price setinggi harga itu. Admin akun bisa memasang pengaturan yang sama sebagai routing default sebuah key; request hanya bisa memperketatnya.

Input gambar

Model dengan badge Input gambar menerima bagian image_url di pesan user: data URL base64 (data:image/png;base64,…) atau URL https:// yang diambil penyedia model (gateway tidak pernah membukanya; URL ke alamat IP atau nama internal ditolak). Format JPEG, PNG, GIF, atau WebP, dikenali dari isi byte-nya; detail boleh auto, low, high, atau original. Operator membatasi jumlah dan ukuran gambar per request; yang melanggar dijawab 400 invalid_image dengan param yang menunjuk gambarnya. Saldo yang ditahan menghitung setiap gambar dengan batas token terbanyak per gambar model itu; tagihannya tetap dari token yang dilaporkan penyedia. Contoh kode ada di setiap panduan.

Gambar, transkripsi, teks ke suara, dan rerank

• POST /v1/images/generations (JSON): prompt (wajib), n (1–10, bawaan 1), size dan quality (salah satu yang tertulis di halaman model; tanpa keduanya dipakai bawaan model, auto ditolak), response_format (url atau b64_json, kalau model menerimanya). Harga per gambar menurut ukuran dan kualitas, ditambah token teks prompt dengan harga input model itu.
• POST /v1/audio/transcriptions (multipart): file (flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, atau webm), model, language, prompt, temperature, response_format (json, text, atau verbose_json). Harga per jam audio, ditagih per detik dari durasi yang dilaporkan provider, dibulatkan ke atas sekali per request; sebagian provider menagih minimal beberapa detik (tertulis di halaman model). Berkas di atas batas ukuran operator dijawab 413 request_too_large.
• POST /v1/audio/speech (JSON): input (wajib, paling banyak sepanjang konteks model, dalam karakter), voice (wajib, salah satu yang tertulis di halaman model), response_format (format audio yang tertulis di halaman model; tanpa itu format bawaannya), speed (0,25–4, kalau model menerimanya). Jawabannya audio yang dikirim sambil dibuat. Harga per 1 juta karakter input; satu karakter adalah satu kode Unicode (huruf, angka, spasi, tanda baca, atau emoji masing-masing satu). Jumlah karakter sudah pasti sebelum dikirim, jadi yang ditahan sama dengan yang ditagih.
• POST /v1/rerank (JSON): query (wajib), documents (wajib, 1–1.000 teks), top_n (jumlah hasil teratas), return_documents (sertakan teks dokumen di hasil). Jawaban: results berisi index, relevance_score, dan document, dari yang paling relevan, plus usage yang ditagih. Model per token menagih token yang dilaporkan provider (kueri dihitung sekali untuk setiap dokumen, ditambah semua dokumen); model per pencarian menagih pencarian yang dilaporkan provider (satu kueri dengan sampai 100 dokumen; dokumen panjang dihitung per potongan). Saldo yang ditahan adalah batas atasnya: setiap byte dihitung satu token.
• Tahan dan tagih. Sebelum dikirim, gateway menahan n gambar dengan harga varian itu yang tertinggi di antara provider yang bisa menjawab (ditambah token prompt), atau untuk audio durasi terpanjang yang mungkin untuk ukuran berkasnya. Yang ditagih adalah gambar yang dikembalikan provider atau detik audio yang dilaporkannya, dengan harga provider yang menjawab, tidak pernah lebih dari yang ditahan. Kalau hasilnya tidak bisa dipastikan setelah request diterima provider (koneksi Anda terputus, waktu habis), yang ditagih jumlah yang diminta: n gambar, atau untuk audio durasi yang ditahan. Teks ke suara ditagih karakternya begitu provider menerima request, walaupun audionya terputus; rerank yang hasilnya tidak bisa dipastikan ditagih perkiraan dari ukuran kueri dan dokumen (4 byte per token). Request yang ditolak provider (error) tidak ditagih dan boleh dicoba ke provider berikutnya.
• max_price tidak berlaku untuk harga per unit (juga rerank per pencarian; rerank per token tetap dibatasi max_price): request atau key dengan max_price ditolak 400 max_price_not_applicable. Preferensi only, order, exclude, dan data_policy berlaku seperti biasa. Model pembuat gambar, transkripsi, teks ke suara, dan rerank hanya dipanggil lewat endpoint-nya sendiri (400 unsupported_model).

Saat ini tidak ada model pembuat gambar, transkripsi suara, teks ke suara, atau rerank di daftar harga.

Moderation

• POST /v1/moderations (JSON, seperti OpenAI): model dan input, yaitu satu teks, daftar sampai 256 teks (satu hasil per teks), atau daftar bagian {"type": "text", "text": ...} dan {"type": "image_url", "image_url": {"url": ...}} (satu hasil untuk semuanya; gambar hanya di model yang input_modalities-nya memuat image, URL http(s) atau data URL base64). Field lain ditolak 400.
• Satu bentuk jawaban. Provider mana pun yang menjawab, setiap hasil memuat 13 kategori OpenAI (harassment, harassment/threatening, hate, hate/threatening, illicit, illicit/violent, self-harm, self-harm/instructions, self-harm/intent, sexual, sexual/minors, violence, violence/graphic) di categories (true/false), category_scores (skor), dan category_applied_input_types. Kategori yang tidak dinilai provider bernilai false dengan skor 0 dan daftar jenis input yang kosong: periksa daftar itu sebelum menganggap teks aman untuk kategori tersebut. flagged true kalau salah satu dari 13 kategori true.
• Kategori khusus provider yang tidak punya padanan (Mistral: pii, health, financial, law, jailbreaking) ada di other_categories dan other_category_scores dengan nama dari provider, dan tidak ikut flagged.
• Pemetaan Mistral: sexual → sexual, hate_and_discrimination → hate, violence_and_threats → violence, dangerous_and_criminal_content (atau dangerous dan criminal) → illicit (skor tertinggi), selfharm → self-harm. Satu kategori provider tidak pernah diisikan ke beberapa kategori OpenAI. Jawaban OpenAI diteruskan dengan kategorinya sendiri (null dibaca false).
• Harga dan batas. Model moderation dihargai per 1 juta token input seperti embedding, dan banyak yang gratis: model gratis tidak butuh saldo, tetapi setiap akun dibatasi jumlah request per menit ke model gratis (429 rate_limit_exceeded dengan Retry-After). Model berbayar menahan setiap byte teks sebagai satu token dengan harga provider termahal yang bisa menjawab, lalu menagih token yang dilaporkan provider, atau perkiraan 4 byte per token kalau provider tidak melaporkannya (usage di jawaban menyebut angka yang dihitung). Request yang hasilnya tidak bisa dipastikan setelah diterima provider ditagih perkiraan itu dan tidak dikirim ke provider lain; koneksi yang gagal dibuat dan jawaban error provider tidak ditagih.

Saat ini tidak ada model moderation di daftar harga.