SDK Python da OpenAI: Instalação, Configuração e Integração Prática

O SDK Python da OpenAI (openai no PyPI) é o cliente Python oficial para a API da OpenAI. Ele lida com autenticação, formatação de requisições, parsing de respostas, streaming e retentativas — para que você não precise implementar isso manualmente. Este guia aborda instalação, a classe principal OpenAI, chat completions, streaming, function calling, uso assíncrono, o equivalente no SDK JavaScript, integração com Azure OpenAI e como configurar o mesmo SDK para usar o endpoint compatível com OpenAI da Novita AI para utilizar modelos de peso aberto sem reescrever seu código.

Instale o Pacote Python da OpenAI

Python 3.8 ou superior é necessário:

pip install openai

Para desenvolvimento, adicione ao seu requirements.txt ou pyproject.toml:

pip install openai>=1.0.0

A versão 1.x (lançada no final de 2023) mudou significativamente a interface em relação à API 0.x. Se você está migrando código antigo, note que openai.ChatCompletion.create() não existe mais; use client.chat.completions.create().

Defina sua chave de API como uma variável de ambiente. Não a coloque no código-fonte:

export OPENAI_API_KEY="sk-..."

A Classe OpenAI Client

A classe OpenAI é o ponto de entrada principal. Ela lê a chave de API da variável de ambiente OPENAI_API_KEY por padrão, ou você pode passá-la explicitamente:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["OPENAI_API_KEY"],
)

O cliente gerencia pooling de conexões, retentativas e timeouts. Você deve criar uma única instância e reutilizá-la em toda a sua aplicação, não instanciá-la por requisição.

Opções configuráveis na inicialização:

Parâmetro	Padrão	Descrição
api_key	variável de ambiente OPENAI_API_KEY	Credencial de autenticação
base_url	https://api.openai.com/v1	Substituir para proxy ou API compatível
timeout	600s	Timeout por requisição
max_retries	2	Retentativas automáticas em erros de limite de taxa
http_client	None	Cliente httpx personalizado para proxy ou configuração de certificado

Chat Completions: Requisição Básica

Chat completions são o caso de uso mais comum. A lista messages segue o mesmo formato da API: uma lista de dicionários role/content representando a conversa:

import os
from openai import OpenAI

client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": "Você é um assistente de codificação útil."},
        {"role": "user", "content": "Qual é a diferença entre uma lista e uma tupla em Python?"},
    ],
    temperature=0.3,
    max_tokens=512,
)

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

A resposta é um objeto ChatCompletion. Campos principais:

• response.choices[0].message.content — a resposta em texto
• response.usage.prompt_tokens — tokens consumidos pela entrada
• response.usage.completion_tokens — tokens consumidos pela saída
• response.model — a versão do modelo que atendeu à requisição

Para uso em produção, passe max_tokens para evitar custos de geração descontrolados e temperature=0 ou valores baixos quando precisar de saídas determinísticas.

Respostas em Streaming

Para interfaces interativas onde os usuários veem os tokens à medida que chegam, use stream=True:

import os
from openai import OpenAI

client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

with client.chat.completions.stream(
    model="gpt-4o",
    messages=[
        {"role": "user", "content": "Explique generators em Python em linguagem simples."},
    ],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

Usar o gerenciador de contexto (comando with) garante que a conexão seja fechada corretamente após a iteração. O atributo .text_stream produz strings simples; .stream produz objetos de evento brutos se você precisar de metadados como estatísticas de uso por chunk.

Se precisar de streaming sem um gerenciador de contexto:

stream = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Liste 5 boas práticas em Python."}],
    stream=True,
)
for chunk in stream:
    delta = chunk.choices[0].delta
    if delta.content:
        print(delta.content, end="", flush=True)

Function Calling

O function calling permite que o modelo decida quando chamar uma função e retorne um objeto de argumento JSON. Sua aplicação executa a função e depois envia o resultado de volta para que o modelo o incorpore em sua resposta:

import os
import json
from openai import OpenAI

client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

tools = [
    {
        "type": "function",
        "function": {
            "name": "obter_clima",
            "description": "Retorna o clima atual para uma cidade.",
            "parameters": {
                "type": "object",
                "properties": {
                    "cidade": {
                        "type": "string",
                        "description": "Nome da cidade, ex. 'São Paulo'",
                    }
                },
                "required": ["cidade"],
            },
        },
    }
]

messages = [{"role": "user", "content": "Qual é o clima em Tóquio?"}]

response = client.chat.completions.create(
    model="gpt-4o",
    messages=messages,
    tools=tools,
    tool_choice="auto",
)

choice = response.choices[0]
if choice.finish_reason == "tool_calls":
    tool_call = choice.message.tool_calls[0]
    args = json.loads(tool_call.function.arguments)
    # Execute sua função real aqui
    result = {"cidade": args["cidade"], "temperatura": "18°C", "condicao": "nublado"}

    messages.append(choice.message)
    messages.append({
        "role": "tool",
        "tool_call_id": tool_call.id,
        "content": json.dumps(result),
    })

    final = client.chat.completions.create(
        model="gpt-4o",
        messages=messages,
    )
    print(final.choices[0].message.content)

