Pontos principais
- Instale openai, depois construa OpenAI(base_url=..., api_key=...) com o modelo definido como uncensored.
- Streaming, modo JSON e chamada de ferramentas usam os parâmetros padrão, e o async funciona da mesma forma.
- Limite a concorrência a 8 com um semáforo e deixe o SDK tentar novamente respostas 429.
- Leia X-Balance-USD dos cabeçalhos da resposta bruta para monitorar seu crédito pelo código.
Exemplo mínimo funcional
Aqui está a configuração Python mais curta e útil para um proxy de API openai. Pressupõe Python 3.9 ou mais recente, uma chave da página chave de API, o pacote instalado com pip install openai e a chave exportada como 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)O endpoint é compatível com OpenAI, mas é um serviço separado. Não é a API oficial da OpenAI ou de qualquer outro fornecedor, e hospeda apenas um modelo, uncensored. Existem apenas duas rotas: POST /v1/chat/completions e GET /v1/models, então use a interface de conclusões de chat do SDK.
Algumas observações sobre esse código. A chave vem de uma variável de ambiente em vez de um literal, então ela nunca vai para o controle de versão. O objeto usage na resposta contém as contagens exatas de tokens nas quais a conta se baseia, o que é útil para logging. E max_tokens é opcional: não o inclua e a conclusão pode usar o resto da janela, o que é bom para histórias e custoso para um loop com bug.
Streaming de tokens conforme chegam
O streaming usa eventos enviados pelo servidor. Passe stream=True e itere sobre os chunks. A última parte do fluxo contém o uso de tokens, então proteja-se contra chunks sem 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)Um detalhe operacional: uma chamada de streaming ocupa uma de suas vagas de concorrência até o fim do fluxo. Se seu código sair do loop antecipadamente, feche o fluxo (stream.close()) para liberar a vaga.
Um aplicativo web geralmente envolve esse loop em um gerador e encaminha cada pedaço ao navegador. Com FastAPI, isso significa retornar um StreamingResponse que gera as partes de texto. Mantenha a chave no servidor nesse design. O navegador fala com sua rota, e sua rota fala com a API, então a chave nunca é exposta ao código do cliente.
Clientes assíncronos e concorrência controlada
Uma chave completa permite 8 requisições simultâneas e 300 por minuto. Uma chave de teste permite 2 e 60. Se você disparar 200 coroutines com asyncio.gather, você receberá erros 429 com o código concurrency. Um semáforo corrige isso antes que aconteça.
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 como tamanho do semáforo enquanto estiver na chave de teste. O SDK tenta novamente respostas 429 com backoff por padrão, e max_retries aumenta o número de tentativas. Para sobrecarga temporária, o serviço responde 429 com Retry-After: 5, que o SDK respeita.
Um semáforo limita apenas requisições em andamento dentro de um único processo. Se você executar vários workers, divida o limite entre eles: com uma chave completa, quatro workers devem usar cada um um semáforo de 2. O limite por minuto de 300 é compartilhado por todos eles, então uma fila com taxa constante é melhor que um pico para grandes trabalhos offline. O limite de corpo de 8 MB raramente é uma preocupação para chat, mas se aplica a cada requisição.
Modo JSON e chamadas de ferramentas
Ambos funcionam através dos parâmetros normais. Para o modo JSON, defina response_format e solicite JSON no 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"])A chamada de ferramentas precisa de um passo extra: você executa a função você mesmo e retorna a saída como uma mensagem tool.
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)O valor retornado para o dado aqui é fixo para brevidade. No código real, chame sua função com sides e envie seu resultado.
Mais dois detalhes sobre ferramentas. Use tool_choice quando precisar forçar uma função específica em vez de deixar o modelo decidir. E mantenha as descrições das ferramentas específicas: o modelo escolhe uma função apenas pelo nome e descrição, então "Rolar um dado com o número de lados dado" funciona melhor que "dados". Se uma resposta contiver várias chamadas de ferramentas, execute todas e anexe uma mensagem tool por ID de chamada antes de pedir a resposta final.
Erros, tentativas de reconexão e histórico de conversas
O SDK lança exceções tipadas, o que torna o tratamento de erros curto. Um 429 lança openai.RateLimitError, uma falha de rede lança openai.APIConnectionError, e outros status não bem-sucedidos lançam openai.APIStatusError. O SDK já tentou novamente antes que você veja o primeiro, então o que chega ao seu código é uma chamada que falhou repetidamente.
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."}]))O código lê Retry-After quando o serviço o envia, o que acontece em sobrecarga temporária (o valor é 5 segundos). Quando o cabeçalho está ausente, ele faz backoff em seu próprio cronograma. Observe que o loop não captura todos os erros: uma solicitação inválida não melhorará com uma nova tentativa, então deixe-a se propagar.
O histórico de conversas é a outra parte do estado. A API não o armazena para você, então seu programa é dono da lista de mensagens. Uma política simples que funciona bem: mantenha a mensagem do sistema, mantenha as últimas N rodadas e, quando o total crescer além de um tamanho que você escolher, peça ao modelo para resumir a parte mais antiga em uma mensagem curta.
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] + recentResumos também custam tokens, mas se pagam: uma conversa que de outra forma reenviaria 20.000 tokens a cada rodada cai para alguns milhares.
Lendo o saldo e o ID da requisição
Cada resposta inclui X-Request-Id e X-Balance-USD. O SDK oculta cabeçalhos por padrão, mas with_raw_response os expõe enquanto ainda fornece o objeto analisado.
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)Registre o ID da requisição em cada falha. Se precisar entrar em contato com a equipe pela página de suporte, esse ID aponta diretamente para a chamada.
O cabeçalho de saldo é útil além do logging. Um trabalho agendado pode lê-lo após cada lote e parar quando o crédito cair abaixo de um limite que você definir, ou enviar uma mensagem para que você possa recarregar antes que os usuários percebam. O crédito nunca expira, então não há pressão para gastá-lo. Recargas são valores inteiros de $20 a $500, então você pode reabastecer em etapas maiores se preferir.
Sem o SDK: requests ou httpx
Se você preferir evitar a dependência, a API é simples o suficiente para um cliente HTTP simples.
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"])Defina um tempo limite generoso para conclusões longas. O modelo pode usar tanto da janela de 100.000 tokens quanto o prompt deixar livre, então uma solicitação sem limite para ficção longa pode demorar.
A mesma abordagem funciona para streaming. Adicione "stream": true ao corpo JSON, passe stream=True para requests.post e leia a resposta com iter_lines(). Cada linha de evento começa com data: seguido por JSON, e o fluxo termina com um marcador data: [DONE]. Analisar isso manualmente é um bom exercício de aprendizado, embora para código de produção o SDK faça isso com menos casos extremos, como linhas parciais e reconexões.
Controle de orçamento dentro do seu código Python
Contagens de tokens em resp.usage permitem calcular o gasto por chamada. O preço é $0,15 por 1M tokens de entrada e $0,50 por 1M tokens de saída.
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.25A segunda linha verifica manualmente: 1M tokens de entrada custam $0,15 e 200.000 tokens de saída custam 0,2 x $0,50 = $0,10, totalizando $0,25. Requisições falhas ou recusadas não são cobradas, então não precisa subtraí-las. Recargas começam em $20, e a página de preços lista bônus de $50, $100 e $200.
Para a lista completa de parâmetros e códigos de erro, consulte a documentação.
Mantenha um totalizador em execução no seu trabalho para que um loop não gaste mais do que você planejou. Um job em lote que classifica 50.000 textos curtos com 400 tokens de entrada e 20 tokens de saída cada usa 20 milhões de tokens de entrada e 1 milhão de tokens de saída. Isso custa 20 x $0,15 + 1 x $0,50 = $3,50. Se o seu contador indicar que o job está gastando o dobro disso, algo está em loop.
