David-Li0406/meta-skill-evloving

OpenAI API - Guia Completo

Versão: Pronto para Produção ✅ Pacote: [email protected] Última Atualização: 2026-11-26

---

Status

✅ Pronto para Produção:

• ✅ API Chat Completions (GPT-5, GPT-4o, GPT-4 Turbo)
• ✅ API Embeddings (text-embedding-3-small, text-embedding-3-large)
• ✅ API Images (Geração DALL-E 3 + Edição GPT-Image-1)
• ✅ API Audio (Transcrição Whisper + TTS com 11 vozes)
• ✅ API Moderation (11 categorias de segurança)
• ✅ Padrões de Streaming (SSE)
• ✅ Function Calling / Tools
• ✅ Saídas Estruturadas (JSON Schema)
• ✅ Visão (GPT-4o)
• ✅ Abordagens com SDK Node.js e fetch

---

Índice

1. Início Rápido
2. API Chat Completions
3. Modelos da Série GPT-5
4. Padrões de Streaming
5. Function Calling
6. Saídas Estruturadas
7. Visão (GPT-4o)
8. API Embeddings
9. API Images
10. API Audio
11. API Moderation
12. Tratamento de Erros
13. Limites de Taxa
14. Melhores Práticas de Produção
15. Relação com openai-responses

---

Início Rápido

Instalação

npm install [email protected]

Configuração de Ambiente

export OPENAI_API_KEY="sk-..."

Ou crie um arquivo .env:

OPENAI_API_KEY=sk-...

Primeira Chamada Chat Completions (SDK Node.js)

import OpenAI from 'openai';

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

const completion = await openai.chat.completions.create({
  model: 'gpt-5',
  messages: [
    { role: 'user', content: 'Quais são as três leis da robótica?' }
  ],
});

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

Primeira Chamada Chat Completions (Fetch - Cloudflare Workers)

const response = await fetch('https://api.openai.com/v1/chat/completions', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${env.OPENAI_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'gpt-5',
    messages: [
      { role: 'user', content: 'Quais são as três leis da robótica?' }
    ],
  }),
});

const data = await response.json();
console.log(data.choices[0].message.content);

---

API Chat Completions

Endpoint: POST /v1/chat/completions

A API Chat Completions é a interface central para interagir com os modelos de linguagem da OpenAI. Ela suporta IA conversacional, geração de texto, function calling, saídas estruturadas e recursos de visão.

Modelos Suportados

Série GPT-5 (Lançada em Agosto de 2025)

• gpt-5: Modelo de raciocínio completo com capacidades avançadas
• gpt-5-mini: Alternativa econômica com bom desempenho
• gpt-5-nano: Variante menor/mais rápida para tarefas simples

Série GPT-4o

• gpt-4o: Modelo multimodal com capacidades de visão
• gpt-4-turbo: Variante rápida do GPT-4

Série GPT-4

• gpt-4: Modelo GPT-4 original

Estrutura Básica da Solicitação

{
  model: string,              // Modelo a ser usado (ex.: "gpt-5")
  messages: Message[],        // Histórico da conversa
  reasoning_effort?: string,  // Apenas GPT-5: "minimal" | "low" | "medium" | "high"
  verbosity?: string,         // Apenas GPT-5: "low" | "medium" | "high"
  temperature?: number,       // NÃO suportado pelo GPT-5
  max_tokens?: number,        // Máximo de tokens a gerar
  stream?: boolean,           // Habilitar streaming
  tools?: Tool[],             // Function calling tools
}

Estrutura da Resposta

{
  id: string,                 // ID único da conclusão
  object: "chat.completion",
  created: number,            // Timestamp Unix
  model: string,              // Modelo utilizado
  choices: [{
    index: number,
    message: {
      role: "assistant",
      content: string,        // Texto gerado
      tool_calls?: ToolCall[] // Se houver function calling
    },
    finish_reason: string     // "stop" | "length" | "tool_calls"
  }],
  usage: {
    prompt_tokens: number,
    completion_tokens: number,
    total_tokens: number
  }
}

Papéis da Mensagem e Conversas de Múltiplas Voltas

Três papéis: system (comportamento), user (entrada), assistant (respostas do modelo).

Importante: A API é stateless - envie o histórico completo da conversa a cada solicitação. Para conversas com estado, use o skill openai-responses.

---

Modelos da Série GPT-5

Os modelos GPT-5 (lançados em agosto de 2025) introduzem controles de raciocínio e verbosidade:

GPT-5.1 (Lançado em 13 de Novembro de 2025)

