Key points
- Install openai, then build OpenAI(base_url=..., api_key=...) with the model set to uncensored.
- Streaming, JSON mode and tool calling use the standard parameters, and async works the same way.
- Cap concurrency at 8 with a semaphore and let the SDK retry 429 responses.
- Read X-Balance-USD from the raw response headers to watch your credit from code.
Minimal working example
Here is the shortest useful openai api proxy python setup. It assumes Python 3.9 or newer, a key from the API key page, the package installed with pip install openai and the key exported as UNCENSORED_API_KEY.
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.openaiapiproxy.com/v1",
api_key=os.environ["UNCENSORED_API_KEY"],
)
resp = client.chat.completions.create(
model="uncensored",
messages=[{"role": "user", "content": "Give me a one-line product tagline for a hiking app."}],
temperature=0.8,
max_tokens=60,
)
print(resp.choices[0].message.content)
print(resp.usage.prompt_tokens, resp.usage.completion_tokens)The endpoint is OpenAI-compatible, but it is a separate service. It is not the official API of OpenAI or any other vendor, and it hosts one model, uncensored. Only two routes exist: POST /v1/chat/completions and GET /v1/models, so stick to the chat completions interface of the SDK.
Some notes on that code. The key comes from an environment variable instead of a literal, so it never lands in version control. The usage object on the response holds the exact token counts that the bill is based on, which is useful for logging. And max_tokens is optional: leave it out and the completion may use the rest of the window, which is fine for stories and costly for a loop that has a bug.
Streaming tokens as they arrive
Streaming uses server-sent events. Pass stream=True and iterate over the chunks. The last part of the stream carries token usage, so guard for chunks without choices.
from openai import OpenAI
client = OpenAI(base_url="https://api.openaiapiproxy.com/v1", api_key="YOUR_KEY")
stream = client.chat.completions.create(
model="uncensored",
messages=[{"role": "user", "content": "Tell a two-paragraph ghost story."}],
stream=True,
)
usage = None
for chunk in stream:
if chunk.choices and chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="", flush=True)
if getattr(chunk, "usage", None):
usage = chunk.usage
print()
if usage:
print("tokens:", usage.prompt_tokens, usage.completion_tokens)One operational detail: a streaming call occupies one of your concurrency slots until the stream ends. If your code breaks out of the loop early, close the stream (stream.close()) so the slot is freed.
A web app usually wraps this loop in a generator and forwards each piece to the browser. With FastAPI, that means returning a StreamingResponse that yields the text parts. Keep the key on the server in that design. The browser talks to your route, and your route talks to the API, so the key is never exposed to client code.
Async clients and controlled concurrency
A full key allows 8 requests at once and 300 per minute. A trial key allows 2 and 60. If you fire off 200 coroutines with asyncio.gather, you will collect 429 errors with the code concurrency. A semaphore fixes that before it happens.
import asyncio
from openai import AsyncOpenAI
client = AsyncOpenAI(base_url="https://api.openaiapiproxy.com/v1", api_key="YOUR_KEY", max_retries=4)
gate = asyncio.Semaphore(8)
async def ask(prompt: str) -> str:
async with gate:
r = await client.chat.completions.create(
model="uncensored",
messages=[{"role": "user", "content": prompt}],
max_tokens=200,
)
return r.choices[0].message.content
async def main():
prompts = [f"Write a title for chapter {i} of a sea adventure." for i in range(1, 41)]
results = await asyncio.gather(*(ask(p) for p in prompts))
for t in results:
print(t)
asyncio.run(main())Use 2 as the semaphore size while you are on the trial key. The SDK retries 429 responses with backoff by default, and max_retries raises the number of attempts. For temporary overload the service answers 429 with Retry-After: 5, which the SDK honors.
A semaphore only limits requests in flight inside one process. If you run several workers, divide the limit between them: with a full key, four workers should each use a semaphore of 2. The per-minute limit of 300 is shared by all of them, so a queue with a steady rate is better than a burst for large offline jobs. The 8 MB body limit is rarely a concern for chat, but it applies to every request.
JSON mode and tool calls
Both work through the normal parameters. For JSON mode, set response_format and ask for JSON in the prompt.
import json
from openai import OpenAI
client = OpenAI(base_url="https://api.openaiapiproxy.com/v1", api_key="YOUR_KEY")
r = client.chat.completions.create(
model="uncensored",
response_format={"type": "json_object"},
messages=[
{"role": "system", "content": "Return JSON with keys name, mood and hook."},
{"role": "user", "content": "Invent a tavern keeper for a fantasy game."},
],
)
npc = json.loads(r.choices[0].message.content)
print(npc["name"])Tool calling needs one extra step: you execute the function yourself and return the output as a tool message.
import json
from openai import OpenAI
client = OpenAI(base_url="https://api.openaiapiproxy.com/v1", api_key="YOUR_KEY")
tools = [{
"type": "function",
"function": {
"name": "roll_dice",
"description": "Roll a die with the given number of sides.",
"parameters": {
"type": "object",
"properties": {"sides": {"type": "integer"}},
"required": ["sides"],
},
},
}]
messages = [{"role": "user", "content": "Roll a twenty-sided die for me."}]
first = client.chat.completions.create(model="uncensored", messages=messages, tools=tools)
msg = first.choices[0].message
if msg.tool_calls:
call = msg.tool_calls[0]
sides = json.loads(call.function.arguments)["sides"]
messages.append(msg)
messages.append({"role": "tool", "tool_call_id": call.id, "content": "14"})
final = client.chat.completions.create(model="uncensored", messages=messages, tools=tools)
print(final.choices[0].message.content)
else:
print(msg.content)The value returned for the die here is hard-coded for brevity. In real code, call your function with sides and send its result.
Two more details on tools. Use tool_choice when you need to force a particular function instead of letting the model decide. And keep tool descriptions specific: the model picks a function from its name and description alone, so "Roll a die with the given number of sides" works better than "dice". If a reply contains several tool calls, run them all and append one tool message per call ID before you ask for the final answer.
Errors, retries and conversation history
The SDK raises typed exceptions, which makes error handling short. A 429 raises openai.RateLimitError, a network failure raises openai.APIConnectionError, and other non-success statuses raise openai.APIStatusError. The SDK has already retried by the time you see the first one, so what reaches your code is a call that failed repeatedly.
import time
import openai
from openai import OpenAI
client = OpenAI(base_url="https://api.openaiapiproxy.com/v1", api_key="YOUR_KEY", max_retries=2)
def chat(messages, attempts=4):
delay = 2.0
for n in range(attempts):
try:
r = client.chat.completions.create(model="uncensored", messages=messages)
return r.choices[0].message.content
except openai.RateLimitError as e:
wait = float(e.response.headers.get("Retry-After", delay))
time.sleep(wait)
delay *= 2
except openai.APIConnectionError:
time.sleep(delay)
delay *= 2
raise RuntimeError("gave up after repeated failures")
print(chat([{"role": "user", "content": "Name a color."}]))The code reads Retry-After when the service sends it, which happens on temporary overload (the value is 5 seconds). When the header is missing, it backs off on its own schedule. Notice that the loop does not catch every error: a bad request will not improve on a retry, so let it propagate.
Conversation history is the other piece of state. The API does not store it for you, so your program owns the list of messages. A simple policy that works well: keep the system message, keep the last N turns, and when the total grows past a size you pick, ask the model to summarize the oldest part into one short message.
from openai import OpenAI
client = OpenAI(base_url="https://api.openaiapiproxy.com/v1", api_key="YOUR_KEY")
def compact(history, keep=6):
system, rest = history[0], history[1:]
if len(rest) <= keep:
return history
old, recent = rest[:-keep], rest[-keep:]
text = "\n".join(m["role"] + ": " + m["content"] for m in old)
r = client.chat.completions.create(
model="uncensored",
messages=[{"role": "user", "content": "Summarize this conversation in 120 words:\n" + text}],
max_tokens=250,
)
summary = {"role": "system", "content": "Earlier in this conversation: " + r.choices[0].message.content}
return [system, summary] + recentSummaries cost tokens too, but they pay for themselves: a conversation that would otherwise resend 20,000 tokens on every turn drops to a few thousand.
Reading the balance and request ID
Every response includes X-Request-Id and X-Balance-USD. The SDK hides headers by default, but with_raw_response exposes them while still giving you the parsed object.
from openai import OpenAI
client = OpenAI(base_url="https://api.openaiapiproxy.com/v1", api_key="YOUR_KEY")
raw = client.chat.completions.with_raw_response.create(
model="uncensored",
messages=[{"role": "user", "content": "Say ok."}],
)
print("request id:", raw.headers.get("X-Request-Id"))
print("balance USD:", raw.headers.get("X-Balance-USD"))
completion = raw.parse()
print(completion.choices[0].message.content)Log the request ID with every failure. If you need to contact the team through the support page, that ID points straight to the call.
The balance header is useful beyond logging. A scheduled job can read it after each batch and stop when the credit falls under a threshold you set, or send you a message so you can top up before users notice. Credit never expires, so there is no pressure to spend it. Top-ups are whole amounts from $20 to $500, so you can refill in bigger steps if you prefer.
Without the SDK: requests or httpx
If you prefer to avoid the dependency, the API is simple enough for a plain HTTP client.
import requests
r = requests.post(
"https://api.openaiapiproxy.com/v1/chat/completions",
headers={"Authorization": "Bearer YOUR_KEY"},
json={
"model": "uncensored",
"messages": [{"role": "user", "content": "Name three sea shanty topics."}],
},
timeout=120,
)
r.raise_for_status()
print(r.json()["choices"][0]["message"]["content"])Set a generous timeout for long completions. The model can use as much of the 100,000-token window as the prompt leaves free, so an uncapped request for long fiction can take a while.
The same approach works for streaming. Add "stream": true to the JSON body, pass stream=True to requests.post and read the response with iter_lines(). Each event line starts with data: followed by JSON, and the stream ends with a data: [DONE] marker. Parsing that by hand is a good learning exercise, though for production code the SDK does it with fewer edge cases, such as partial lines and reconnects.
Budgeting inside your Python code
Token counts in resp.usage let you compute spend per call. The price is $0.15 per 1M input tokens and $0.50 per 1M output tokens.
from openai import OpenAI
client = OpenAI(base_url="https://api.openaiapiproxy.com/v1", api_key="YOUR_KEY")
def cost_usd(prompt_tokens: int, completion_tokens: int) -> float:
return prompt_tokens * 0.15 / 1_000_000 + completion_tokens * 0.50 / 1_000_000
r = client.chat.completions.create(model="uncensored", messages=[{"role": "user", "content": "Hi"}])
print(cost_usd(r.usage.prompt_tokens, r.usage.completion_tokens))
print(cost_usd(1_000_000, 200_000)) # 0.25The second line checks out by hand: 1M input tokens cost $0.15 and 200,000 output tokens cost 0.2 x $0.50 = $0.10, which makes $0.25. Failed or refused requests are not charged, so you do not need to subtract them. Top-ups start at $20, and the pricing page lists the bonuses at $50, $100 and $200.
For the full parameter list and error codes, see the docs.
Keep a running total in your job so a loop cannot spend more than you planned. A batch job that classifies 50,000 short texts at 400 input tokens and 20 output tokens each uses 20M input tokens and 1M output tokens. That costs 20 x $0.15 + 1 x $0.50 = $3.50. If your counter says the job is at twice that, something is looping.
