Chat Completions com cURL em Vários Modelos de IA

Você pode aprender mais sobre um gateway de IA com um único comando no terminal do que com uma longa lista de recursos. Se o gateway for realmente compatível com OpenAI, a mesma solicitação curl deve funcionar em várias famílias de modelos suportadas, enquanto a URL base, o cabeçalho de autorização, o formato da mensagem e o processamento da resposta permanecem estáveis.

Este tutorial mostra o padrão prático com a Flatkey: comece com uma solicitação de chat-completions, mova o nome do modelo para uma variável e teste várias famílias de modelos atuais sem reescrever a integração. Ele foi projetado para desenvolvedores que querem validar uma API a partir do terminal antes de adicionar um SDK ou comprometer código da aplicação.

Nota sobre seleção de modelos: Os catálogos de modelos mudam. Os IDs de modelo abaixo refletem a documentação pública da Flatkey verificada em 24 de julho de 2026. Confirme a linha do modelo atual e a disponibilidade antes de usar um ID em produção.

The shortest working chat-completions cURL request

Crie uma chave de API da Flatkey, exporte-a no seu shell e envie uma solicitação para o endpoint de chat-completions compatível com OpenAI:

export FLATKEY_API_KEY="your-flatkey-api-key"

curl https://router.flatkey.ai/v1/chat/completions \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {
        "role": "user",
        "content": "Write a one-sentence product description for a waterproof daypack."
      }
    ]
  }'

Quatro partes importam:

Para modelos de chat compatíveis, o principal campo que você altera é model.

Use the same cURL shape across model families

Coloque o ID do modelo em uma variável de shell para que o corpo da solicitação não precise mudar:

export FLATKEY_API_KEY="your-flatkey-api-key"
export MODEL="gpt-4o-mini"

curl -sS https://router.flatkey.ai/v1/chat/completions \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"$MODEL\",
    \"messages\": [
      {
        \"role\": \"system\",
        \"content\": \"Return concise ecommerce copy.\"
      },
      {
        \"role\": \"user\",
        \"content\": \"Write a product title for a lightweight waterproof daypack.\"
      }
    ],
    \"temperature\": 0.2
  }" | jq -r '.choices[0].message.content'

Agora execute novamente o comando com outro ID de modelo documentado:

export MODEL="claude-sonnet-4-6"

export MODEL="gemini-2.5-flash"

export MODEL="deepseek-v3.1"

A solicitação ainda usa o mesmo endpoint, cabeçalhos, mensagens e o parser jq. Essa forma estável da chamada é a vantagem operacional: você pode comparar famílias de modelos suportadas sem manter um script de terminal separado para cada provedor.

Observação sobre seleção de modelo: Uma forma de solicitação compartilhada não significa que todos os modelos se comportem de maneira idêntica. Parâmetros suportados, limites de contexto, comportamento de ferramentas, comportamento de segurança, latência e estilo de saída podem diferir. Trate a compatibilidade como uma interface de integração mais simples, não como prova de que os modelos são intercambiáveis.

Execute um pequeno loop de teste com vários modelos

Para uma comparação rápida no terminal, defina uma lista curta e envie o mesmo prompt para cada modelo:

#!/usr/bin/env bash
set -euo pipefail

: "${FLATKEY_API_KEY:?Defina FLATKEY_API_KEY primeiro}"

MODELS=(
  "gpt-4o-mini"
  "claude-sonnet-4-6"
  "gemini-2.5-flash"
  "deepseek-v3.1"
)

PROMPT="Write three benefit-led bullet points for a waterproof commuter backpack."

for MODEL in "${MODELS[@]}"; do
  echo
  echo "=== $MODEL ==="

  jq -n \
    --arg model "$MODEL" \
    --arg prompt "$PROMPT" \
    '{
      model: $model,
      messages: [
        {role: "system", content: "You write concise ecommerce copy."},
        {role: "user", content: $prompt}
      ],
      temperature: 0.2
    }' |
  curl -sS https://router.flatkey.ai/v1/chat/completions \
    -H "Authorization: Bearer $FLATKEY_API_KEY" \
    -H "Content-Type: application/json" \
    --data-binary @- |
  jq -r '.choices[0].message.content // .error.message'
done

Usar jq -n para construir JSON é mais seguro do que escapar manualmente uma longa string de shell. Isso também torna o script mais fácil de estender com variáveis, mensagens adicionais ou parâmetros opcionais.

Salve o script como compare-models.sh, torne-o executável e execute-o:

chmod +x compare-models.sh
./compare-models.sh

O que comparar na saída

Um teste com vários modelos só é útil quando o prompt e o método de avaliação são consistentes. Para uma tarefa de texto de ecommerce, compare:

Adicione campos de tempo do cURL quando a latência for importante:

curl -sS -o response.json \
  -w 'status=%{http_code} total=%{time_total}s\n' \
  https://router.flatkey.ai/v1/chat/completions \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-2.5-flash",
    "messages": [
      {"role": "user", "content": "Escreva um slogan de produto com cinco palavras."}
    ]
  }'

jq . response.json

Isso separa as medições de transporte da saída do modelo. O terminal exibe o status HTTP e o tempo total da solicitação, enquanto a resposta JSON permanece disponível para inspeção.