Modelo mais recente com grandes melhorias:

• gpt-5.1: Raciocínio adaptativo que varia o tempo de pensamento dinamicamente
• Cache de prompt estendido de 24 horas: Consultas de acompanhamento mais rápidas e de baixo custo
• Novas ferramentas para desenvolvedores: apply_patch (edição de código), shell (execução de comandos)

MUDANÇA IMPORTANTE: O GPT-5.1 padroniza reasoning_effort: 'none' (em vez de GPT-5 que padroniza 'medium'). Atualize seu código ao migrar!

Parâmetro reasoning_effort

Controla a profundidade do pensamento (disponível no GPT-5 e GPT-5.1):

• "none": Sem raciocínio (mais rápido, menor latência) - padrão GPT-5.1
• "minimal": Respostas rápidas, pensamento mínimo
• "low": Raciocínio básico
• "medium": Raciocínio equilibrado - padrão GPT-5
• "high": Raciocínio profundo para problemas complexos

// GPT-5.1 sem raciocínio (rápido)
const completion = await openai.chat.completions.create({
  model: 'gpt-5.1',
  messages: [{ role: 'user', content: 'Consulta simples' }],
  // reasoning_effort: 'none' é o padrão implícito para GPT-5.1
});

// GPT-5.1 com raciocínio alto (tarefas complexas)
const completion = await openai.chat.completions.create({
  model: 'gpt-5.1',
  messages: [{ role: 'user', content: 'Resolva este problema matemático complexo...' }],
  reasoning_effort: 'high',
});

Parâmetro verbosity

Controla o detalhamento da saída (GPT-5/GPT-5.1):

• "low": Conciso
• "medium": Equilibrado (padrão)
• "high": Verboso

Limitações do GPT-5

NÃO Suportado:

• ❌ Parâmetros temperature, top_p, logprobs
• ❌ Cadeia de Pensamento com estado entre turnos

Alternativas: Use GPT-4o para temperature/top_p, ou o skill openai-responses para raciocínio com estado

---

Padrões de Streaming

Habilite com stream: true para entrega token por token.

SDK Node.js

const stream = await openai.chat.completions.create({
  model: 'gpt-5.1',
  messages: [{ role: 'user', content: 'Escreva um poema' }],
  stream: true,
});

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

Fetch (Cloudflare Workers)

const response = await fetch('https://api.openai.com/v1/chat/completions', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${env.OPENAI_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'gpt-5.1',
    messages: [{ role: 'user', content: 'Escreva um poema' }],
    stream: true,
  }),
});

const reader = response.body?.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader!.read();
  if (done) break;

  const chunk = decoder.decode(value);
  const lines = chunk.split('\n').filter(line => line.trim() !== '');

  for (const line of lines) {
    if (line.startsWith('data: ')) {
      const data = line.slice(6);
      if (data === '[DONE]') break;

      try {
        const json = JSON.parse(data);
        const content = json.choices[0]?.delta?.content || '';
        console.log(content);
      } catch (e) {
        // Ignorar JSON inválido
      }
    }
  }
}

Formato Server-Sent Events (SSE):

data: {"id":"chatcmpl-xyz","choices":[{"delta":{"content":"Olá"}}]}
data: [DONE]

Pontos-chave: Lide com chunks incompletos, sinal [DONE] e JSON inválidos de forma adequada.

---

Function Calling

Defina ferramentas com JSON Schema, o modelo as invoca com base no contexto.

Definição da Ferramenta e Solicitação

const tools = [{
  type: 'function',
  function: {
    name: 'get_weather',
    description: 'Obter clima atual para uma localização',
    parameters: {
      type: 'object',
      properties: {
        location: { type: 'string', description: 'Nome da cidade' },
        unit: { type: 'string', enum: ['celsius', 'fahrenheit'] }
      },
      required: ['location']
    }
  }
}];

const completion = await openai.chat.completions.create({
  model: 'gpt-5.1',
  messages: [{ role: 'user', content: 'Como está o clima em SF?' }],
  tools: tools,
});

Lidando com Chamadas de Ferramentas

const message = completion.choices[0].message;

if (message.tool_calls) {
  for (const toolCall of message.tool_calls) {
    const args = JSON.parse(toolCall.function.arguments);
    const result = await executeFunction(toolCall.function.name, args);

    // Enviar resultado de volta ao modelo
    await openai.chat.completions.create({
      model: 'gpt-5.1',
      messages: [
        ...messages,
        message,
        {
          role: 'tool',
          tool_call_id: toolCall.id,
          content: JSON.stringify(result)
        }
      ],
      tools: tools,
    });
  }
}

