Alternativa à API Venice para Python: configuração do SDK OpenAI
Você pode usar o SDK Python oficial da OpenAI contra essa API alterando a URL base, a chave e o nome do modelo. Abaixo está o código funcional para cada tarefa comum.

Pontos principais
- Instale o pacote openai, defina base_url para https://api.veniceapialternative.com/v1 e o modelo para uncensored.
- Streaming, chamadas de ferramentas e modo JSON funcionam por meio das chamadas padrão do SDK.
- Mantenha as requisições paralelas em ou abaixo de 8 requisições simultâneas com uma chave completa (2 com a chave de teste).
- Um 429 significa rate_limited, concorrência ou sobrecarga temporária; reduza a taxa e tente novamente.
Instale e faça a primeira chamada
Para uma alternativa à API Venice com configuração Python, você não precisa de biblioteca especial. O serviço usa o formato de chat da OpenAI, então o SDK padrão funciona. Instale-o com pip install openai, depois obtenha uma chave. Novos usuários podem reivindicar $0,50 de crédito de teste na página da chave de API após entrar com Google ou com e-mail e senha. Nenhum cartão é necessário.
Armazene a chave em uma variável de ambiente em vez do seu arquivo de origem. Então crie um cliente com a base URL e chame o modelo 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)
O SDK envia Authorization: Bearer <key> para você. O objeto usage mostra tokens de prompt e de conclusão, que você usará para rastrear custos posteriormente. Se a chamada falhar com um erro de autenticação, verifique se a chave não possui nova linha final e se a URL base termina com /v1.
Os parâmetros temperature, top_p, stop e seed, além das penalidades de frequência e presença, são passados para o modelo, então você pode ajustar a amostragem da mesma forma que faria em outro lugar. Deixe max_tokens fora se quiser que o modelo use qualquer espaço restante na janela, ou defina-o quando quiser um limite rígido no comprimento da resposta e no custo.
Verifique a conexão com o endpoint de modelos
Antes de construir qualquer coisa, confirme que o endpoint é acessível. O segundo método suportado, GET /v1/models, lista o que a chave pode usar:
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")
Você deve ver uncensored. Esse é o único ID de modelo, e é o valor para passar como model em todas as requisições. Se você está portando um app que selecionava entre vários nomes de modelo, substitua a lógica de seleção por uma constante. Não há nada mais para escolher entre.
A referência completa de parâmetros está na página de documentação. Apenas chat de texto é suportado: sem imagens, áudio, embeddings ou fine-tuning, então remova essas chamadas de qualquer código que você trouxer.
Respostas em streaming
O streaming retorna tokens conforme são produzidos, o que faz interfaces de chat parecerem mais rápidas. Defina stream=True e itere sobre os blocos. O uso chega no final do streaming, então proteja-se contra blocos que não contêm respostas:
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)
Um detalhe importante para o planejamento de capacidade: uma solicitação em streaming ocupa seu slot de concorrência até o fim do streaming. Se um usuário iniciar um streaming e sair sem fechá-lo, esse slot permanece ocupado. Feche streams no lado do cliente quando o usuário sair e defina um tempo limite de solicitação.
Chamada de ferramentas e modo JSON
A chamada de funções segue o formato OpenAI. Você descreve funções em tools, o modelo retorna tool_calls, você executa a função e envia o resultado de volta com 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)
Sempre analise function.arguments com try/except em código de produção, já que um modelo pode ocasionalmente emitir JSON malformado. O modo JSON ajuda quando você deseja saída estruturada sem ferramentas:
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))
Diga ao modelo no prompt quais chaves você quer. O modo JSON torna a saída JSON válida, mas não pode adivinhar seu schema.
Tratamento de erros 429 e limites de requisição
Uma chave completa permite 8 requisições simultâneas e 300 requisições por minuto. Uma chave de teste permite 2 simultâneas e 60 por minuto. Ao ultrapassar um limite, você recebe HTTP 429, e o código de erro indica qual:
rate_limited: muitas requisições por minuto. Reduza a velocidade.concurrency: muitas requisições em andamento. Aguarde algumas terminarem.- Um 429 com um cabeçalho
Retry-After: 5: sobrecarga temporária. Aguarde 5 segundos e tente novamente.
O SDK já tenta novamente algumas vezes por padrão e respeita Retry-After. Para algo mais pesado, adicione seu próprio wrapper e leia os cabeçalhos de limite. Você pode acessar a resposta bruta através de 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."))
Registre X-Request-Id com cada falha. Se você contatar o suporte, esse ID permite que eles encontrem a chamada exata. O cabeçalho X-Balance-USD dá o crédito restante sem uma requisição extra. Requisições falhas e recusadas não são cobradas.
Executando requisições em paralelo sem atingir o limite
Para trabalhos em lote, use o cliente assíncrono e um semáforo dimensionado para sua chave. Em uma chave completa, 8 é o teto. Deixe uma margem de segurança se você também servir usuários em tempo real pela mesma chave.
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())
O ritmo importa também para o limite por minuto. Com 6 trabalhadores paralelos e 4 segundos por chamada, você envia cerca de 90 requisições por minuto, bem abaixo de 300. Se suas chamadas forem rápidas, adicione um pequeno sleep ou um bucket de tokens para não exceder o limite em rajadas.
Migrando um projeto Python existente
A maioria das migrações é menor do que as pessoas esperam. Se seu código já constrói um cliente OpenAI(...), você altera dois argumentos do construtor e uma string. Se você lê configurações de variáveis de ambiente, muitas vezes pode evitar tocar no código: o pacote openai lê OPENAI_API_KEY e OPENAI_BASE_URL, então definir esses dois no seu shell ou no seu arquivo .env aponta todo o programa para o novo endpoint.
Então procure no seu projeto por estes itens, porque eles são as fontes usuais de quebra:
- Nomes de modelo hardcoded. Substitua todo nome antigo por
uncensored. Um grep pormodel=encontra a maioria deles. - Chamadas para outros endpoints. Chamadas de imagem, áudio, embedding e fine-tuning não têm equivalente aqui. Encaminhe-as para um serviço que as ofereça, ou remova-as.
- Extras específicos do fornecedor. Campos extras de requisição ou cabeçalhos personalizados que pertencem ao seu antigo provedor podem causar erros. Remova-os para o formato OpenAI simples.
- Orçamentos de tokens. A janela é de 100.000 tokens para prompt mais respostas. Se você reduziu o histórico para caber em uma janela menor, agora pode manter mais, mas fique de olho no custo, porque cada mensagem mantida é paga novamente em cada turno.
Prompts merecem uma nova verificação. Um prompt do sistema que funcionava para um modelo pode dar um tom diferente em outro, então execute seus dez prompts mais importantes e compare a saída com o que você espera antes de lançar.
Problemas comuns e suas correções
Uma lista curta dos erros que aparecem mais frequentemente quando as pessoas configuram um novo endpoint compatível com OpenAI a partir do Python:
- 404 na primeira chamada. A base URL está faltando
/v1, ou tem um segmento de caminho extra. Deve ler exatamentehttps://api.veniceapialternative.com/v1. - 401 ou erro de autenticação. A chave está errada, ainda tem aspas ao redor dela de uma linha copiada do
.env, ou nunca foi exportada para o shell que executa Python. - A requisição congela em entradas grandes. O corpo máximo é 8 MB. Colar um arquivo enorme em um prompt pode exceder isso muito antes de você atingir o limite de token. Divida o texto.
- 429 aleatórios durante os testes. Na chave de teste, você tem apenas 2 requisições simultâneas. Um executor de testes que dispare cinco de uma vez atingirá o limite. Execute testes em série, ou recarregue e use uma chave completa.
- Respostas truncadas. Verifique
finish_reason. Um valor delengthsignifica que a saída atingiu sua configuraçãomax_tokensou preencheu a janela. - Resultados diferentes de execução para execução. Passe
seede umtemperaturebaixo se você precisar de saída repetível para testes.
Se algo ainda parecer errado, envie o valor X-Request-Id para o suporte junto com o horário da chamada.
Estimando custos no código
O preço é $0,15 por 1M tokens de entrada e $0,50 por 1M tokens de saída. Um pequeno utilitário converte qualquer bloco de uso em dólares:
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))
Uma chamada com 2.000 tokens de prompt e 500 tokens de respostas retorna 0,00055. Execute 1.000 delas e você gastará $0,55. O crédito de teste de $0,50 cobre cerca de 909 chamadas assim. Após o teste, as recargas começam em $20 e o crédito nunca expira; a página de preços lista os níveis de bônus. Se seu app vem de um projeto de chatbot com seus próprios problemas, o artigo sobre erros comuns de API cobre vários que se aplicam aqui também.
Mais guias
Perguntas e respostas
Qual pacote Python eu preciso?
O pacote openai oficial. Instale-o com pip, defina base_url para https://api.veniceapialternative.com/v1, e use o modelo uncensored. Nenhuma outra biblioteca de cliente é necessária.
O streaming funciona com o SDK?
Sim. Passe stream=True e itere sobre os blocos. O uso é reportado no final do streaming.
Por que recebo um erro 429?
Você ultrapassou o limite de requisições por minuto (rate_limited), tinha muitas requisições abertas ao mesmo tempo (concorrência) ou o serviço estava brevemente sobrecarregado e enviou Retry-After: 5. Aguarde e tente novamente.
Quantas requisições simultâneas posso executar?
Uma chave completa permite 8 requisições simultâneas e 300 por minuto. Uma chave de teste permite 2 simultâneas e 60 por minuto.
Posso usar LangChain ou outras ferramentas compatíveis com OpenAI?
Qualquer cliente que permita definir uma Base URL e chave compatíveis com OpenAI deve funcionar. Use a mesma Base URL e o nome do modelo uncensored.