# API docs

Base URL: `https://openuncensored.com/api/v1` (OpenAI compatible). Auth: `Authorization: Bearer <key>` (keys start with `ou-`).

## Endpoints

- `POST /chat/completions`: OpenAI chat completions. Extra body field `routing` (optional).
- `POST /responses`: OpenAI Responses API (function, custom and namespaced MCP tools, streaming), for Codex and other Responses clients. Stateless: send the whole conversation in `input` each turn (`previous_response_id` and `store` are not supported).
- `POST /images/generations`: OpenAI image generation (uncensored models; adult content allowed; minors, real people without consent and non consensual imagery are not). `model`, `prompt`, `n` 1-4, `size` (auto, 256x256, 512x512, 1024x1024, 1536x1024, 1024x1536, 1792x1024, 1024x1792), `response_format` b64_json or url (a data URL), `negative_prompt` (Civitai models). Billed per image delivered. Civitai Red checkpoints (Pony, Illustrious, SDXL) are included.
- `GET /images/models`: image models with price per image. No key needed.
- `GET /models`, `GET /models/{id}`: catalogue with providers, prices and live provider metrics. No key needed.
- `GET /stats/latency`: speed on real traffic per model and provider (p50/p90 latency, time to first token, tokens/s). No key needed.
- `GET /credits`: remaining prepaid credit of the key (`remaining_usd`).
- `POST https://openuncensored.com/api/feedback`: tell us what to improve (`{"message": "...", "category": "..."}`), no key needed.
- MCP: `https://openuncensored.com/mcp` (agents, key in the header) and `https://openuncensored.com/mcp/connect` (apps, OAuth sign-in). See https://openuncensored.com/agents.md#6-mcp-servers.
- OpenAPI: https://openuncensored.com/openapi.json

## Integrations

Any OpenAI compatible client works with base URL `https://openuncensored.com/api/v1` and your key (below as `OPENUNCENSORED_API_KEY`).

- Agent skill (Claude Code, Codex, Cursor, OpenCode and other agents): `npx skills add DhruvAtreja/open-uncensored-skills`
  installs a SKILL.md that teaches your agent to pick a model, get a key and call the API (https://skills.sh/dhruvatreja/open-uncensored-skills/open-uncensored).

- Vercel AI SDK: `createOpenAICompatible({ name: "openuncensored", apiKey: process.env.OPENUNCENSORED_API_KEY, baseURL: "https://openuncensored.com/api/v1", includeUsage: true, supportsStructuredOutputs: true })`
  from `@ai-sdk/openai-compatible`, then `generateText({ model: openUncensored("<model id>"), ... })`. Tools with `stopWhen`,
  streaming, `Output.object` and `providerOptions.openuncensored.reasoningEffort` all work.
- OpenCode 2 (`opencode.json`): `{"providers": {"openuncensored": {"name": "Open Uncensored", "env": ["OPENUNCENSORED_API_KEY"],
  "package": "@opencode/ai/providers/openai-compatible", "settings": {"baseURL": "https://openuncensored.com/api/v1"}, "models": {"<model id>": {}}}}}`,
  then `opencode run -m openuncensored/<model id>`.
- LiteLLM: `litellm.completion(model="openai/<model id>", api_base="https://openuncensored.com/api/v1", api_key=...)`.
- Cline, Kilo Code, Roo Code: API provider "OpenAI Compatible", base URL `https://openuncensored.com/api/v1`, your key, any model id.
- Codex CLI: `[model_providers.openuncensored]` with `base_url = "https://openuncensored.com/api/v1"`, `env_key = "OPENUNCENSORED_API_KEY"`, `wire_api = "responses"`.

Full snippets: https://openuncensored.com/docs#integrations

## Routing

`"routing": {"strategy": "quality" | "speed" | "cost" | "random", "only": ["venice"], "ignore": ["nanogpt"], "allow_fallbacks": true}`
or the header `X-OU-Strategy`. Fallbacks: providers are tried in order; one that fails or rejects the request hands over to the next. If none can serve the model, up to 2 other models built on the same original are tried, best ranked first. If everything fails, the error is the requested model's (for a rejected request, its first provider's message). `allow_fallbacks: false` turns off both the provider and the model fallbacks.
Response headers: `X-OU-Model`, `X-OU-Provider`, `X-OU-Upstream-Model`, `X-OU-Strategy`, `X-OU-Attempts`, `X-OU-Latency-Ms`, `X-Request-ID`.

## Streaming

`"stream": true` returns server-sent `chat.completion.chunk` events ending in `data: [DONE]`; usage is in the last chunk.

## Errors

OpenAI style `{"error": {"message", "type", "code"}}`. 401 invalid_api_key, 402 insufficient_quota (top up),
404 model_not_found, 429 rate_limit_exceeded or concurrency_limit (32 requests in flight per key), 502 all_providers_failed,
503 no_provider_available or billing_unavailable, 400 upstream_rejected_request (every provider rejected it, for example
images sent to a text model) and invalid_size (images). Details: https://openuncensored.com/agents.md#5-errors-you-can-act-on