O modelo retorna finish_reason="tool_calls" quando deseja invocar uma função. Você executa a função, adiciona o resultado à lista de mensagens e faz uma segunda requisição. Este loop de dois passos é o padrão.

Uso Assíncrono com AsyncOpenAI

Para FastAPI, serviços baseados em asyncio ou qualquer código que se beneficie de I/O não bloqueante, use AsyncOpenAI:

import os
import asyncio
from openai import AsyncOpenAI

client = AsyncOpenAI(api_key=os.environ["OPENAI_API_KEY"])

async def obter_resposta(prompt: str) -> str:
    response = await client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": prompt}],
        max_tokens=256,
    )
    return response.choices[0].message.content

async def main():
    resultado = await obter_resposta("O que é asyncio em Python?")
    print(resultado)

asyncio.run(main())

AsyncOpenAI é uma contraparte assíncrona equivalente; todos os métodos são aguardáveis. Isso é preferível a usar asyncio.to_thread para encapsular o cliente síncrono.

SDK JavaScript da OpenAI

O SDK JavaScript da OpenAI (openai no npm) espelha de perto a interface Python. Instale-o:

npm install openai

Chat completion básico em Node.js:

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});

const response = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [
    { role: "system", content: "Você é um assistente útil." },
    { role: "user", content: "Explique promises vs async/await em JavaScript." },
  ],
  max_tokens: 512,
});

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

Streaming em JavaScript:

import OpenAI from "openai";

const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

const stream = await client.chat.completions.stream({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Resuma a API fetch em 3 frases." }],
});

for await (const chunk of stream) {
  const text = chunk.choices[0]?.delta?.content ?? "";
  process.stdout.write(text);
}

O SDK JavaScript suporta Node.js 18+, Deno e ambientes de navegador (embora expor sua chave de API no navegador seja inseguro — use um proxy no servidor). A opção base_url para apontar para APIs compatíveis funciona exatamente como em Python.

Integração com Azure OpenAI Python

Se você estiver usando o serviço Azure OpenAI em vez da API direta da OpenAI, use o cliente AzureOpenAI do mesmo pacote:

import os
from openai import AzureOpenAI

client = AzureOpenAI(
    api_key=os.environ["AZURE_OPENAI_API_KEY"],
    azure_endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
    api_version="2024-02-01",
)

response = client.chat.completions.create(
    model="gpt-4o",  # Nome da sua implantação no Azure
    messages=[
        {"role": "user", "content": "Como usar Azure OpenAI com Python?"},
    ],
)

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

Variáveis de ambiente necessárias para Azure:

• AZURE_OPENAI_API_KEY: Sua chave de API do recurso Azure
• AZURE_OPENAI_ENDPOINT: URL do seu endpoint, ex. https://seu-recurso.openai.azure.com/

O parâmetro model no Azure OpenAI se refere ao nome da sua implantação, não ao nome do modelo subjacente. Defina api_version para corresponder à versão da API do Azure que sua implantação usa (verifique a documentação do Azure OpenAI para versões suportadas atuais).

Para autenticação via Microsoft Entra ID (antigo Azure AD) em vez de uma chave de API:

from azure.identity import DefaultAzureCredential, get_bearer_token_provider
from openai import AzureOpenAI

token_provider = get_bearer_token_provider(
    DefaultAzureCredential(),
    "https://cognitiveservices.azure.com/.default",
)

client = AzureOpenAI(
    azure_ad_token_provider=token_provider,
    azure_endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
    api_version="2024-02-01",
)

Mude para a API Compatível com OpenAI da Novita AI

A Novita AI expõe um endpoint compatível com OpenAI em https://api.novita.ai/openai. Você pode usar o mesmo SDK openai Python ou JavaScript, alterando apenas base_url e api_key. Nenhuma outra alteração de código é necessária:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NOVITA_API_KEY"],
    base_url="https://api.novita.ai/openai",
)

response = client.chat.completions.create(
    model="deepseek/deepseek-v4-pro",
    messages=[
        {"role": "system", "content": "Você é um assistente de codificação útil."},
        {"role": "user", "content": "Explique como o GIL do Python afeta o multithreading."},
    ],
    temperature=0.3,
    max_tokens=512,
)

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

Obtenha uma chave de API da Novita AI em novita.ai/settings/key-management. A mesma chave funciona em todas as APIs da Novita AI, incluindo o endpoint compatível com OpenAI.

JavaScript com Novita AI:

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NOVITA_API_KEY,
  baseURL: "https://api.novita.ai/openai",
});

const response = await client.chat.completions.create({
  model: "qwen/qwen3-coder-30b-a3b-instruct",
  messages: [{ role: "user", content: "Escreva uma folha de dicas de anotações de tipo em Python." }],
  max_tokens: 600,
});

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

