Quickstart da Flatkey API: Faça sua primeira chamada por meio de router.flatkey.ai

Se você já usa o SDK da OpenAI, o caminho mais curto para fazer uma primeira chamada à Flatkey API é simples: crie uma chave da Flatkey, aponte seu cliente para https://router.flatkey.ai/v1, envie uma solicitação de chat-completions e confirme a chamada no console.

Este quickstart percorre esse fluxo completo. Ele também mostra como adicionar uma sequência básica de fallback depois que o primeiro modelo funcionar, sem ocultar erros ou criar uma cadeia de tentativas infinitas.

O que você vai concluir

Ao final deste guia, você terá:

1. Uma conta Flatkey e uma chave de API.
2. Um cliente compatível com a OpenAI usando o router da Flatkey.
3. Uma solicitação bem-sucedida e uma resposta legível.
4. Um ponto de verificação no console para uso, custo e solução de problemas da solicitação.
5. Um pequeno padrão de fallback que você pode testar antes da produção.

Você não precisa reescrever sua aplicação em torno de um novo SDK para este teste inicial. A documentação pública da Flatkey expõe um endpoint compatível com a OpenAI em https://router.flatkey.ai/v1, então fluxos comuns de chat, ferramentas, streaming e saída estruturada podem manter a mesma forma familiar de cliente.

Antes de começar

Você precisa de:

• Uma conta Flatkey.
• Uma chave de API da Flatkey que comece com sk-fk-.
• Python 3.9+ ou Node.js 18+ se quiser usar um exemplo de SDK.
• Um nome de modelo atualmente disponível para sua conta.

Catálogos de modelos e disponibilidade podem mudar. Use o catálogo de modelos atual ou o console, em vez de copiar um nome de modelo antigo para produção.

Etapa 1: Crie sua conta Flatkey

Abra o fluxo de cadastro da Flatkey e crie uma conta. Depois de entrar, use o console para criar a credencial que sua aplicação enviará a cada solicitação.

Referência do console

Vá para Console → API Keys.

Crie uma chave para este quickstart e copie-a imediatamente. Trate a chave como uma senha: não a cole em código do lado do cliente, não a registre no Git, não a inclua em capturas de tela e não a envie em mensagens de suporte.

Para um ambiente de equipe, crie chaves separadas para desenvolvedores ou serviços diferentes. A documentação da Flatkey também descreve controles por chave, como um limite mensal e uma allowlist opcional de modelos. Esses controles facilitam isolar um teste, rotacionar uma credencial ou interromper uma carga de trabalho sem afetar todas as aplicações.

Defina a chave no seu shell:

export FLATKEY_API_KEY="sk-fk-your-key-here"

Se você usar um arquivo .env, mantenha-o fora do controle de versão:

FLATKEY_API_KEY=sk-fk-your-key-here

Etapa 2: Altere a URL base

A URL base da Flatkey compatível com a OpenAI é:

https://router.flatkey.ai/v1

Esta é a mudança de configuração mais importante no quickstart. Sua chave de API autentica a solicitação, enquanto a URL base a envia pelo router da Flatkey em vez de diretamente para o endpoint de outro provedor.

Mantenha ambos os valores na configuração do ambiente para poder alterá-los sem editar a lógica da aplicação:

export OPENAI_API_KEY="$FLATKEY_API_KEY"
export OPENAI_BASE_URL="https://router.flatkey.ai/v1"

Use os nomes de variáveis esperados pelo seu framework. Algumas bibliotecas leem OPENAI_BASE_URL; outras exigem uma opção base_url ou baseURL quando o cliente é criado.

Passo 3: Envie sua primeira solicitação

Comece com um prompt curto e determinístico. O objetivo é comprovar autenticação, conectividade, acesso ao modelo e análise da resposta antes de adicionar streaming, ferramentas, saída estruturada ou comportamento de fallback.

Opção A: cURL

