Use Groq GPT-OSS 120B com o SDK da OpenAI: Base URL, preços e cache

O endpoint compatível com OpenAI da Groq é uma troca real de uma linha: defina base_url como https://api.groq.com/openai/v1 e continue usando o SDK da OpenAI. Em 17 de junho de 2026, a Groq lista openai/gpt-oss-120b a US$ 0,15 por 1M de tokens de entrada sem cache, US$ 0,075 por 1M de tokens de entrada em cache e US$ 0,60 por 1M de tokens de saída em sua página de preços (Preços da Groq).

Essa é a parte útil. A armadilha é assumir que “compatível com OpenAI” significa “comportamento idêntico e cobrança idêntica”. Não significa. Você ainda precisa escolher o ID do modelo da Groq, acompanhar acertos de cache, evitar parâmetros da OpenAI não compatíveis e contabilizar separadamente as chamadas de ferramentas integradas.

O que você está realmente trocando

A documentação da Groq diz que sua API é “principalmente compatível com as bibliotecas cliente da OpenAI” e mostra a configuração exata do cliente OpenAI: passe sua chave da Groq e defina base_url="https://api.groq.com/openai/v1" (Compatibilidade da Groq com OpenAI).

Instale o SDK Python da OpenAI:

pip install openai
export GROQ_API_KEY="gsk_..."

Então chame o GPT-OSS 120B pela Groq:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["GROQ_API_KEY"],
    base_url="https://api.groq.com/openai/v1",
)

response = client.chat.completions.create(
    model="openai/gpt-oss-120b",
    messages=[
        {"role": "system", "content": "You are a concise senior backend engineer."},
        {"role": "user", "content": "Write a PostgreSQL index plan for a slow user_events query."},
    ],
)

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

A diferença importante é o model. Na própria plataforma da OpenAI, você talvez use o nome de um modelo hospedado pela OpenAI. Na Groq, o GPT-OSS é endereçado como openai/gpt-oss-120b ou openai/gpt-oss-20b.

A OpenAI lançou gpt-oss-120b e gpt-oss-20b em 5 de agosto de 2025 como modelos de raciocínio com pesos abertos sob Apache 2.0 (OpenAI). A OpenAI diz que gpt-oss-120b tem 117B de parâmetros totais, 5,1B de parâmetros ativos por token, 128 especialistas, 4 especialistas ativos por token e suporte nativo a comprimentos de contexto de até 128k (OpenAI). A página do modelo da Groq lista a janela de contexto do openai/gpt-oss-120b hospedado como 131.072 tokens e o máximo de tokens de saída como 65.536 (model card da Groq).

Escolha 120B ou 20B

Use 120B quando qualidade for mais importante que custo bruto: planejamento de agentes, tarefas de programação mais difíceis, extração complexa ou raciocínio em várias etapas. Use 20B quando você precisar de throughput mais barato para roteamento, sumarização, classificação, assistentes curtos ou jobs em background de alto volume.

ID do modelo da Groq	Velocidade listada	Entrada sem cache	Entrada em cache	Saída
openai/gpt-oss-120b	500 TPS	US$ 0,15 / 1M	US$ 0,075 / 1M	US$ 0,60 / 1M
openai/gpt-oss-20b	1.000 TPS	US$ 0,075 / 1M	US$ 0,0375 / 1M	US$ 0,30 / 1M

Esses preços vêm da tabela de preços atual da Groq e da tabela de cache de prompts (Preços da Groq). O modelo 20B custa exatamente metade do preço por token listado para o 120B. Isso faz dele um bom padrão para fluxos de trabalho do tipo “teste primeiro”. Se a qualidade da resposta não for boa o suficiente, promova esse caminho para 120B.

Aqui está uma pequena troca que você pode manter na configuração:

import os
from openai import OpenAI

MODEL = os.getenv("GROQ_MODEL", "openai/gpt-oss-20b")

client = OpenAI(
    api_key=os.environ["GROQ_API_KEY"],
    base_url="https://api.groq.com/openai/v1",
)

def ask(prompt: str) -> str:
    response = client.chat.completions.create(
        model=MODEL,
        messages=[
            {"role": "system", "content": "Answer with practical developer steps."},
            {"role": "user", "content": prompt},
        ],
    )
    return response.choices[0].message.content

print(ask("Give me a minimal Redis rate limiter design."))

Execute com 20B:

GROQ_MODEL=openai/gpt-oss-20b python app.py

Execute com 120B:

GROQ_MODEL=openai/gpt-oss-120b python app.py

Precifique requisições com acertos de cache

O cache de prompts da Groq é automático para modelos compatíveis, incluindo openai/gpt-oss-20b e openai/gpt-oss-120b. A Groq diz que não são necessárias mudanças no código, que acertos de cache usam correspondência exata de prefixo, que partes em cache recebem 50% de desconto em tokens de entrada e que dados em cache expiram automaticamente após 2 horas sem uso (Cache de prompts da Groq).

A regra prática: coloque texto estável primeiro.

Boa ordem:

1. Prompt de sistema
2. Definições de ferramentas
3. Exemplos few-shot
4. Documentos ou esquemas compartilhados
5. Entrada específica do usuário
6. Timestamps, IDs, dados por requisição

Má ordem: colocar um timestamp, ID de requisição ou campo específico do usuário antes de um prompt compartilhado de 20.000 tokens. Isso quebra o prefixo.

Aqui está um helper de custo para GPT-OSS 120B:

def groq_gpt_oss_120b_cost(prompt_tokens, cached_tokens, completion_tokens):
    uncached_tokens = max(prompt_tokens - cached_tokens, 0)

    return (
        uncached_tokens / 1_000_000 * 0.15
        + cached_tokens / 1_000_000 * 0.075
        + completion_tokens / 1_000_000 * 0.60
    )

