# Kiosapi.id

> OpenAI-compatible AI API gateway and creative studio for Indonesian developers and creators. One API key gives access to many text models (GPT, Claude, Gemini, DeepSeek, Llama, Qwen, MiniMax, and more) plus image, video, music (full vocal songs), and text-to-speech generation (Imagen, Veo, Nano Banana, Wan, Hailuo, Lyria, MiniMax Music). Pay-as-you-go from a prepaid Indonesian Rupiah balance. Operated by PT Mura Teras Kreatif.

## Getting started
- Base URL (OpenAI-compatible): https://api.kiosapi.id/v1
- Anthropic-style base URL (for Claude Code): https://api.kiosapi.id
- Auth: HTTP header `Authorization: Bearer kios_live_...` — create a key at https://kiosapi.id/dashboard/keys
- Text is 100% OpenAI-compatible: use any OpenAI SDK, just set base_url + api_key. The model id is e.g. `openai/gpt-4o`, `anthropic/claude-sonnet-4-6`, `google/gemini-3.1-pro`, `deepseek/deepseek-v4-pro`, `meta/llama-3.1-8b`.

## Text (chat) — OpenAI-compatible
- `POST /v1/chat/completions` — standard OpenAI Chat Completions; supports `"stream": true` (SSE).
- `GET /v1/models` — list available models. Each entry has `id`, `kind` ("text" | "image" | "video" | "music" | "audio"), `tier`, `provider`; media models also include `media: { unit, options: [<valid option keys>] }` so you can discover valid `option` values programmatically.

## Image generation (synchronous, billed per image)
- `POST /v1/images/generations`
- Body: `{ "model": "<image model id>", "prompt": "...", "option": "<tier key>", "n": 1, "aspect_ratio": "1:1" }` (n = 1..4)
- Image models and their `option` keys:
  - `openai/gpt-image-1`: 1024x1024:low | 1024x1024:medium | 1024x1024:high | 1536x1024:medium | 1024x1536:medium
  - `google/imagen-3`: standard
  - `google/imagen-3-fast`: standard
  - `google/nano-banana-2`: standard
  - `alibaba/wan-2.7-image-pro`: standard
  - `minimax/image-01`: standard
- Response 200: `{ "created", "model", "data": [{ "b64_json": "<base64>", "mime": "image/png" }], "kiosapi": { "option", "count", "cost_rupiah" } }`
- The image bytes are base64 in `data[].b64_json` — decode and save them.

## Video generation (asynchronous job, billed per second or per clip)
- `POST /v1/videos/generations` → 202 `{ "job_id", "status": "running", "poll_url", "estimate_rupiah" }`
- Body: `{ "model": "<video model id>", "prompt": "...", "option": "<resolution>", "duration_seconds": 5, "aspect_ratio": "16:9", "image": "<base64, image-to-video only>", "image_mime": "image/png" }` (duration 1..12)
- Video models and their `option` keys:
  - `google/veo-3`: 720p | 1080p (billed per second)
  - `alibaba/wan2.7-t2v`: standard (per second)
  - `alibaba/happyhorse-1.0-t2v`: standard (per second)
  - `alibaba/wan2.7-i2v`: standard (image-to-video; requires `image`; per second)
  - `minimax/hailuo-2.3`: 768p-6s | 768p-10s | 1080p-6s (billed PER CLIP — the option key fixes resolution + duration; `duration_seconds` is ignored)
- Poll: `GET /v1/jobs/:id` → `{ "status": "running" }` | `{ "status": "succeeded", "video_url", "expires_at", "cost_rupiah" }` | `{ "status": "failed", "error" }`
- When succeeded, download the clip from `video_url` (also available at `GET /v1/jobs/:id/video`). Poll every ~5s. Finished videos are also auto-saved to your dashboard gallery.
- Optional `callback_url` (API-key auth, public https): POSTed once on job.succeeded/job.failed, signed with `X-Kiosapi-Signature` (HMAC-SHA256; secret = hex SHA-256 of your API key).

## Music generation (sync clip, or async vocal-song job — billed per clip/song)
- `POST /v1/music/generations`
- Body: `{ "model": "<music model id>", "prompt": "<genre, mood, instruments, vocal character>", "lyrics": "<[Verse]/[Chorus] markers>", "is_instrumental": false, "option": "<tier key>" }`
- Music models and their `option` keys:
  - `google/lyria-2`: standard — 30s INSTRUMENTAL clip, SYNCHRONOUS: responds 200 with base64 WAV in `data[].b64_json` (same shape as images). Also accepts `negative_prompt` + `seed`.
  - `minimax/music-2.6`: song — FULL SONG WITH VOCALS up to ~5 minutes, ASYNC: responds 202 `{ "job_id", "poll_url", "estimate_rupiah" }`; poll `GET /v1/jobs/:id` until `{ "status": "succeeded", "audio_url", ... }` (renders in 1–3 min; poll every ~5s). Requires `lyrics`, or `lyrics_optimizer: true` (auto-writes ENGLISH lyrics regardless of prompt language — send your own `lyrics` for Indonesian), or `is_instrumental: true`. Supports `callback_url` like video. Finished songs are auto-saved to your dashboard gallery and downloadable at `GET /v1/jobs/:id/audio`.

## Text-to-speech (synchronous, billed per 1,000 input characters)
- `POST /v1/audio/speech` — OpenAI-compatible; returns RAW audio bytes (mp3 default). Cost + remaining balance in `X-Kiosapi-Cost-IDR` / `X-Kiosapi-Balance-IDR` response headers.
- Body: `{ "model": "<tts model id>", "input": "<text, max 8000 chars>", "voice": "<voice id>", "response_format": "mp3", "speed": 1.0 }`
- TTS models and voices:
  - `openai/tts-1`, `openai/tts-1-hd`: voices alloy | echo | fable | onyx | nova | shimmer
  - `minimax/speech-2.8-turbo`, `minimax/speech-2.8-hd`: system voice ids incl. 9 NATIVE INDONESIAN voices — Indonesian_CalmWoman (default) | Indonesian_ConfidentWoman | Indonesian_SweetGirl | Indonesian_GentleGirl | Indonesian_CharmingGirl | Indonesian_CaringMan | Indonesian_BossyLeader | Indonesian_ReservedYoungMan | Indonesian_DeterminedBoy, plus English voices

## Errors
JSON shape: `{ "error": { "message", "type", "code" } }`. Common codes:
- 401 authentication_error — invalid/missing key
- 400 model_not_found — unknown/hidden model; invalid_request_error — bad option
- 402 insufficient_balance — top up; spend_cap_reached — monthly cap hit
- 422 prompt_blocked / output_blocked — moderation; generation_refused — provider safety refusal
- 429 rate_limit_exceeded; abuse_throttled — temporary block after repeated moderation hits
- 504 generation_timeout; 502 upstream_unavailable

## Notes & policies
- Provider safety filters are always on; prompts and generated media are moderated.
- A free tier exists for selected text models (50 requests/day per verified-email account). Media generation is always paid (per image / per second / per clip / per 1,000 characters) from the prepaid Rupiah balance, charged on success only.
- Acceptable Use Policy: https://kiosapi.id/aturan-penggunaan

## More
- Machine-readable OpenAPI 3.1 spec: https://api.kiosapi.id/openapi.json (model ids + media `option` keys are generated from the live catalog, always in sync)
- Full documentation: https://kiosapi.id/docs
- Pricing and full model list: https://kiosapi.id/pricing