API OpenAI para Desenvolvedores: Use um Endpoint Compatível

A versão curta

A maioria dos guias sobre a API da OpenAI para desenvolvedores assume um único fornecedor e uma única fatura. O formato de comunicação, no entanto, é apenas JSON sobre HTTPS, e muito código de cliente, frameworks e ferramentas podem conectar-se a qualquer servidor que o implemente. Este site hospeda um desses servidores. Você mantém seu SDK, altera a URL base, troca por uma chave deste site e define o modelo para uncensored.

Essa é a migração inteira para um aplicativo típico. Aqui está a lista de verificação, e o resto da página preenche cada etapa.

1. Crie uma conta e reivindique o crédito de teste na página da chave de API.
2. Defina a base URL para https://api.openaigatewayapi.com/v1.
3. Envie o cabeçalho Authorization: Bearer <key>. Os SDKs fazem isso para você quando você passa api_key.
4. Use uncensored como o ID do modelo em cada solicitação.
5. Trate HTTP 429 com uma nova tentativa curta, conforme mostrado no final.

Existem dois endpoints: POST /v1/chat/completions e GET /v1/models. O serviço é apenas de texto. Não há geração de imagem ou áudio, nem embeddings nem ajuste fino, então se seu aplicativo chamar esses recursos, eles precisarão de um provedor diferente.

Verifique a conexão com curl

Antes de modificar seu aplicativo, confirme que a chave funciona. O endpoint de modelos é o teste mais barato, pois não gera tokens.

Copyexport API_KEY="paste-your-key-here"

curl https://api.openaigatewayapi.com/v1/models \
  -H "Authorization: Bearer $API_KEY" | grep -o uncensored

O grep imprime o ID do modelo uncensored se a lista contiver; remova o grep para ver a lista JSON completa. Se você receber 401, a chave está errada ou falta o prefixo Bearer. Agora envie uma solicitação real:

Copycurl https://api.openaigatewayapi.com/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "uncensored",
    "messages": [
      {"role": "system", "content": "You are a concise technical assistant."},
      {"role": "user", "content": "Explain idempotency keys in two sentences."}
    ],
    "temperature": 0.4
  }'

A resposta carrega os objetos usuais choices e usage. Ela também inclui cabeçalhos dignos de registro: X-Request-Id para perguntas de suporte, X-Balance-USD para seu crédito restante e os dois cabeçalhos X-RateLimit-Limit-* que mostram os limites de requisição e concorrência.

Python com o pacote openai oficial

Em Python, você só toca no construtor do cliente. Tudo depois disso é o código que você já tem.

Copyfrom openai import OpenAI

client = OpenAI(
    base_url="https://api.openaigatewayapi.com/v1",
    api_key="paste-your-key-here",
)

resp = client.chat.completions.create(
    model="uncensored",
    messages=[
        {"role": "system", "content": "You write short, accurate release notes."},
        {"role": "user", "content": "Summarise: added retry logic, fixed timeout bug."},
    ],
    temperature=0.5,
    max_tokens=200,
)

print(resp.choices[0].message.content)
print(resp.usage.prompt_tokens, resp.usage.completion_tokens)

Leia a chave de uma variável de ambiente no código real. A amostra a codifica apenas para manter o trecho curto. max_tokens é opcional aqui; se você não o definir, a conclusão pode usar o que sobrar da janela de 100.000 tokens (prompt mais conclusão juntos). Definir isso de qualquer maneira é uma maneira barata de limitar o custo em uma geração descontrolada.

Streaming

O streaming usa Server-Sent Events e o mesmo sinalizador stream=True que você conhece. Os números de uso chegam no final do fluxo, então o último pedaço pode ter uma lista choices vazia.

Copyfrom openai import OpenAI

client = OpenAI(base_url="https://api.openaigatewayapi.com/v1", api_key="paste-your-key-here")

stream = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "List five edge cases for a date parser."}],
    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("\ntokens:", chunk.usage.total_tokens)