Tudo downstream — streaming, function calling, uso assíncrono, response_format, temperature, max_tokens — funciona de forma idêntica. O endpoint da Novita AI segue a especificação da API Chat Completions da OpenAI.

Modelos de Código Aberto via Novita AI

Trocar base_url dá acesso a um catálogo de modelos de peso aberto que agora são competitivos com fronteiras de código fechado em tarefas específicas. Para fluxos de trabalho de codificação, function calling e raciocínio de contexto longo, a lacuna prática diminuiu substancialmente.

Modelos disponíveis através do endpoint compatível com OpenAI da Novita AI que valem a pena avaliar:

DeepSeek V4 Pro (deepseek/deepseek-v4-pro): Um modelo MoE grande (licença adjacente ao MIT) que está entre os primeiros no SWE-Bench e benchmarks de function calling. Forte para agentes de codificação, revisão de código e tarefas de uso de ferramentas em várias etapas onde você normalmente recorreria ao GPT-4o ou Claude Opus.

Qwen3 Coder 30B A3B Instruct (qwen/qwen3-coder-30b-a3b-instruct): Um modelo MoE esparso de 30B da família Qwen Coder, otimizado para geração de código, triagem de bugs e revisão de pull requests. A $0,07 por 1M de tokens de entrada e $0,27 por 1M de tokens de saída na Novita AI, é substancialmente mais barato do que a maioria das APIs fechadas para assistência de codificação rotineira.

Qwen3 235B A22B Instruct (qwen/qwen3-235b-a22b-instruct-2507): Um modelo MoE grande (Apache 2.0) com forte raciocínio e desempenho de codificação multilíngue. Bom para tarefas onde você atualmente usa GPT-4o para respostas criativas ou complexas, mas deseja reduzir o custo por token em volume.

O formato do ID do modelo na Novita AI é provider/model-name. Você o passa diretamente para o parâmetro model no SDK.

Um padrão de roteamento direto para equipes que desejam misturar modelos abertos e fechados:

def obter_cliente(usar_novita: bool = False) -> OpenAI:
    if usar_novita:
        return OpenAI(
            api_key=os.environ["NOVITA_API_KEY"],
            base_url="https://api.novita.ai/openai",
        )
    return OpenAI(api_key=os.environ["OPENAI_API_KEY"])

# Use peso aberto para tarefas de codificação sensíveis a custo e de alto volume
cliente_codificacao = obter_cliente(usar_novita=True)

# Use OpenAI para tarefas onde o modelo fechado é genuinamente melhor
cliente_openai = obter_cliente(usar_novita=False)

Isso permite testar A/B a qualidade da saída, avaliar o desempenho por tarefa e deslocar o volume para modelos mais baratos sem tocar na lógica da requisição.

FAQ

Qual é o nome do pacote Python da OpenAI?

O nome do pacote no PyPI é openai. Instale com pip install openai.

Como é chamada a classe cliente Python da OpenAI?

A classe principal é OpenAI para uso síncrono e AsyncOpenAI para uso assíncrono. Ambas estão no módulo openai: from openai import OpenAI, AsyncOpenAI.

O SDK Python da OpenAI suporta streaming?

Sim. Use client.chat.completions.stream() como um gerenciador de contexto, ou passe stream=True para client.chat.completions.create() e itere sobre os chunks.

Qual é o nome do pacote do SDK JavaScript da OpenAI?

O pacote npm é openai. Instale com npm install openai. As assinaturas de classe e método são quase idênticas ao SDK Python.

Como usar Azure OpenAI com Python?

Use a classe AzureOpenAI do pacote openai. Passe azure_endpoint, api_key e api_version. O parâmetro model se refere ao nome da sua implantação no Azure, não ao modelo subjacente.

Posso usar o SDK Python da OpenAI com outros provedores?

Sim. Qualquer provedor que implemente o formato da API Chat Completions da OpenAI pode ser usado configurando base_url no cliente. O endpoint da Novita AI em https://api.novita.ai/openai é um exemplo; o conjunto completo de recursos do SDK — streaming, function calling, assíncrono — funciona sem alterações.

Como manter minha chave de API da OpenAI segura?

Armazene a chave em uma variável de ambiente (OPENAI_API_KEY) e leia-a com os.environ["OPENAI_API_KEY"]. Nunca a coloque no código-fonte, repositórios públicos, logs de build ou JavaScript do lado do cliente.

Artigos Recomendados

• Novita AI Agora Suporta o SDK OpenAI Agents! — Conecte modelos Novita AI ao SDK OpenAI Agents para orquestração multiagente, guardrails e tracing.
• Guia de Início Rápido do Qwen3 Coder 30B A3B Instruct — ID do modelo, preços, janela de contexto e exemplos de API para este modelo de codificação econômico na Novita AI.
• SDK Vercel AI: Guia Completo para Desenvolvedores para Criar Aplicações de IA — Use o SDK Vercel AI com o endpoint compatível com OpenAI da Novita AI para streaming, chamadas de ferramentas e loops de agente em TypeScript.