Padrão de Loop: Continue chamando a API até que não haja tool_calls na resposta.

---

Saídas Estruturadas

Saídas estruturadas permitem que você aplique validação de JSON Schema nas respostas do modelo.

Usando JSON Schema

const completion = await openai.chat.completions.create({
  model: 'gpt-4o', // Nota: Saídas estruturadas são melhor suportadas no GPT-4o
  messages: [
    { role: 'user', content: 'Gere um perfil de pessoa' }
  ],
  response_format: {
    type: 'json_schema',
    json_schema: {
      name: 'person_profile',
      strict: true,
      schema: {
        type: 'object',
        properties: {
          name: { type: 'string' },
          age: { type: 'number' },
          skills: {
            type: 'array',
            items: { type: 'string' }
          }
        },
        required: ['name', 'age', 'skills'],
        additionalProperties: false
      }
    }
  }
});

const person = JSON.parse(completion.choices[0].message.content);
// { name: "Alice", age: 28, skills: ["TypeScript", "React"] }

Modo JSON (Simples)

Para casos de uso mais simples, sem validação estrita de esquema:

const completion = await openai.chat.completions.create({
  model: 'gpt-5',
  messages: [
    { role: 'user', content: 'Liste 3 linguagens de programação como JSON' }
  ],
  response_format: { type: 'json_object' }
});

const data = JSON.parse(completion.choices[0].message.content);

Importante: Ao usar response_format, inclua "JSON" em seu prompt para orientar o modelo.

---

Visão (GPT-4o)

O GPT-4o suporta compreensão de imagens junto com texto.

Imagem via URL

const completion = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [
    {
      role: 'user',
      content: [
        { type: 'text', text: 'O que há nesta imagem?' },
        {
          type: 'image_url',
          image_url: {
            url: 'https://example.com/image.jpg'
          }
        }
      ]
    }
  ]
});

Imagem via Base64

import fs from 'fs';

const imageBuffer = fs.readFileSync('./image.jpg');
const base64Image = imageBuffer.toString('base64');

const completion = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [
    {
      role: 'user',
      content: [
        { type: 'text', text: 'Descreva esta imagem em detalhes' },
        {
          type: 'image_url',
          image_url: {
            url: `data:image/jpeg;base64,${base64Image}`
          }
        }
      ]
    }
  ]
});

Múltiplas Imagens

const completion = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [
    {
      role: 'user',
      content: [
        { type: 'text', text: 'Compare estas duas imagens' },
        { type: 'image_url', image_url: { url: 'https://example.com/image1.jpg' } },
        { type: 'image_url', image_url: { url: 'https://example.com/image2.jpg' } }
      ]
    }
  ]
});

---

API Embeddings

Endpoint: POST /v1/embeddings

Converta texto em vetores para busca semântica e RAG.

Modelos

• text-embedding-3-large: 3072 dims (custom: 256-3072), maior qualidade
• text-embedding-3-small: 1536 dims (custom: 256-1536), econômico, recomendado

Solicitação Básica

const embedding = await openai.embeddings.create({
  model: 'text-embedding-3-small',
  input: 'A comida estava deliciosa.',
});
// Retorna: { data: [{ embedding: [0.002, -0.009, ...] }] }

Dimensões Personalizadas (Específico da OpenAI)

const embedding = await openai.embeddings.create({
  model: 'text-embedding-3-small',
  input: 'Texto de exemplo',
  dimensions: 256, // Reduzido do padrão de 1536
});

Benefícios: Redução de armazenamento de 4x-12x, busca mais rápida, perda mínima de qualidade.

Processamento em Lote

const embeddings = await openai.embeddings.create({
  model: 'text-embedding-3-small',
  input: ['Primeiro doc', 'Segundo doc', 'Terceiro doc'],
});

Limites: 8192 tokens/entrada, 300k tokens no total por lote, tamanho máximo de array de 2048.

Pontos-chave: Use dimensões personalizadas para eficiência, processe em lote até 2048 docs, cacheie embeddings (determinísticos).

---

API Images

Geração de Imagens (DALL-E 3)

Endpoint: POST /v1/images/generations

const image = await openai.images.generate({
  model: 'dall-e-3',
  prompt: 'Um gato siamês branco com olhos azuis impressionantes',
  size: '1024x1024', // Também: 1024x1536, 1536x1024, 1024x1792, 1792x1024
  quality: 'standard', // ou 'hd'
  style: 'vivid', // ou 'natural'
});

