Integrar IA via API: um guia prático

Você tem um app. Quer que ele fale com IA. Talvez queira chat completions, talvez geração de imagem, talvez os dois. A boa notícia: se você já usou a API da OpenAI, já sabe usar a nossa. A melhor notícia: você tem acesso a 367 modelos de 61 provedores por um único endpoint.

Sem SDK novo para aprender. Sem protocolo proprietário. Só mude a base URL e sua chave de API.

Passo 1: obtenha sua chave de API

Cadastre-se em zubnet.com e navegue até as configurações do seu workspace. Sua chave de API vive lá. Começa com um prefixo reconhecível:

zub_live_a1b2c3d4e5f6...

Mantenha em segredo. Trate como uma senha. Se vazar, rotacione imediatamente nas configurações do workspace — a chave antiga para de funcionar no momento em que você gera uma nova.

Passo 2: defina sua base URL

Toda requisição vai para:

https://api.zubnet.ai/v1

É isso. O prefixo /v1 combina com a convenção da OpenAI, então qualquer biblioteca, ferramenta ou framework que suporte OpenAI vai funcionar só trocando a URL.

Passo 3: faça sua primeira requisição

Usando curl

O teste mais simples possível — um chat completion com uma mensagem:

curl https://api.zubnet.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer zub_live_YOUR_KEY" \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "messages": [
      {"role": "user", "content": "What is the capital of France?"}
    ]
  }'

Você vai receber uma resposta JSON com a resposta do modelo em choices[0].message.content. Exatamente o mesmo formato da resposta da OpenAI.

Usando Python com o SDK da OpenAI

Instale o SDK se ainda não tiver:

pip install openai

Depois use com nossa base URL:

from openai import OpenAI

client = OpenAI(
    api_key="zub_live_YOUR_KEY",
    base_url="https://api.zubnet.ai/v1"
)

response = client.chat.completions.create(
    model="claude-sonnet-4-20250514",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Explain quantum computing in three sentences."}
    ],
    max_tokens=500,
    temperature=0.7
)

print(response.choices[0].message.content)

Esse é um exemplo completo e funcional. Copie, cole, substitua a chave de API, rode.

O parâmetro modelo

O campo model é onde fica interessante. Em vez de ficar preso a um provedor, você escolhe entre 367 modelos por 61 provedores. Alguns exemplos:

A lista completa está na nossa página de modelos, filtrável por tipo (LLM, imagem, vídeo, áudio, 3D, código) e provedor. O ID de modelo que você vê lá é exatamente o que vai no campo model.

Geração de imagens

Modelos de imagem usam o mesmo padrão de endpoint. Aqui está FLUX via Python:

response = client.images.generate(
    model="flux-1.1-pro",
    prompt="A serene Japanese garden at dawn, soft morning light",
    n=1,
    size="1024x1024"
)

image_url = response.data[0].url
print(image_url)

A resposta inclui uma URL para a imagem gerada hospedada no nosso CDN. Baixe, exiba, embede — a URL é válida por 24 horas.

Respostas em streaming

Para modelos de chat, o streaming envia tokens à medida que são gerados em vez de esperar pela resposta completa. Isso é essencial para qualquer interface de chat de usuário — ninguém quer olhar uma tela em branco por 10 segundos.

stream = client.chat.completions.create(
    model="claude-sonnet-4-20250514",
    messages=[
        {"role": "user", "content": "Write a short poem about code."}
    ],
    stream=True
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

Por baixo do capô, isso usa Server-Sent Events (SSE). Cada chunk chega como uma linha data: na resposta HTTP. O SDK da OpenAI lida com o parsing pra você, mas se você usar HTTP cru, vai ver linhas como:

data: {"choices":[{"delta":{"content":"Once"},"index":0}]}
data: {"choices":[{"delta":{"content":" upon"},"index":0}]}
data: {"choices":[{"delta":{"content":" a"},"index":0}]}
...
data: [DONE]

O fluxo termina com data: [DONE]. Parseie cada linha, extraia delta.content, adicione ao buffer de saída. Esse é o protocolo inteiro.

Tratamento de erros

A API usa códigos de status HTTP padrão. Aqui estão os que você vai realmente encontrar:

400 Bad Request — seu corpo de requisição está malformado. Verifique a estrutura JSON, certifique-se que messages é um array, certifique-se que model é um ID de modelo válido.

401 Unauthorized — sua chave de API está faltando, inválida ou expirada. Verifique o header Authorization: Bearer.

403 Forbidden — sua conta não tem acesso a esse modelo ou recurso. Verifique o nível de assinatura do seu workspace.

429 Too Many Requests — você bateu no limite de taxa. A resposta inclui um header Retry-After dizendo quantos segundos esperar. Implemente backoff exponencial:

import time
from openai import RateLimitError

max_retries = 3
for attempt in range(max_retries):
    try:
        response = client.chat.completions.create(
            model="claude-sonnet-4-20250514",
            messages=[{"role": "user", "content": "Hello"}]
        )
        break
    except RateLimitError:
        wait = 2 ** attempt
        print(f"Rate limited. Waiting {wait}s...")
        time.sleep(wait)

500 / 502 / 503 — problemas do lado do servidor. São raros mas acontecem. Retente com backoff. Se persistir, verifique nossa página de status Pulse.

Detalhes de autenticação

Toda requisição precisa de um header Authorization:

Authorization: Bearer zub_live_YOUR_KEY

A chave é escopada para seu workspace. Todos os membros do time no mesmo workspace compartilham a mesma chave e pool de uso. Se você precisa de rastreamento separado por membro do time, crie workspaces separados.

Limites de taxa

Limites de taxa dependem do seu nível de plano. Os padrões são generosos para a maioria dos casos de uso:

• Requisições por minuto: varia por plano (60-600 RPM)
• Tokens por minuto: varia por modelo e plano
• Requisições concorrentes: sem limite rígido, mas 429s vão disparar se você fizer burst muito agressivo

Headers de limite de taxa são incluídos em cada resposta:

x-ratelimit-limit-requests: 120
x-ratelimit-remaining-requests: 119
x-ratelimit-reset-requests: 0.5s

Leia esses headers. Construa seu cliente para respeitá-los. Seus usuários vão agradecer quando as requisições deles não falharem aleatoriamente.

Juntando tudo

Aqui está uma função Python pronta para produção que lida com erros, retries e streaming:

import os
from openai import OpenAI, APIError, RateLimitError
import time

client = OpenAI(
    api_key=os.environ["ZUBNET_API_KEY"],
    base_url="https://api.zubnet.ai/v1"
)

def ask(prompt, model="claude-sonnet-4-20250514", stream=False):
    for attempt in range(3):
        try:
            response = client.chat.completions.create(
                model=model,
                messages=[{"role": "user", "content": prompt}],
                stream=stream
            )
            if stream:
                return response  # iterate over chunks
            return response.choices[0].message.content
        except RateLimitError:
            time.sleep(2 ** attempt)
        except APIError as e:
            if attempt == 2:
                raise
            time.sleep(1)

# Usage
print(ask("Summarize the latest in quantum computing"))
print(ask("Same question, different model", model="gpt-4.1"))

Troque modelos trocando uma string. Sem refatoração de código, sem dependências novas, sem formato de resposta diferente. Esse é o ponto inteiro da compatibilidade com OpenAI.

---

Todos os exemplos de código neste guia estão testados e funcionando em março de 2026. Copie, rode, construa em cima. É pra isso que eles servem.

Pronto para começar? Pegue sua chave de API em zubnet.com