Um detalhe importa para o planejamento de capacidade. Uma solicitação em streaming mantém sua vaga de concorrência até que o fluxo termine, não até o primeiro token. Se um cliente abandonar um fluxo sem fechá-lo, essa vaga permanecerá ocupada por mais tempo do que você espera.

Exemplo em Node.js

O SDK Node usa as mesmas duas configurações com nomes diferentes.

Copyimport OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.openaigatewayapi.com/v1",
  apiKey: process.env.GATEWAY_KEY,
});

const completion = await client.chat.completions.create({
  model: "uncensored",
  messages: [
    { role: "user", content: "Write a regex that matches ISO 8601 dates, and explain it." },
  ],
  temperature: 0.3,
});

console.log(completion.choices[0].message.content);

Se você usar um framework que tenha sua própria integração OpenAI, procure um campo chamado URL base, endpoint ou base da API nas configurações. Colar a mesma URL lá geralmente é tudo o que é necessário. Interfaces de chat, frameworks de agentes e plugins de editores seguem principalmente esse padrão. Parâmetros de amostragem como temperature, top_p, stop, seed e as penalidades de frequência e presença são passados para o modelo.

Chamada de funções e modo JSON

Dois recursos decidem se um modelo se encaixa em um aplicativo real: chamar suas funções e retornar dados que você pode analisar. Ambos são suportados.

Chamada de funções

Você declara ferramentas com tools, opcionalmente força uma escolha com tool_choice e envia resultados de volta como mensagens com role: "tool". Respostas streamadas entregam tool_calls em pedaços, como com o formato padrão.

Copyimport json
from openai import OpenAI

client = OpenAI(base_url="https://api.openaigatewayapi.com/v1", api_key="paste-your-key-here")

tools = [{
    "type": "function",
    "function": {
        "name": "get_order_status",
        "description": "Look up the status of an order by its ID.",
        "parameters": {
            "type": "object",
            "properties": {"order_id": {"type": "string"}},
            "required": ["order_id"],
        },
    },
}]

messages = [{"role": "user", "content": "Where is order A-1042?"}]
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]
    args = json.loads(call.function.arguments)
    result = {"order_id": args["order_id"], "status": "shipped"}  # your real lookup here
    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 valide os argumentos antes de agir sobre eles. O modelo produz JSON que corresponde ao seu esquema na maioria das vezes, não sempre, então trate call.function.arguments como qualquer outra entrada não confiável.

Modo JSON

Para tarefas de extração e classificação, solicite um objeto JSON e também diga isso no prompt. Mencionar JSON nas instruções dá resultados melhores do que confiar apenas no sinalizador.

Copyfrom openai import OpenAI
import json

client = OpenAI(base_url="https://api.openaigatewayapi.com/v1", api_key="paste-your-key-here")

resp = client.chat.completions.create(
    model="uncensored",
    response_format={"type": "json_object"},
    messages=[
        {"role": "system", "content": "Reply with JSON only: {\"sentiment\": string, \"topics\": [string]}."},
        {"role": "user", "content": "The docs are clear but the rate limits caught me off guard."},
    ],
)
data = json.loads(resp.choices[0].message.content)
print(data)

Limites, erros e retentativas

Uma chave completa permite 8 solicitações em andamento e 300 solicitações por minuto. A chave de teste permite 2 em andamento e 60 por minuto. O corpo máximo da solicitação é de 8 MB. Ultrapassar um limite resulta em HTTP 429, e o código de erro indica qual limite foi.

Código de erro	Significado	O que fazer
rate_limited	Muitas requisições por minuto	Diminua o produtor ou distribua o trabalho ao longo do minuto
concurrency	Muitas requisições de uma vez	Reduza sua contagem de processos para 8 ou menos, ou 2 em uma chave de teste
429 com Retry-After: 5	Sobrecarga temporária	Aguarde os segundos indicados e tente novamente

Os SDKs já fazem retentativas para algumas falhas. Adicione seu próprio tratamento para 429 para que uma explosão não derrube um trabalho em lote:

Copyimport time
from openai import OpenAI, RateLimitError

client = OpenAI(
    base_url="https://api.openaigatewayapi.com/v1",
    api_key="paste-your-key-here",
    max_retries=0,
)