console.log(image.data[0].url);
console.log(image.data[0].revised_prompt); // DALL-E 3 pode revisar o prompt por segurança

Especificidades do DALL-E 3:

• Suporta apenas n: 1 (uma imagem por solicitação)
• Pode revisar prompts para segurança/qualidade (verifique revised_prompt)
• URLs expiram em 1 hora (use response_format: 'b64_json')
• Custo: $0.040-0.080/imagem

Edição de Imagens (GPT-Image-1)

Endpoint: POST /v1/images/edits

import fs from 'fs';

const imageBuffer = fs.readFileSync('./input.png');
const maskBuffer = fs.readFileSync('./mask.png');

const response = await openai.images.edit({
  image: imageBuffer,
  mask: maskBuffer,
  prompt: 'Substitua o fundo por uma praia tropical',
  size: '1024x1024',
});

console.log(response.data[0].url);

Requisitos: Imagem PNG (<4MB, quadrada), máscara PNG (branca para áreas editáveis, preta para intocáveis). Sem máscara: edita imagem inteira.

---

API Audio

Transcrição (Whisper)

Endpoint: POST /v1/audio/transcriptions

import fs from 'fs';

const audioFile = fs.createReadStream('./audio.mp3');

const transcription = await openai.audio.transcriptions.create({
  model: 'whisper-1',
  file: audioFile,
});

console.log(transcription.text);

Formatos suportados: flac, m4a, mp3, mp4, mpeg, mpga, oga, ogg, wav, webm Tamanho máximo do arquivo: 25 MB

Tradução (Whisper)

const translation = await openai.audio.translations.create({
  model: 'whisper-1',
  file: audioFile,
});
// Traduz qualquer áudio para inglês (melhor para falas não-inglesas)

Síntese de Fala (TTS)

Endpoint: POST /v1/audio/speech

const speech = await openai.audio.speech.create({
  model: 'tts-1', // ou 'tts-1-hd' para maior qualidade
  voice: 'alloy', // Ver tabela de vozes abaixo
  input: 'Olá! Esta é uma mensagem de texto para fala.',
  speed: 1.0, // Opcional: 0.25 a 4.0
});

const buffer = Buffer.from(await speech.arrayBuffer());
// Salve ou transmita o buffer de áudio

Tabela de Vozes:

Voz	Descrição	Melhor Para
alloy	Neutra, versátil	Uso geral
ash	Calma, jovem	Conversas casuais
ballad	Expressiva, emotiva	Contação de histórias
coral	Amigável, acolhedora	Conteúdo educativo
echo	Masculina, profunda	Narração
fable	Britânica, animada	Conteúdo infantil
nova	Feminina, clara	Assistente virtual
sage	Suave, serena	Meditação/relaxamento
shimmer	Brilhante, otimista	Conteúdo motivacional
verst	Sotaque americano, enérgico	Anúncios/marketing

---

API Moderation

Endpoint: POST /v1/moderations

const moderation = await openai.moderations.create({
  model: 'omni-moderation-latest', // ou 'text-moderation-latest' para legado
  input: 'Eu quero prejudicar alguém',
});

console.log(moderation.results[0].flagged); // true se violar políticas
console.log(moderation.results[0].categories);
// { sexual: false, hate: false, harassment: false, self-harm: false, ... }
console.log(moderation.results[0].category_scores);
// { sexual: 0.01, hate: 0.02, violence: 0.95, ... }

Categorias de Segurança: sexual, hate, harassment, self-harm, sexual/minors, hate/threatening, violence/graphic, violence, self-harm/intent, self-harm/instructions, harassment/threatening

Casos de Uso: Moderação de entrada/saída, filtragem de conteúdo gerado pelo usuário, verificação de segurança para saídas da IA.

---

Tratamento de Erros

Erros Comuns

Código	Erro	Causa	Solução
400	bad_request	Parâmetros inválidos (modelo não suporta campo)	Verifique documentação
401	authentication_error	Chave API inválida/ausente	Verifique OPENAI_API_KEY
429	rate_limit_error	Excedeu limite de taxa ou cota	Implemente retry com backoff exponencial
500	server_error	Problema no servidor OpenAI	Repita após 2-5 segundos

Tratamento no SDK Node.js

import OpenAI from 'openai';

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

try {
  const completion = await openai.chat.completions.create({
    model: 'gpt-5',
    messages: [{ role: 'user', content: 'Olá' }],
  });
} catch (error) {
  if (error instanceof OpenAI.APIError) {
    console.error(`Erro na API: ${error.status} - ${error.message}`);
    
    switch (error.status) {
      case 429:
        // Limite de taxa excedido - implementar retry
        break;
      case 401:
        // Erro de autenticação
        break;
      case 400:
        // Solicitação inválida
        break;
    }
  } else {
    console.error('Erro inesperado:', error);
  }
}

