# Open Uncensored: guide for AI agents

You are reading the machine guide to https://openuncensored.com. Open Uncensored is OpenRouter for uncensored models: one
OpenAI compatible API for 48 abliterated and uncensored text models and 17 uncensored image models, with the text models ranked by the OpenUncensored Score.
No markup, no commission: every request costs exactly the provider's price. No account, no sign up, no subscription: a prepaid API key is all you need. Everything a human can do on the
website, you can do with the HTTP calls below or the MCP server.

## Fastest path

1. Pick a model: `GET https://openuncensored.com/api/rankings.json` (no key). Current top 5: `deepseek-v4.1-flash-1017-uncensored`, `glm-5.3-flash-uncensored`, `qwen3.8-27b-uncensored-fast`, `deepseek-v4.1-flash-0910-uncensored`, `deepseek-v4.1-flash-uncensored`.
2. Get a key: `POST https://openuncensored.com/api/agent/checkout`, hand the `payment_url` to your human, poll for the key (below).
3. Call it: OpenAI compatible `POST https://openuncensored.com/api/v1/chat/completions` (or `POST https://openuncensored.com/api/v1/responses` for Responses API clients such as Codex) with `Authorization: Bearer <key>`.
4. Images: `POST https://openuncensored.com/api/v1/images/generations` with an uncensored image model from `GET https://openuncensored.com/api/v1/images/models` (e.g. `z-image-turbo`, about $0.01 per image). Same key and credits. Details in section 3.

## 1. Get an API key (agent flow, no browser for you)

Credits are prepaid in US cents, 500 ($5) to 100000 ($1000). Payment is by card through
Stripe, so a human pays once; you never need to visit the website.

```bash
curl -X POST https://openuncensored.com/api/agent/checkout -H "Content-Type: application/json" -d '{"credits": 1000}'
# -> {"payment_url": "https://checkout.stripe.com/...", "session_id": "cs_...", "claim_token": "...", ...}
```

Show `payment_url` to your human. Then poll every 5 seconds:

```bash
curl https://openuncensored.com/api/agent/checkout/<session_id> -H "Authorization: Bearer <claim_token>"
# -> {"status": "pending"} ... then {"status": "paid", "api_key": "ou-cus_...", "balance_cents": 1000}
```

`api_key` is returned exactly once. Store it (for example as `OU_API_KEY`). To add credit to an existing key,
send `{"credits": 1000, "key": "ou-..."}`; the same poll then reports `"status": "paid"` with the new balance.
`"status": "expired"` means the payment link timed out: start a new checkout.

## 2. Call the API

Base URL `https://openuncensored.com/api/v1`. Works with any OpenAI SDK or tool (Cline, Kilo Code, Roo, Cursor, OpenCode, Claude Code
via an OpenAI compatible provider, LangChain, LiteLLM): set the base URL and the key.

```bash
curl https://openuncensored.com/api/v1/chat/completions \
  -H "Authorization: Bearer $OU_API_KEY" -H "Content-Type: application/json" \
  -d '{"model": "deepseek-v4.1-flash-1017-uncensored", "messages": [{"role": "user", "content": "Hello"}], "stream": false}'
```

```python
import os
from openai import OpenAI
client = OpenAI(base_url="https://openuncensored.com/api/v1", api_key=os.environ["OU_API_KEY"])
client.chat.completions.create(model="deepseek-v4.1-flash-1017-uncensored", messages=[{"role": "user", "content": "Hello"}])
```

- Streaming: `"stream": true` (server-sent events, usage in the last chunk).
- Tools: the OpenAI `tools` parameter is passed through to the provider.
- Routing (optional): `"routing": {"strategy": "quality" | "speed" | "cost" | "random", "only": [...], "ignore": [...], "allow_fallbacks": true}`.
- 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).
  Response header `X-OU-Model` (and `ou.model` in the body) names the model that answered; `X-OU-Provider` the provider.
- Each response has `ou.cost_usd` (provider cost of the request).
- Responses API: `POST https://openuncensored.com/api/v1/responses` also works (function, custom and namespaced MCP tools, streaming), so clients that only speak the
  Responses API, such as the Codex CLI, can use every model. Codex config: a provider with `base_url = "https://openuncensored.com/api/v1"`,
  `env_key = "OU_API_KEY"`, `wire_api = "responses"`.
- Ready-made setup for the Vercel AI SDK, OpenCode, LiteLLM, Cline, Kilo, Roo and Codex: https://openuncensored.com/docs#integrations.

## 3. Images

```bash
curl https://openuncensored.com/api/v1/images/generations -H "Authorization: Bearer $OU_API_KEY" -H "Content-Type: application/json" \
  -d '{"model": "z-image-turbo", "prompt": "a red fox in fresh snow at sunrise", "size": "1024x1024", "n": 1}'
# -> {"created": ..., "data": [{"b64_json": "..."}], "ou": {"model": "z-image-turbo", "providers": ["venice"], "cost_usd": ..., "images_failed": 0}}
```

