# APIKO

> APIKO is an AI API for supported text, image and video models. Compare model-specific pricing and availability, then call each model through its documented endpoint with one API key.

## Integration summary

- Control plane: `https://apiko.app` (account, keys, catalog, billing, usage, and documentation).
- OpenAI-compatible API base URL: `https://api.apiko.app/v1` (send model requests here, not to the control-plane origin).
- Authentication: `Authorization: Bearer $APIKO_API_KEY`.
- API keys: create one at https://apiko.app/dashboard/apikeys; the full `sk-...` value is shown once.
- Model discovery: browse https://apiko.app/models or call authenticated `GET https://api.apiko.app/v1/models`.
- Agent skills: `npx skills add https://apiko.app` installs `apiko-agents` (set up Claude Code, Codex, OpenCode, Kimi Code) and `apiko-api` (call models); index at https://apiko.app/.well-known/agent-skills/index.json.

## Quickstart

1. Create an account at https://apiko.app/sign-up, then create an API key at https://apiko.app/dashboard/apikeys.
2. Store the key in the `APIKO_API_KEY` environment variable. Never commit it or expose it in browser/mobile code.
3. Set your OpenAI client's base URL to `https://api.apiko.app/v1`.
4. Choose a model from https://apiko.app/models or authenticated `GET https://api.apiko.app/v1/models`. The authenticated endpoint is authoritative for which models that key can call.
5. Choose a chat-capable model returned for this key. If none are available, stop and consult the model documentation; do not guess an id or use a media model with a chat request.
6. Make a non-streaming `POST /chat/completions` request using the selected model id and its documented request format. For media, follow the task and polling guide.

### cURL

```bash
curl https://api.apiko.app/v1/chat/completions \
  -H "Authorization: Bearer $APIKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "'"$MODEL_ID"'", "messages": [{"role": "user", "content": "Hello"}], "stream": false}'
```

### JavaScript (OpenAI SDK)

```js
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.apiko.app/v1",
  apiKey: process.env.APIKO_API_KEY,
});

const response = await client.chat.completions.create({
  model: process.env.MODEL_ID,
  messages: [{ role: "user", content: "Hello" }],
  stream: false,
});

console.log(response.choices[0].message.content);
```

### Python (OpenAI SDK)

```python
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.apiko.app/v1",
    api_key=os.environ["APIKO_API_KEY"],
)

response = client.chat.completions.create(
    model=os.environ["MODEL_ID"],
    messages=[{"role": "user", "content": "Hello"}],
    stream=False,
)

print(response.choices[0].message.content)
```

## API behavior

- `POST https://api.apiko.app/v1/chat/completions` — chat completions; supports streaming.
- `POST https://api.apiko.app/v1/messages` — Anthropic Messages API, for Claude models only; other model ids return 503.
- `POST https://api.apiko.app/v1/responses` — OpenAI Responses API for GPT models. Send `input` (not `messages`, which returns 400 `input is required`). `previous_response_id` is accepted but has no effect (conversations are not stored) — send the full conversation in `input` each time.
- `GET https://api.apiko.app/v1/models` — models available to the supplied API key.
- `POST https://api.apiko.app/v1/images/generations` — JSON image generation for image-capable models.
- `POST https://api.apiko.app/v1/images/edits` — JSON image editing; reference images and masks must be public HTTPS URLs.
- Send `"async": true` on image POSTs to get a task id immediately (recommended; without it the request waits for the image and can hit proxy timeouts).
- `GET https://api.apiko.app/v1/tasks/:task_id` — owner-scoped status for image tasks; `GET https://api.apiko.app/v1/images/generations/:task_id` and `/images/edits/:task_id` remain available.
- Optional `callback_url` (public HTTPS) on media POSTs receives the finished task JSON; re-fetch the task to confirm it.
- Media is billed per call and refunded on failure. Results are Apiko-signed links stored for 24 hours; download anything you need to keep.
- Model ids and supported endpoint families vary. Confirm the model in the catalog and documentation instead of guessing from its name.
- Streaming uses server-sent events. Set `"stream": true` and read until `data: [DONE]`. With `"stream_options": {"include_usage": true}`, billed token usage arrives in a separate final chunk after the one with `finish_reason`; that chunk has an empty `choices` array. DeepSeek, GLM, Kimi and Grok return thinking in `delta.reasoning_content` (non-streaming: `message.reasoning_content`).
- One response returns at most 32,000 output tokens (16,000 while the account is on the free trial); larger `max_tokens` values are lowered to that cap.
- Thinking tokens and output limits differ by model family. GPT, GLM, Kimi and `deepseek-v4-pro` count thinking toward `max_tokens` (`max_output_tokens` on Responses); leave room for the visible answer, because a small limit can be spent entirely on thinking and return no text. On Gemini and Grok, thinking can be generated and billed beyond `max_tokens`, so do not rely on it to cap cost; check `usage.completion_tokens`.
- Reasoning level: GPT, Gemini, Grok, DeepSeek and GLM accept `reasoning_effort` (for example `low`) on Chat Completions; GPT also accepts `"reasoning": {"effort": "low"}` on Responses. For Claude, set `reasoning_effort` (`none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`) on Chat Completions, or `output_config.effort` / `thinking` on `POST /v1/messages`. `thinking` must be an object such as `{"type": "adaptive"}`; a string returns 400. Claude thinking counts toward `max_tokens` and is billed as output tokens even at lower levels.
- `claude-haiku-4-5`: `system`, `stop_sequences` and `reasoning_effort` are currently not guaranteed to take effect on every request; check the reply before relying on them.
- `model` in a response may be a versioned upstream name rather than the id you sent; log and reconcile by the id you sent.
- A non-streaming request that runs longer than about 100 seconds can end with HTTP 524 at the proxy while the model call is still billed. Stream long outputs and use `"async": true` for images.
- Chat Completions and Responses errors use the OpenAI error shape: `{"error":{"message","type","code"}}`. `POST /v1/messages` errors use the Anthropic shape `{"type":"error","error":{"type","message"}}`, with no `code`.