Observação sobre seleção de modelo: Não escolha um modelo de produção com base em uma única resposta. Execute um conjunto representativo de prompts, repita as solicitações e pontue as saídas em relação aos requisitos que importam para a sua aplicação.

Mantenha a solicitação comparável

Pequenas mudanças no prompt ou nos parâmetros podem tornar um teste de modelo enganoso. Use estes controles:

1. Mantenha as mensagens idênticas. Não melhore o prompt para um modelo e não para os outros.
2. Use a mesma temperatura. Valores mais baixos geralmente facilitam a revisão das execuções de comparação.
3. Capture o JSON bruto. Armazene a resposta completa, não apenas o texto renderizado.
4. Registre o ID do modelo. Um nome de exibição não é preciso o suficiente para testes reproduzíveis.
5. Separe erros de respostas ruins. Um erro de transporte ou disponibilidade não é uma pontuação de qualidade de saída.
6. Verifique a disponibilidade atual. Um modelo documentado ainda pode ter um status operacional variável.

Adicione tratamento básico de falhas

Use --fail-with-body para que o cURL saia em erros HTTP preservando o corpo da resposta:

HTTP_BODY=$(mktemp)

if ! curl --fail-with-body -sS \
  -o "$HTTP_BODY" \
  https://router.flatkey.ai/v1/chat/completions \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {"role": "user","content":"Retorne a palavra pronto."}
    ]
  }'; then
  jq -r '.error.message // "Request failed"' "$HTTP_BODY" >&2
  rm -f "$HTTP_BODY"
  exit 1
fi

jq -r '.choices[0].message.content' "$HTTP_BODY"
rm -f "$HTTP_BODY"

No código da aplicação, adicione também timeouts explícitos, tentativas limitadas para falhas que possam ser repetidas e logging que não exponha chaves secretas nem conteúdo sensível do prompt.

Uma política prática de seleção de modelo

A política mais simples é selecionar pelo tipo de carga de trabalho, e não pelo nome do provedor:

Comece com o menor modelo que supere de forma confiável o seu limite de qualidade. Escalone para um modelo mais forte quando a tarefa exigir. Se você adicionar roteamento de fallback, teste o fallback com o mesmo contrato de resposta em vez de assumir que ele pode substituir o modelo principal sem تغيões na aplicação.

Você pode revisar o acesso atual aos modelos e os preços na página de preços da Flatkey antes de selecionar os IDs para um teste em produção.

Quando migrar de cURL para um SDK

cURL é ideal para confirmar rapidamente quatro coisas:

• a chave de API funciona
• a URL base está correta
• o modelo selecionado aceita a requisição
• a estrutura da resposta corresponde ao seu parser

Migre para um SDK quando você precisar de helpers de streaming, lógica de retry estruturada, respostas tipadas, clientes reutilizáveis ou observabilidade no nível da aplicação. Mantenha a requisição cURL bem-sucedida no seu runbook: ela continua sendo a maneira mais rápida de separar problemas de acesso ao gateway de problemas de configuração do SDK.

Checklist final de implementação

• Exporte a chave de API em vez de colocá-la diretamente nos scripts.
• Use https://router.flatkey.ai/v1 como URL base.
• Envie requisições de chat compatíveis para /chat/completions.
• Coloque o ID do modelo na configuração.
• Gere JSON com jq quando o escape no shell se tornar complexo.
• Capture status HTTP, latência, conteúdo da resposta e dados de uso.
• Compare modelos com prompts e parâmetros idênticos.
• Verifique a disponibilidade atual do catálogo antes da implementação em produção.
• Adicione timeouts, retries limitados e logs seguros para segredos no código da aplicação.

Uma requisição cURL estável oferece um ponto de partida limpo. Quando ela funcionar, alterar o campo model transforma essa requisição em um banco de testes prático para várias famílias de modelos de IA — sem precisar mudar a autenticação, a URL base ou o parser da resposta a cada vez.

Perguntas frequentes

Posso usar a mesma requisição cURL de chat-completions para todos os modelos de IA?

Use-a para modelos que a Flatkey expõe por meio da rota compatível de chat-completions. Outros modos ou recursos específicos de protocolo podem exigir endpoints ou campos de requisição diferentes.

Qual é o conjunto mínimo de campos para uma requisição chat-completions?

Para uma requisição básica, forneça um model compatível e um array messages. Você também precisa do cabeçalho de autorização bearer e do tipo de conteúdo JSON.

Por que colocar o nome do modelo em uma variável de ambiente?

Mantém a estrutura da requisição estável, reduz erros de edição e facilita a execução de scripts em configurações de staging, avaliação e produção.

Devo usar cURL em produção?

O cURL é excelente para verificação, scripts e runbooks. A maioria das aplicações em produção se beneficia de um SDK ou cliente HTTP com suporte explícito a timeout, retry, telemetria e tratamento de tipos.

Como escolher entre os modelos GPT, Claude, Gemini e DeepSeek?

Escolha com um conjunto de avaliação representativo. Compare o seguimento de instruções, a qualidade da saída, a latência, o uso de tokens, o comportamento em caso de erro e os recursos específicos que sua carga de trabalho exige. Confirme a disponibilidade atual antes da implementação.