E aqui está uma chamada executável que imprime o uso de cache se a Groq retornar isso:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["GROQ_API_KEY"],
    base_url="https://api.groq.com/openai/v1",
)

STATIC_POLICY = """
You are an internal code review assistant.
Always check correctness, security, performance, and migration risk.
Return JSON with keys: summary, risks, suggested_patch.
"""

def review(diff: str):
    response = client.chat.completions.create(
        model="openai/gpt-oss-120b",
        messages=[
            {"role": "system", "content": STATIC_POLICY},
            {"role": "user", "content": diff},
        ],
        response_format={"type": "json_object"},
    )

    usage = response.usage
    details = getattr(usage, "prompt_tokens_details", None)
    cached = getattr(details, "cached_tokens", 0) if details else 0

    print("prompt_tokens:", usage.prompt_tokens)
    print("cached_tokens:", cached)
    print("completion_tokens:", usage.completion_tokens)
    print("estimated_cost_usd:", groq_gpt_oss_120b_cost(
        usage.prompt_tokens,
        cached,
        usage.completion_tokens,
    ))

    return response.choices[0].message.content

A documentação de cache da Groq mostra cached_tokens em usage.prompt_tokens_details e define a taxa de acerto de cache como cached_tokens / prompt_tokens × 100% (Cache de prompts da Groq). Não presuma que toda segunda requisição será mais barata. Prefixos exatos importam.

Conte chamadas de ferramentas separadamente

Preços por token não são a conta inteira se você habilitar ferramentas integradas. A página de preços da Groq lista Built-In Tools para GPT-OSS separadamente: Browser Search basic search custa US$ 5 / 1000 requisições, Browser Search visit website custa US$ 1 / 1000 requisições e Code Execution Python custa US$ 0,18 / hora (Preços da Groq).

Isso muda como você projeta agentes. Um bot de suporte que chama busca uma vez por mensagem de usuário tem um formato de custo diferente de um sumarizador que usa apenas tokens de prompt. Cache ajuda com esquemas de ferramentas repetidos, mas não torna chamadas de ferramentas externas gratuitas.

Também verifique a compatibilidade antes de copiar e colar código da OpenAI. A documentação de compatibilidade da Groq com OpenAI lista campos não compatíveis que podem retornar 400, incluindo logprobs, logit_bias, top_logprobs, messages[].name e valores de n diferentes de 1 (Compatibilidade da Groq com OpenAI). A Groq também diz que temperature=0 é convertido para 1e-8.

Uma requisição mínima segura fica assim:

response = client.chat.completions.create(
    model="openai/gpt-oss-120b",
    temperature=0.2,
    messages=[
        {"role": "system", "content": "Be precise. If unsure, say so."},
        {"role": "user", "content": "Explain this stack trace and suggest a fix: ..."},
    ],
)

Evite migrar o app inteiro em um único commit. Coloque configurações do provedor atrás de variáveis de ambiente:

LLM_BASE_URL=https://api.groq.com/openai/v1
LLM_API_KEY=$GROQ_API_KEY
LLM_MODEL=openai/gpt-oss-120b

Então conecte-as ao SDK:

client = OpenAI(
    api_key=os.environ["LLM_API_KEY"],
    base_url=os.environ["LLM_BASE_URL"],
)

response = client.chat.completions.create(
    model=os.environ["LLM_MODEL"],
    messages=[{"role": "user", "content": "Summarize this incident report."}],
)

Uma saída prática para múltiplos provedores

Se você está conectando isso em produção, não espalhe suposições sobre o provedor por toda a base de código. Mantenha base_url, api_key e model na configuração. Isso facilita testar a Groq e também torna o roteamento de provedores algo simples.

Para equipes que querem um endpoint compatível com OpenAI para Claude, GPT e Gemini, onehop é o caminho fácil: altere a base URL para https://api.onehop.ai/v1. Ele é compatível com OpenAI/Anthropic, tem preço mais barato que os provedores primários, e novas contas recebem US$ 10 grátis sem precisar de cartão.

import os
from openai import OpenAI

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

response = client.chat.completions.create(
    model=os.environ["ONEHOP_MODEL"],
    messages=[
        {"role": "user", "content": "Compare this API design against common REST mistakes."}
    ],
)

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

Use a Groq quando você quiser especificamente inferência rápida de GPT-OSS e a stack de ferramentas/cache da Groq. Use onehop quando quiser uma superfície única de integração entre Claude, GPT, Gemini e outros modelos hospedados sem reescrever código cliente. Você pode chamar Claude e outros modelos na onehop ou cadastre-se para ganhar US$ 10 em crédito grátis.

Checklist de produção

Antes de colocar em produção, rode este checklist:

• Fixe o ID do modelo: openai/gpt-oss-120b para qualidade, openai/gpt-oss-20b para menor custo.
• Mantenha as seções estáveis do prompt primeiro para que a Groq possa reutilizar prefixos em cache.
• Registre prompt_tokens, cached_tokens e completion_tokens para cada requisição.
• Adicione contabilização separada para Browser Search, Visit Website e Code Execution.
• Remova parâmetros da OpenAI não compatíveis antes de rotear tráfego para a Groq.
• Mantenha base_url configurável para testar Groq, APIs first-party ou onehop sem tocar na lógica de negócio.

A migração inteira pode ser uma linha. A migração confiável são três linhas mais contabilidade: base URL, ID do modelo e telemetria de custo. Comece por aí, depois decida se a qualidade do 120B vale o gasto com tokens de saída para cada caminho no seu app. Se você quiser o mesmo padrão de base URL para acesso mais amplo a modelos, chame Claude e outros modelos na onehop e cadastre-se para ganhar US$ 10 em crédito grátis.