- `n` 1 to 4; `size` one of auto, 256x256, 512x512, 1024x1024, 1536x1024, 1024x1536, 1792x1024, 1024x1792.
- `response_format`: `b64_json` (default) or `url` (answered with a data URL; nothing is hosted).
- `negative_prompt`: what to keep out of the image (used by the Civitai checkpoints).
- Billed per image delivered, at the price in `GET https://openuncensored.com/api/v1/images/models` (all models and prices: https://openuncensored.com/models.md).
- Adult content is allowed. Minors, real people without consent and non consensual imagery are not.

## 4. Balance, models, rankings

| What | Call | Key needed |
|---|---|---|
| Remaining credit | `GET https://openuncensored.com/api/v1/credits` | yes |
| All text models | `GET https://openuncensored.com/api/v1/models` | no |
| One model | `GET https://openuncensored.com/api/v1/models/<id>` | no |
| Image models and prices | `GET https://openuncensored.com/api/v1/images/models` | no |
| Live speed per model and provider | `GET https://openuncensored.com/api/v1/stats/latency` | no |
| Rankings (JSON) | `GET https://openuncensored.com/api/rankings.json` | no |
| OpenAPI spec | `GET https://openuncensored.com/openapi.json` | no |
| Top up | `POST https://openuncensored.com/api/agent/checkout` with `key` | no (the key is in the body) |

## 5. Errors you can act on

| HTTP | code | What to do |
|---|---|---|
| 401 | invalid_api_key | Missing or wrong key. Get one with `POST https://openuncensored.com/api/agent/checkout`. |
| 402 | insufficient_quota | Credit used up. Top up: `POST https://openuncensored.com/api/agent/checkout` with `{"credits": 1000, "key": "<key>"}`. |
| 404 | model_not_found | Unknown model id. List ids with `GET https://openuncensored.com/api/v1/models`. |
| 429 | rate_limit_exceeded | Every provider is rate limiting. Wait for `Retry-After`, or pick another model. |
| 429 | concurrency_limit | Over 32 requests in flight on one key. Retry after `Retry-After` (1 s). |
| 400 | upstream_rejected_request | Every provider rejected the request (for example images sent to a text model); the message is the first provider's. Fix the request. |
| 400 | invalid_size | Image `size` not in the supported list (section 3). |
| 502/503 | all_providers_failed / no_provider_available | Providers down; retry, or pick another model from the rankings. |
| 503 | billing_unavailable | Credits could not be checked for a moment. Retry after `Retry-After` (5 s). |

## 6. MCP servers

Two remote MCP servers (Streamable HTTP), both also listed in the official MCP Registry as `com.openuncensored/open-uncensored`.

**For agents: `https://openuncensored.com/mcp`.** Pass your key as `Authorization: Bearer <key>` for the balance and chat tools;
listing, rankings and buying work without it.

```bash
claude mcp add --transport http open-uncensored https://openuncensored.com/mcp --header "Authorization: Bearer $OU_API_KEY"
```

Tools: `list_models`, `get_rankings`, `get_model`, `buy_credits`, `check_purchase`, `check_balance`, `chat`, `send_feedback`, `get_guide`.

**For apps with OAuth (Claude, ChatGPT, Cursor and others): `https://openuncensored.com/mcp/connect`.** Add it as a custom connector; the app
opens a sign-in page where the human pastes their API key once. Tools: `list_models`, `get_rankings`, `get_model`,
`chat`, `check_balance`, `send_feedback` (text models only, no purchases).

## 7. Feedback

Tell us what to improve, from you or your human: missing models, bugs, pricing, docs, anything that slowed you down.
A human reads every submission. No key needed.

```bash
curl -X POST https://openuncensored.com/api/feedback -H "Content-Type: application/json" \
  -d '{"message": "What we should improve", "category": "model_request", "agent": "claude-code", "contact": "optional@email"}'
```

Categories: bug, model_request, pricing, docs, agent_experience, feature, other. Over MCP: the `send_feedback` tool.

## Pricing and policy

- No markup, no commission: usage is billed at exactly the serving provider's per-token price, nothing on top; cached
  prompt tokens at the provider's cached price. No fee when buying credits. Unused credit is refundable (https://openuncensored.com/refunds).
- Sexual content involving minors is prohibited on every model, route and provider.
- Support: support@openuncensored.com or https://openuncensored.com/support.

## More

- Model list with prices (text and image): https://openuncensored.com/models.md
- Rankings with all components: https://openuncensored.com/rankings.md
- Full docs in one file: https://openuncensored.com/llms-full.txt
- Mac app for humans (chat and a coding agent with image generation on every model): `curl -fsSL https://openuncensored.com/install.sh | sh`, source https://github.com/DhruvAtreja/open-uncensored-desktop