Venice API Alternative Python: OpenAI SDK Setup
You can use the official OpenAI Python SDK against this API by changing the base URL, the key and the model name. Below is working code for each common task.

Key points
- Install the openai package, set base_url to https://api.veniceapialternative.com/v1 and model to uncensored.
- Streaming, tool calling and JSON mode all work through the standard SDK calls.
- Keep parallel work at or below 8 concurrent requests on a full key (2 on the trial key).
- A 429 means rate_limited, concurrency or temporary overload; back off and retry.
Install and make the first call
For a venice api alternative python setup, you need no special library. The service speaks the OpenAI chat format, so the standard SDK works. Install it with pip install openai, then get a key. New users can claim $0.50 of trial credit on the API key page after signing up with Google or with email and password. No card is needed.
Store the key in an environment variable instead of in your source file. Then create a client with the base URL and call the model uncensored:
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.veniceapialternative.com/v1",
api_key=os.environ["UNCENSORED_API_KEY"],
)
resp = client.chat.completions.create(
model="uncensored",
messages=[
{"role": "system", "content": "You are a concise writing assistant."},
{"role": "user", "content": "Give me three opening lines for a noir story."},
],
temperature=0.8,
)
print(resp.choices[0].message.content)
print(resp.usage)
The SDK sends Authorization: Bearer <key> for you. The usage object shows prompt and completion tokens, which you will use for cost tracking later. If the call fails with an authentication error, check that the key has no trailing newline and that the base URL ends in /v1.
The temperature, top_p, stop and seed parameters, plus the frequency and presence penalties, are passed through to the model, so you can tune sampling the same way you would elsewhere. Leave max_tokens out if you want the model to use whatever room is left in the window, or set it when you want a hard cap on reply length and cost.
Check the connection with the models endpoint
Before you build anything, confirm the endpoint is reachable. The second supported method, GET /v1/models, lists what the key can use:
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.veniceapialternative.com/v1",
api_key=os.environ["UNCENSORED_API_KEY"],
)
for m in client.models.list():
print(m.id, m.id == "uncensored")
You should see uncensored. That is the only model ID, and it is the value to pass as model in every request. If you are porting an app that selected among several model names, replace the selection logic with a constant. There is nothing else to choose between.
The full parameter reference is on the docs page. Only text chat is supported: no images, audio, embeddings or fine-tuning, so remove those calls from any code you bring over.
Streaming responses
Streaming returns tokens as they are produced, which makes chat interfaces feel faster. Set stream=True and iterate over the chunks. Usage arrives at the end of the stream, so guard for chunks that carry no choices:
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.veniceapialternative.com/v1",
api_key=os.environ["UNCENSORED_API_KEY"],
)
stream = client.chat.completions.create(
model="uncensored",
messages=[{"role": "user", "content": "Describe a rainy harbor town in 120 words."}],
stream=True,
)
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):
print("\n", chunk.usage)
One detail matters for capacity planning: a streamed request holds its concurrency slot until the stream ends. If a user opens a stream and walks away without closing it, that slot stays busy. Close streams on the client side when the user leaves, and set a request timeout.
Tool calling and JSON mode
Tool calling follows the OpenAI shape. You describe functions in tools, the model returns tool_calls, you run the function and send the result back with role: "tool":
import json
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.veniceapialternative.com/v1",
api_key=os.environ["UNCENSORED_API_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 the next encounter."}]
first = client.chat.completions.create(
model="uncensored", messages=messages, tools=tools, tool_choice="auto"
)
msg = first.choices[0].message
if msg.tool_calls:
call = msg.tool_calls[0]
args = json.loads(call.function.arguments)
result = {"value": 14, "sides": args["sides"]}
messages.append(msg)
messages.append({"role": "tool", "tool_call_id": call.id, "content": json.dumps(result)})
final = client.chat.completions.create(model="uncensored", messages=messages, tools=tools)
print(final.choices[0].message.content)
Always parse function.arguments with a try/except in production code, since a model can emit malformed JSON now and then. JSON mode helps when you want structured output without tools:
import json
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.veniceapialternative.com/v1",
api_key=os.environ["UNCENSORED_API_KEY"],
)
r = client.chat.completions.create(
model="uncensored",
response_format={"type": "json_object"},
messages=[
{"role": "system", "content": "Reply with a JSON object with keys name, mood and hook."},
{"role": "user", "content": "Invent a tavern keeper for a fantasy campaign."},
],
)
print(json.loads(r.choices[0].message.content))
Tell the model in the prompt which keys you want. JSON mode makes the output valid JSON, but it cannot guess your schema.
Handling 429 errors and rate limits
A full key allows 8 concurrent requests and 300 requests per minute. A trial key allows 2 concurrent and 60 per minute. Past a limit you get HTTP 429, and the error code tells you which one:
rate_limited: too many requests per minute. Slow down.concurrency: too many requests in flight. Wait for some to finish.- A 429 with a
Retry-After: 5header: temporary overload. Wait 5 seconds and retry.
The SDK already retries a few times by default and respects Retry-After. For anything heavier, add your own wrapper and read the limit headers. You can reach the raw response through with_raw_response:
import os
import time
import openai
from openai import OpenAI
client = OpenAI(
base_url="https://api.veniceapialternative.com/v1",
api_key=os.environ["UNCENSORED_API_KEY"],
max_retries=0,
)
def ask(prompt, attempts=4):
for n in range(attempts):
try:
raw = client.chat.completions.with_raw_response.create(
model="uncensored",
messages=[{"role": "user", "content": prompt}],
)
print("balance:", raw.headers.get("X-Balance-USD"),
"request id:", raw.headers.get("X-Request-Id"))
return raw.parse().choices[0].message.content
except openai.RateLimitError as e:
wait = int(e.response.headers.get("Retry-After", 2 ** n))
time.sleep(wait)
raise RuntimeError("still rate limited after retries")
print(ask("Name three plot twists for a heist story."))
Log X-Request-Id with every failure. If you contact support, that ID lets them find the exact call. The X-Balance-USD header gives you the remaining credit without an extra request. Failed and refused requests are not charged.
Running requests in parallel without hitting the cap
For batch jobs, use the async client and a semaphore sized to your key. On a full key, 8 is the ceiling. Leave a little headroom if you also serve live users from the same key.
import asyncio
import os
from openai import AsyncOpenAI
client = AsyncOpenAI(
base_url="https://api.veniceapialternative.com/v1",
api_key=os.environ["UNCENSORED_API_KEY"],
)
gate = asyncio.Semaphore(6)
async def summarize(text):
async with gate:
r = await client.chat.completions.create(
model="uncensored",
messages=[{"role": "user", "content": "Summarize in one sentence: " + text}],
max_tokens=80,
)
return r.choices[0].message.content
async def main():
docs = ["First long text ...", "Second long text ...", "Third long text ..."]
for line in await asyncio.gather(*(summarize(d) for d in docs)):
print(line)
asyncio.run(main())
Pace matters for the per-minute cap too. At 6 parallel workers and 4 seconds per call, you send about 90 requests a minute, well under 300. If your calls are fast, add a small sleep or a token bucket so you do not exceed the cap in bursts.
Moving an existing Python project over
Most migrations are smaller than people expect. If your code already builds an OpenAI(...) client, you change two constructor arguments and one string. If you read settings from environment variables, you can often avoid touching the code at all: the openai package reads OPENAI_API_KEY and OPENAI_BASE_URL, so setting those two in your shell or your .env file points the whole program at the new endpoint.
Then search your project for these items, because they are the usual sources of breakage:
- Hard-coded model names. Replace every old name with
uncensored. A grep formodel=finds most of them. - Calls to other endpoints. Image, audio, embedding and fine-tuning calls have no equivalent here. Route them to a service that offers them, or remove them.
- Vendor-specific extras. Extra request fields or custom headers that belong to your old provider can cause errors. Strip them to the plain OpenAI format.
- Token budgets. The window is 100,000 tokens for prompt plus completion. If you trimmed history to fit a smaller window, you can now keep more, but keep an eye on cost, because every kept message is paid for again on each turn.
Prompts deserve a re-test. A system prompt that worked for one model may give a different tone on another, so run your ten most important prompts and compare the output with what you expect before you ship.
Common problems and their fixes
A short list of the errors that show up most often when people wire up a new OpenAI-compatible endpoint from Python:
- 404 on the first call. The base URL is missing
/v1, or it has an extra path segment. It should read exactlyhttps://api.veniceapialternative.com/v1. - 401 or authentication error. The key is wrong, still has quotes around it from a copied
.envline, or was never exported into the shell that runs Python. - The request hangs on large inputs. The maximum body is 8 MB. Pasting a huge file into a prompt can exceed it long before you reach the token limit. Split the text.
- Random 429s during testing. On the trial key you have only 2 concurrent requests. A test runner that fires five at once will trip the limit. Run tests serially, or top up and use a full key.
- Truncated answers. Check
finish_reason. A value oflengthmeans the output hit yourmax_tokenssetting or filled the window. - Different results run to run. Pass
seedand a lowtemperatureif you need repeatable output for tests.
If something still looks wrong, send the X-Request-Id value to support along with the time of the call.
Estimating cost in code
The price is $0.15 per 1M input tokens and $0.50 per 1M output tokens. A tiny helper turns any usage block into dollars:
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.veniceapialternative.com/v1",
api_key=os.environ["UNCENSORED_API_KEY"],
)
def cost_usd(usage):
return (usage.prompt_tokens * 0.15 + usage.completion_tokens * 0.50) / 1_000_000
r = client.chat.completions.create(
model="uncensored",
messages=[{"role": "user", "content": "Write a limerick about a lighthouse."}],
)
print(round(cost_usd(r.usage), 6))
A call with 2,000 prompt tokens and 500 completion tokens returns 0.00055. Run 1,000 of them and you spend $0.55. The trial credit of $0.50 covers about 909 such calls. After the trial, top-ups start at $20 and credit never expires; the pricing page lists the bonus tiers. If your app comes from a chatbot project with its own pitfalls, the article on common API mistakes covers several that apply here too.
More guides
Questions and answers
Which Python package do I need?
The official openai package. Install it with pip, set base_url to https://api.veniceapialternative.com/v1, and use model uncensored. No other client library is required.
Does streaming work with the SDK?
Yes. Pass stream=True and iterate over the chunks. Usage is reported at the end of the stream.
Why do I get a 429 error?
Either you passed the requests-per-minute limit (rate_limited), had too many requests open at once (concurrency), or the service was briefly overloaded and sent Retry-After: 5. Back off and retry.
How many parallel requests can I run?
A full key allows 8 concurrent requests and 300 per minute. A trial key allows 2 concurrent and 60 per minute.
Can I use LangChain or other OpenAI-compatible tools?
Any client that lets you set an OpenAI-compatible base URL and key should work. Use the same base URL and the model name uncensored.