---

Limites de Taxa

Níveis de Uso

• Free: $5/mês de crédito gratuito (taxas limitadas)
• Tier 1: $50 pagos (aumenta taxas)
• Tier 5: $10k+ pagos (taxas mais altas)

Melhores Práticas para Limites de Taxa

const sleep = (ms: number) => new Promise(resolve => setTimeout(resolve, ms));

async function retryWithBackoff<T>(
  fn: () => Promise<T>,
  maxRetries: number = 5
): Promise<T> {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error instanceof OpenAI.APIError && error.status === 429) {
        const waitTime = Math.pow(2, i) * 1000 + Math.random() * 1000;
        console.log(`Atingiu limite. Tentativa ${i + 1}/${maxRetries}. Aguardando ${waitTime}ms...`);
        await sleep(waitTime);
      } else {
        throw error; // Erro não relacionado a limite
      }
    }
  }
  throw new Error('Máximo de tentativas de retry excedido');
}

Estratégias de Otimização

• Cache: Armazene respostas de embeddings (determinísticas)
• Batching: Combine múltiplas solicitações pequenas
• Off-peak: Execute tarefas pesadas fora do horário de pico (se aplicável)

---

Melhores Práticas de Produção

Otimização de Custo

// Use gpt-5-nano para tarefas simples (velocidade, baixo custo)
const simpleTask = await openai.chat.completions.create({
  model: 'gpt-5-nano',
  messages: [{ role: 'user', content: 'Traduza "Olá" para espanhol' }],
});

// Use GPT-5.1 com baixo esforço de raciocínio para tarefas rotineiras
const routine = await openai.chat.completions.create({
  model: 'gpt-5.1',
  messages: [{ role: 'user', content: 'Resuma este texto' }],
  reasoning_effort: 'low',
});

// Use GPT-5.1 com raciocínio alto para tarefas complexas
const complexAnalysis = await openai.chat.completions.create({
  model: 'gpt-5.1',
  messages: [{ role: 'user', content: 'Analise este código e sugira otimizações' }],
  reasoning_effort: 'high',
});

Otimização de Latência

• Use streaming (stream: true) para experiências interativas
• Escolha o menor modelo que atenda às suas necessidades (gpt-5-nano < gpt-5-mini < gpt-5)
• Minimize o histórico de mensagens (envie apenas contexto essencial)
• Cacheie resultados determinísticos (embeddings são idênticos para entrada exata)

Otimização de Confiabilidade

• Implemente retry com backoff exponencial para erros 429 e 500
• Valide entradas antes de enviar (tamanho, formato)
• Use saídas estruturadas (response_format) para garantir que as respostas correspondam ao esquema esperado
• Monitore o uso de tokens para evitar exceder cotas

Considerações de Segurança

• Nunca exponha chaves API no lado do cliente
• Armazene chaves com segurança em variáveis de ambiente
• Implemente moderação de entrada e saída (use API Moderation)
• Valide e limpe entradas do usuário antes de passá-las para a API

---

Relação com openai-responses

Quando Usar openai-responses (API com Estado)

Use o skill openai-responses quando você precisa de:

• Conversas com estado (histórico gerenciado automaticamente)
• Cadeia de Pensamento com estado entre turnos
• Busca de conhecimento incorporada
• Web browsing
• Ferramentas de código (interpretador de código)

Quando Usar Este Skill (API Stateless)

Use este skill (OpenAI API) quando você precisa:

• Controle direto sobre todas as chamadas de API
• Acesso a todas as APIs (Chat, Embeddings, Images, Áudio, Moderação)
• Custos previsíveis (sem armazenamento gerenciado)
• Integração com fluxos de trabalho existentes
• Implantações serverless (Cloudflare Workers)

Combinando Ambos

// Use openai-responses para conversas complexas com estado
// Use este skill para tarefas auxiliares como embeddings ou moderação

// Exemplo: RAG com embeddings deste skill
const queryEmbedding = await openai.embeddings.create({
  model: 'text-embedding-3-small',
  input: userQuery,
  dimensions: 256,
});

// Buscar documentos relevantes do banco vetorial
const relevantDocs = await searchVectorDB(queryEmbedding.data[0].embedding);

// Passar contexto para uma conversa openai-responses
// (Supondo que você tenha acesso ao cliente responses)