Substitua YOUR_CURRENT_MODEL por um modelo disponível no catálogo atual da Flatkey:

curl https://router.flatkey.ai/v1/chat/completions \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_CURRENT_MODEL",
    "messages": [
      {
        "role": "user",
        "content": "Responda exatamente com: flatkey quickstart connected"
      }
    ],
    "temperature": 0
  }'

Opção B: Python

Instale o cliente OpenAI:

pip install openai

Crie quickstart.py:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["FLATKEY_API_KEY"],
    base_url="https://router.flatkey.ai/v1",
)

response = client.chat.completions.create(
    model="YOUR_CURRENT_MODEL",
    messages=[
        {
            "role": "user",
            "content": "Responda exatamente com: flatkey quickstart connected",
        }
    ],
    temperature=0,
)

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

Execute:

python quickstart.py

Opção C: JavaScript

Instale o cliente:

npm install openai

Crie quickstart.mjs:

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.FLATKEY_API_KEY,
  baseURL: "https://router.flatkey.ai/v1",
});

const response = await client.chat.completions.create({
  model: "YOUR_CURRENT_MODEL",
  messages: [
    {
      role: "user",
      content: "Responda exatamente com: flatkey quickstart connected",
    },
  ],
  temperature: 0,
});

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

Execute:

node quickstart.mjs

Passo 4: Leia a resposta

Para uma solicitação padrão de chat completions, comece com quatro campos:

Uma resposta simplificada se parece com isto:

{
  "id": "chatcmpl-example",
  "model": "YOUR_CURRENT_MODEL",
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "flatkey quickstart connected"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 5,
    "total_tokens": 17
  }
}

Os identificadores exatos e as contagens de tokens serão diferentes. A condição de sucesso da sua primeira chamada não é uma correspondência byte a byte; é uma resposta HTTP válida, uma mensagem do assistente que possa ser analisada e informações de uso que seu aplicativo possa registrar.

Passo 5: Verifique o uso após a chamada

Não pare em 200 OK. Um quickstart útil também prova que a solicitação está visível para as pessoas que operarão a integração.

Referência do Console

Abra Console → Usage & Logs após a solicitação.

Procure a nova chamada e confirme os detalhes disponíveis para sua conta, como:

• Hora da solicitação.
• Modelo ou rota.
• Status.
• Uso de tokens.
• Custo ou impacto no saldo.
• Detalhes do erro quando uma solicitação falha.

Se o aplicativo recebeu uma resposta, mas a entrada esperada no log estiver ausente, primeiro verifique se você está visualizando a mesma conta, workspace e chave de API usados pela solicitação. Também registre o ID da resposta e a hora da solicitação antes de tentar novamente; esses dois detalhes tornam a solução de problemas muito mais fácil.

Reveja a página de preços da Flatkey atual antes de passar de um teste rápido para uma carga de trabalho sustentada. Compare o modelo, o volume de solicitações, a combinação de tokens e o comportamento de fallback que você espera usar — não apenas o custo de uma chamada bem-sucedida.

Passo 6: Adicione uma sequência de fallback segura

O roteamento de fallback deve vir depois que o primeiro modelo funcionar. Caso contrário, uma rota de backup pode esconder o problema real: uma chave inválida, base URL incorreta, modelo indisponível, solicitação malformada ou limite da conta.

Comece com uma pequena lista ordenada de modelos que você testou para a mesma tarefa:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["FLATKEY_API_KEY"],
    base_url="https://router.flatkey.ai/v1",
)

models = [
    "PRIMARY_CURRENT_MODEL",
    "FALLBACK_CURRENT_MODEL",
]

last_error = None

for model in models:
    try:
        response = client.chat.completions.create(
            model=model,
            messages=[
                {
                    "role": "user",
                    "content": "Return JSON with one key named status and value ok",
                }
            ],
            temperature=0,
        )
        print(model, response.choices[0].message.content)
        break
    except Exception as error:
        last_error = error
        print(f"Route failed: {model}")