def ask(prompt, attempts=5):
    for i in range(attempts):
        try:
            r = client.chat.completions.create(
                model="uncensored",
                messages=[{"role": "user", "content": prompt}],
            )
            return r.choices[0].message.content
        except RateLimitError as e:
            wait = float(e.response.headers.get("retry-after", 2 ** i))
            time.sleep(wait)
    raise RuntimeError("still rate limited after retries")

Solicitações falhas ou recusadas não são cobradas, então um loop de nova tentativa não dobra sua conta. Um semáforo dimensionado para seu limite de concorrência é a maneira mais limpa de permanecer abaixo do limite em código assíncrono.

Migrando um aplicativo existente

Se você tem um aplicativo funcionando, não codifique os novos valores. Coloque a URL base, a chave e o nome do modelo em variáveis de ambiente para que você possa alternar entre ambientes sem uma implantação. Isso também permite executar o mesmo conjunto de testes contra dois backends e comparar a saída lado a lado.

Copyimport os
from openai import OpenAI

client = OpenAI(
    base_url=os.environ.get("LLM_BASE_URL", "https://api.openaigatewayapi.com/v1"),
    api_key=os.environ["LLM_API_KEY"],
)
MODEL = os.environ.get("LLM_MODEL", "uncensored")

def complete(messages, **kw):
    return client.chat.completions.create(model=MODEL, messages=messages, **kw)

Então execute uma rotina de migração curta:

1. Execute seus prompts existentes contra o novo endpoint e leia as saídas você mesmo. Verificações automáticas capturam quebras de formato, não tom.
2. Verifique se qualquer código que analisa JSON ainda passa com response_format definido e mantenha um fallback que remove texto estranho ao redor do objeto.
3. Meça as contagens reais de tokens de usage, porque um modelo diferente tokeniza o texto de forma diferente e suas estimativas antigas podem estar erradas.
4. Defina seu conjunto de processos para 8 ou menos para que o limite de concorrência nunca seja a primeira coisa a falhar sob carga.
5. Implante para uma pequena parte do tráfego, monitore a taxa de 429 e os logs de erro, depois amplie.

Equipes frequentemente esquecem o prompt do sistema neste processo. Prompts escritos para persuadir um modelo propenso a recusas a se comportar geralmente contêm linhas de hesitação que não são necessárias aqui e podem poluir a saída. Leia o seu novamente e corte o que não faz mais nada.

O que saber antes de mudar

A compatibilidade cobre o formato de solicitação e resposta. Não torna esta a API oficial de nenhum fabricante de modelo. O serviço executa um modelo de pesos abertos, hospedado por um provedor independente e ajustado para responder sem recusas de conteúdo para uso adulto legal. Não é um roteador entre fornecedores, então você não encontrará um menu de outros modelos por trás dele. Conteúdo sexual envolvendo menores de idade não é permitido, e esse limite não pode ser alterado.

Planeje-se para três diferenças práticas de uma plataforma multi-modelo de grande porte:

• Um modelo. O ID é uncensored. Se seu código alterna modelos por tarefa, reduza isso para um valor.
• Apenas texto. Remova quaisquer chamadas de imagem, áudio ou embedding do caminho que vai para este endpoint.
• O comportamento do prompt difere. Um modelo diferente lê instruções de forma diferente, então execute seus prompts e testes novamente após a mudança. Ajuste os prompts do sistema onde a saída se desvia.

Os prompts não são usados para treinamento. Para a lista completa de parâmetros, consulte a documentação da API. Se você está estimando gastos, a página de preços lista as taxas por token: $0,15 por 1M de tokens de entrada e $0,50 por 1M de tokens de saída, cobrados do crédito pré-pago sem assinatura. Recargas variam de $20 a $500 e o crédito não expira. Se você está ponderando uma camada de proxy na frente de vários serviços, a página sobre gateways LLM aborda quando essa peça extra vale a pena.

Mais guias

• OpenAI Gateway API Explicada em Termos Simples
• Preços da OpenAI Gateway API: Exemplos de Custo Real
• Gateway LLM: Análise de Custo vs. Complexidade