---
name: kaien-api
description: Use when an agent needs to configure, integrate, or generate code for Kaien API, an OpenAI-compatible API service at https://kaienapi.com. Use for OpenAI SDK base URL setup, API key authentication, model discovery, Chat Completions, Responses, Claude Messages, Gemini native APIs, image generation and editing, video generation tasks, audio, files, embeddings, rerank, moderation, billing usage, and AI tool integration. Also use when choosing the correct Kaien endpoint, reading Kaien API Reference, or avoiding unsafe paid API calls.
---

# Kaien API

Use this as the first context file for agent-assisted Kaien API integration.

## Base URL and authentication

- Base URL: `https://kaienapi.com`
- Default authentication: `Authorization: Bearer <YOUR_API_KEY>`
- Claude native clients may use `x-api-key`.
- Gemini native clients may use `x-goog-api-key` or `?key=`.
- Keep real API keys out of frontend code, logs, screenshots, prompts, and committed files.

## Required workflow

1. Read this file first.
2. Query or ask the user to query `GET /v1/models` before hard-coding model names.
3. Choose the endpoint from the routing table below.
4. Read the relevant guide or API Reference page before writing final integration code.
5. Start with a minimal request and inspect the actual response shape.
6. For task-based media APIs, save the task ID and poll until a terminal state.
7. Run real paid API calls only after the user explicitly confirms the API key, model, cost-bearing action, and test payload.

## Endpoint routing

| Task | Prefer | Read next |
|---|---|---|
| List available models | `GET /v1/models` | `/docs/en/quickstart/models.md` |
| OpenAI-style chat | `POST /v1/chat/completions` | `/docs/en/api-reference/overview` -> Chat Completions |
| OpenAI Responses | `POST /v1/responses` | `/docs/en/api-reference/overview` -> Responses |
| Claude native messages | `POST /v1/messages` | `/docs/en/api-reference/overview` -> Claude Messages |
| Gemini native payloads | `/v1beta/models/{model}:generateContent` | `/docs/en/api-reference/overview` -> Gemini native APIs |
| Standard image generation/editing | `/v1/images/generations`, `/v1/images/edits` | `/docs/en/images-video/images.md` |
| GPT Image 2 | image async jobs first | `/docs/en/images-video/gpt-image-2.md` |
| Agent-assisted GPT Image 2 generation | install `kaien-gpt-image-2` with `npx skills` | `/docs/en/ai/agent-image-generation.md` |
| Upload a local reference image | `POST /v1/files` with `purpose=vision`, then read `url` | `/docs/en/api-reference/overview` -> Files |
| Gemini image models | `POST /v1/images/generations/jobs` or synchronous `/v1/images/generations` | `/docs/en/images-video/gemini-image-preview.md` |
| Video generation | `/v1/video/generations` or `/v1/videos` | `/docs/en/images-video/video-tasks.md` |
| Audio transcription, translation, or speech | `/v1/audio/*` | `/docs/en/api-reference/overview` -> Audio |
| Files | `/v1/files` | `/docs/en/api-reference/overview` -> Files |
| Embeddings | `POST /v1/embeddings` | `/docs/en/api-reference/overview` -> Embeddings |
| Reranking | rerank API | `/docs/en/api-reference/overview` -> Rerank |
| Moderation | `POST /v1/moderations` | `/docs/en/api-reference/overview` -> Moderation |
| Billing and usage | dashboard billing APIs | `/docs/en/quickstart/billing-usage.md` |

## Media task rules

- Treat image jobs, video generation, Midjourney, Suno, and other media generation as cost-bearing task APIs.
- When an image job only accepts network URLs, upload each local reference image through `POST /v1/files` and put the returned public `url` into the image request.
- Persist `id`, `task_id`, or `video_id` with the model, request summary, creation time, status, and result URLs.
- Poll with backoff and stop only on terminal states such as `succeeded`, `failed`, `completed`, or `canceled`.
- Do not create a duplicate task just because one poll fails.
- Copy downloaded images, videos, or audio that need long-term access to the user's own object storage.

## Common mistakes to avoid

- For Gemini image generation, submit `model`, `prompt`, optional reference `image` URLs, `aspect_ratio`, and `image_size` to `/v1/images/generations/jobs`; poll the returned job ID for `data` results.
- Do not assume media creation returns the final asset immediately; many endpoints return a task object first.
- Do not parse video download responses as JSON; video content endpoints return binary data.
- Do not invent model IDs. Use `/v1/models` or a model name provided by the user.
- Do not expose API keys in browser bundles. Route production calls through a server if the client is public.
- Do not truncate usage or price precision to two decimals unless the UI explicitly requires rounded display.

## Response handling

- Chat text is usually in `choices[0].message.content`.
- Responses output may be an output array; inspect the returned structure.
- Image results may contain URLs, base64, or task IDs.
- Video and music results usually require polling before final URLs or binary downloads are available.
- Surface error responses with the upstream message and the request's model, endpoint, and task ID when available.

## Documentation entry points

- Human docs: `https://kaienapi.com/docs/en`
- This skill file: `https://kaienapi.com/docs/en/skill.md`
- API Reference overview: `https://kaienapi.com/docs/en/api-reference/overview`
- Markdown pages: append `.md` to a docs page path, for example `/docs/en/images-video/video-tasks.md`.
- The current self-hosted docs do not provide a dynamic Mintlify MCP endpoint. Treat `/docs/en/mcp` as boundary documentation, not a live MCP server.