## Error handling

- `401` — the API key is missing, invalid, or revoked. Check the Bearer header.
- `402` / `403` with `insufficient_user_quota` — add credit in Dashboard → Billing, then retry.
- `503` with `model_not_found` (on `POST /v1/messages`: `not_found_error`, "No available channel for model …") — the model id is wrong or not available to this key. This is permanent: do not retry; check the id with `GET /v1/models`.
- `403` "This token has no access to model …" (or a message saying the free trial covers only some models) — the key belongs to a free-trial account and the model is outside the trial. Top up in Dashboard → Billing to unlock every model; do not retry unchanged.
- `429` — retry with exponential backoff and jitter; do not retry in a tight loop.
- Other `5xx` — the gateway already attempts provider failover. Use bounded retries; failed upstream calls are not billed. Do not retry a 503 `model_not_found`; it will not succeed.

## Billing

- Trial credit is not currently enabled. Add credit in Dashboard → Billing before making paid requests.
- Token-priced requests settle from the provider's real input/output token counts at the per-model prices on https://apiko.app/models. Image models use the listed per-call/tiered price.
- A pre-hold is taken when a request starts and adjusted at settlement; failed upstream calls are refunded automatically.
- Inspect exact request cost, token counts, and latency at https://apiko.app/dashboard/usage.

## Public control-plane APIs

- `GET https://apiko.app/api/public/models?billing=all` — public catalog with capabilities, status, context, and pricing. Optional filters: `search`, `provider`, `capability`, `status`, `billing`, `page`, `pageSize` (max 100).
- `GET https://apiko.app/api/public/models/<url-encoded-model-id>` — one public model.
- `GET https://apiko.app/api/public/status` — real model availability from customer calls. The response includes `availability`, `sampleCount`, 24 hourly tiers, `generatedAt`, and `dataSufficient`; availability is shown once a model has 20 or more counted samples, and a model with fewer samples and no recorded failure is `operational`.
- These control-plane APIs use `{ code, message, data }`; successful responses have `code: 0`. They are not OpenAI-compatible model inference endpoints.

## Security

- Keep API keys on a trusted server and load them from environment variables or a secret manager.
- Use a separate key per application. Apply a spending limit and model allow-list when available.
- Revoke and replace a key immediately if it may have leaked; revocation takes effect immediately.
- Never log the full key or include it in client-side bundles, screenshots, URLs, or support chats.

## Docs

