Instalar o SDK Python
Nesta página
Instalar o SDK Python
O SDK Python openai é a biblioteca oficial para interagir com a API. Esta lição guia-o na instalação e configura uma estrutura de projeto limpa que utilizará ao longo do restante curso.
Pré-requisitos e Instalação
Precisa do Python 3.10 ou superior — o mínimo exigido pelo SDK openai (versão 3.42.1 em 2 de novembro de 2026, segundo o PyPI) —, de um gestor de pacotes (pip ou uv) e da chave de API que obteve na lição anterior. Comece por confirmar o seu interpretador, uma vez que as máquinas de desenvolvimento costumam alojar múltiplas versões:
python --version
# Python 3.12.4
A instalação requer apenas um comando: pip install openai, ou uv pip install openai se utilizar o uv, que é significativamente mais rápido. No entanto, crie o hábito de trabalhar dentro de um ambiente virtual. Isto evita o cenário comum em que, seis meses depois, descobre que dois projetos exigem versões incompatíveis da mesma biblioteca.
# Criar um ambiente virtual
python -m venv .venv
# Ativar (Linux/macOS)
source .venv/bin/activate
# Ativar (Windows)
.venv\Scripts\activate
# Instalar o SDK
pip install openai
Dois companheiros surgem em quase todos os projetos e merecem ser instalados juntamente com o SDK. O Pydantic ajuda a definir esquemas para Saída Estruturada, que verá mais tarde; o python-dotenv carrega o ficheiro .env para variáveis de ambiente.
# Instalar com suporte para dataclasses do Pydantic
pip install openai pydantic
# Instalar com python-dotenv para variáveis de ambiente
pip install openai python-dotenv
Por fim, verifique se a importação funciona e anote a versão instalada. Esta é a primeira informação a fornecer caso abra um ticket de suporte.
import openai
print(f"OpenAI SDK version: {openai.__version__}")
# Output: OpenAI SDK version: 1.68.0 (or newer)
Um Cliente, Todas as APIs
O SDK gira em torno de um único objeto cliente que expõe toda a plataforma através de submódulos. Não precisa de instanciar nada de novo para alternar entre geração de texto, embeddings ou moderação.
from openai import OpenAI
client = OpenAI()
# Responses API (texto, chamada de funções, saída estruturada)
client.responses.create(...)
# Chat Completions API (legado)
client.chat.completions.create(...)
# Embeddings
client.embeddings.create(...)
# Imagens
client.images.generate(...)
# Áudio
client.audio.transcriptions.create(...)
client.audio.speech.create(...)
# Moderação
client.moderations.create(...)
Configurar o Cliente para o Seu Contexto
As predefinições do SDK funcionam para experimentação, mas são insuficientes para aplicações web. O tempo limite predefinido é de dez minutos: numa API HTTP esperada responder em segundos, isto significa que um pedido bloqueado ocupa um trabalhador durante demasiado tempo. Reduza-o e aumente o número de novas tentativas automáticas, que por predefinição é duas.
from openai import OpenAI
client = OpenAI(
timeout=60.0, # 60 segundos (predefinição: 10 minutos)
max_retries=3, # 3 tentativas em caso de erro (predefinição: 2)
)
O parâmetro base_url responde a outra necessidade: encaminhar chamadas através de um proxy corporativo que regista o tráfego de saída, ou para um serviço que expõe uma API compatível.
# Útil para proxies corporativos ou APIs compatíveis
client = OpenAI(
base_url="https://your-proxy.company.com/v1"
)
Por fim, se a sua aplicação depende de asyncio — FastAPI, aiohttp e semelhantes —, utilize AsyncOpenAI. O cliente síncrono bloquearia o ciclo de eventos durante a geração, anulando os benefícios do código assíncrono.
from openai import AsyncOpenAI
async_client = AsyncOpenAI()
# Utilização com await
import asyncio
async def main():
response = await async_client.responses.create(
model="gpt-5.6-terra",
input="Hello!"
)
print(response.output_text)
asyncio.run(main())
# Output: Hello! How can I help you today?
Estruturar o Seu Projeto
Adote uma organização que isole a configuração do cliente do resto do seu código desde o início. Isto evita dispersar dezenas de chamadas OpenAI() por todo o projeto, cada uma com as suas próprias definições.
my-project/
├── .env # Chave de API (NUNCA fazer commit para git)
├── .gitignore # Inclui .env
├── requirements.txt # Dependências
├── src/
│ ├── __init__.py
│ ├── client.py # Configuração do cliente OpenAI
│ └── main.py # Ponto de entrada
└── tests/
└── test_api.py
O ficheiro src/client.py centraliza a fábrica do cliente: no dia em que alterar o tempo limite ou adicionar um proxy, só precisa de modificar um local.
from openai import OpenAI
from dotenv import load_dotenv
load_dotenv()
def get_client() -> OpenAI:
"""Devolve um cliente OpenAI configurado."""
return OpenAI(
max_retries=3,
timeout=30.0
)
E o requirements.txt fixa as versões mínimas esperadas:
openai>=1.60.0
python-dotenv>=1.0.0
pydantic>=2.0.0
Três Falhas Comuns
Um ModuleNotFoundError em openai sinaliza quase sempre um ambiente virtual inativo ou diferente daquele onde instalou o pacote. Localize o interpretador realmente em uso com which python no Linux e macOS, ou where python no Windows, e reinstale com pip install --upgrade openai. Um AuthenticationError aponta para a variável de ambiente: imprima os.environ.get("OPENAI_API_KEY", "NOT DEFINED") para descartar problemas — o ficheiro .env não é carregado se load_dotenv() não tiver sido chamado antes de instanciar o cliente. Por fim, um erro relativo a um parâmetro desconhecido indica geralmente um SDK demasiado antigo para a funcionalidade que está a utilizar: pip install --upgrade openai resolve isto.
Pontos-chave
- Instale o SDK com
pip install openaidentro de um ambiente virtual - O cliente
OpenAI()é o ponto de entrada para todas as APIs - Utilize
AsyncOpenAI()para aplicações assíncronas - Configure o tempo limite e as novas tentativas conforme as suas necessidades
- Estruture o seu projeto com um ficheiro
.enve um cliente centralizado