OpenAI Python SDK: 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, análise de respostas, streaming e tentativas. Este guia cobre instalação, a classe principal OpenAI, conclusões de chat, streaming, chamada de funções, uso assíncrono, o equivalente no SDK JavaScript, integração com Azure OpenAI e compatibilidade com Novita AI.

Instalar o Pacote Python da OpenAI

Python 3.10 ou superior é necessário:

pip install openai

Se você está migrando da API legada 0.x, substitua openai.ChatCompletion.create() por 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 Cliente OpenAI

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 pool de conexões, tentativas e timeouts. Você deve criar uma instância e reutilizá-la em toda a 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	Sobrescrever para proxy ou API compatível
timeout	600s	Timeout por requisição
max_retries	2	Tentativas automáticas em erros de limite de taxa
http_client	None	Cliente httpx personalizado para proxy ou configuração de certificado

Conclusões de Chat: Requisição Básica

Conclusões de chat 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 de 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 você 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 geradores Python em linguagem simples."},
    ],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

Usar o gerenciador de contexto (declaração 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 você precisar de streaming sem um gerenciador de contexto:

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

Chamada de Funções

A chamada de funções 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, em seguida, envia o resultado de volta para o modelo incorporar 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": "get_weather",
            "description": "Retorna o clima atual para uma cidade.",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {
                        "type": "string",
                        "description": "Nome da cidade, ex. 'São Paulo'",
                    }
                },
                "required": ["city"],
            },
        },
    }
]

messages = [{"role": "user", "content": "Como está 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 = {"city": args["city"], "temperature": "18°C", "condition": "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 duas etapas é o padrã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 get_response(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():
    result = await get_response("O que é asyncio em Python?")
    print(result)

asyncio.run(main())

AsyncOpenAI é um equivalente assíncrono de substituição direta; todos os métodos são aguardáveis. Isso é preferível a usar asyncio.to_thread para envolver o cliente síncrono.

SDK JavaScript da OpenAI

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

npm install openai

Conclusão de chat básica 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, mas expor sua chave de API no navegador é inseguro. Use um proxy no lado do servidor. A opção base_url para APIs compatíveis funciona da mesma forma que em Python.

Integração Python com Azure OpenAI

Se você está 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",  # Seu nome de implantação no Azure
    messages=[
        {"role": "user", "content": "Como usar o Azure OpenAI com Python?"},
    ],
)

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

Variáveis de ambiente necessárias para o 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 seu nome de 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",
)

Usar Novita AI com o Mesmo SDK

A Novita AI expõe um endpoint compatível com OpenAI em https://api.novita.ai/openai. Você pode usar o mesmo SDK Python ou JavaScript openai e alterar apenas base_url e api_key:

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-v3.1",
    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-480b-a35b-instruct",
  messages: [{ role: "user", content: "Escreva uma folha de dicas de anotações de tipo Python." }],
  max_tokens: 600,
});

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

Tudo a jusante - streaming, chamada de funções, uso assíncrono, response_format, temperature e max_tokens - funciona da mesma forma.

Quando Usar o Novita Agent Sandbox

Use o SDK da OpenAI para chamadas de modelo e, em seguida, use o Novita Agent Sandbox quando seu fluxo de trabalho precisar de execução de código, ações de navegador ou operações de arquivo em isolamento. Isso mantém a camada do SDK focada em inferência enquanto o Sandbox lida com as partes arriscadas de um loop de agente.

Modelos Open-Source via Novita AI

Trocar base_url dá acesso a modelos de peso aberto na Novita AI sem alterar seu código do cliente. Isso é útil quando você quer um modelo para codificação, uso de ferramentas ou trabalho de contexto longo, mas ainda quer o mesmo fluxo de trabalho do SDK.

O formato do ID do modelo na Novita AI é provider/model-name, e você o passa diretamente para o parâmetro model.

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

def get_client(use_novita: bool = False) -> OpenAI:
    if use_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 alto volume
coding_client = get_client(use_novita=True)

# Use OpenAI para tarefas onde o modelo fechado é genuinamente melhor
openai_client = get_client(use_novita=False)

Isso permite testar A/B a qualidade da saída, rotear trabalho para a Novita AI quando for adequado e manter um caminho único de SDK entre provedores.

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 do 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 o 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 definindo 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, chamada de funções, 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 em código fonte, repositórios públicos, logs de build ou JavaScript do lado do cliente.

Artigos Recomendados

• Novita AI Agora Suporta o SDK de Agentes da OpenAI! — Conecte modelos da Novita AI ao SDK de Agentes da OpenAI para orquestração multi-agente, guardrails e tracing.
• 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 de IA da Vercel: Guia Completo para Desenvolvedores na Criação de Aplicações de IA — Use o SDK de IA da Vercel com o endpoint compatível com OpenAI da Novita AI para streaming, chamadas de ferramentas e loops de agente em TypeScript.