- [API documentation](https://apiko.app/docs/introduction): overview of every documented endpoint
- [Quickstart](https://apiko.app/docs/quickstart): first text and image requests
- [Unified API](https://apiko.app/docs/api): entry points, timeouts and retries
- [Model discovery](https://apiko.app/docs/models): authenticated model list and parameters
- [Async tasks](https://apiko.app/docs/tasks): task lifecycle and polling
- [Reference assets](https://apiko.app/docs/assets): rules for input images and masks
- [Account API](https://apiko.app/docs/account-api): Dashboard, keys, usage, and billing
- [FAQ](https://apiko.app/docs/faq): common key, model, and task failures
- [Claude Code CLI](https://apiko.app/docs/integration-guide): setup with Claude models
- [Codex CLI](https://apiko.app/docs/integration-guide/codex-cli): setup with GPT models
- [OpenCode](https://apiko.app/docs/integration-guide/opencode): setup with Claude models
- [Agent skills](https://apiko.app/docs/integration-guide/agent-skills): install the APIKO skills so a coding agent sets up APIKO for you
- [Agent skills troubleshooting](https://apiko.app/docs/integration-guide/agent-skills/troubleshooting): install, key and setup errors
- [Kimi Code](https://apiko.app/docs/integration-guide/kimi-code): setup with any chat model
- [GPT Image 2 API](https://apiko.app/docs/api-manual/image-series/gpt-image-2/gpt-image-2-image-generation): parameters and examples
- [GPT Image 2.5 Flare API](https://apiko.app/docs/api-manual/image-series/gpt-image-2.5-flare/images): parameters and examples
- [GPT Image 2.5 Sunburst API](https://apiko.app/docs/api-manual/image-series/gpt-image-2.5-sunburst/images): parameters and examples
- [Nano Banana 2 API](https://apiko.app/docs/api-manual/image-series/nano-banana-2/images): parameters and examples
- [Nano Banana Pro API](https://apiko.app/docs/api-manual/image-series/nano-banana-pro/images): parameters and examples
- [Seedream 5.0 Pro API](https://apiko.app/docs/api-manual/image-series/doubao-seedream-5-0-pro/images): parameters and examples
- [Wan 3.0 Text-to-Video API](https://apiko.app/docs/api-manual/video-series/wan3.0/wan3.0-text-to-video): parameters and examples
- [Wan 3.0 Image-to-Video API](https://apiko.app/docs/api-manual/video-series/wan3.0/wan3.0-image-to-video): parameters and examples
- [Wan 3.0 Reference-to-Video API](https://apiko.app/docs/api-manual/video-series/wan3.0/wan3.0-reference-video): parameters and examples
- [Wan 3.0 Prime Text-to-Video API](https://apiko.app/docs/api-manual/video-series/wan3.0/wan3.0-prime-text-to-video): parameters and examples
- [Wan 3.0 Prime Image-to-Video API](https://apiko.app/docs/api-manual/video-series/wan3.0/wan3.0-prime-image-to-video): parameters and examples
- [Wan 3.0 Prime Reference-to-Video API](https://apiko.app/docs/api-manual/video-series/wan3.0/wan3.0-prime-reference-video): parameters and examples
- [Claude](https://apiko.app/docs/api-manual/text-series/claude): parameters and examples
- [GPT](https://apiko.app/docs/api-manual/text-series/gpt): parameters and examples
- [Gemini](https://apiko.app/docs/api-manual/text-series/gemini): parameters and examples
- [DeepSeek](https://apiko.app/docs/api-manual/text-series/deepseek): parameters and examples
- [GLM](https://apiko.app/docs/api-manual/text-series/glm): parameters and examples
- [Kimi](https://apiko.app/docs/api-manual/text-series/kimi): parameters and examples
- [Grok](https://apiko.app/docs/api-manual/text-series/grok): parameters and examples
- [Qwen](https://apiko.app/docs/api-manual/text-series/qwen): parameters and examples
- [Seedance 2.0 API](https://apiko.app/docs/api-manual/video-series/seedance/seedance-2.0): parameters and examples
- [Seedance 2.0 Fast API](https://apiko.app/docs/api-manual/video-series/seedance/seedance-2.0-fast): parameters and examples
- [Seedance 2.0 Mini API](https://apiko.app/docs/api-manual/video-series/seedance/seedance-2.0-mini): parameters and examples
- [Seedance 2.5 API](https://apiko.app/docs/api-manual/video-series/seedance/seedance-2.5): parameters and examples
- [Nano Banana 2.1 API](https://apiko.app/docs/api-manual/image-series/nano-banana-2.1/images): parameters and examples
- [Kling 4.0 API](https://apiko.app/docs/api-manual/video-series/kling/kling-4.0): parameters and examples

## Product

- [APIKO MCP for Claude Code and Codex](https://apiko.app/mcp): add image and video generation to your coding agent with the npm package `apiko-mcp` (`npx -y apiko-mcp`)
- [Nano Banana MCP for Claude Code and Codex](https://apiko.app/nano-banana-mcp): generate and edit images with Nano Banana 2.1, 2 and Pro from your coding agent; live per-image prices and setup commands
- [Seedance MCP for Claude Code and Codex](https://apiko.app/seedance-mcp): make videos with Seedance 2.5 and 2.0 from your coding agent; live per-second prices and setup commands
- [Model catalog](https://apiko.app/models): models and per-model prices
- [Status](https://apiko.app/status): real model availability
- [API price comparisons](https://apiko.app/compare): every dated provider price comparison
- [Seedance API price comparison](https://apiko.app/compare/seedance-api-pricing): dated per-second prices across providers
- [Wan 3.0 API price comparison](https://apiko.app/compare/wan-api-pricing): dated per-second prices across providers
- [Wan 3.0 prompts](https://apiko.app/wan-3-0-prompts): official example prompts with result videos
- [Seedance 2.5 prompts](https://apiko.app/seedance-2-5-prompts): community video prompts with their results, credited to the authors
- [GPT Image 2.5 prompts](https://apiko.app/gpt-image-2-5-prompts): community image prompts with their results
- [GPT Image 2 prompts](https://apiko.app/gpt-image-2-prompts): public-domain image prompts by category (ads, characters, e-commerce, portraits, posters, UI)
- [Claude Opus 5.5 video prompts](https://apiko.app/claude-opus-5-5-video-prompts): prompts that make Claude write code (HTML, Remotion, Blender) which renders a video
- [Public catalog API](https://apiko.app/api/public/models?billing=all): machine-readable catalog JSON

## Optional

- [Blog](https://apiko.app/blog): guides and release notes
- [Developer console](https://apiko.app/dashboard): sign-in required
- [API keys](https://apiko.app/dashboard/apikeys): create and revoke keys
- [Billing](https://apiko.app/dashboard/billing): balance and top-up
- [Support](https://apiko.app/contact#chat): live chat with the APIKO team