else:
    raise RuntimeError("All approved model routes failed") from last_error

Este exemplo é intencionalmente pequeno. Antes de usá-lo em produção, adicione:

• Uma lista restrita de erros passíveis de retentativa.
• Um tempo limite por tentativa e um prazo total da solicitação.
• Backoff para falhas transitórias.
• Logs estruturados contendo o modelo tentado e o ID da resposta.
• Validação da saída para JSON, chamadas de ferramentas ou outros esquemas necessários.
• Um teto de custo para que o fallback não selecione silenciosamente uma rota inadequada.

Não tente novamente erros de autenticação com vários modelos. Não tente novamente solicitações malformadas até que a solicitação seja corrigida. Não trate todos os modelos como intercambiáveis apenas porque aceitam um payload de chat-completions.

Uma política prática de fallback

Use esta tabela de decisão como ponto de partida:

A regra central é simples: tente novamente falhas transitórias de transporte; corrija falhas de configuração e de esquema; use um fallback somente quando ele estiver aprovado para o mesmo trabalho de produto.

Erros comuns na primeira chamada

401 ou falha de autenticação

Confirme que a solicitação usa Authorization: Bearer <key>, que a chave está ativa e que não foi copiado espaço em branco extra. Verifique se o aplicativo está lendo a variável de ambiente esperada.

404 ou endpoint incorreto

Use a URL base compatível com OpenAI https://router.flatkey.ai/v1 e o caminho de chat /chat/completions. Evite adicionar /v1 duas vezes por engano.

Modelo não encontrado ou indisponível

Escolha um modelo atualmente disponível no catálogo ao vivo ou no console. Não assuma que um nome de modelo de um tutorial antigo ainda está habilitado para sua conta.

Resposta HTTP bem-sucedida, mas erro na aplicação

Registre a resposta bruta uma vez em um ambiente de desenvolvimento seguro. Confirme que seu código lê choices[0].message.content para chat completions e não espera o esquema de resposta de um endpoint diferente.

Gasto inesperado durante o fallback

Registre o modelo tentado em cada chamada, limite a lista de rotas e revise Usage & Logs. Uma política de fallback sem um prazo e um limite de custo pode transformar uma ação do usuário em várias solicitações cobradas.

Checklist de produção

Antes de enviar tráfego real pela integração, confirme:

• [ ] A chave da API é armazenada em um gerenciador de segredos ou em um ambiente no lado do servidor.
• [ ] Desenvolvimento, staging e produção usam chaves separadas.
• [ ] A URL base é uma configuração, não algo codificado diretamente em toda a base de código.
• [ ] O modelo selecionado está disponível e foi testado para a carga de trabalho real.
• [ ] Timeouts, erros passíveis de retentativa e prazos totais são explícitos.
• [ ] Modelos de fallback usam o mesmo contrato de saída exigido.
• [ ] Os registros de uso e de erro ficam visíveis para a equipe operacional.
• [ ] As expectativas de custo foram verificadas com base na precificação atual.
• [ ] Limites de chave ou allowlists estão configurados onde apropriado.
• [ ] Um caminho de rollback pode restaurar rapidamente a rota anterior.

Faça a primeira chamada, depois otimize

A maneira mais rápida de avaliar a Flatkey é manter o primeiro teste restrito. Crie uma chave, altere uma URL base, envie uma solicitação, leia uma resposta e encontre a mesma chamada em Usage & Logs.

Depois que esse caminho estiver comprovado, adicione roteamento de fallback como uma política observável, em vez de um loop de retentativa oculto. Mantenha a lista de modelos aprovados curta, preserve as evidências do erro, valide a saída e revise a precificação atual antes de aumentar o tráfego.

Quando estiver pronto, crie uma conta Flatkey, faça a primeira chamada por meio de router.flatkey.ai e use o registro no console como teste de aceitação para sua integração.