SDK Python

Dois caminhos em Python — anthropic para código Claude nativo, openai para migrações. Os dois funcionam trocando só a base_url.

Instalação

pip3 install anthropic
# or, for OpenAI-style code:
pip3 install openai
# In a venv (recommended):
# python3 -m venv .venv && source .venv/bin/activate
# pip install anthropic openai

Anthropic SDK

import os
from anthropic import Anthropic
client = Anthropic(
api_key=os.environ["ONEPROVIDER_KEY"],
base_url="https://api.oneprovider.dev",
)
resp = client.messages.create(
model="claude-sonnet-5-5",
max_tokens=1024,
messages=[{"role": "user", "content": "Say hi."}],
)
print(resp.content[0].text)

Compatível com a OpenAI

import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["ONEPROVIDER_KEY"],
base_url="https://api.oneprovider.dev/v1",
)
resp = client.chat.completions.create(
model="claude-sonnet-5-5",
messages=[{"role": "user", "content": "Say hi."}],
)
print(resp.choices[0].message.content)

Cliente assíncrono

import asyncio
from anthropic import AsyncAnthropic
async def main():
client = AsyncAnthropic(base_url="https://api.oneprovider.dev")
resp = await client.messages.create(
model="claude-sonnet-5-5",
max_tokens=512,
messages=[{"role": "user", "content": "Hi async."}],
)
print(resp.content[0].text)
asyncio.run(main())

Streaming

with client.messages.stream(
model="claude-sonnet-5-5",
max_tokens=512,
messages=[{"role": "user", "content": "Tell me a haiku."}],
) as stream:
for chunk in stream.text_stream:
print(chunk, end="", flush=True)

Uso de ferramentas

tools = [{
"name": "get_weather",
"description": "Get current weather for a city.",
"input_schema": {
"type": "object",
"properties": {"city": {"type": "string"}},
"required": ["city"],
},
}]
resp = client.messages.create(
model="claude-sonnet-5-5",
max_tokens=1024,
tools=tools,
messages=[{"role": "user", "content": "What's the weather in Frankfurt?"}],
)
# resp.stop_reason == "tool_use"
# Inspect resp.content for tool_use blocks.

Novas tentativas e tratamento de erros

from anthropic import APIStatusError
from tenacity import retry, stop_after_attempt, wait_exponential
@retry(
stop=stop_after_attempt(3),
wait=wait_exponential(multiplier=0.5, min=0.5, max=4),
retry_error_cls=APIStatusError,
)
def call():
return client.messages.create(
model="claude-sonnet-5-5",
max_tokens=512,
messages=[{"role": "user", "content": "Hi."}],
)

Qual modelo escolher

Passe o ID em model. claude-sonnet-5-5 é o padrão para a maior parte do código, claude-haiku-5-5 para chamadas rápidas e de alto volume e claude-opus-5-5 para raciocínio difícil. A forma compatível com a OpenAI também aceita IDs GPT, como gpt-6.1-terra. Use a forma da Anthropic com https://api.oneprovider.dev e a forma da OpenAI com https://api.oneprovider.dev/v1. Os IDs estão na página de modelos .

Erros comuns e soluções

404 NotFoundError

SDK da Anthropic: base_url="https://api.oneprovider.dev", sem /v1. SDK da OpenAI: base_url="https://api.oneprovider.dev/v1", com /v1.

401 AuthenticationError

A variável de ambiente está vazia ou tem uma quebra de linha no final. Imprima len(os.environ["ONEPROVIDER_KEY"]) antes da chamada.

429 RateLimitError

Leia a mensagem: “Insufficient balance” significa que é preciso recarregar o saldo (não tente de novo); qualquer outro 429 é limite de requisições, então espere um pouco e respeite o Retry-After.

APIConnectionError ou read timeout

Desative VPN ou variáveis de proxy (HTTPS_PROXY) e use streaming para respostas longas: uma requisição sem streaming precisa começar a responder em até 6 minutos.

400 sobre max_tokens

O SDK da Anthropic exige max_tokens em toda requisição.

Perguntas frequentes

Posso continuar com os SDKs oficiais?

Pode. Só a chave e a base_url mudam, veja migrar da Anthropic e migrar da OpenAI .

O streaming funciona?

Funciona, com os dois SDKs; veja Streaming .

Onde guardo a chave?

Em uma variável de ambiente, nunca no repositório.

Respostas rápidas

Qual base URL devo usar?

O Claude Code e os SDKs da Anthropic usam https://api.oneprovider.dev. Os SDKs da OpenAI e os clientes compatíveis com a OpenAI usam https://api.oneprovider.dev/v1. Uma única chave funciona nos dois; a lista de modelos está na página de modelos e os preços, na página de preços .

Como me autentico?

Envie a chave sk-… pura em x-api-key ou em Authorization: Bearer: um dos dois, nunca ambos. Guarde a chave em uma variável de ambiente, não em um arquivo que vai para o commit. Mais sobre autenticação .

Onde consigo uma chave?

Abra o seu painel no bot do Telegram @oneprovider_robot ou em app.oneprovider.dev, recarregue o saldo e toque em “Emitir chave”. Cada chave pode ter o seu próprio limite de gastos. Painel e chaves de API .

O que significam 401, 404 e 429?

401: a chave está ausente, foi digitada errado ou enviada no cabeçalho errado; cole a chave inteira, sem aspas nem espaços. 404: em geral, uma base URL errada, por exemplo um /v1 ausente ou duplicado. 429 com “Insufficient balance”: o saldo do painel ou o limite de gastos da chave acabou, então recarregue em vez de tentar de novo; qualquer outro 429 é um limite de requisições, então aguarde o tempo de Retry-After. Detalhes: códigos de erro e solução de problemas .

Por que os streams são cortados ou reiniciados?

VPNs e proxies VLESS costumam armazenar SSE em buffer ou quebrar a negociação do HTTP/2. A OneProvider não tem restrições regionais e não armazena streams em buffer; desative o proxy e tente de novo.

Onde pergunto se isso não bastar?

Escreva para @Oneproviderhelpbot no Telegram ou abra “Suporte” no painel web, informando o código de status HTTP e a mensagem de erro exata. Como funciona o suporte .