DEV Community: Lucas

Ghostty Deixando o GitHub: Impacto para Criadores de Ferramentas de Desenvolvedores

Lucas — Thu, 30 Apr 2026 03:57:48 +0000

Em 28 de abril de 2026, Mitchell Hashimoto anunciou que o Ghostty, seu emulador de terminal de código aberto, deixará o GitHub. Hashimoto é o usuário 1299 do GitHub, entrou na plataforma em fevereiro de 2008 e a usou quase todos os dias por mais de 18 anos. Mesmo assim, após registrar interrupções frequentes em um diário de “quase todo dia tem um X”, uma falha do GitHub Actions no dia do anúncio bloqueou suas revisões de PR por duas horas. O veredito foi direto: “Este não é mais um lugar para trabalho sério se ele simplesmente te bloqueia por horas por dia, todos os dias.”

Experimente o Apidog hoje

Se você desenvolve ferramentas para desenvolvedores, vale ler esse anúncio como um estudo de caso de confiabilidade. Hashimoto não é um usuário casual: ele cofundou a HashiCorp sobre o GitHub e lançou Terraform, Vagrant, Vault, Consul e Boundary usando a plataforma. Quando um usuário desse perfil sai por motivos de confiabilidade, a discussão deixa de ser “qual forja usar” e passa a ser: sua ferramenta continua funcionando quando a infraestrutura que você não controla falha?

Para contexto sobre ferramentas de desenvolvedor na era da IA e fluxos nativos do GitHub, veja como escrever arquivos AGENTS.md e uso e API de faturamento do GitHub Copilot para equipes. Para um exemplo de automação em torno de lacunas de confiabilidade do GitHub, veja o artigo sobre o bot de triagem Clawsweeper.

Resumo

Mitchell Hashimoto anunciou em 28 de abril de 2026 que o Ghostty deixará o GitHub para uma forja ainda não nomeada.
O motivo foi confiabilidade: interrupções recorrentes do GitHub Actions e da plataforma, registradas por ele em um diário de “quase todo dia tem um X”.
No dia do anúncio, uma interrupção de duas horas do Actions bloqueou revisões de PR.
O repositório do Ghostty no GitHub permanecerá como espelho somente leitura; o desenvolvimento ativo migrará de forma incremental.
A lição principal para quem constrói ferramentas de desenvolvedor: confiabilidade supera recursos quando sua ferramenta está no caminho crítico.
Para equipes de API, o caminho prático é desacoplar dependências: simulações, múltiplos provedores, adaptadores intercambiáveis e pipelines de fallback.
O Apidog segue esse padrão ao permitir modelagem, testes e simulação de APIs em um fluxo único.

O que Hashimoto anunciou

A publicação de Hashimoto é curta e direta. Ele explica que começou a manter um diário de interrupções do GitHub, que esse diário cresceu mais rápido do que o esperado e que, na manhã em que escreveu o anúncio, uma falha do GitHub Actions o impediu de revisar PRs por duas horas.

A decisão não foi apresentada como reação a um único incidente. Segundo ele, o problema era o padrão: interrupções frequentes o suficiente para tornar o GitHub inadequado para o trabalho diário do Ghostty.

O escopo da mudança também foi delimitado:

O Ghostty sairá do GitHub.
Outros projetos de Hashimoto permanecerão no GitHub por enquanto.
O repositório Ghostty continuará disponível como espelho somente leitura.
Issues, pull requests e CI migrarão para uma nova forja.
A migração será incremental.
O destino ainda não foi anunciado.

O ponto importante: Hashimoto não citou preço, recursos, Copilot, Microsoft ou direção de produto. A queixa foi operacional: a plataforma parava de responder por horas, e isso bloqueava o trabalho.

Por que o problema central é confiabilidade

A pergunta menos útil é “para onde o Ghostty vai?”. A pergunta mais útil para equipes técnicas é:

O que acontece quando uma plataforma central para o seu fluxo de entrega deixa de ser confiável o suficiente?

Três fatores tornam esse caso relevante para desenvolvedores:

1. O usuário

Hashimoto construiu ferramentas de infraestrutura usadas em escala empresarial. Quando ele diz que uma plataforma não é confiável para trabalho sério, essa mensagem chega a pessoas que decidem onde código-fonte, CI, releases e automações corporativas vivem.

2. O motivo

Ele não saiu por uma controvérsia de produto. Saiu porque o serviço continuava falhando. Isso reduz a discussão ao critério mais importante para ferramentas de desenvolvedor:

A ferramenta funciona quando o usuário precisa dela?

3. O tom

A publicação não é um manifesto. Parece uma decisão operacional tomada depois de tentativas de continuar. Isso torna o sinal mais forte: não há exagero, apenas acúmulo de falhas.

Para quem opera uma ferramenta de desenvolvedor, esse é o pior cenário: um usuário avançado registra pequenas falhas durante meses até concluir que migrar custa menos do que continuar.

Como auditar sua própria ferramenta

Se seu produto está no caminho crítico de desenvolvedores, use o caso Ghostty como checklist.

1. Quantos usuários poderiam escrever o mesmo diário sobre você?

Faça um levantamento dos últimos 90 dias:

incidentes públicos;
degradações não publicadas;
falhas parciais;
lentidão em endpoints críticos;
jobs de background atrasados;
erros intermitentes em integrações.

Depois mapeie isso contra as horas de trabalho dos seus principais clientes.

Pergunta prática:

Quantas horas produtivas um usuário pesado perdeu por causa da nossa ferramenta nesta semana?

Se a resposta for “mais de zero” de forma recorrente, você tem um problema de tendência.

2. Sua confiabilidade está melhorando ou piorando?

Não olhe apenas para uptime agregado. Observe a direção.

Um serviço pode cumprir SLA e, ainda assim, estar ficando pior para usuários intensivos. O diário de Hashimoto não documentava um único evento; documentava uma tendência.

Implemente um orçamento de erro por componente:

Componente: CI
SLO: 99,9% de disponibilidade em horário comercial
Orçamento de erro mensal: 43 minutos
Responsável: Equipe de plataforma
Revisão: toda segunda-feira

Se ninguém lê esse orçamento semanalmente, ele não influencia decisões.

3. Sua página de status reduz ou aumenta a desconfiança?

Usuários criam seus próprios diários quando não confiam no sinal público.

Sua página de status deve indicar degradação real, não apenas downtime total. Publique quando:

uma região estiver lenta;
filas estiverem atrasadas;
webhooks estiverem com latência elevada;
APIs estiverem retornando 5xx acima do normal;
CI estiver com tempo de espera elevado;
autenticação estiver intermitente.

Se o usuário percebe falha e sua página diz “All systems operational”, você perdeu credibilidade.

4. Seu uptime mede a experiência certa?

Um uptime de 99,95% pode ser ruim se o downtime ocorrer no horário em que os desenvolvedores usam o produto.

Para ferramentas de desenvolvedor, meça disponibilidade contra a curva real de uso:

horário de revisão de PR;
janelas de deploy;
horário de execução de CI;
picos de chamadas de API;
ciclos de release.

Duas horas de indisponibilidade durante uma sessão de revisão podem invalidar a sessão inteira.

O custo real do “sempre GitHub”

Hashimoto escreveu que, para ele, “nunca foi uma questão onde colocar meus projetos: sempre GitHub”.

Esse hábito tem custo.

Quando uma plataforma concentra repositórios, issues, PRs, CI, pacotes, releases e identidade, o lock-in não está apenas no Git. Clonar o histórico do repositório é simples. Migrar todo o resto não é.

O que costuma ficar preso:

histórico de issues;
discussões;
comentários de PR;
revisões;
checks de CI;
segredos;
permissões;
CODEOWNERS;
GitHub Actions;
GitHub Packages;
automações via API;
integrações OAuth;
workflows internos.

O custo de migração é um iceberg: o repositório é a parte visível.

Como reduzir lock-in na prática

Se você constrói uma ferramenta de desenvolvedor integrada ao GitHub, trate o GitHub como um provedor, não como a infraestrutura inteira.

Use adaptadores

Em vez de espalhar chamadas diretas para a API do GitHub pelo código, isole-as:

interface SourceControlProvider {
  getPullRequest(id: string): Promise<PullRequest>;
  listIssues(repo: string): Promise<Issue[]>;
  createComment(targetId: string, body: string): Promise<void>;
  getChangedFiles(prId: string): Promise<FileChange[]>;
}

Depois implemente provedores:

class GitHubProvider implements SourceControlProvider {
  async getPullRequest(id: string) {
    // chamada para GitHub API
  }

  async listIssues(repo: string) {
    // chamada para GitHub Issues
  }

  async createComment(targetId: string, body: string) {
    // comentário em PR ou issue
  }

  async getChangedFiles(prId: string) {
    // arquivos alterados no PR
  }
}

No futuro, você pode adicionar:

class GitLabProvider implements SourceControlProvider {
  // mesma interface, outro backend
}

class ForgejoProvider implements SourceControlProvider {
  // mesma interface, outro backend
}

O objetivo não é migrar amanhã. É evitar que a migração exija reescrever o produto.

Separe CI da plataforma de hospedagem

Se todo o seu pipeline depende do GitHub Actions, uma interrupção do Actions bloqueia seu release.

Opções práticas:

manter um runner auto-hospedado para caminhos críticos;
espelhar jobs essenciais em outro CI;
documentar release manual;
manter artefatos reproduzíveis localmente;
evitar que publicação de pacote dependa de uma única plataforma.

Exemplo de checklist mínimo:

[ ] Consigo gerar build localmente?
[ ] Consigo rodar testes sem GitHub Actions?
[ ] Consigo publicar release se o GitHub estiver fora?
[ ] Consigo reconstruir artefatos a partir de tag assinada?
[ ] Existe runbook para release manual?

Espelhe antes de precisar

Espelhamento semanal para uma segunda forja já reduz risco.

Exemplo simples de mirror com Git:

git clone --mirror git@github.com:org/projeto.git
cd projeto.git
git remote add backup git@codeberg.org:org/projeto.git
git push --mirror backup

Automatize isso em CI ou em um job agendado fora do GitHub.

Alternativas de forja

Hashimoto não anunciou o destino do Ghostty. As opções plausíveis incluem:

Forgejo: fork FOSS do Gitea, mantido pela Codeberg e.V.; opção comum para projetos alinhados ao ecossistema FOSS.
Codeberg: instância hospedada do Forgejo, operada como organização sem fins lucrativos.
GitLab: CI/CD forte e ampla cobertura de recursos, com suporte comercial.
Sourcehut: fluxo baseado em e-mail, minimalista e rápido.
Forgejo ou Gitea auto-hospedado: controle máximo, maior responsabilidade operacional.
Radicle: abordagem peer-to-peer, ainda mais inicial para projetos públicos de grande visibilidade.

Nenhuma substitui o GitHub perfeitamente em todos os fluxos. Esse é justamente o problema: quando uma plataforma absorve toda a pilha, sair dela exige planejamento incremental.

A lição para equipes de API

Para equipes que constroem APIs ou ferramentas de API, substitua:

GitHub Actions

por:

API upstream da qual seu produto depende

A questão estrutural é a mesma:

Quanto do trabalho do cliente depende de um serviço que você não controla?

Três práticas reduzem esse risco.

1. Simule tudo que você depende

Se a API upstream cair, o desenvolvimento local e os testes não devem parar.

Você precisa de mocks realistas para:

desenvolvimento local;
testes automatizados;
CI;
demos;
validação de contrato;
cenários de erro.

Exemplo de resposta simulada para uma API de chat:

{
  "id": "chatcmpl_mock_123",
  "object": "chat.completion",
  "created": 1714300000,
  "model": "mock-model",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Resposta simulada para ambiente de desenvolvimento."
      },
      "finish_reason": "stop"
    }
  ]
}

Com o Apidog, você define os esquemas de request/response e gera um servidor simulado a partir dessas definições. Isso permite continuar desenvolvendo mesmo quando o provedor real está indisponível.

Veja também como usar a API GPT-5.5 para um exemplo de fluxo multi-provedor no formato OpenAI.

2. Teste contra múltiplos provedores

Se seu produto depende de provedores como OpenAI, Anthropic, Mistral, DeepSeek, Google ou xAI, evite acoplar a lógica de negócio a apenas um deles.

Use variáveis de ambiente:

API_PROVIDER=openai
API_BASE_URL=https://api.openai.com/v1
API_KEY=...

Para alternar:

API_PROVIDER=backup
API_BASE_URL=https://api.backup-provider.example/v1
API_KEY=...

O teste deve validar o contrato comum:

describe("chat completion provider", () => {
  it("returns a message with content", async () => {
    const response = await client.createChatCompletion({
      messages: [{ role: "user", content: "Olá" }]
    });

    expect(response.choices[0].message.content).toBeTruthy();
  });
});

A diferença entre “estamos fora porque o provedor caiu” e “roteamos para um fallback” costuma ser arquitetura, não milagre.

3. Desacople release da hospedagem

Se CI, artefatos e publicação dependem de uma única plataforma, a falha dessa plataforma bloqueia entrega.

Tenha pelo menos um caminho alternativo para:

build;
testes críticos;
assinatura;
publicação;
rollback.

Um runbook mínimo deve responder:

Se o CI primário estiver indisponível por 4 horas, como lançamos uma correção crítica?

Se a resposta não estiver documentada, a resposta real é: não lançamos.

Um fluxo resiliente com Apidog

Um fluxo prático para equipes de API:

Baixe o Apidog e crie um projeto para cada API upstream crítica.
Defina schemas de request e response uma vez.
Gere um servidor mock a partir desses schemas.
Configure ambientes como dev, staging e prod.
Guarde credenciais como segredos por ambiente.
Rode os mesmos testes de contrato contra mocks, sandbox e produção.
Quando o upstream estiver degradado, alterne para o mock e continue desenvolvendo.
Quando houver múltiplos provedores, rode a mesma suíte contra todos.

Exemplo de separação por ambiente:

dev      -> servidor mock
staging  -> sandbox do provedor
prod     -> API real
backup   -> provedor alternativo

Esse padrão não é específico de IA, GitHub ou Ghostty. É uma forma geral de manter desenvolvimento, testes e release funcionando mesmo quando dependências externas falham.

O que os desenvolvedores estão concluindo

As reações ao anúncio tendem a cair em quatro grupos.

“Finalmente alguém disse”

Usuários avançados do GitHub que já estavam frustrados viram a publicação como validação. Muitos já mantinham mirrors e agora consideram promovê-los.

“Foi só uma interrupção”

Alguns apontam que o uptime geral do GitHub continua competitivo. O argumento faz sentido no agregado, mas perde o ponto principal: Hashimoto reagiu a uma tendência, não a um único incidente.

“Migrar é caro”

Esse grupo está certo. Issues, PRs, CI e automações tornam migração difícil. Por isso a abordagem incremental com espelho somente leitura é mais realista do que uma troca abrupta.

“Isso também me afeta?”

Depende da criticidade. Para um projeto de fim de semana, uma interrupção de algumas horas pode ser aceitável. Para uma ferramenta usada diariamente por equipes pagantes, pode ser bloqueante.

Checklist prático para sua stack

Use esta lista como auditoria rápida:

[ ] Repositórios ativos são espelhados para uma segunda forja?
[ ] O mirror é testado periodicamente?
[ ] Issues e PRs críticos têm estratégia de exportação?
[ ] GitHub API está isolada atrás de uma interface?
[ ] Existe adaptador para outro provedor ou plano para criá-lo?
[ ] CI crítico roda fora do GitHub Actions se necessário?
[ ] Existe release manual documentado?
[ ] Dependências externas críticas estão listadas?
[ ] Para cada dependência, há resposta para “e se cair por 4 horas?”
[ ] APIs upstream têm mocks realistas?
[ ] Testes de contrato rodam contra mock e produção?
[ ] Métricas de confiabilidade são revisadas semanalmente?
[ ] A página de status reflete degradações parciais?
[ ] A equipe monitora tendência de incidentes, não apenas SLA?

Para um exemplo aplicado a APIs, veja como construir fluxos de trabalho duráveis que sobrevivem a interrupções de provedores, usando DeepSeek e OpenAI como exemplo de provedor duplo.

Perguntas frequentes

Para onde o Ghostty está se mudando?

Hashimoto não anunciou o destino. Ele afirmou que está conversando com vários provedores, comerciais e FOSS, e que a migração será incremental. O repositório atual no GitHub continuará como espelho somente leitura.

O GitHub é realmente tão pouco confiável?

Os números agregados de uptime do GitHub seguem competitivos com plataformas similares. A crítica de Hashimoto é sobre a recorrência de interrupções parciais e o impacto acumulado em trabalho real, especialmente em Actions, Packages e API.

Devo mover meus repositórios para fora do GitHub agora?

Para a maioria das equipes, espelhar vale a pena imediatamente. Tornar outra forja primária depende do custo de migrar issues, PRs, CI e integrações. Comece por reduzir dependência antes de precisar sair.

Isso afeta GitHub Copilot ou GitHub Actions?

A publicação não foi sobre Copilot. O gatilho imediato citado foi uma interrupção do GitHub Actions. Para equipes que usam Copilot, mudanças relacionadas a faturamento estão documentadas em uso e API de faturamento do GitHub Copilot para equipes.

O que isso significa para ferramentas de IA que dependem da API do GitHub?

Bots de revisão, triagem de issues, servidores MCP e automações similares herdam a confiabilidade do GitHub. Mitigue com cache, fallback, filas resilientes e mocks de upstream. O artigo sobre o bot de triagem Clawsweeper mostra um exemplo funcional.

Isso é uma tendência de saída do GitHub?

Provavelmente será lenta. Migrar projetos grandes é caro. O sinal importante é que um dos usuários mais antigos da plataforma concluiu que o custo de continuar superou o custo de migrar.

O que significa “ferramenta de desenvolvedor” aqui?

Qualquer software usado por desenvolvedores no fluxo diário de trabalho: terminais, editores, CI, clientes de API, monitoramento, registros de pacotes, bots de revisão e assistentes de IA. Se sua ferramenta fica entre o desenvolvedor e a entrega, confiabilidade é parte central do produto.

Como Usar a API Mistral Medium 3.5? Guia Completo

Lucas — Thu, 30 Apr 2026 03:49:10 +0000

A Mistral lançou o Medium 3.5 em 29 de abril de 2026. O ID do modelo da API é mistral-medium-3.5, o endpoint é https://api.mistral.ai/v1/chat/completions, e o formato da requisição é próximo ao padrão da OpenAI. Na prática, migrar de outro provedor costuma exigir apenas trocar a URL base e o ID do modelo. Os destaques: contexto de 256K, visão nativa, chamada de função, suporte a 24 idiomas e 77,6% no SWE-Bench Verified.

Experimente o Apidog hoje

Este guia mostra como autenticar, configurar parâmetros, chamar a API em Python e Node, usar visão, ferramentas, modo JSON, streaming, tratamento de erros e um fluxo de trabalho com Apidog para acompanhar custo por chamada enquanto você itera nos prompts. Para modelos comparáveis, veja como usar a API DeepSeek V4 e como usar a API GPT-5.5.

TL;DR

Endpoint: POST https://api.mistral.ai/v1/chat/completions.
Autenticação: bearer token no cabeçalho Authorization.
Modelo: mistral-medium-3.5.
Contexto: 256K tokens.
Preço: US$ 1,5 por milhão de tokens de entrada e US$ 7,5 por milhão de tokens de saída.
Recursos: visão nativa, chamada de função, saída JSON estruturada, raciocínio e suporte a 24 idiomas.
Pesos abertos: mistralai/Mistral-Medium-3.5-128B no Hugging Face sob Licença MIT Modificada com exceção para grandes receitas.
Benchmarks citados: 77,6% no SWE-Bench Verified e 91,4 no τ³-Telecom.
Use o Apidog para salvar requisições, proteger a chave como variável secreta e comparar custo entre execuções.

O que mudou no Medium 3.5

O Medium 3 foi lançado como um modelo apenas de texto com contexto de 128K. O Medium 3.5 muda o perfil: ele combina seguimento de instruções, raciocínio e codificação em um único conjunto de pesos. Você não precisa alternar entre um checkpoint de chat e outro de raciocínio.

Principais mudanças:

Contexto ampliado de 128K para 256K.
Visão nativa.
Chamada de função integrada.
Melhor desempenho em tarefas de código e agentes.
Preço mais alto que o Medium 3.

Os números mais relevantes para implementação são:

77,6% no SWE-Bench Verified: útil para revisão e correção de código.
91,4 no τ³-Telecom: indica bom comportamento em fluxos agenticos de múltiplos turnos.
256K de contexto: permite enviar uma base de código média, documentos longos ou transcrições grandes em uma única chamada.

O preço também muda. O Medium 3 custava US$ 0,40/M tokens de entrada e US$ 2,00/M tokens de saída. O Medium 3.5 sobe para US$ 1,5/M entrada e US$ 7,5/M saída. Use o Medium 3.5 quando a tarefa justificar raciocínio, visão, ferramentas ou contexto longo.

Pré-requisitos

Antes de chamar a API, prepare:

Uma conta em console.mistral.ai com método de pagamento. Sem saldo, a API pode retornar 402 Payment Required.
Uma chave de API com escopo para o projeto correto.
Um SDK:
- mistralai para Python ou JavaScript.
- SDK da OpenAI, se você quiser reaproveitar código com base_url.
Um cliente de API para repetir e versionar requisições. O curl serve para o primeiro teste; para iteração, use o Apidog.

Exporte a chave:

export MISTRAL_API_KEY="..."

Endpoint e autenticação

A URL base da API é:

https://api.mistral.ai/v1

O endpoint de chat completions:

POST https://api.mistral.ai/v1/chat/completions

Requisição mínima com curl:

curl https://api.mistral.ai/v1/chat/completions \
  -H "Authorization: Bearer $MISTRAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mistral-medium-3.5",
    "messages": [
      {
        "role": "user",
        "content": "Explain dense merged checkpoints in two sentences."
      }
    ]
  }'

Uma resposta bem-sucedida retorna:

choices: lista de respostas.
usage.prompt_tokens: tokens de entrada.
usage.completion_tokens: tokens de saída.
usage.total_tokens: total.
id: identificador para rastreamento.

Erros retornam um envelope error com code e message, semelhante ao formato da OpenAI.

Parâmetros principais

Parâmetro	Tipo	Valores	Observações
`model`	string	`mistral-medium-3.5`	Obrigatório.
`messages`	array	pares `role` / `content`	Obrigatório. Mesmo padrão da OpenAI.
`temperature`	float	`0` a `1.5`	A Mistral recomenda `0.7` para uso geral e `0.3` para código.
`top_p`	float	`0` a `1`	Padrão `1.0`.
`max_tokens`	int	`1` até o limite de contexto	Limita a saída.
`stream`	bool	`true` ou `false`	Habilita streaming SSE.
`tools`	array	especificação de ferramenta estilo OpenAI	Chamada de função nativa.
`tool_choice`	string/object	`auto`, `any`, `none` ou ferramenta específica	Use `any` para forçar ferramenta.
`response_format`	object	`{"type":"json_object"}` ou schema JSON	Saída estruturada.
`random_seed`	int	qualquer inteiro	Para reprodutibilidade.
`safe_prompt`	bool	`true` ou `false`	Adiciona o preâmbulo de segurança da Mistral.
`presence_penalty`	float	`-2` a `2`	Penaliza tópicos repetidos.
`frequency_penalty`	float	`-2` a `2`	Penaliza tokens repetidos.

Duas diferenças importantes ao migrar da OpenAI:

OpenAI: tool_choice="required" Mistral: tool_choice="any"
OpenAI: seed Mistral: random_seed

Cliente Python

Instale o SDK oficial:

pip install mistralai

Chamada básica:

import os
from mistralai import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

response = client.chat.complete(
    model="mistral-medium-3.5",
    messages=[
        {"role": "system", "content": "Reply in code only."},
        {"role": "user", "content": "Write a Rust function that debounces events."},
    ],
    temperature=0.3,
    max_tokens=2048,
)

print("Conteúdo:", response.choices[0].message.content)
print("Total de tokens:", response.usage.total_tokens)

estimated_cost = (
    response.usage.prompt_tokens * 1.5 / 1_000_000
    + response.usage.completion_tokens * 7.5 / 1_000_000
)

print("Estimativa de custo (USD):", estimated_cost)

Se sua aplicação já usa o SDK da OpenAI, altere apenas base_url e model:

import os
from openai import OpenAI

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

response = client.chat.completions.create(
    model="mistral-medium-3.5",
    messages=[
        {"role": "user", "content": "Hello, Mistral."}
    ],
)

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

Use o SDK mistralai quando quiser suporte mais direto a recursos específicos da Mistral. Use o SDK da OpenAI quando a prioridade for compatibilidade com código existente.

Cliente Node.js

Instale o SDK oficial:

npm install @mistralai/mistralai

Exemplo com SDK nativo:

import { Mistral } from "@mistralai/mistralai";

const client = new Mistral({
  apiKey: process.env.MISTRAL_API_KEY,
});

const response = await client.chat.complete({
  model: "mistral-medium-3.5",
  messages: [
    {
      role: "user",
      content: "Explain dense merged checkpoints in plain English.",
    },
  ],
  temperature: 0.7,
});

console.log(response.choices[0].message.content);
console.log("Uso:", response.usage);

Exemplo com SDK da OpenAI:

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.MISTRAL_API_KEY,
  baseURL: "https://api.mistral.ai/v1",
});

const response = await client.chat.completions.create({
  model: "mistral-medium-3.5",
  messages: [
    {
      role: "user",
      content: "Hello, Mistral.",
    },
  ],
});

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

Streaming de respostas

Para streaming, defina stream: true ou use o método de stream do SDK.

stream = client.chat.stream(
    model="mistral-medium-3.5",
    messages=[
        {
            "role": "user",
            "content": "Stream a 300-word essay on merged checkpoints.",
        }
    ],
)

for chunk in stream:
    delta = chunk.data.choices[0].delta.content or ""
    print(delta, end="", flush=True)

O formato segue o padrão SSE. O conteúdo incremental aparece em choices[].delta.content.

Para depurar streaming e comparar execuções lado a lado, use o visualizador de respostas do Apidog.

Chamada de ferramenta

O Medium 3.5 suporta chamada de função nativa via tools.

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Return the current weather for a city.",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {"type": "string"},
                    "unit": {"type": "string", "enum": ["c", "f"]},
                },
                "required": ["city"],
            },
        },
    }
]

response = client.chat.complete(
    model="mistral-medium-3.5",
    messages=[
        {
            "role": "user",
            "content": "Weather in Lagos in Celsius?",
        }
    ],
    tools=tools,
    tool_choice="auto",
)

tool_call = response.choices[0].message.tool_calls[0]

print(tool_call.function.name)
print(tool_call.function.arguments)

Fluxo típico:

Envie messages + tools.
Leia message.tool_calls.
Execute a função localmente.
Adicione o resultado como mensagem role: "tool".
Chame a API novamente para gerar a resposta final.

Exemplo conceitual:

messages = [
    {"role": "user", "content": "Weather in Lagos in Celsius?"}
]

response = client.chat.complete(
    model="mistral-medium-3.5",
    messages=messages,
    tools=tools,
    tool_choice="auto",
)

tool_call = response.choices[0].message.tool_calls[0]

# Execute sua função real aqui
tool_result = {
    "city": "Lagos",
    "temperature": 29,
    "unit": "c",
}

messages.append(response.choices[0].message)
messages.append({
    "role": "tool",
    "tool_call_id": tool_call.id,
    "content": json.dumps(tool_result),
})

final_response = client.chat.complete(
    model="mistral-medium-3.5",
    messages=messages,
    tools=tools,
)

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

Modo JSON e saída estruturada

Para forçar JSON válido, use:

response = client.chat.complete(
    model="mistral-medium-3.5",
    messages=[
        {
            "role": "system",
            "content": "Reply with a single valid JSON object.",
        },
        {
            "role": "user",
            "content": "Summarize today's Mistral Medium 3.5 release.",
        },
    ],
    response_format={"type": "json_object"},
)

Para validar por schema:

schema = {
    "type": "json_schema",
    "json_schema": {
        "name": "release_note",
        "schema": {
            "type": "object",
            "properties": {
                "title": {"type": "string"},
                "date": {"type": "string"},
                "bullets": {
                    "type": "array",
                    "items": {"type": "string"},
                },
            },
            "required": ["title", "date", "bullets"],
            "additionalProperties": False,
        },
        "strict": True,
    },
}

response = client.chat.complete(
    model="mistral-medium-3.5",
    messages=[
        {
            "role": "system",
            "content": "Reply with a single JSON object matching the schema.",
        },
        {
            "role": "user",
            "content": "Summarize today's Mistral Medium 3.5 release.",
        },
    ],
    response_format=schema,
)

Use schema estrito quando o resultado alimentar outro sistema. Use json_object quando você só precisa garantir JSON válido e fará a validação no cliente.

Entrada de visão

O Medium 3.5 aceita imagem e texto no mesmo message.content.

response = client.chat.complete(
    model="mistral-medium-3.5",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "What is in this image and what is it doing wrong?",
                },
                {
                    "type": "image_url",
                    "image_url": "https://example.com/diagram.png",
                },
            ],
        }
    ],
)

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

As imagens são cobradas como tokens de entrada. A contagem depende da resolução e aparece em usage.prompt_tokens.

Para controlar custo:

Corte a região relevante antes de enviar.
Reduza a resolução quando possível.
Evite enviar frames redundantes em fluxos de vídeo.
Registre tokens por imagem antes de escalar.

Crie uma coleção no Apidog

Um fluxo prático para desenvolvimento:

Baixe o Apidog e crie um projeto.
Crie um ambiente com:
- BASE_URL=https://api.mistral.ai/v1
- MISTRAL_API_KEY como variável secreta.
Salve uma requisição:
- Método: POST
- URL: {{BASE_URL}}/chat/completions
- Header: Authorization: Bearer {{MISTRAL_API_KEY}}
- Header: Content-Type: application/json
Parametrize model, temperature, max_tokens e tool_choice.
Inspecione usage em cada resposta.
Adicione um cálculo de custo por chamada:

const usage = response.body.usage;

const cost =
  usage.prompt_tokens * 1.5 / 1_000_000 +
  usage.completion_tokens * 7.5 / 1_000_000;

console.log(`Estimated cost: $${cost.toFixed(6)}`);

Se você já tem uma coleção da API DeepSeek V4, duplique a coleção, troque a URL base para https://api.mistral.ai/v1 e altere o modelo para mistral-medium-3.5. O mesmo padrão vale para comparar com o GPT-5.5.

Tratamento de erros

Códigos comuns:

Código	Significado	Como resolver
`400`	Requisição inválida	Valide `messages`, `tools` e JSON.
`401`	Chave inválida	Regenere a chave em console.mistral.ai.
`402`	Pagamento necessário	Adicione saldo ou método de pagamento.
`403`	Modelo não permitido	Verifique escopo da chave e grafia do modelo.
`422`	Parâmetro fora do intervalo	Revise `max_tokens`, `tool_choice` e schema.
`429`	Rate limit	Use retry com backoff exponencial e jitter.
`500`	Erro do servidor	Tente novamente uma vez.
`503`	Sobrecarga	Espere ou faça fallback para outro modelo.

Exemplo simples de retry em Python:

import time
import random

def call_with_retry(fn, max_attempts=4):
    for attempt in range(max_attempts):
        try:
            return fn()
        except Exception as exc:
            status = getattr(exc, "status_code", None)

            if status not in [429, 500, 502, 503, 504]:
                raise

            if attempt == max_attempts - 1:
                raise

            sleep = (2 ** attempt) + random.random()
            time.sleep(sleep)

Não tente novamente erros 4xx automaticamente, exceto 429. Em geral, eles indicam bug de payload ou configuração.

Controle de custo

O Medium 3.5 é mais caro que o Medium 3. Use roteamento e limites desde o início.

1. Use Medium 3 como padrão e escale para 3.5

Faça a primeira passagem com um modelo mais barato. Envie para o Medium 3.5 apenas quando:

o validador falhar;
a confiança for baixa;
houver necessidade de visão;
o contexto exceder o limite do modelo menor;
a tarefa envolver ferramentas ou raciocínio mais complexo.

2. Defina `max_tokens`

A saída é o lado mais caro. Evite deixar a geração sem limite.

response = client.chat.complete(
    model="mistral-medium-3.5",
    messages=messages,
    max_tokens=1200,
)

3. Reduza prompts de sistema

Prompts de sistema longos são cobrados em todas as chamadas. Se um preâmbulo de 2K tokens pode virar 500 tokens, você reduz custo de entrada em 75% naquele trecho.

4. Registre `usage`

Envie para sua observabilidade:

prompt_tokens
completion_tokens
total_tokens
custo estimado
modelo usado
endpoint
latência

5. Use visão seletivamente

Não envie imagens inteiras quando um recorte resolve. Não envie múltiplos frames quando um único frame responde à pergunta.

Comparando o Medium 3.5 com outros níveis da Mistral

Linha citada para o final de abril de 2026:

Modelo	Contexto	Entrada $/M	Saída $/M	Visão	Melhor para
`mistral-small`	32K	US$ 0.10	US$ 0.30	Não	Classificação de alto volume e chat leve
`mistral-medium-3`	128K	US$ 0.40	US$ 2.00	Não	Alto rendimento e chat longo
`mistral-medium-3.5`	256K	US$ 1.5	US$ 7.5	Sim	Raciocínio, código, visão e agentes
`mistral-large`	128K	US$ 2.00	US$ 6.00	Limitado	Raciocínio de texto de nível de fronteira

O Medium 3.5 é o nível que combina contexto longo, visão e capacidades mescladas de raciocínio. Escolha pelo tipo de trabalho, não apenas pelo nome do modelo.

Migrando de outro provedor

A migração costuma ser uma troca de URL base e modelo.

Da OpenAI:

- base_url="https://api.openai.com/v1"
- model="gpt-5.5"
+ base_url="https://api.mistral.ai/v1"
+ model="mistral-medium-3.5"

Da DeepSeek:

- base_url="https://api.deepseek.com/v1"
- model="deepseek-v4-pro"
+ base_url="https://api.mistral.ai/v1"
+ model="mistral-medium-3.5"

Ajustes obrigatórios:

- tool_choice="required"
+ tool_choice="any"

- seed=123
+ random_seed=123

Antes de mudar produção:

Rode sua suíte de testes.
Compare respostas para prompts críticos.
Espelhe tráfego em modo sombra por um dia.
Registre as duas respostas.
Compare latência, custo e taxa de falha no Apidog.

Casos de uso práticos

Revisão de código

O contexto de 256K permite enviar diffs grandes com arquivos relacionados. A pontuação de 77,6% no SWE-Bench Verified torna o modelo relevante para fluxos de PR review e correção de bugs.

QA em documentos longos

Contratos, RFPs, políticas internas e documentos técnicos podem caber em uma única chamada, reduzindo a necessidade de chunking.

Extração multimodal

Você pode extrair campos estruturados de recibos, screenshots ou diagramas usando visão + JSON estruturado na mesma chamada.

Agentes com ferramentas

A chamada de função nativa ajuda em fluxos onde o modelo precisa decidir entre:

chamar uma ferramenta;
pedir mais informação;
responder diretamente;
continuar um loop de execução.

FAQ

Qual é o ID do modelo na API?

Use:

mistral-medium-3.5

O checkpoint no Hugging Face é:

mistralai/Mistral-Medium-3.5-128B

Para a API hospedada, use o ID curto. Para self-hosting, use o ID do Hugging Face.

O Medium 3.5 é compatível com OpenAI?

É próximo, mas não idêntico. O endpoint, cabeçalhos e a maioria dos parâmetros seguem o padrão da OpenAI. Os SDKs Python e Node da OpenAI funcionam com override de URL base.

Diferenças principais:

tool_choice="any" em vez de required.
random_seed em vez de seed.

Posso executar o Medium 3.5 localmente?

Sim. Os pesos são abertos sob uma Licença MIT Modificada com exceção para grandes receitas. O modelo tem 128B parâmetros, então exige memória GPU significativa. Builds GGUF quantizados de unsloth/Mistral-Medium-3.5-128B-GGUF podem rodar em uma placa de consumidor de ponta. Os padrões de como executar o DeepSeek V4 localmente são aplicáveis.

Ele suporta streaming com chamadas de ferramenta?

Sim. O streaming retorna fragmentos de argumentos de ferramenta em delta.tool_calls, no mesmo estilo do streaming de tool calls da OpenAI. Os fragmentos formam um JSON completo ao final do stream.

Como contar tokens antes de enviar?

Use o tokenizador do pacote Python mistral-common. Ele usa o mesmo tokenizador da API, então as contagens devem corresponder a usage.prompt_tokens.

Qual contexto devo planejar para produção?

O limite é 256K, mas o custo escala linearmente. Uma chamada com 200K tokens de entrada custa US$ 0,30 antes da geração. Para a maioria dos workloads, tente ficar abaixo de 32K e use contexto longo apenas quando necessário.

Existe nível gratuito?

A Mistral não anuncia um nível gratuito permanente, mas novas contas geralmente recebem um pequeno crédito de teste. Para experimentação gratuita em modelos similares, veja como usar a API DeepSeek V4 gratuitamente.

Plataforma API para Workflow API Design-First

Lucas — Thu, 30 Apr 2026 03:31:25 +0000

TL;DR

A abordagem design-first significa escrever a especificação da API antes do código de implementação. Essa especificação passa a orientar mocks, documentação, testes e stubs de cliente. Ao usar uma plataforma que cobre esse fluxo de ponta a ponta, você reduz o atrito de manter código, documentação e contratos sincronizados.

Experimente o Apidog hoje

Apidog

Experimente o Apidog gratuitamente

Introdução

A maioria dos desenvolvedores começa criando APIs com uma abordagem code-first:

Escreve uma rota.
Adiciona anotações ou decorators.
Gera documentação.
Ajusta conforme o código evolui.

Isso funciona em projetos pequenos. O problema aparece quando a API cresce.

A documentação se desvia. As anotações ficam desatualizadas. Um endpoint muda o formato da resposta, mas a especificação não é atualizada. Meses depois, o frontend consome uma documentação que diz que a API retorna um array de strings, enquanto a resposta real retorna um array de objetos com um campo value.

No design-first, a especificação é a fonte da verdade. Código, documentação, mocks e testes partem dela. Quando a especificação muda, todo o fluxo acompanha essa mudança.

Na prática, isso permite:

Desenvolvimento frontend e backend em paralelo.
Mocks disponíveis antes da implementação.
Documentação sempre alinhada ao contrato.
Testes de contrato para detectar divergências.
Revisão explícita de mudanças na API.

O ponto crítico é a ferramenta. Se escrever a especificação for mais lento do que implementar a rota diretamente, a equipe tende a ignorar o processo. Uma boa plataforma design-first precisa tornar a criação do contrato rápida, visual e integrada ao restante do ciclo de desenvolvimento.

O que design-first significa na prática

Design-first não é uma tecnologia específica. É um fluxo de trabalho.

A ideia central é simples:

Defina o contrato da API antes de implementar a API.

Esse contrato geralmente é escrito em OpenAPI para APIs REST.

Antes de escrever código

Comece definindo a especificação da API. Ela deve incluir:

Caminhos e métodos HTTP.
Parâmetros de path, query e headers.
Schemas de request body para POST, PUT e PATCH.
Schemas de resposta para status como 200, 400, 401, 422 e 500.
Requisitos de autenticação.
Descrições de campos.
Exemplos de payloads.

Exemplo simplificado de especificação OpenAPI:

openapi: 3.0.3
info:
  title: "Users API"
  version: 1.0.0

paths:
  /users/{id}:
    get:
      summary: Buscar usuário por ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: "Usuário encontrado"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserProfile"
        "404":
          description: "Usuário não encontrado"

components:
  schemas:
    UserProfile:
      type: object
      required:
        - id
        - name
        - email
      properties:
        id:
          type: string
          example: "usr_123"
        name:
          type: string
          example: "Ana Silva"
        email:
          type: string
          format: email
          example: "ana@example.com"

Essa etapa força decisões importantes antes da implementação:

Como os recursos serão nomeados.
Qual será o formato dos erros.
Como paginação será representada.
Quais campos são obrigatórios.
Quais status HTTP serão usados.
Como autenticação será aplicada.

Durante o desenvolvimento

Depois que a especificação existe, publique um mock baseado nela.

Com isso:

O frontend consome a URL mockada.
O backend implementa seguindo o contrato.
Ambos trabalham em paralelo.
A integração começa antes da API real estar pronta.

Exemplo de fluxo:

1. Equipe define GET /users/{id} na especificação
2. Mock é gerado automaticamente
3. Frontend usa o mock para construir a tela
4. Backend implementa o endpoint real
5. Testes validam se a resposta real segue o schema

Após a implementação

A implementação deve ser validada contra a especificação.

Por exemplo, se a especificação diz que email é obrigatório e a API real não retorna esse campo, o teste deve falhar.

Esse tipo de validação evita que divergências cheguem ao ambiente de produção.

Quando os requisitos mudam

A ordem correta é:

Atualizar a especificação.
Revisar a mudança com as partes envolvidas.
Atualizar mocks e documentação.
Ajustar implementação.
Rodar testes de contrato.

A implementação não deve mudar silenciosamente sem atualizar o contrato.

O que uma plataforma design-first precisa oferecer

Nem toda ferramenta de API suporta bem fluxos design-first. Para funcionar no dia a dia, a plataforma precisa cobrir mais do que edição de YAML.

Editor visual de API

YAML puro é útil, mas não é a melhor interface para design colaborativo.

Um bom editor visual deve permitir configurar:

Método HTTP.
Path.
Parâmetros.
Headers.
Body.
Responses.
Schemas.
Exemplos.
Regras de validação.

Também deve gerar OpenAPI válido sem exigir que a equipe escreva tudo manualmente.

Validação OpenAPI em tempo real

A especificação precisa ser válida antes de ser usada para mocks, documentação ou geração de código.

A ferramenta deve indicar problemas como:

Campos obrigatórios ausentes.
Referências $ref quebradas.
Tipos inválidos.
Responses sem schema.
Parâmetros declarados no path, mas não definidos.

Isso evita descobrir erros apenas no CI ou no momento da integração.

Mock automático a partir da especificação

O mock deve ser gerado diretamente da especificação, sem configuração duplicada.

Fluxo ideal:

Criar endpoint → Definir schema → Salvar → Obter URL mockada

O mock deve respeitar:

Tipos de campos.
Formatos como email, date, uuid.
Valores mínimos e máximos.
Enums.
Arrays.
Objetos aninhados.
Schemas reutilizáveis via $ref.

Documentação com pré-visualização

A documentação deve ser derivada da especificação.

Durante o design, a equipe deve conseguir revisar:

Descrição do endpoint.
Parâmetros.
Payloads.
Schemas.
Exemplos de request e response.
Códigos de erro.

Isso ajuda frontend, backend, QA, produto e integrações externas a validarem o contrato antes da implementação.

Revisão em equipe

Mudanças em APIs devem ser tratadas como mudanças de código.

Uma plataforma design-first deve permitir:

Comentários em endpoints.
Discussões em campos específicos.
Histórico de alterações.
Revisão assíncrona.
Visibilidade sobre quem alterou o quê.

Exportação para OpenAPI padrão

A especificação precisa ser portátil.

Você deve conseguir exportar OpenAPI 3.x e usar com outras ferramentas, como:

Geradores de código.
Gateways de API.
Validadores.
Test runners.
Ferramentas de documentação.
Pipelines de CI/CD.

Apidog como plataforma design-first

O Apidog organiza o fluxo em torno da especificação da API. Design, mock, documentação, testes e colaboração usam a mesma definição de API como base.

Editor visual OpenAPI

No Apidog, cada endpoint é editado em uma interface estruturada.

Você configura:

Path.
Método HTTP.
Parâmetros.
Headers.
Body.
Responses.
Schemas.
Descrições.
Exemplos.
Regras de validação.

Isso reduz a necessidade de escrever YAML manualmente.

Ainda assim, se preferir, é possível visualizar e editar a representação bruta em YAML ou JSON. As alterações feitas na visualização visual e na visualização bruta permanecem sincronizadas.

Reutilização com componentes

Componentes de schema são essenciais para evitar duplicação.

Exemplo:

components:
  schemas:
    ErrorResponse:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          example: "USER_NOT_FOUND"
        message:
          type: string
          example: "Usuário não encontrado"

Depois, o mesmo schema pode ser referenciado em vários endpoints:

responses:
  "404":
    description: Usuário não encontrado
    content:
      application/json:
        schema:
          $ref: "#/components/schemas/ErrorResponse"

No Apidog, esses componentes podem ser definidos uma vez e reutilizados em múltiplas rotas. Ao alterar o schema, os endpoints que o referenciam refletem a mudança.

Pré-visualização de documentação em tempo real

Enquanto você projeta um endpoint, a documentação pode ser pré-visualizada.

Isso permite validar rapidamente:

Se os nomes dos campos estão claros.
Se os exemplos fazem sentido.
Se os status HTTP estão documentados.
Se os erros estão compreensíveis.
Se a estrutura do payload é fácil de consumir.

Essa pré-visualização é útil para revisar a API com frontend, QA, produto ou times externos antes de implementar o backend.

Smart Mock: da especificação para um mock funcional

Ao salvar um endpoint no Apidog, o servidor de mock fica disponível.

O mock gera respostas com base nos schemas definidos. Por exemplo:

Campos string com format: email retornam emails válidos.
Campos integer com minimum e maximum retornam valores dentro do intervalo.
Campos enum retornam um dos valores permitidos.
Arrays e objetos aninhados seguem a estrutura definida.
Schemas com $ref são resolvidos corretamente.

Exemplo de schema:

UserProfile:
  type: object
  properties:
    id:
      type: string
      example: "usr_123"
    email:
      type: string
      format: email
    role:
      type: string
      enum:
        - admin
        - member
        - viewer

O mock pode retornar algo compatível com esse contrato:

{
  "id": "usr_123",
  "email": "user@example.com",
  "role": "member"
}

Também é possível configurar regras de mock para cenários específicos, como:

Retornar 404 quando id = 0.
Retornar um payload específico para determinado parâmetro de query.
Simular respostas de erro.
Testar estados vazios.

Revisão em equipe e histórico de mudanças

Mudanças na especificação ficam visíveis para os membros do workspace.

A equipe pode comentar em endpoints ou campos específicos e acompanhar o histórico de alterações.

Para um fluxo design-first, isso ajuda a manter uma prática importante:

Nenhuma mudança de contrato deve acontecer sem visibilidade para quem consome a API.

Design-first vs. code-first: compensações reais

Design-first não é sempre a melhor escolha. A decisão depende do contexto.

Vantagens do design-first

Use design-first quando você precisa de coordenação entre pessoas ou times.

Benefícios principais:

Frontend e backend trabalham em paralelo.
Mocks ficam disponíveis desde o início.
A documentação nasce junto com o contrato.
Mudanças são revisadas antes da implementação.
Testes conseguem validar a implementação contra o schema.
Problemas de integração aparecem mais cedo.

Desvantagens do design-first

O design-first também tem custos:

Exige tempo inicial para definir a especificação.
A equipe precisa aprender a ferramenta.
É necessário manter disciplina para não alterar a implementação sem atualizar o contrato.
Especificar demais muito cedo pode dificultar mudanças quando o domínio ainda está incerto.

Vantagens do code-first

Code-first pode ser melhor quando:

O projeto é pequeno.
Você está prototipando.
Há apenas um desenvolvedor.
A API ainda é experimental.
A velocidade de descoberta é mais importante do que a estabilidade do contrato.

Desvantagens do code-first

Os problemas aparecem conforme a API cresce:

Documentação tende a ficar desatualizada.
Frontend precisa esperar a implementação real.
O contrato fica implícito no código.
Mudanças quebram consumidores com mais facilidade.
Refatorações exigem atualização manual da documentação.

Como regra prática:

Projeto experimental ou solo → code-first pode ser suficiente
API consumida por múltiplos times → design-first tende a escalar melhor

Ferramentas que suportam fluxos design-first

Apidog

O Apidog combina editor visual, mock, documentação, testes e revisão em equipe em uma única plataforma.

É uma boa opção para times que querem manter a especificação como fonte da verdade e usar o mesmo contrato para design, mock, validação e documentação.

Stoplight Studio

O Stoplight Studio oferece um editor OpenAPI forte e linting com Spectral para padronização.

É útil para organizações que precisam de governança de API. Porém, não foca no mesmo nível de integração entre mock, testes e fluxo completo de desenvolvimento.

SwaggerHub

O SwaggerHub é uma plataforma madura para edição e colaboração em OpenAPI.

É bastante usado em ambientes corporativos e funciona bem para organizações já inseridas no ecossistema Swagger. Sua capacidade de mock e testes é mais limitada em comparação com plataformas mais integradas.

Postman com API Builder

O Postman oferece recursos de design de API e geração de especificações OpenAPI.

Ainda assim, os fluxos de design e collections podem parecer separados. O mock geralmente exige configuração manual a partir de collections, em vez de nascer automaticamente da especificação.

Funciona bem para equipes code-first que querem adicionar documentação e alguns recursos de contrato.

Insomnia com modo de documento

O Insomnia permite editar especificações OpenAPI e oferece mock básico.

É uma opção leve para desenvolvedores solo, mas menos completa para fluxos design-first colaborativos.

Como configurar um fluxo design-first no Apidog

Passo 1: comece pela especificação

Crie um projeto e abra a área de design.

Antes de enviar qualquer request, defina pelo menos:

Path.
Método HTTP.
Parâmetros.
Schema de resposta.
Possíveis códigos de erro.

Exemplo mínimo:

GET /users/{id}

Path param:
- id: string, obrigatório

Responses:
- 200: UserProfile
- 404: ErrorResponse

Passo 2: defina componentes compartilhados

Antes de criar muitos endpoints, padronize os schemas reutilizáveis.

Componentes comuns:

ErrorResponse
Pagination
UserProfile
AuthToken
ValidationError
Metadata

Exemplo:

Pagination:
  type: object
  properties:
    page:
      type: integer
      example: 1
    pageSize:
      type: integer
      example: 20
    total:
      type: integer
      example: 150

Isso evita que cada endpoint implemente paginação ou erros de forma diferente.

Passo 3: salve o endpoint e use a URL de mock

Assim que o endpoint estiver salvo, copie a URL do mock e compartilhe com o frontend.

O frontend pode começar com algo como:

const response = await fetch("https://mock.example.com/users/usr_123");
const user = await response.json();

console.log(user.name);

Mesmo que o backend ainda não esteja pronto, a interface já pode ser implementada usando o contrato.

Passo 4: revise a documentação antes do código

Abra a pré-visualização da documentação e valide:

O objetivo do endpoint está claro?
Os campos têm descrições úteis?
Os exemplos representam casos reais?
Os erros estão documentados?
O frontend tem informação suficiente para consumir a API?

Se algo não estiver claro na documentação, corrija na especificação antes da implementação.

Passo 5: bloqueie o contrato durante o sprint

Depois da revisão, trate a especificação como o contrato do sprint.

Se a implementação exigir uma mudança, não altere apenas o código. Faça o fluxo correto:

1. Propor alteração na especificação
2. Revisar impacto com consumidores da API
3. Atualizar mock e documentação
4. Ajustar backend
5. Validar com testes

Isso evita que o frontend integre contra um comportamento diferente do planejado.

Passo 6: valide schemas no CI

Configure testes para garantir que a resposta real respeite o contrato.

Exemplo de validação esperada:

Endpoint: GET /users/{id}
Esperado:
- status 200
- body compatível com UserProfile
- campo email presente
- campo email no formato correto

Em um pipeline, a ideia é:

Build → Deploy ambiente de teste → Executar testes de API → Validar schema → Aprovar ou falhar

Esse passo mantém implementação e especificação sincronizadas ao longo do tempo.

FAQ

O design-first é apenas para APIs REST?

Não.

O princípio se aplica a qualquer tecnologia em que exista um contrato:

REST com OpenAPI.
GraphQL com schema-first.
gRPC com arquivos .proto.
Sistemas orientados a eventos com AsyncAPI.

O Apidog suporta design REST e GraphQL. Para gRPC, os arquivos proto cumprem o papel de contrato primeiro.

Precisamos definir todos os endpoints antes de começar?

Não.

Você pode adotar design-first por recurso.

Por exemplo:

Sprint atual: módulo de usuários
Defina primeiro apenas os endpoints de usuários
Implemente backend e frontend em paralelo
Depois avance para o próximo módulo

A adoção incremental funciona bem e reduz resistência da equipe.

Como design-first funciona com sprints ágeis?

No início do sprint, faça uma sessão curta de design da API.

Saída esperada:

Endpoints definidos.
Schemas revisados.
Mocks publicados.
Documentação inicial disponível.
Pontos de dúvida registrados.

Depois disso, frontend e backend trabalham em paralelo durante o sprint.

E se a implementação precisar divergir da especificação?

Isso pode acontecer.

O processo correto é:

Atualizar a especificação.
Revisar a mudança com os consumidores da API.
Atualizar mocks e documentação.
Alterar a implementação.
Rodar os testes.

A especificação deve continuar sendo a fonte da verdade.

Podemos gerar stubs de servidor a partir da exportação OpenAPI do Apidog?

Sim.

Exporte a especificação como OpenAPI 3.x e use um gerador de código compatível.

Por exemplo, com openapi-generator:

openapi-generator-cli generate \
  -i openapi.yaml \
  -g nodejs-express-server \
  -o ./generated-server

O openapi-generator suporta várias linguagens e frameworks.

Como lidar com versionamento da especificação?

O Apidog mantém histórico de mudanças dentro do projeto.

Para versões principais mantidas em paralelo, como v1 e v2, uma abordagem comum é usar projetos ou branches separados.

Exemplo:

API Users v1 → projeto/branch estável
API Users v2 → projeto/branch em evolução

Conclusão

Design-first exige um pequeno investimento inicial em disciplina, mas reduz custos de integração conforme a API cresce.

O fluxo recomendado é:

Especificar → Revisar → Mockar → Implementar → Testar → Documentar automaticamente

A ferramenta escolhida precisa tornar esse fluxo simples. Se escrever a especificação for difícil, a equipe volta para code-first.

Com editor visual, mock instantâneo, documentação em tempo real e testes conectados ao mesmo contrato, o Apidog torna o design-first mais prático para equipes que precisam construir APIs de forma colaborativa e previsível.

APIDOG Abril: Novidades, Debugger IA, Debugger A2A e Migração Postman Fácil

Lucas — Wed, 29 Apr 2026 08:48:27 +0000

O lançamento de abril foca em um problema comum no desenvolvimento de Agentes de IA: inspecionar o que aconteceu antes da resposta final.

Experimente o Apidog hoje

Quando você está construindo agentes, a dificuldade raramente está apenas na resposta retornada. O desafio é entender o caminho até ela:

O agente interpretou corretamente a intenção do usuário?
Qual modelo foi chamado?
Qual ferramenta foi executada?
O retorno da ferramenta estava correto?
O erro veio do prompt, da configuração do modelo ou da lógica de negócio?

Neste mês, o Apidog adiciona recursos para tornar esse fluxo mais fácil de depurar:

AI Agent Debugger
A2A Debugger
Importação do Postman via API
Pergunte à IA em documentos publicados na barra lateral
Provedores personalizados de modelo de IA

⭐ Novas Atualizações

🔥 AI Agent Debugger: inspecione a execução completa do agente

O Apidog já suportava depuração visual para endpoints SSE, útil para:

respostas de modelo em streaming;
atualizações de progresso;
notificações em tempo real;
APIs orientadas a eventos.

Mas depurar agentes exige mais do que visualizar um stream.

Uma resposta final mostra onde o agente chegou. Para corrigir problemas reais, você precisa ver como ele chegou lá.

Com o novo AI Agent Debugger, você pode acompanhar a execução completa do agente dentro do Apidog, incluindo:

rodadas de conversa;
chamadas de modelo;
chamadas de ferramenta MCP;
execução de Skills personalizadas;
resultados das ferramentas;
saída final.

Na prática, isso ajuda a responder perguntas como:

O prompt forneceu contexto suficiente?
O agente escolheu a ferramenta correta?
A ferramenta MCP retornou o resultado esperado?
O problema está no modelo, nos parâmetros da ferramenta ou na regra de negócio?

Esse tipo de inspeção é especialmente útil quando o fluxo do agente deixa de ser uma demo simples e passa a envolver múltiplas etapas, ferramentas e decisões intermediárias.

🤝 A2A Debugger: teste comunicação agente-para-agente

Sistemas multiagentes estão se tornando mais comuns. Quando agentes começam a trabalhar juntos, você precisa validar se eles conseguem:

delegar tarefas;
trocar mensagens;
retornar resultados;
lidar corretamente com parâmetros e respostas.

O Apidog agora suporta depuração para o protocolo A2A, ou Agente-para-Agente, do Google.

Com o A2A Debugger, você pode:

enviar requisições A2A diretamente;
inspecionar os parâmetros da requisição;
verificar a resposta;
validar o resultado da interação entre agentes.

A diferença entre os dois novos recursos é direta:

AI Agent Debugger: depura o que acontece dentro de um único agente durante a execução.
A2A Debugger: depura a comunicação entre um agente e outro.

Se você está criando sistemas com múltiplos agentes, provavelmente vai precisar dos dois.

📦 Importe dados do Postman através da API do Postman

A migração do Postman agora tem uma opção melhor para equipes maiores.

O Apidog já suportava importação de arquivos locais do Postman. Agora, também é possível importar:

Workspaces;
Coleções;
Ambientes.

Tudo isso através da API do Postman.

Esse fluxo é mais adequado para migrações em massa ao criar novos projetos.

Em vez de exportar arquivos manualmente, fazer upload e depois ajustar tudo, você pode importar dados diretamente. Se sua conta do Postman tiver vários Workspaces, o Apidog criará projetos correspondentes após a importação.

Use assim:

Para importações pequenas: arquivos locais ainda funcionam.
Para migrações maiores: use a importação via API do Postman.

📄 Pergunte à IA em documentos publicados agora abre na barra lateral

O recurso Pergunte à IA em documentação publicada agora funciona em uma barra lateral.

Isso permite que o leitor mantenha a documentação aberta enquanto faz perguntas sobre ela.

Na prática, o fluxo fica mais simples:

leia a documentação da API;
abra a barra lateral do Pergunte à IA;
faça uma pergunta sobre o conteúdo;
continue na mesma página, sem perder o contexto.

Essa mudança é útil principalmente em documentações longas, onde a resposta pode estar na página, mas não é fácil de localizar rapidamente.

🧠 Provedores de modelo de IA personalizados

Equipes agora podem conectar provedores personalizados usando uma URL Base personalizada.

Isso é útil se sua empresa já usa:

um serviço de modelo auto-hospedado;
um gateway interno de modelos;
uma configuração própria para fluxos de IA.

Assim, você pode usar essa configuração no Apidog ao depurar fluxos relacionados à IA, sem alternar entre várias ferramentas.

🐞 Correções de bugs e melhorias menores

Também foram lançadas correções e melhorias neste mês:

Corrigido um problema onde a mesclagem inteligente OpenAPI não mantinha exemplos de resposta de endpoint.
Corrigido um problema onde a mesclagem de uma branch filha para uma branch principal protegida poderia incluir endpoints que não foram selecionados.
Corrigida a exibição incorreta do menu suspenso ao criar versões de endpoint a partir de branches.
Corrigido um problema onde TestData e TestCases não funcionavam ao executar testes via CLI.
Corrigido um problema onde a exportação OpenAPI incluía componentes de resposta de módulos não relacionados.
Corrigida a formatação da exportação Markdown para JSON com comentários.
Corrigido um erro de exportação Word causado por crypto is not defined.
Corrigido um problema onde a importação do Knife4j com Basic Auth habilitado não mostrava os campos de usuário e senha.
Corrigido um erro de filtragem de endpoint quando as tags eram números.
Corrigido um problema onde apidog endpoint list --branch não retornava dados para a branch especificada.
Corrigidos vários problemas de parâmetros, filtragem e mensagens de erro da ferramenta MCP.
Corrigido um problema onde o código gerado estava faltando a opção de configuração typescriptThreePlus.

🌟 O que isso significa

Este lançamento é voltado para equipes que estão levando Agentes de IA para projetos reais.

Resumo prático:

Use o AI Agent Debugger para entender a execução interna de um agente.
Use o A2A Debugger para validar comunicação entre agentes.
Use a importação via API do Postman para migrações maiores.
Use o Pergunte à IA na barra lateral para melhorar a experiência em documentação publicada.
Use provedores personalizados de modelo para trabalhar com sua própria infraestrutura de IA.

O objetivo não é adicionar recursos chamativos. É reduzir o tempo gasto tentando descobrir onde um fluxo de agente falhou.

💬 Participe da conversa

Conecte-se com outros engenheiros de API e com a equipe Apidog:

Junte-se à nossa comunidade do Discord para discussões e suporte em tempo real.
Participe da nossa comunidade do Slack para conversas técnicas.
Siga-nos no X (Twitter) para as últimas atualizações.

P.S. Para todos os detalhes sobre as atualizações, confira o Apidog Changelog!

Atenciosamente,

A Equipe Apidog

GitHub Copilot: Faturamento e Custos para Equipes de API

Lucas — Wed, 29 Apr 2026 07:09:07 +0000

O modelo de faturamento do GitHub Copilot mudou duas vezes no ano passado e mudou novamente este mês. Agora, a revisão de código do Copilot em pull requests consome minutos do GitHub Actions da conta de faturamento proprietária do repositório. Para equipes de API, isso significa gerenciar três medidores ao mesmo tempo: licenças do Copilot, solicitações premium e minutos do Actions. Este guia mostra como cada medidor funciona, por que repositórios de API tendem a consumir mais e como estimar o custo antes de ele aparecer na fatura.

Experimente o Apidog hoje

No final, combinamos esse modelo com um fluxo de trabalho no Apidog para manter especificação da API, testes de contrato e etapas de revisão de IA em um único fluxo, em vez de espalhar o controle entre vários painéis de faturamento.

Se você também está avaliando modelos de API consumidos diretamente pela sua equipe, veja os guias sobre precificação do GPT-5.5 e precificação do DeepSeek V4, que cobrem o lado por token da mesma discussão.

TL;DR

O Copilot agora tem três medidores principais: licença por usuário, solicitações premium e minutos do Actions para revisão de código.
A revisão de código em PRs roda como uma GitHub Action e consome a cota normal de minutos da organização.
Repositórios de API tendem a consumir mais porque PRs incluem especificação, clientes gerados, handlers e testes.
Solicitações premium impactam principalmente recursos como Workspace, modo agente, Copilot Spaces e seleção de modelos.
Defina limites de gastos antes do próximo ciclo. Para um repositório de API ativo, comece estimando 400 a 800 minutos do Actions por mês e ajuste após 30 dias.

Os três medidores do Copilot

O Copilot deixou de ser uma única linha previsível na fatura. Agora você precisa acompanhar três itens.

1. Licença por usuário

Este é o custo fixo:

Copilot Business:    $10 por usuário/mês
Copilot Enterprise:  $19 por usuário/mês

A licença cobre recursos como:

chat;
conclusões inline;
sugestões de múltiplas linhas;
integrações com IDE;
acesso ao pool padrão de modelos.

Esse é o medidor mais simples de prever, mas também o mais fácil de superdimensionar. Faça uma auditoria trimestral e remova licenças de usuários inativos.

2. Solicitações premium

Solicitações premium são usadas pelos recursos mais caros do Copilot, como:

modo agente;
Workspace;
Copilot Spaces;
seleção manual de modelos fora do padrão.

Custos atuais em solicitações premium:

Recurso	Custo em solicitações premium
Chat do modelo padrão	Gratuito para planos pagos
Conclusões inline	Gratuito para planos pagos
Modo agente com modelo padrão	1 por solicitação
Workspace com modelo padrão	1 por solicitação
Claude Sonnet 4.5	Multiplicador de 1,5x
GPT-5.5	Multiplicador de 2x
GPT-5.5 Pro	Multiplicador de 6x
Consulta Copilot Spaces	1 por consulta

Cotas incluídas:

Copilot Business:    300 solicitações premium por licença/mês
Copilot Enterprise:  1.000 solicitações premium por licença/mês
Excedente:           $0.04 por solicitação

Para equipes de API, os prompts que mais consomem esse medidor geralmente são tarefas do modo agente, por exemplo:

Regenerar o cliente OpenAPI.
Criar testes de contrato para este endpoint.
Atualizar os mocks com base na nova especificação.
Refatorar handlers afetados pela mudança de schema.

Uma única tarefa pode gerar várias etapas internas. Na prática, um prompt pode consumir quatro ou cinco solicitações premium.

3. Minutos do Actions para revisão de código

Esta é a mudança que mais surpreende equipes de engenharia.

Quando o Copilot executa uma revisão automática em um pull request, essa revisão roda sobre a infraestrutura do GitHub Actions. Ou seja, ela consome os mesmos minutos usados pela sua CI.

Pontos importantes:

Os minutos entram na cota existente do GitHub Actions.
Eles não são uma cota separada do Copilot.
Repositórios privados consomem minutos faturáveis.
Repositórios públicos continuam com Actions gratuito, conforme as regras do GitHub.

Uma revisão típica do Copilot em um PR de API consome de 2 a 6 minutos do Actions. Em PRs grandes, com muitos arquivos e contexto completo do repositório, esse número pode chegar a 15 minutos.

Por que repositórios de API consomem mais

Repositórios de API costumam amplificar os três medidores por alguns motivos práticos.

1. PRs de API são maiores

Uma alteração simples em API pode tocar vários arquivos:

openapi.yaml
clientes gerados
handler do servidor
schemas
testes de contrato
mocks
documentação

Quanto maior o diff, mais trabalho para a revisão automática e maior o tempo de execução no Actions.

2. Código gerado aumenta o ruído

Muitas equipes versionam clientes gerados no repositório. Quando isso acontece, a revisão do Copilot pode analisar também arquivos que não deveriam ser revisados manualmente.

Exemplo comum:

clients/typescript/**
clients/python/**
clients/java/**

Se esses diretórios entram no diff, eles aumentam o tempo de revisão sem necessariamente melhorar a qualidade do feedback.

3. O PR pode acionar vários revisores

Em um mesmo pull request, a equipe pode rodar:

Copilot Review;
CodeQL;
Snyk;
scanner interno de segurança;
testes de contrato;
linters;
validação de OpenAPI.

Cada ferramenta tem seu próprio custo operacional. O Copilot passa a ser mais um item nesse pipeline.

Exemplo de impacto:

50 PRs/mês × 4 minutos por revisão = 200 minutos/mês

Em um plano Team com 3.000 minutos mensais para runners Linux, isso representa cerca de 7% da cota mensal para um único repositório. Com três repositórios semelhantes, você já compromete aproximadamente 21% antes de considerar o restante da CI.

Como estimar sua fatura mensal

Modele o custo em três etapas.

Etapa 1: calcule as licenças

Business:
seats = usuários_ativos × $10

Enterprise:
seats = usuários_ativos × $19

Exemplo:

10 usuários no Enterprise = 10 × $19 = $190/mês

Etapa 2: estime solicitações premium

Use uma estimativa por perfil de uso:

Uso leve:
~150 solicitações/mês por pessoa

Uso intenso com Workspace ou modo agente:
~600 a 800 solicitações/mês por pessoa

Fórmula para excedente no Business:

premium_overage = max(0, requests_used - 300_por_licença) × $0.04

Exemplo:

5 usuários Business
Cota incluída: 5 × 300 = 1.500 solicitações

Uso real: 2.000 solicitações
Excedente: 500 solicitações

Custo: 500 × $0.04 = $20

Defina um limite de gastos no nível da organização. O padrão ilimitado é arriscado para qualquer equipe que use agentes sem monitoramento ativo.

Etapa 3: estime minutos do Actions para revisão

Comece com uma média de 4 minutos por PR de API.

review_minutes = prs_por_mês × 4

Se houver excedente de Actions:

review_overage = max(0, review_minutes - actions_quota_remaining) × $0.008

Para repositórios privados Linux, use o valor vigente do GitHub como base de cálculo.

Exemplo:

200 PRs/mês × 4 minutos = 800 minutos/mês

Em uma organização Enterprise, isso provavelmente fica dentro da cota. Em uma equipe menor no Business, pode acelerar o consumo dos minutos disponíveis.

Exemplo completo de estimativa

Cenário:

10 desenvolvedores
Copilot Enterprise
200 PRs de API por mês
Uso moderado de modo agente
4 minutos por revisão

Estimativa:

Licenças:
10 × $19 = $190

Excedente premium:
~$40

Minutos de revisão:
200 × 4 = 800 minutos
Dentro da cota Enterprise: $0

Total aproximado:
$230/mês

O valor exato depende do uso real de solicitações premium e da cota restante do Actions, mas esse modelo ajuda a detectar riscos antes do fechamento da fatura.

Como ajustar seu pipeline de CI

Três mudanças reduzem custo rapidamente.

1. Ignore PRs de bots

Você provavelmente não precisa de revisão de IA para atualizações automáticas do Dependabot ou Renovate.

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  copilot-review:
    if: github.actor != 'dependabot[bot]' && github.actor != 'renovate[bot]'
    runs-on: ubuntu-latest
    steps:
      - uses: github/copilot-review@v1

2. Filtre arquivos gerados

Não revise clientes gerados se eles forem resultado direto da especificação.

Exemplo de estrutura:

apis/**/*.yaml
cmd/**
internal/**
tests/**
clients/generated/**

Mantenha a revisão nos arquivos que exigem decisão humana:

on:
  pull_request:
    paths:
      - 'apis/**/*.yaml'
      - 'cmd/**'
      - 'internal/**'
      - 'tests/**'

Se os clientes gerados estiverem em clients/generated/**, deixe-os fora do gatilho.

3. Use labels para acionar revisão

Em vez de rodar a revisão em todo PR, execute apenas quando o PR tiver uma label específica.

Exemplo de política:

review-please

Esse modelo reduz revisões desnecessárias e mantém o controle com o autor ou mantenedor do PR.

Governança: quatro controles obrigatórios

Configure estes itens antes do próximo ciclo de faturamento.

1. Limite de gastos

Defina no nível da organização.

Regra prática:

limite = orçamento_máximo_aceitável × 0.8

Arredondar para baixo cria margem para erro.

2. Alertas de solicitações premium

O GitHub envia alertas em marcos como 50%, 75% e 90% da cota. Encaminhe esses alertas para Slack, Teams ou ferramenta de incidentes.

Não dependa apenas de e-mail individual.

3. Política de gatilho por repositório

Decida explicitamente:

Revisão em todo PR?
Revisão apenas com label?
Revisão apenas em branches principais?
Revisão apenas em paths críticos?

Para repositórios de API, o modelo com label costuma ser mais eficiente.

4. Habilitação por equipe

Não habilite todos os recursos do Copilot Enterprise para toda a organização de uma vez.

Prefira ativar por equipe:

time-api-core
time-integrations
time-platform

Isso reduz risco de adoção acidental e facilita comparar uso por grupo.

Onde o Apidog se encaixa

O Apidog não substitui o Copilot. Ele entra como camada para centralizar especificação, mocks e testes de contrato.

Um fluxo prático para equipes de API:

Manter a especificação e exemplos de request na coleção do Apidog.
Commitar a coleção junto com o repositório.
Executar testes de contrato contra o mock server do Apidog.
Validar contrato antes da revisão de IA.
Acionar a revisão do Copilot apenas se os checks baratos passarem.

Exemplo de ordem no pipeline:

lint
openapi validation
contract tests with Apidog
unit tests
Copilot review
security scans

A ordem importa porque a revisão do Copilot é uma das etapas mais caras. Se um erro de contrato pode ser detectado em 30 segundos, não faz sentido gastar minutos de revisão de IA antes disso.

O guia de testes de API sem Postman cobre o fluxo de mock do Apidog. O guia da API DeepSeek V4 mostra o padrão aplicado a um modelo de API.

O que observar no próximo ciclo de faturamento

Acompanhe o uso por semana.

Dias 1 a 7

O uso de solicitações premium costuma parecer normal. A maioria dos usuários ainda está abaixo da cota incluída.

Dias 14 a 21

Usuários intensivos começam a exceder a cota. Se houver limite de gastos, algumas solicitações podem falhar. Sem limite, a fatura cresce.

Dias 28 a 30

Os minutos do Actions consumidos pela revisão do Copilot ficam mais visíveis. Compare a fatura com o mês anterior e separe:

CI tradicional
revisões do Copilot
scans de segurança
testes de contrato

Depois do primeiro mês, ajuste:

licenças de usuários inativos;
plano de usuários pesados;
filtros de paths;
labels de revisão;
limite de gastos.

Erros comuns

Evite estes cinco problemas.

1. Não definir limite de gastos

Um loop de agente pode rodar por muito tempo. Sempre configure um teto.

2. Habilitar revisão em todo repositório

Nem todo repositório precisa de revisão automática. Priorize APIs críticas ou serviços com alto volume de mudanças.

3. Revisar código gerado

Filtre clientes gerados, SDKs e artefatos derivados da especificação.

4. Revisar PRs de bots

Ignore Dependabot, Renovate e atualizadores internos automáticos.

5. Não criar linha de base

Baixe mensalmente o CSV de faturamento do GitHub. Sem baseline, você não consegue medir se uma otimização realmente reduziu custo.

FAQ

O preço da licença ainda é $10 por usuário?

Sim, para Copilot Business. O Copilot Business custa $10 por usuário/mês, o Copilot Enterprise custa $19 por usuário/mês, e o Copilot Pro para indivíduos custa $10/mês. A licença também define a cota de solicitações premium incluídas.

Conclusões inline agora são cobradas?

Não. Chat com modelo padrão e conclusões inline continuam sem cobrança adicional para planos pagos. Solicitações premium se aplicam aos recursos mais caros e à seleção de modelos.

O que acontece quando a cota premium acaba?

Por padrão, solicitações podem falhar por erro de cota. Você pode permitir excedente a $0.04 por solicitação até o limite de gastos configurado.

Os minutos do Actions para revisão são cobrados separadamente?

Não. Eles consomem o mesmo pool de minutos do GitHub Actions usado pelo restante da CI.

Posso desabilitar a revisão do Copilot?

Sim. O administrador da organização pode controlar a revisão por política, repositório ou equipe.

A revisão funciona em especificações privadas de API?

Sim. Em repositórios privados, a execução consome minutos do Actions. O revisor lê arquivos de especificação, handlers e testes como qualquer outro código-fonte.

A revisão do Copilot também usa solicitações premium?

Atualmente, a revisão consome minutos do Actions. O modelo usado pelo revisor faz parte da plataforma Copilot e não é cobrado separadamente como solicitação premium. Essa é uma área que pode mudar, então acompanhe o changelog do GitHub.

Para equipes que executam tanto revisão do Copilot quanto chamadas diretas a APIs de modelo em CI, o guia do Codex gratuito GPT-5.5 cobre o lado por token, enquanto o Apidog ajuda a manter mocks e contratos antes da etapa mais cara de revisão de IA.

Como Usar a API Zuplo: Guia Completo

Lucas — Mon, 27 Apr 2026 08:43:19 +0000

Se você leu sobre o Zuplo e quer colocar algo real em produção, este guia te mostra como fazer na prática. Aqui você vai criar um projeto, expor uma rota, adicionar autenticação por chave de API e limitação de taxa, escrever uma política TypeScript customizada, fazer deploy para a edge e testar com o Apidog — tudo em passos objetivos para implementação rápida.

Experimente o Apidog hoje

No final, você terá um gateway de API funcional na frente da sua origem, com autenticação, limitação de taxa, portal do desenvolvedor auto-gerado e CI friendly via Git. O passo a passo leva cerca de 30 minutos.

Se ainda está avaliando se o Zuplo é o ideal, comece pelo nosso post complementar: O que é o gateway de API Zuplo. Para cenários não cobertos aqui, confira a documentação do Zuplo.

TL;DR

Cadastre-se em portal.zuplo.com ou crie um projeto local com npm create zuplo.
Defina rotas em config/routes.oas.json e encaminhe para sua origem via URL Forward Handler.
Adicione políticas de entrada (API key auth, rate limit, validação de schema) editando o arquivo de rota ou usando o Route Designer.
Escreva lógica customizada como módulos TypeScript em modules/.
Faça push para sua branch Git para deploy de preview; merge para produção em mais de 300 edges.
Teste todas as rotas com o Apidog antes de promover para produção.
O plano gratuito oferece 100 mil requisições/mês; o Builder custa $25/mês.

Pré-requisitos

Você precisa de:

Conta Zuplo
Uma API de origem (use https://echo.zuplo.io se não tiver uma)
Node.js 18+ para usar o CLI

Para desenvolvimento local, use um editor de código. VS Code com TypeScript é recomendado, e pode ser integrado com a extensão Apidog VS Code.

Passo 1: Crie seu projeto Zuplo

Duas formas de começar: via portal web ou CLI.

Opção A: Portal

Faça login em portal.zuplo.com.
Clique em "New Project" e escolha um nome, ex: acme-gateway.
Selecione "Empty Project" para não gerar nada automaticamente.
A aba "Code" mostra a estrutura inicial.

O portal já vincula a um repositório Git, que pode ser conectado ao seu GitHub, GitLab, Bitbucket ou Azure DevOps depois.

Opção B: CLI

O CLI prepara o projeto local para editar na IDE e usar Git desde o início:

npm create zuplo@latest -- --name acme-gateway
cd acme-gateway
npm install
npm run dev

O dev server inicia na porta 9000 e o Route Designer local em http://localhost:9100.

Para vincular ao seu Zuplo e fazer deploy:

npx zuplo link

Escolha conta/ambiente. Depois, use:

npx zuplo deploy

Passo 2: Defina sua primeira rota

Abra config/routes.oas.json e adicione a rota que faz proxy para sua origem:

{
  "openapi": "3.1.0",
  "info": { "title": "Acme Gateway", "version": "1.0.0" },
  "paths": {
    "/v1/products": {
      "get": {
        "summary": "List products",
        "operationId": "list-products",
        "x-zuplo-route": {
          "corsPolicy": "anything-goes",
          "handler": {
            "export": "urlForwardHandler",
            "module": "$import(@zuplo/runtime)",
            "options": {
              "baseUrl": "${env.ORIGIN_URL}"
            }
          },
          "policies": { "inbound": [] }
        },
        "responses": {
          "200": { "description": "Success" }
        }
      }
    }
  }
}

x-zuplo-route define handler e políticas.
${env.ORIGIN_URL} usa variável de ambiente. Defina em Settings > Environment Variables no portal ou em config/.env local.

Salve e teste em http://localhost:9000/v1/products.

Passo 3: Adicione autenticação por chave de API

Para proteger APIs públicas, use a política de API key do Zuplo.

No arquivo da rota, adicione:

"policies": {
  "inbound": ["api-key-auth"]
}

Depois, defina a política em config/policies.json:

{
  "name": "api-key-auth",
  "policyType": "api-key-inbound",
  "handler": {
    "export": "ApiKeyInboundPolicy",
    "module": "$import(@zuplo/runtime)",
    "options": {
      "allowUnauthenticatedRequests": false
    }
  }
}

Crie um consumidor (usuário de chave):

No portal: Services > API Key Service.
Clique em "Create Consumer".
Use um identificador, ex: acme-customer-1, e e-mail do responsável.
Copie a chave gerada.

Teste:

curl -i https://YOUR-PROJECT.zuplo.app/v1/products
# Deve retornar HTTP/2 401

curl -i https://YOUR-PROJECT.zuplo.app/v1/products \
  -H "Authorization: Bearer SUA_API_KEY"
# Deve retornar HTTP/2 200

Se preferir usar cliente real, importe a OpenAPI no Apidog, defina header global Authorization: Bearer {{api_key}} e vincule a variável.

Passo 4: Limite a taxa da rota

Para evitar abusos, adicione rate limit logo após a autenticação:

"policies": {
  "inbound": ["api-key-auth", "rate-limit-by-key"]
}

Em config/policies.json:

{
  "name": "rate-limit-by-key",
  "policyType": "rate-limit-inbound",
  "handler": {
    "export": "RateLimitInboundPolicy",
    "module": "$import(@zuplo/runtime)",
    "options": {
      "rateLimitBy": "sub",
      "requestsAllowed": 60,
      "timeWindowMinutes": 1
    }
  }
}

"rateLimitBy": "sub" limita por cliente autenticado.
Troque para "ip" se quiser limitar por IP.

Teste com 70 requisições rápidas:

for i in {1..70}; do
  curl -s -o /dev/null -w "%{http_code}\n" \
    https://YOUR-PROJECT.zuplo.app/v1/products \
    -H "Authorization: Bearer SUA_API_KEY"
done | sort | uniq -c

Espere 60 respostas 200 e 10 de 429.

Passo 5: Valide payloads de requisição

Para rotas POST, use validação automática via JSON Schema na OpenAPI.

Exemplo de rota:

"/v1/products": {
  "post": {
    "summary": "Create product",
    "operationId": "create-product",
    "requestBody": {
      "required": true,
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": ["name", "priceCents"],
            "properties": {
              "name": { "type": "string", "minLength": 1 },
              "priceCents": { "type": "integer", "minimum": 1 },
              "category": { "type": "string", "enum": ["food", "drink"] }
            }
          }
        }
      }
    },
    "x-zuplo-route": {
      "handler": { /* igual ao anterior */ },
      "policies": {
        "inbound": [
          "api-key-auth",
          "rate-limit-by-key",
          "validate-request"
        ]
      }
    }
  }
}

Política em config/policies.json:

{
  "name": "validate-request",
  "policyType": "open-api-request-validation-inbound",
  "handler": {
    "export": "OpenApiRequestValidationInboundPolicy",
    "module": "$import(@zuplo/runtime)",
    "options": {
      "validateBody": "reject"
    }
  }
}

Teste no Apidog com casos: sucesso, campo ausente, enum inválido. Execute todos em um clique.

Passo 6: Escreva uma política TypeScript personalizada

Quando precisar de lógica especial, crie uma política customizada.

Exemplo: cabeçalho de cache variando por plano.

Crie modules/tiered-cache.ts:

import { ZuploRequest, ZuploContext } from "@zuplo/runtime";

interface PolicyOptions {
  paidPlanHeader: string;
  paidMaxAge: number;
}

export default async function (
  response: Response,
  request: ZuploRequest,
  context: ZuploContext,
  options: PolicyOptions,
): Promise<Response> {
  const plan = request.user?.data?.plan ?? "free";

  if (plan === "free") {
    response.headers.set("Cache-Control", "no-store");
  } else {
    response.headers.set(
      "Cache-Control",
      `public, max-age=${options.paidMaxAge}`,
    );
  }

  context.log.info(`Cache header set for plan=${plan}`);
  return response;
}

Defina em config/policies.json:

{
  "name": "tiered-cache",
  "policyType": "custom-code-outbound",
  "handler": {
    "export": "default",
    "module": "$import(./modules/tiered-cache)",
    "options": {
      "paidPlanHeader": "x-plan",
      "paidMaxAge": 300
    }
  }
}

Referencie na rota:

"policies": {
  "inbound": ["api-key-auth", "rate-limit-by-key"],
  "outbound": ["tiered-cache"]
}

Testes unitários podem ser feitos com Vitest/Jest simulando requests e responses.

Passo 7: Faça o deploy para a edge

Deploy = push Git. Exemplo:

git add .
git commit -m "Add products gateway with auth, rate limit, and tiered cache"
git push origin feature/products-gateway

Zuplo cria ambiente de preview para cada branch, com subdomínio separado.

Teste a URL de preview no Apidog. Se tudo ok, faça merge:

git checkout main
git merge feature/products-gateway
git push origin main

Em menos de um minuto, a produção é atualizada em mais de 300 edges. Rollback é só revert/push.

Passo 8: Gere o portal do desenvolvedor

Portal automático em https://YOUR-PROJECT.developers.zuplo.com, reconstruído a cada deploy. Inclui:

Página por rota, esquema, descrição, console de testes.
Exemplos de código para várias linguagens.
Emissão de chave de API self-service.
Branding customizável em Developer Portal > Settings.

Se sua OpenAPI tem descrições e exemplos, o portal já fica apresentável. Para customizar, clone o código Next.js do repositório do portal Zuplo.

Passo 9: Teste tudo com o Apidog

Garanta qualidade testando todas as rotas, políticas e erros com o Apidog.

Workflow recomendado:

Importe a OpenAPI do gateway de https://YOUR-PROJECT.zuplo.app/openapi no Apidog.
Crie ambientes para local, preview e production, cada um com seu base_url e api_key.
Salve pelo menos três requisições por rota: sucesso, falha de auth, limite de taxa. Rode tudo antes de cada deploy.
Use cenários automatizados do Apidog para encadear chamadas e validar respostas.
Gere exemplos de código e adicione aos runbooks.

Migrando do Postman? Siga o guia de migração. Baixe o Apidog se ainda não tiver.

Perguntas comuns sobre o uso do Zuplo

Como alternar uma rota entre ambientes sem alterar a especificação?

Use variáveis de ambiente. Defina ORIGIN_URL por ambiente (portal ou config/.env), e referencie como ${env.ORIGIN_URL} nas opções do handler.

Posso rodar o Zuplo offline?

Sim. npm run dev sobe gateway local na porta 9000 e Route Designer na 9100. Políticas, validação e rate limit funcionam localmente. Apenas o serviço de chave de API é online, mas pode ser usado com npx zuplo link.

Como faço rollback de um deploy ruim?

Use git revert do commit de merge e push. O Zuplo faz deploy do estado anterior. Não existe botão de "rollback" porque o Git é a fonte da verdade.

O que acontece com requisições em andamento durante o deploy?

Deploys são atômicos na edge: requisições em andamento terminam na versão antiga, novas já usam a nova versão. Sem downtime.

Posso usar o Zuplo com gRPC ou WebSockets?

Sim. O urlForwardHandler faz proxy de upgrades WebSocket, e existe handler específico para gRPC. REST e GraphQL têm suporte nativo.

Como expor minha API Zuplo para agentes de IA?

Adicione o MCP Server Handler na rota, referencie sua OpenAPI e selecione operações a expor. Políticas de autenticação e rate limit também se aplicam. Veja a documentação do Zuplo MCP Server.

Quanto custa o gateway em produção?

Plano gratuito cobre 100k requisições/mês. Builder: $25/mês para 1 milhão/mês, adicionais por $100/100k. Enterprise começa em $1.000/mês. Veja preços completos.

Conclusão

Agora você tem um gateway Zuplo funcional com autenticação por chave de API, limitação de taxa, validação de requisição, política TypeScript customizada e portal do desenvolvedor — tudo versionado e implantado via Git, pronto para CI/CD e ambientes de preview e produção.

O que mantém seu gateway robusto é o ciclo de testes. Use o Apidog em cada preview antes do merge e capture problemas de autenticação, schema ou rate limit antes de irem para produção. Baixe o Apidog e conecte ao seu gateway agora.

O Que É o Zuplo API Gateway?

Lucas — Mon, 27 Apr 2026 06:29:21 +0000

A maioria dos gateways de API ainda parece ter sido projetada para uma equipe de operações de 2014. Você escreve YAML, luta com um painel de controle e espera que alguém com acesso ao cluster envie suas alterações. O Zuplo inverte esse modelo. É um gateway de API programável, nativo da borda, onde suas rotas vivem em um repositório Git, suas políticas são TypeScript, e cada commit é implantado em mais de 300 locais globais em segundos.

Experimente o Apidog hoje

Este guia explica o que o gateway de API Zuplo faz, como ele difere do Kong e AWS API Gateway, quais são seus custos e como lançar seu primeiro gateway em menos de trinta minutos. Você verá exemplos de código para roteamento, autenticação e limitação de taxa, além de uma seção sobre como testar cada endpoint com Apidog antes que ele chegue à produção.

O Zuplo se encaixa em uma categoria que costumava ser dominada por Kong, Apigee e AWS API Gateway. A proposta é simples: desenvolvedores obtêm uma linguagem de programação real, operações obtêm um serviço gerenciado e o produto obtém uma camada de monetização integrada. As compensações e o fluxo de trabalho real são o que esta postagem detalha.

TL;DR

Zuplo é um gateway de API totalmente gerenciado e nativo da borda que executa suas rotas em mais de 300 data centers da Cloudflare com latência inferior a 50ms e zero inicializações a frio.
A configuração é nativa de GitOps; seu gateway reside em um repositório Git e é entregue via CI/CD, não por uma UI.
As políticas são escritas em TypeScript com suporte total a IDEs, não em YAML ou Lua.
O nível gratuito cobre 100 mil requisições por mês com ambientes ilimitados, chaves de API e portais de desenvolvedor.
Recursos integrados incluem autenticação por chave de API, JWT, OAuth2, limitação de taxa, validação de requisições, um portal de desenvolvedor gerado automaticamente e monetização impulsionada pelo Stripe.
O Zuplo agora oferece um MCP Server Handler, para que qualquer rota do gateway possa ser exposta ao Claude, Codex, Cursor ou qualquer cliente MCP.
Teste cada rota do Zuplo de ponta a ponta com Apidog antes de ativar a produção.

O que é o Zuplo?

Zuplo é uma plataforma de gerenciamento de API centrada em: código em vez de configuração, borda em vez de região e Git em vez de GUI. Ele roda como um serviço gerenciado na rede de borda da Cloudflare, então uma única implantação chega a mais de 300 data centers sem configuração manual.

Diferente dos gateways tradicionais que usam YAML armazenado em um painel, o Zuplo trata o gateway como um projeto TypeScript. Você tem um routes.oas.json para endpoints, módulos TypeScript para lógica personalizada e um arquivo de configuração de políticas. Basta enviar para o GitHub e a plataforma constrói, valida e implanta.

A plataforma suporta REST, GraphQL, gRPC, WebSockets e SOAP. É compatível com SOC 2 Tipo II, funciona em backends AWS, Azure e GCP, e oferece opção Kubernetes auto-hospedada. O preço começa gratuito e escala por volume de requisições. Veja o detalhamento na página de preços do Zuplo.

Por que desenvolvedores escolhem o Zuplo em vez de Kong, Apigee e AWS API Gateway

Cada gateway tem seu perfil. Kong oferece controle máximo e exige experiência em Lua. Apigee é corporativo, mas complexo. O AWS API Gateway é padrão se você está na AWS, mas carece de portal do dev e as integrações Lambda têm inicializações a frio.

O Zuplo foca em equipes pequenas que querem recursos empresariais sem a necessidade de um time de plataforma dedicado.

Destaques práticos:

Código, não YAML: Políticas como limitação de taxa são três linhas de TypeScript. No Kong, são quinze linhas de YAML. Se você programa em TypeScript ou JavaScript, o Zuplo é direto.
Portal do desenvolvedor incluído: Portal gerado direto da OpenAPI, mesmo no plano gratuito.
GitOps por padrão: Cada mudança é um pull request. Você tem histórico, auditoria e rollback via git revert.
Nativo da borda, sem inicializações a frio: Zuplo roda em Cloudflare Workers. Cada requisição atinge o datacenter mais próximo e começa em milissegundos.

Se sua equipe já usa Kong ou Apigee e está satisfeita, migrar não faz sentido. Se está começando ou sofrendo com o gateway atual, o Zuplo é muito mais simples de operar.

Recursos principais do gateway de API Zuplo

Programabilidade com prioridade a TypeScript

O Zuplo define o comportamento do gateway em arquivos TypeScript, lado a lado com as rotas. Políticas personalizadas são funções que recebem a requisição, modificam/validam e retornam o resultado. Você ganha tipos, autocompletar, refatoração e testes.

Exemplo de política de saída que remove um cabeçalho interno:

import { ZuploRequest, ZuploContext } from "@zuplo/runtime";

export default async function (
  response: Response,
  request: ZuploRequest,
  context: ZuploContext,
) {
  response.headers.delete("x-internal-trace-id");
  return response;
}

Coloque em modules/strip-internal-header.ts, referencie na rota, envie para o Git, e está implantado.

Mais de 60 políticas pré-construídas

O Zuplo inclui mais de 60 políticas prontas: autenticação por chave de API, JWT, OAuth2, limitação de taxa (fixed window, sliding window, token bucket), validação OpenAPI, CORS, listas de IP, transformação de requests e integrações. Basta editar a definição da rota (JSON); não precisa de código para casos comuns.

Portal do desenvolvedor gerado automaticamente

Aponte para sua OpenAPI e obtenha documentação hospedada, consoles interativos, exemplos em cURL/JS/Python/Go, e emissão de chaves de API self-service. Usuários registram, geram chaves e já podem chamar a API.

Monetização de API integrada

Integração com Stripe para vender acesso à API. Defina planos, conecte o Stripe, e o portal faz checkout, assinatura e cobrança. Isso elimina semanas de desenvolvimento se você quer monetizar.

MCP Server Handler para agentes de IA

O MCP Server Handler transforma sua API em um endpoint MCP. Basta apontar para sua OpenAPI e escolher as operações. APIs ficam acessíveis para Claude Code, OpenAI Codex, Cursor e clientes MCP. Veja o tutorial do Zuplo para detalhes.

Implantação na borda, latência inferior a 50ms

Cada gateway é implantado em 300+ locais Cloudflare. Latência real abaixo de 50ms, sem cold start. O usuário sempre atinge o ponto mais próximo do planeta, sem configuração manual.

Como o Zuplo funciona por baixo dos panos

O pipeline de uma requisição:

Correspondência de rota: URL/método são casados com o routes.oas.json.
Políticas de entrada: Autenticação, validação, limites de taxa, etc., são executados em ordem. Falha? Resposta é enviada e o pipeline termina.
Handler: Proxy para origem, retorno estático, código TypeScript ou MCP Handler.
Políticas de saída: Transformações finais e remoção de cabeçalhos.
Resposta: Enviada ao cliente; logs e métricas vão para observabilidade (Zuplo ou integrações externas).

Tudo roda em Cloudflare Workers — por isso a latência é baixa e você não paga por capacidade ociosa.

Configurando seu primeiro gateway Zuplo

Monte um gateway funcional em ~30 minutos. Fluxo prático:

Cadastre-se em zuplo.com: Crie projeto e integre ao GitHub.
Importe uma especificação OpenAPI: Se já tiver, importe. Cada operação vira uma rota. Se não, esboce na UI e exporte depois.
Adicione autenticação por chave de API: No editor de rotas, inclua a política api-key-inbound. O Zuplo monta banco de consumidores e UI de chaves automaticamente.
Configure limite de taxa: Insira rate-limit-inbound com orçamento (ex: 100 req/min/chave). Isso é um bloco JSON.
Implante: Faça push para a branch. O Zuplo gera ambiente de preview com URL única. Faça merge para produção.
Teste o gateway: Use Apidog para testar endpoints, chaves válidas/invalidas, limites e payloads. O inspetor visual facilita a validação das políticas.

O setup inicial leva minutos. O maior trabalho é nomear rotas e decidir onde aplicar lógica customizada.

Escrevendo políticas personalizadas em TypeScript

Para necessidades específicas, escreva políticas customizadas. Exemplo: enriquecer a requisição com dados de um serviço interno.

import { ZuploRequest, ZuploContext } from "@zuplo/runtime";

interface UserContext {
  userId: string;
  plan: "free" | "pro" | "enterprise";
}

export default async function (
  request: ZuploRequest,
  context: ZuploContext,
): Promise<ZuploRequest | Response> {
  const apiKey = request.user?.sub;
  if (!apiKey) {
    return new Response("Unauthorized", { status: 401 });
  }

  const lookupUrl = `https://internal.example.com/users/${apiKey}`;
  const userResponse = await fetch(lookupUrl, {
    headers: { authorization: `Bearer ${context.environment.INTERNAL_TOKEN}` },
  });

  if (!userResponse.ok) {
    return new Response("User lookup failed", { status: 502 });
  }

  const user = (await userResponse.json()) as UserContext;
  request.headers.set("x-user-id", user.userId);
  request.headers.set("x-user-plan", user.plan);
  return request;
}

Dicas práticas:

A política é uma função assíncrona testável via unit test.
Variáveis de ambiente vêm de context.environment (tipado, seguro).
Retornar uma Response encerra o pipeline (bom para autenticação ou erros upstream).

Preços do Zuplo em 2026

Três planos objetivos:

Grátis (US$0/mês): 100 mil requisições/mês, ambientes e chaves ilimitadas, 1GB de egresso, 2 devs, todos os 300+ pontos de borda. Tráfego real.
Builder (US$25/mês): Até 1 milhão de requisições, domínios personalizados, egresso ampliado, requisições extras a US$100/100mil.
Enterprise (personalizado, a partir de US$1.000/mês): Requisições/domínios ilimitados, SLA de 99,5% a 99,999%, integrações corporativas, suporte 24/7, SSO, RBAC.

Produtos AI Gateway e Developer Portal têm níveis separados e opção de portal auto-hospedado open source a US$0. Veja detalhes atualizados na página de preços do Zuplo.

Comparando: AWS API Gateway cobra US$3,50/milhão de requisições REST, mais transferência de dados e custos Lambda. Kong Enterprise geralmente é mais caro que o piso do Zuplo. O plano gratuito do Zuplo já é competitivo para projetos novos.

Quando o Zuplo é a escolha certa (e quando não é)

Use Zuplo se:

Quer um gateway gerenciado (sem manter Kong/K8s).
Sua equipe domina TypeScript/JavaScript.
Precisa de portal de desenvolvedores integrado.
Vai monetizar a API com Stripe.
Quer expor API para agentes de IA com MCP sem código extra.
Tem tráfego global e precisa de latência mínima.

Evite Zuplo se:

Precisa de controle total open source (Kong é melhor).
Stack 100% on-premise sem saída internet (Kong/Tyk auto-hospedados).
Precisa mexer nos internos do NGINX.
Já investiu pesado em Apigee/MuleSoft (alto custo de migração).

Testando seu gateway Zuplo com o Apidog

Com o ambiente de preview ativo, teste todas as rotas, políticas e casos de borda antes de promover para produção. Um cliente dedicado é essencial.

Apidog importa sua OpenAPI direto, então a mesma especificação usada nas rotas alimenta sua suíte de testes. Com Apidog, você pode:

Chamar rotas com chaves válidas/invalidas para checar autenticação.
Enviar payloads malformados para conferir rejeição correta.
Simular excesso de chamadas para validar limites de taxa.
Salvar variáveis de ambiente (preview, produção, chaves) e alternar rapidamente.
Gerar exemplos de código (cURL, JS, Python, Go) para sua equipe.

Execute cenários automatizados no Apidog — mais rápido que scripts únicos. Se for a primeira vez, veja a extensão VS Code do Apidog e o guia de migração sem Postman. Baixe o Apidog e teste agora.

Perguntas frequentes sobre o gateway de API Zuplo

O Zuplo é de código aberto?

O runtime do gateway é fechado, mas o portal do desenvolvedor e várias libs de suporte são open source no GitHub. Precisa auto-hospedar? O portal open source + Zuplo em Kubernetes cobre boa parte dos casos.

O Zuplo pode rodar na minha própria infraestrutura?

Sim, no plano Enterprise há opção Kubernetes auto-hospedado. Você perde a borda global e assume operações do cluster. Para requisitos rígidos de residência, é o caminho.

Como o Zuplo se compara ao Cloudflare API Shield?

API Shield é segurança (validação, abuso, mTLS). Zuplo é gestão de API completa: roteamento, políticas, portal, monetização, MCP. Podem coexistir. Se só precisa de segurança, API Shield basta. Para ciclo completo, use Zuplo.

O Zuplo funciona com minha especificação OpenAPI existente?

Sim. A OpenAPI é a fonte central no Zuplo. Importe, as rotas aparecem, o portal é gerado, e as políticas usam os mesmos esquemas.

Posso expor meu gateway Zuplo a agentes de IA como Claude ou Codex?

Sim, via MCP Server Handler. Basta apontar para sua OpenAPI, escolher operações, e o gateway fica disponível para clientes MCP. Políticas de autenticação/limite valem para humanos e agentes.

Quanto tempo leva uma implantação do Zuplo?

Push-to-deploy leva menos de 60 segundos para preview. Promoção para produção é ainda mais rápida (artefato já construído). Não há janela de manutenção.

O que acontece se a Cloudflare cair?

Como roda na borda da Cloudflare, quedas regionais afetam aquela região. O plano Enterprise oferece failover multi-nuvem. A maioria aceita a dependência pelo histórico de confiabilidade.

Conclusão

O Zuplo entrega recursos empresariais sem peso operacional: políticas TypeScript, GitOps, portal de desenvolvedor automático, monetização integrada e suporte MCP para IA. O plano gratuito cobre uso real; o Enterprise cuida do resto.

Avalie: faça o setup de 30 minutos com uma API real, teste cada política no Apidog e decida com base em evidências técnicas. A combinação de gateway gerenciado e cliente de testes robusto é o caminho mais rápido de "temos uma API" para "temos um produto". Baixe o Apidog e comece a testar.

Como Usar DeepSeek V4 Grátis: Guia Completo

Lucas — Fri, 24 Apr 2026 04:48:54 +0000

DeepSeek V4 foi lançado em 23 de abril de 2026 e, ao contrário da maioria dos lançamentos de ponta, os caminhos gratuitos são reais. O chat web oficial executa o V4-Pro sem necessidade de cartão de crédito. Os pesos são licenciados pelo MIT e estão disponíveis para download hoje. Agregadores como OpenRouter e Chutes geralmente expõem camadas gratuitas poucos dias após um lançamento do DeepSeek. Somando tudo, você pode executar cargas de trabalho sérias do V4 a custo zero antes mesmo de decidir se deseja recarregar uma conta.

Experimente o Apidog hoje

Este guia detalha todos os caminhos sem custo que podemos verificar, qual se adapta a cada caso de uso e como configurar uma coleção pronta para produção no Apidog para que a transição para a cobrança paga seja suave quando o uso aumentar.

Para uma visão geral do produto, consulte o que é DeepSeek V4. Para o guia completo da API, confira como usar a API do DeepSeek V4.

TL;DR

chat.deepseek.com — chat web gratuito no V4-Pro com alternadores Think High e Think Max. Sem cartão. Funciona hoje.
Pesos do Hugging Face + sua própria GPU — Licença MIT, V4-Flash roda em 2 a 4 H100s, V4-Pro precisa de um cluster.
Camadas gratuitas do OpenRouter e Chutes — gateways de terceiros que geralmente abrem cota gratuita em modelos DeepSeek dentro de uma semana após o lançamento.
Provedores de Inferência Hugging Face — um endpoint compartilhado e com limite de taxa que expõe o V4 para experimentação inicial.
Créditos de teste do Kaggle, Colab e RunPod — computação gratuita para execuções únicas quando você quiser testar a auto-hospedagem.
Todo caminho gratuito limita o uso. Para cargas de trabalho de produção, passe para a cobrança paga antes que o limite seja atingido.

Caminho 1: chat.deepseek.com (o caminho gratuito padrão)

O caminho gratuito mais rápido e confiável é a interface de chat oficial. O V4-Pro é o modelo padrão; o botão na parte superior do compositor alterna entre os modos de raciocínio Non-Think, Think High e Think Max.

Configuração

Abra chat.deepseek.com.
Faça login com e-mail, Google ou WeChat.
Confirme que o modelo ativo é V4-Pro.
Comece a digitar.

O que você obtém

Janela de contexto completa de 1M tokens.
Upload de arquivos para PDFs, imagens e pacotes de código.
Pesquisa web sob demanda.
Todos os três modos de raciocínio, incluindo Think Max.
Histórico de conversas e pastas.

Como são os limites

O DeepSeek não publica um limite rígido de mensagens por dia; o nível gratuito é suavizado sob carga. O uso intenso pode atrasar respostas ou enfileirar solicitações, mas raramente bloqueia totalmente. Caso veja limites de taxa persistentes, diminua a cadência ou mude para a API.

Bons usos: comparar V4 com Claude em prompts difíceis, revisão arquitetônica colando um tarball, rodar Think Max em um contrato complexo.

Maus usos: automação, tarefas que precisam ser reproduzidas.

Caminho 2: Auto-hospede o V4-Flash na sua própria GPU

O V4-Flash é a variante licenciada pelo MIT que você pode auto-hospedar. Com 284B no total e 13B ativos, uma multi-H100 roda em FP8; quantização INT4 permite executar em uma única placa de 80GB.

O custo aqui é hardware, não licença. Se já possui GPU, é o caminho gratuito mais durável.

Baixe os pesos

pip install -U "huggingface_hub[cli]"
huggingface-cli login
huggingface-cli download deepseek-ai/DeepSeek-V4-Flash \
  --local-dir ./models/deepseek-v4-flash

Aproximadamente 500GB em FP8 – reserve espaço em disco.

Sirva com vLLM

pip install "vllm>=0.9.0"

vllm serve deepseek-ai/DeepSeek-V4-Flash \
  --tensor-parallel-size 4 \
  --max-model-len 1048576 \
  --dtype auto \
  --port 8000

Com o serviço ativo, aponte qualquer cliente compatível com OpenAI para http://localhost:8000/v1. O endpoint aceita o mesmo formato da API paga do DeepSeek; o Apidog trata como outra URL base, e todas suas coleções salvas funcionam sem alterações.

Verificação da realidade do hardware

Variante	Placas mínimas (FP8)	Placas mínimas (INT4)	Taxa de transferência realista
V4-Flash	2 × H100 80GB	1 × H100 80GB	50 a 150 tok/s
V4-Pro	16 × H100 80GB	8 × H100 80GB	dependente do cluster

Se não tem placas ociosas, geralmente vale mais a pena usar a API do que alugar GPUs. Auto-hospedagem serve melhor equipes com hardware próprio ou requisitos regulatórios.

Caminho 3: Nível gratuito do OpenRouter

OpenRouter é um gateway que agrega modelos abertos e fechados via uma única API. Normalmente libera nível gratuito em lançamentos DeepSeek; padrão válido desde V3.

Configuração

Cadastre-se em openrouter.ai.
Gere uma chave de API.
No catálogo de modelos, busque deepseek/deepseek-v4-pro ou deepseek/deepseek-v4-flash. Variantes gratuitas costumam vir com :free.
Consuma via SDK compatível com OpenAI.

from openai import OpenAI

client = OpenAI(
    api_key=OPENROUTER_KEY,
    base_url="https://openrouter.ai/api/v1",
)

response = client.chat.completions.create(
    model="deepseek/deepseek-v4-flash:free",
    messages=[{"role": "user", "content": "Escreva uma CLI Python para aumento de versão semver."}],
)

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

Limites

Em geral, algumas centenas de solicitações por dia por chave, com prioridade reduzida sob carga. Ótimo para prototipar, não para produção.

Caminho 4: Provedores de Inferência Hugging Face

Hugging Face oferece inferência hospedada dos checkpoints V4 logo após o lançamento. Limites de taxa são rigorosos e latência pode variar, mas é gratuito.

from huggingface_hub import InferenceClient

client = InferenceClient(model="deepseek-ai/DeepSeek-V4-Flash")

response = client.chat_completion(
    messages=[{"role": "user", "content": "Resuma o relatório técnico do V4 em 5 pontos."}],
    max_tokens=512,
)

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

O token HF é gratuito. Para cargas mais intensas, contas Pro oferecem limites mais flexíveis, ainda muito abaixo do custo da API oficial.

Caminho 5: Créditos de teste no Colab, Kaggle, RunPod e Lambda

Provedores de GPU oferecem créditos de teste que permitem experimentos pontuais com V4-Flash sem custo real.

Google Colab. Nível gratuito T4 é pequeno para V4. Colab Pro+ oferece 500 unidades/mês, suficiente para alguns testes com V4-Flash em A100.
Kaggle. Oferece horas semanais gratuitas em T4 e P100; suficiente apenas para experimentos pequenos.
RunPod. US$ 10 de crédito cobre algumas horas em H100 – suficiente para rodar benchmarks e desligar.
Lambda. Ofertas promocionais de horas grátis em H100/H200 – confira sempre a página de cadastro.

São caminhos para experimentos curtos, não uso contínuo.

Crie uma coleção Apidog agnóstica de provedor

A vantagem dos caminhos gratuitos é testar o mesmo prompt em todos, sem retrabalho. Siga este fluxo:

Baixe o Apidog.
Crie uma coleção com quatro ambientes: chat (placeholder), deepseek (https://api.deepseek.com/v1), openrouter (https://openrouter.ai/api/v1), self-hosted (http://localhost:8000/v1).
Salve uma requisição POST para {{BASE_URL}}/chat/completions.
Guarde a chave de cada provedor como variável secreta; o corpo da requisição fica idêntico em todos os ambientes.
Alterne entre ambientes para testar o mesmo prompt em cada backend.

Esse padrão é o mesmo da coleção gratuita do GPT-5.5: uma ferramenta, vários provedores, sem duplicação de trabalho.

Qual caminho gratuito escolher?

Siga estas heurísticas para decidir:

Quero formar uma opinião em cinco minutos: use chat.deepseek.com.
Quero prototipar um produto: use o nível gratuito do OpenRouter até atingir o limite, então recarregue no DeepSeek.
Tenho GPUs e histórico de conformidade: auto-hospede o V4-Flash no vLLM.
Preciso de uso gratuito a longo prazo: não existe. Combine chat.deepseek.com para uso interativo com recarga paga para automação.

Quando sair do nível gratuito

Troque para o pago quando:

Limite de taxa diário recorrente: sua carga já justifica orçamento.
Precisa de SLA: só disponível na API oficial.
Exige logging, auditoria ou compliance: só a API paga garante registros claros.

Quando chegar nesses pontos, migre para a API oficial. Mínimo de recarga: US$ 2, preço por token mais baixo da categoria.

FAQ

O chat.deepseek.com é realmente gratuito?

Sim. Sem cartão, sem tempo de teste. O serviço é suavizado, mas sem paywall.
Preciso de conta Hugging Face para baixar pesos?

Tecnicamente não, mas na prática sim — logado, você tem limites de taxa melhores.
Qual caminho gratuito roda o V4-Pro real?

chat.deepseek.com executa o V4-Pro completo. OpenRouter costuma liberar V4-Flash. Precisa do V4-Pro sem pagar? Use o chat web.
Posso colocar um nível gratuito por trás de um produto?

Não de forma responsável. Limites de taxa mudam e podem sumir. Para entregar V4 a clientes, use API paga ou auto-hospede.
Auto-hospedagem é realmente gratuita?

Licença sim, hardware não. Se já possui GPU, custo marginal é eletricidade. Alugando, normalmente sai mais caro que API.
Haverá nível gratuito Apidog para testes?

O Apidog é gratuito para design e teste de API; só cobra créditos ao acessar APIs pagas. Então, sim: você pode ter workspace Apidog gratuito combinando com chat.deepseek.com ou OpenRouter para fluxo 100% gratuito.

Como Executar o DeepSeek V4 Localmente?

Lucas — Fri, 24 Apr 2026 04:35:43 +0000

O DeepSeek V4 foi lançado em 23 de abril de 2026 com pesos licenciados pelo MIT no Hugging Face. Essa escolha de licença facilita para equipes que querem IA de ponta rodando em hardware próprio. O V4-Flash (284B total, 13B ativo) roda em dois H100s em FP8; o V4-Pro (1.6T total, 49B ativo) exige um cluster, mas compete com GPT-5.5 e Claude Opus 4.6 em tarefas de código e raciocínio.

Experimente o Apidog hoje

Este guia é um passo a passo para implantação local: requisitos de hardware, quantização, configurações de vLLM e SGLang, uso de ferramentas, e como validar seu servidor local usando o Apidog antes de redirecionar tráfego de produção.

Para uma visão geral do produto, veja o que é DeepSeek V4. Para integração via API hospedada, confira como usar a API DeepSeek V4. Para custos, veja preços da API DeepSeek V4.

TL;DR

V4-Flash roda em 2 × H100 80GB em FP8, ou 1 × H100 em INT4 (~500GB de pesos em FP8).
V4-Pro precisa de 16+ H100s em FP8 para produção; não recomendado para laptops.
vLLM é o caminho mais rápido para um servidor compatível com OpenAI (vllm>=0.9.0 já suporta o V4).
SGLang é a alternativa para equipes que focam em ferramentas e saída estruturada.
Quantização para AWQ INT4 ou GPTQ INT4 permite rodar o V4-Flash em uma única GPU de 80GB com ~5% de perda de qualidade.
Use o Apidog para testar seu endpoint local em http://localhost:8000/v1 usando a mesma coleção da API hospedada.

Quem deve hospedar por conta própria

Hospede o V4 localmente se sua equipe:

Precisa de conformidade: setores como saúde, finanças, jurídico ou defesa, onde dados não podem sair da rede. Licença MIT → sem acordos extras ou transferência internacional de dados.
Tem grandes cargas de trabalho estáveis: Acima de 200 bilhões de tokens/mês, hardware próprio compensa.
Precisa de ajuste fino e pesquisa: Checkpoints Base servem para pré-treinamento contínuo e adaptação de domínio. MIT permite redistribuição comercial.

Quem não deve hospedar: prototipadores, equipes sem experiência em operações de GPU, ou workloads abaixo de US$ 200/mês em API hospedada.

Requisitos de hardware

O DeepSeek V4 usa precisão mista FP4 + FP8. Isso reduz o uso de memória real comparado ao número bruto de parâmetros.

Variante	Total de parâmetros	Parâmetros ativos	VRAM FP8	VRAM INT4	Placas mínimas
V4-Flash	284B	13B	~500GB	~140GB	2 × H100 80GB (FP8) ou 1 × H100 (INT4)
V4-Pro	1.6T	49B	~2.4TB	~700GB	16 × H100 80GB (FP8) ou 8 × H100 (INT4)

Notas:

Memória MoE é o total, não apenas ativa.
H200 e MI300X são mais eficientes (mais VRAM/placa).
GPUs de consumidor não servem (nem RTX 5090).
Apple Silicon (M3/M4 Max) roda com quantização pesada, mas apenas para desenvolvimento/testes.

Etapa 1: Baixar os pesos

Repositórios oficiais:

deepseek-ai/DeepSeek-V4-Flash
deepseek-ai/DeepSeek-V4-Pro
deepseek-ai/DeepSeek-V4-Flash-Base e DeepSeek-V4-Pro-Base para ajuste fino.

Instale o CLI e baixe os pesos:

pip install -U "huggingface_hub[cli]"
huggingface-cli login

huggingface-cli download deepseek-ai/DeepSeek-V4-Flash \
  --local-dir ./models/deepseek-v4-flash \
  --local-dir-use-symlinks False

Reserve ~500GB para o V4-Flash, vários TBs para o V4-Pro. Usuários na China: modelscope.cn é mais rápido.

Etapa 2: Escolha um mecanismo de serviço

vLLM: melhor taxa de transferência, interface compatível com OpenAI, comunidade maior. Recomendado.
SGLang: melhores recursos para ferramentas e saída estruturada; útil se depende de chamadas de funções.

Ambos já suportam DeepSeek V4.

Etapa 3: Sirva V4-Flash com vLLM

pip install "vllm>=0.9.0"

vllm serve deepseek-ai/DeepSeek-V4-Flash \
  --tensor-parallel-size 2 \
  --max-model-len 1048576 \
  --dtype auto \
  --enable-prefix-caching \
  --port 8000

Sinalizadores úteis:

--tensor-parallel-size 2: divide entre 2 H100s.
--max-model-len 1048576: ativa contexto de 1M tokens; reduza para liberar VRAM.
--enable-prefix-caching: ativa cache de prefixo, acelerando prompts repetidos.
--dtype auto: usa FP8 automaticamente.

Clientes OpenAI funcionam em http://localhost:8000/v1.

Etapa 4: Sirva V4-Pro com vLLM

V4-Pro exige cluster; ajuste os parâmetros de paralelismo:

vllm serve deepseek-ai/DeepSeek-V4-Pro \
  --tensor-parallel-size 8 \
  --pipeline-parallel-size 2 \
  --max-model-len 524288 \
  --enable-prefix-caching \
  --port 8000

Ajuste --max-model-len conforme a VRAM disponível.

Etapa 5: Sirva com SGLang (alternativa para uso de ferramentas)

pip install "sglang[all]>=0.4.0"

python -m sglang.launch_server \
  --model-path deepseek-ai/DeepSeek-V4-Flash \
  --tp 2 \
  --context-length 1048576 \
  --port 30000

SGLang expõe /v1 compatível com OpenAI em http://localhost:30000/v1. O DSL lang facilita chamadas de função e saída JSON.

Etapa 6: Quantize para uma GPU única

Quantização INT4 permite rodar o V4-Flash em uma H100 de 80GB com perda mínima de qualidade.

AWQ (recomendado)

pip install autoawq

python -c "
from awq import AutoAWQForCausalLM
from transformers import AutoTokenizer

model_path = './models/deepseek-v4-flash'
out_path = './models/deepseek-v4-flash-awq'
model = AutoAWQForCausalLM.from_pretrained(model_path)
tokenizer = AutoTokenizer.from_pretrained(model_path)
model.quantize(tokenizer, quant_config={'w_bit': 4, 'q_group_size': 128})
model.save_quantized(out_path)
tokenizer.save_pretrained(out_path)
"

GPTQ

pip install auto-gptq
# Siga a receita de quantização GPTQ; processo semelhante ao AWQ.

Sirva o checkpoint quantizado com vLLM usando --quantization awq ou --quantization gptq.

Etapa 7: Teste com Apidog

Não envie produção direto para o novo servidor. Valide antes.

Baixe o Apidog.
Crie uma coleção apontando para http://localhost:8000/v1/chat/completions.
Use o mesmo prompt de teste que na API hospedada e compare as respostas.
Faça teste com contexto de 500K tokens para validar o cache KV.
Execute um fluxo de chamada de ferramentas antes de conectar automações.

A coleção usada na API hospedada DeepSeek V4 funciona localmente mudando só o URL base.

Observabilidade e monitoramento

Monitore estas métricas desde o início:

Tokens por segundo (prompt e geração) — vLLM expõe em /metrics formato Prometheus.
Utilização da GPU — nvidia-smi ou DCGM; taxa <70% indica batch size subótimo.
Taxa de acerto do cache KV — vLLM mostra; queda sinaliza prompts não otimizados.
Latência p50/p95/p99 — rastreamento padrão; p99 alto com p50 estável indica requisições problemáticas.

Envie todas para Grafana ou sua stack de observabilidade.

Ajuste fino dos checkpoints Base do V4

Checkpoints Base servem para pré-treinamento contínuo e SFT (fine-tuning supervisionado):

pip install "torch>=2.6" transformers accelerate peft trl

# SFT padrão com LoRA no V4-Flash-Base
python -m trl sft \
  --model_name_or_path deepseek-ai/DeepSeek-V4-Flash-Base \
  --dataset_name your-org/your-sft-set \
  --output_dir ./models/v4-flash-custom \
  --per_device_train_batch_size 1 \
  --gradient_accumulation_steps 16 \
  --learning_rate 2e-5 \
  --bf16 true \
  --use_peft true \
  --lora_r 64 \
  --lora_alpha 128

Full fine-tuning no V4-Pro é tarefa de pesquisa. LoRA adapters no V4-Flash-Base são o caminho prático para a maioria.

Armadilhas comuns

OOM (Out Of Memory) na inicialização: contexto alto demais ou paralelismo baixo. Diminua --max-model-len ou aumente --tensor-parallel-size.
Primeira requisição lenta: vLLM compila kernels sob demanda; aqueça com request dummy.
Erros de parsing em uso de ferramentas: DeepSeek difere levemente do OpenAI; use SDKs com suporte explícito ao V4.
Erros FP8 em GPUs antigas: A100 não suporta FP8. Use BF16 e espere dobrar a necessidade de VRAM.

Quando a hospedagem própria compensa

Cálculo de breakeven, usando os preços da API DeepSeek V4:

V4-Flash com 200B tokens in / 20B out/mês: ~$33,6K pela API. Uma máquina com 8 × H100 custa ~$20K/mês. Economia de ~40%.
V4-Pro com 500B in / 50B out/mês: ~$1,04M na API. Cluster de 16 × H100 sai por ~$35K/mês. Economia >95%.

O ponto crítico para V4-Flash é em ~100B tokens/mês. Abaixo disso, a API hospedada é mais barata.

FAQ

Posso executar V4-Flash em uma A100?

Com quantização pesada e contexto reduzido, sim, mas é lento (5-15 tok/s). H100 é o hardware ideal.

O V4 suporta fine-tuning com LoRA?

Sim. Use checkpoints Base e pipelines TRL ou Axolotl. MoE não afeta o LoRA.

O servidor local é compatível com OpenAI?

Sim. vLLM e SGLang expõem /v1/chat/completions e /v1/completions. O guia da API hospedada funciona com localhost.

Como habilito modo de pensamento ("thinking mode")?

Inclua thinking_mode: "thinking" ou "thinking_max" na requisição. vLLM e SGLang encaminham ao modelo.

Consigo fazer streaming do servidor V4 local?

Sim. Use stream: true igual ao OpenAI ou API DeepSeek.

Forma mais barata de testar antes de comprar hardware?

Alugue uma H100 no RunPod ou Lambda, rode V4-Flash em INT4 e meça throughput real. Teste de $10–$30 resolve rápido.

Como Usar a API DeepSeek V4 Gratuitamente?

Lucas — Fri, 24 Apr 2026 04:23:57 +0000

O DeepSeek V4 foi lançado em 23 de abril de 2026, trazendo uma API com preço tão baixo que muitas equipes ignoram camadas gratuitas. Porém, existe um caminho realmente gratuito para desenvolvedores que querem integrar o V4 programaticamente antes de adicionar um cartão. Gateways agregadores oferecem variantes :free, o Hugging Face tem endpoint aberto, e a API oficial concede crédito de teste para novas contas. Neste artigo, você verá como combinar os três em uma cadeia de fallback no Apidog para prototipar produtos baseados em V4 sem gastar nada.

Experimente o Apidog hoje

Este guia mostra o caminho gratuito para a API. Para um tutorial mais amplo cobrindo chat web e auto-hospedagem, acesse como usar o DeepSeek V4 gratuitamente. Se quiser um passo a passo pago, veja como usar a API DeepSeek V4. Para visão geral do produto, confira o que é DeepSeek V4.

EM RESUMO

Camada gratuita do OpenRouter — deepseek/deepseek-v4-flash:free e, às vezes, deepseek-v4-pro:free. Compatível com OpenAI, centenas de requisições/dia por chave.
Provedores de Inferência Hugging Face — endpoint gratuito em https://router.huggingface.co/hf-inference; limitado por taxa, útil para protótipos.
Camada gratuita do Chutes — rede de GPU comunitária que geralmente libera endpoints DeepSeek gratuitos logo após o lançamento.
Crédito de teste do DeepSeek — novas contas em platform.deepseek.com podem receber saldo inicial.
O V4-Flash auto-hospedado em GPU própria é gratuito na licença; veja como rodar o DeepSeek V4 localmente.
Monte uma cadeia de fallback no Apidog para manter o formato da requisição idêntico em todos os provedores.

Por que o caminho gratuito da API existe

Mesmo com as taxas pagas do DeepSeek sendo baixíssimas, há motivos práticos para buscar opções gratuitas:

Prototipagem antes de cadastrar cartão: Teste integrações reais sem precisar de pagamento.
Projetos acadêmicos, pesquisa e open source: Permite acesso a tecnologia de ponta mesmo sem orçamento.
Comparação de provedores: Execute o mesmo prompt em três endpoints gratuitos, avaliando latência, qualidade e confiabilidade.

Se você está nesse perfil, siga o passo a passo abaixo. Caso precise de uso contínuo e SLAs, considere a API paga — a recarga mínima de US$2 na API oficial é mais prática do que lutar contra limites gratuitos.

Caminho 1: Camada gratuita do OpenRouter

O OpenRouter agrega modelos de ponta com API compatível OpenAI. Em todos os lançamentos DeepSeek, libera variantes gratuitas.

Configuração

Cadastre-se em openrouter.ai.
Crie sua chave API em Configurações → Chaves.
Cheque o catálogo de modelos por entradas com :free (ex: deepseek/deepseek-v4-flash:free).
Chame o endpoint com qualquer SDK compatível com OpenAI.

from openai import OpenAI

client = OpenAI(
    api_key=OPENROUTER_API_KEY,
    base_url="https://openrouter.ai/api/v1",
)

response = client.chat.completions.create(
    model="deepseek/deepseek-v4-flash:free",
    messages=[{"role": "user", "content": "Refactor this Go function to use channels."}],
)

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

Como são os limites

Requisições gratuitas entram na fila atrás do tráfego pago. Limite típico: 50–200 requisições/dia/chave, concorrência baixa. A variante pode ser removida a qualquer momento — use só para prototipagem.

Versão Node

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.OPENROUTER_API_KEY,
  baseURL: "https://openrouter.ai/api/v1",
});

const response = await client.chat.completions.create({
  model: "deepseek/deepseek-v4-flash:free",
  messages: [{ role: "user", content: "Explain MoE routing like I'm 12." }],
});

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

Caminho 2: Provedores de Inferência Hugging Face

O Hugging Face disponibiliza endpoint de inferência compartilhado com checkpoints V4 após o lançamento. É só usar o token HF logado — os limites são rigorosos para uso gratuito.

import os
from huggingface_hub import InferenceClient

client = InferenceClient(
    model="deepseek-ai/DeepSeek-V4-Flash",
    token=os.environ["HF_TOKEN"],
)

response = client.chat_completion(
    messages=[
        {"role": "user", "content": "Write a Python decorator that retries with jitter."}
    ],
    max_tokens=512,
)

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

Token gratuito em huggingface.co/settings/tokens. Latência varia conforme carga, e o limite é diário por conta. Para limites maiores, só com HF Pro.

Caminho 3: Chutes e gateways da comunidade

Chutes é uma rede descentralizada de GPU que frequentemente libera modelos DeepSeek gratuitos. O endpoint compatível OpenAI é https://llm.chutes.ai/v1:

client = OpenAI(
    api_key=CHUTES_API_KEY,
    base_url="https://llm.chutes.ai/v1",
)

response = client.chat.completions.create(
    model="deepseek-ai/DeepSeek-V4-Flash",
    messages=[{"role": "user", "content": "Compare CSA and HCA attention in two sentences."}],
)

Disponibilidade muda rápido — sempre confira ID do modelo e custo no painel do provedor antes de depender dele.

Caminho 4: Crédito de teste do DeepSeek

Novas contas DeepSeek frequentemente recebem pequeno crédito inicial (ex: US$1), válido após verificação de e-mail. Cheque seu painel em platform.deepseek.com após o cadastro.

US$1 cobre cerca de 7 milhões de tokens no V4-Flash ou 570 mil no V4-Pro — suficiente para centenas de chamadas de protótipo.

Construa uma cadeia gratuita agnóstica de provedores no Apidog

Ao integrar múltiplos caminhos gratuitos, seu protótipo se torna resiliente. Siga:

Baixe o Apidog e crie um projeto.
Crie quatro ambientes: openrouter, huggingface, chutes, deepseek-trial.
Em cada ambiente, armazene a chave de API como variável secreta e defina BASE_URL.
Salve uma requisição POST para {{BASE_URL}}/chat/completions com campo model parametrizado.
Alterne o ambiente para rodar o mesmo prompt em todos os provedores sem mexer no código.

Essa abordagem também serve para caminhos gratuitos do GPT-5.5: só troque os provedores.

Monte uma cadeia de fallback no código

Implemente fallback automático para garantir resposta mesmo com limites atingidos:

import os
from openai import OpenAI, RateLimitError, APIError

PROVIDERS = [
    {
        "base_url": "https://openrouter.ai/api/v1",
        "api_key": os.environ["OPENROUTER_API_KEY"],
        "model": "deepseek/deepseek-v4-flash:free",
    },
    {
        "base_url": "https://llm.chutes.ai/v1",
        "api_key": os.environ["CHUTES_API_KEY"],
        "model": "deepseek-ai/DeepSeek-V4-Flash",
    },
    {
        "base_url": "https://api.deepseek.com/v1",
        "api_key": os.environ["DEEPSEEK_API_KEY"],
        "model": "deepseek-v4-flash",
    },
]

def call_v4(messages):
    for provider in PROVIDERS:
        try:
            client = OpenAI(
                api_key=provider["api_key"],
                base_url=provider["base_url"],
            )
            return client.chat.completions.create(
                model=provider["model"],
                messages=messages,
            )
        except (RateLimitError, APIError) as e:
            print(f"{provider['base_url']} failed: {e}")
            continue
    raise RuntimeError("all providers exhausted")

Para que cada caminho gratuito realmente serve

Caminho	Melhor para	Pior para
OpenRouter gratuito	Prototipagem, desenvolvimento diário	Qualquer coisa com SLAs rigorosos
Inferência HF	Chamadas exploratórias, notebooks	Cargas de trabalho de baixa latência
Chutes	Trabalho experimental da comunidade	Dependências de longo prazo
Teste DeepSeek	Testes de fidelidade total	Produção contínua
V4-Flash auto-hospedado	Trabalho vinculado à conformidade	Equipes sem capacidade de GPU

Matemática de cota que importa

Antes de decidir, avalie quanto cada caminho gratuito entrega:

OpenRouter gratuito: ~100 requisições/dia/chave, ~50K tokens cada. Útil para 30–50 chamadas reais/dia.
Inferência HF gratuita: ~1.000 requisições/dia por conta. Latência pode ser alta.
Chutes: variável; trate como "best effort".
Teste DeepSeek (US$1): ~700 chamadas de 10K tokens cada no V4-Flash.
V4-Flash auto-hospedado: limitado ao seu hardware. Uma máquina 4 × H100 faz 50–150 tok/s.

Se precisar de mais, a economia muda. Com V4-Flash a US$ 0,14/M, 10.000 chamadas com 2K contexto + 500 tokens de saída custam só US$2,80. Após o protótipo, a API paga geralmente é melhor.

Quando mudar para a API paga

Pare de usar apenas camadas gratuitas quando:

Você atinge limites de taxa mais de uma vez por dia;
Precisa encadear vários provedores só para atender uma carga básica;
Exige latência previsível ou SLA.

A recarga mínima em platform.deepseek.com é US$2. Um dia inteiro em camadas gratuitas pode custar mais tempo de dev do que a API paga. Veja guia de preços DeepSeek V4 para detalhes.

PERGUNTAS FREQUENTES

Algum desses caminhos é permanentemente gratuito? Não. As camadas gratuitas mudam sem aviso. Use só para prototipagem.

O OpenRouter :free executa o V4 real? Sim, mas em infraestrutura compartilhada e com taxa limitada.

Posso usar saída de caminho gratuito em produto lançado? Veja os termos de cada provedor. OpenRouter permite uso comercial dentro do limite. HF permite, mas limita. O crédito de teste do próprio DeepSeek segue os termos principais.

Qual caminho gratuito tem melhor latência? O crédito de teste DeepSeek (infraestrutura de produção). OpenRouter é o segundo. HF e Chutes variam.

Posso auto-hospedar o V4 gratuitamente? Sim, a licença é MIT. Só o hardware é custo. Veja como rodar o DeepSeek V4 localmente.

Como rastrear consumo dos caminhos gratuitos? Use Apidog e fixe usage no visualizador de respostas. A maioria dos gateways tem painel de uso no console.

Preços da API DeepSeek V4

Lucas — Fri, 24 Apr 2026 04:22:49 +0000

DeepSeek publicou os preços do V4 no mesmo dia em que os modelos foram lançados, 23 de abril de 2026, redefinindo o patamar para IA de ponta. O V4-Flash opera a $0.14 por milhão de tokens de entrada e $0.28 por milhão de tokens de saída, enquanto o V4-Pro opera a $1.74 de entrada e $3.48 de saída. Ambos oferecem uma janela de contexto de 1M de tokens e até 384K tokens de saída, além de desconto agressivo por acerto de cache que reduz os custos de entrada em 80% a 90% em prompts repetidos.

Experimente o Apidog hoje

Este guia mostra a tabela completa de preços, como o cache de contexto altera o custo real por chamada, comparação com GPT-5.5 e Claude Opus, e quatro práticas para manter os gastos previsíveis usando o Apidog.

Para visão geral do produto, veja o que é DeepSeek V4. Para guia do desenvolvedor, veja como usar a API DeepSeek V4. Para caminhos gratuitos, veja como usar o DeepSeek V4 gratuitamente.

Resumo

V4-Flash: $0.14 / M de entrada (cache miss), $0.028 / M de entrada (cache hit), $0.28 / M de saída.
V4-Pro: $1.74 / M de entrada (cache miss), $0.145 / M de entrada (cache hit), $3.48 / M de saída.
Janela de contexto: 1M de tokens de entrada, 384K de tokens de saída.
Desconto por acerto de cache: aproximadamente 80% de desconto no Flash, 92% de desconto no Pro em prefixos repetidos.
deepseek-chat e deepseek-reasoner serão descontinuados em 24 de julho de 2026; cobrança mapeia para V4-Flash.
Com taxas de cache miss, o V4-Pro é ~2.9x mais barato que o GPT-5.5 na entrada e ~8.6x mais barato na saída.

A tabela de preços completa

Modelo	Entrada (cache miss)	Entrada (cache hit)	Saída	Contexto
`deepseek-v4-flash`	$0.14 / M	$0.028 / M	$0.28 / M	1M / 384K
`deepseek-v4-pro`	$1.74 / M	$0.145 / M	$3.48 / M	1M / 384K
`deepseek-chat` (descontinuado em 24/07/2026)	mapeia para V4-Flash sem raciocínio	—	—	—
`deepseek-reasoner` (descontinuado em 24/07/2026)	mapeia para V4-Flash com raciocínio	—	—	—

Três pontos práticos sobre a precificação:

Os preços são iguais, independentemente do uso de raciocínio. O ID do modelo define a taxa; o modo de raciocínio só altera o volume de tokens.
O desconto por acerto de cache é automático: qualquer chamada com prefixo repetido (mínimo 1.024 tokens, byte a byte) na mesma conta já obtém o desconto, sem necessidade de configuração.
Os IDs antigos deepseek-chat e deepseek-reasoner agora são aliases do V4-Flash. Se você não migrou, já está usando V4-Flash com os mesmos preços.

Cache de contexto na prática

O cache é a principal ferramenta para redução de custo no DeepSeek V4. Qualquer trecho repetido entre chamadas (prompts de sistema, esquemas de ferramentas, contexto RAG) paga só uma fração do valor nas execuções seguintes.

Exemplo prático:

Prompt de sistema fixo: 20.000 tokens
100 perguntas de usuário (200 tokens cada)

Sem cache:

Entrada: 100 × 20.200 × $1.74 / M = $3.52
Saída: 100 × 500 × $3.48 / M = $0.17
Total: $3.69

Com cache (após a primeira chamada):

Entrada da primeira chamada: 20.200 × $1.74 / M = $0.035
Próximos 99 prefixos com cache hit: 99 × 20.000 × $0.145 / M = $0.287
Turnos de usuário (cache miss): 99 × 200 × $1.74 / M = $0.034
Saída: 100 × 500 × $3.48 / M = $0.174
Total: $0.53

Ganho: 7x mais barato. No V4-Flash, o efeito é ainda mais expressivo.

Comparação com GPT-5.5 e Claude

A tabela abaixo facilita a comparação direta:

Modelo	Entrada (padrão)	Entrada (em cache)	Saída	Contexto
DeepSeek V4-Flash	$0.14 / M	$0.028 / M	$0.28 / M	1M
DeepSeek V4-Pro	$1.74 / M	$0.145 / M	$3.48 / M	1M
GPT-5.5	$5 / M	$1.25 / M	$30 / M	1M
GPT-5.5 Pro	$30 / M	—	$180 / M	1M
Claude Opus 4.6	$15 / M	$1.50 / M	$75 / M	200K

Destaques práticos:

V4-Pro é ~8.6x mais barato que GPT-5.5 em tokens de saída e 21x mais barato que Claude Opus 4.6.
Em entrada cacheada, V4-Pro é ~10x mais barato que GPT-5.5/Claude para prompts longos e contextos repetidos.
Performance: V4-Pro alcança ou supera GPT-5.5 em benchmarks de código (LiveCodeBench e Codeforces), custando uma fração do preço.
- Veja benchmarks completos.

Atenção: Claude ainda vence em recuperação de contexto longo e Gemini 3.1 Pro lidera o MMLU-Pro. Se sua aplicação depende de recuperação avançada em contexto extenso, teste antes de migrar.

Modelagem de custos para workloads comuns

Quatro padrões cobrem a maioria dos casos de uso. Veja o cálculo prático no V4-Pro (sem cache):

1. Loop de codificação de agente (50K contexto, 2K saída, 20 execuções)

Entrada: 50.000 × 20 × $1.74 / M = $1.74
Saída: 2.000 × 20 × $3.48 / M = $0.14
Custo por tarefa: ~$1.88

No GPT-5.5: ~$6.20 por tarefa.

2. Perguntas e Respostas em documentos longos (500K contexto, 1K saída)

Entrada: 500.000 × $1.74 / M = $0.87
Saída: 1.000 × $3.48 / M = $0.003
Custo por chamada: ~$0.87

No GPT-5.5: ~$2.53 por chamada.

3. Classificação de alto volume (2K contexto, 200 saída, 10.000 execuções)

Use V4-Flash para este caso.

Entrada: 2.000 × 10.000 × $0.14 / M = $2.80
Saída: 200 × 10.000 × $0.28 / M = $0.56
Custo total: ~$3.36

No GPT-5.5: ~$110.

4. Chatbot com prompt repetido (10K prompt, 500 tokens usuário, 1K saída, 1.000 sessões)

Entrada da primeira chamada: 10.500 × $1.74 / M = $0.018
Entrada com cache: 999 × 10.000 × $0.145 / M = $1.45
Usuário (cache miss): 999 × 500 × $1.74 / M = $0.87
Saída: 1.000 × 1.000 × $3.48 / M = $3.48
Custo total: ~$5.82

No GPT-5.5 com cache: ~$26.35.

Custos ocultos: o que monitorar

Após o primeiro mês, quatro fatores impactam o orçamento:

Inflação de tokens em raciocínio: thinking_max pode consumir de 3x a 10x mais tokens de saída. Controle via flag.
Crescimento silencioso do contexto: Loops de agente realimentam toda a conversa. Trunque ou resuma agressivamente.
Tempestades de retry: Bugs podem dobrar custos rapidamente. Implemente backoff exponencial e limite de tentativas.
Rotatividade de desenvolvimento: Testar prompts via curl reenvia todo o contexto. Com Apidog, variáveis e reexecuções são gratuitas.

Como monitorar custos no Apidog

Fluxo de trabalho recomendado:

Baixe o Apidog e armazene DEEPSEEK_API_KEY como variável secreta.
Salve uma requisição POST para https://api.deepseek.com/v1/chat/completions.
No painel de resposta, fixe usage.prompt_tokens, usage.completion_tokens e usage.reasoning_tokens. Veja o custo direto em cada chamada.
Parametrize model e thinking_mode para comparar V4-Flash vs V4-Pro e diferentes modos de raciocínio sem duplicar requests.
Espelhe a coleção para GPT-5.5 (veja o guia da API GPT-5.5). Assim, você compara ambos os provedores lado a lado.

Esse fluxo detecta cerca de 80% das surpresas de custo antes de chegarem na fatura.

Quatro regras para manter os gastos previsíveis

Use V4-Flash por padrão. Só migre ao V4-Pro quando a diferença de qualidade justificar.
Prefira Non-Think. Escale para Think High em tarefas complexas. Reserve Think Max para casos críticos.
Defina um limite para max_tokens. O teto de 384K é segurança, não objetivo. 2K atende a maioria das respostas reais.
Log de uso. Registre prompt_tokens, completion_tokens e reasoning_tokens por chamada. Alerta em picos de tokens de raciocínio previne custos inesperados.

FAQ

Existe um nível gratuito?

Não há API gratuita, mas novas contas podem receber crédito de teste. Para alternativas grátis, veja como usar o DeepSeek V4 gratuitamente.

Como funciona o desconto de cache?

Prefixos a partir de 1.024 tokens repetidos entre solicitações na mesma conta pagam a taxa reduzida. O cache é automático.

Modos de raciocínio custam mais?

A taxa por token é igual, mas modos de raciocínio consomem mais tokens. Monitore reasoning_tokens no retorno da API.

Os preços são estáveis?

DeepSeek pode alterar valores. Confira sempre a página oficial de preços antes de orçar.

A taxa de saída é igual entre V4-Pro e V4-Flash?

Não. V4-Pro cobra $3.48 / M na saída; V4-Flash $0.28 / M. O gap de 12.4x é a principal razão para usar o Flash padrão.

O endpoint Anthropic muda o preço?

Não. Tanto https://api.deepseek.com/anthropic quanto o endpoint OpenAI cobram as mesmas taxas.

Como Usar a API DeepSeek V4? Guia Completo

Lucas — Fri, 24 Apr 2026 04:16:06 +0000

DeepSeek V4 foi lançado com suporte imediato à API. Os IDs dos modelos são deepseek-v4-pro e deepseek-v4-flash. O endpoint segue o padrão OpenAI, com URL base https://api.deepseek.com. Basta trocar a URL base para começar a usar o V4 com qualquer cliente compatível com GPT-5.5 ou OpenAI.

Experimente o Apidog hoje

Neste guia, você vai implementar autenticação, configurar parâmetros essenciais, rodar exemplos em Python e Node, ativar matemática com raciocínio, chamar ferramentas, usar streaming e montar um fluxo no Apidog para acompanhar custos enquanto testa.

Veja a visão geral em o que é DeepSeek V4 e para experimentar sem custo, confira como usar o DeepSeek V4 gratuitamente.

TL;DR (Resumo)

Endpoint OpenAI: https://api.deepseek.com/v1/chat/completions. Endpoint Anthropic: https://api.deepseek.com/anthropic.
Modelos: deepseek-v4-pro (1.6T total, 49B ativos) e deepseek-v4-flash (284B total, 13B ativos).
Contexto de 1 milhão de tokens e três modos de raciocínio: non-thinking, thinking, thinking_max.
Use temperature=1.0, top_p=1.0 como padrão (não use padrões do GPT-5.5/Claude).
IDs deepseek-chat e deepseek-reasoner expiram em 24/07/2026; migre antes disso.
Baixe o Apidog para reproduzir requisições, comparar modos de raciocínio e manter a chave protegida.

Pré-requisitos

Antes de começar, prepare:

Conta DeepSeek em platform.deepseek.com com saldo de pelo menos $2.
Chave de API com escopo de projeto.
SDK compatível com OpenAI: Python openai>=1.30.0 ou Node openai@4.x.
Cliente de API para testar requisições. Use Apidog para repetir e comparar chamadas.

Defina sua chave no ambiente:

export DEEPSEEK_API_KEY="sk-..."

Endpoint e autenticação

Dois formatos:

POST https://api.deepseek.com/v1/chat/completions    # OpenAI
POST https://api.deepseek.com/anthropic/v1/messages  # Anthropic

Prefira OpenAI se não tiver legado Anthropic. O padrão deste guia é OpenAI.

Envie o token Bearer no cabeçalho Authorization. Exemplo de chamada mínima:

curl https://api.deepseek.com/v1/chat/completions \
  -H "Authorization: Bearer $DEEPSEEK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-pro",
    "messages": [
      {"role": "user", "content": "Explique o roteamento MoE em duas frases."}
    ]
  }'

Respostas incluem choices, usage detalhado e id para rastreamento. Erros seguem o padrão OpenAI.

Parâmetros da requisição

Configure cada campo para ajustar custo e comportamento:

Parâmetro	Tipo	Valores	Notas
`model`	string	`deepseek-v4-pro`, `deepseek-v4-flash`	Obrigatório.
`messages`	array	pares role/content	Obrigatório. Mesmo esquema do OpenAI.
`thinking_mode`	string	`non-thinking`, `thinking`, `thinking_max`	O padrão é `non-thinking`.
`temperature`	float	0 a 2	DeepSeek recomenda 1.0.
`top_p`	float	0 a 1	DeepSeek recomenda 1.0.
`max_tokens`	int	1 a 131.072	Limita o comprimento da saída.
`stream`	bool	true ou false	Habilita streaming SSE.
`tools`	array	Especificação de ferramenta OpenAI	Para chamada de função.
`tool_choice`	string ou objeto	`auto`, `required`, `none`, ou ferramenta específica	Controla o uso da ferramenta.
`response_format`	objeto	`{"type": "json_object"}`	Saída em modo JSON.
`seed`	int	qualquer int	Para reprodutibilidade.
`presence_penalty`	float	-2 a 2	Penaliza tópicos repetidos.
`frequency_penalty`	float	-2 a 2	Penaliza tokens repetidos.

thinking_mode é o principal driver de custo. Use non-thinking para performance, thinking para precisão em código/matemática, e thinking_max para máxima qualidade (usa mais tokens, requer contexto grande).

Cliente Python

O SDK openai funciona direto, só alterando a base URL:

import os
from openai import OpenAI

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

response = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[
        {"role": "system", "content": "Responda apenas em código."},
        {"role": "user", "content": "Escreva uma função Rust que faça 'debounce' de eventos."},
    ],
    extra_body={"thinking_mode": "thinking"},
    temperature=1.0,
    top_p=1.0,
    max_tokens=2048,
)

choice = response.choices[0]
print("Conteúdo:", choice.message.content)
print("Tokens de raciocínio:", response.usage.reasoning_tokens)
print("Total de tokens:", response.usage.total_tokens)

Passe parâmetros DeepSeek extras via extra_body.

Cliente Node

No Node, basta ajustar baseURL:

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.DEEPSEEK_API_KEY,
  baseURL: "https://api.deepseek.com/v1",
});

const response = await client.chat.completions.create({
  model: "deepseek-v4-flash",
  messages: [
    { role: "user", content: "Explique o otimizador Muon em linguagem simples." },
  ],
  thinking_mode: "thinking",
  temperature: 1.0,
  top_p: 1.0,
});

console.log(response.choices[0].message.content);
console.log("Uso:", response.usage);

No Node, thinking_mode pode ir direto.

Respostas em Streaming

Para streaming, use stream=True e consuma os chunks:

stream = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[{"role": "user", "content": "Transmita um ensaio de 300 palavras sobre MoE."}],
    stream=True,
    extra_body={"thinking_mode": "non-thinking"},
)

for chunk in stream:
    delta = chunk.choices[0].delta.content or ""
    print(delta, end="", flush=True)

Se usar raciocínio, monitore delta.reasoning_content.

Chamada de Ferramentas

Implemente funções conforme esquema OpenAI:

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Retorna o clima atual de uma cidade.",
        "parameters": {
            "type": "object",
            "properties": {
                "city": {"type": "string"},
                "unit": {"type": "string", "enum": ["c", "f"]},
            },
            "required": ["city"],
        },
    },
}]

response = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[{"role": "user", "content": "Clima em Lagos em Celsius?"}],
    tools=tools,
    tool_choice="auto",
    extra_body={"thinking_mode": "thinking"},
)

tool_call = response.choices[0].message.tool_calls[0]
print(tool_call.function.name, tool_call.function.arguments)

Chame a função, retorne o resultado como role: "tool", e continue o ciclo.

Modo JSON

Peça saída JSON válida assim:

response = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[
        {"role": "system", "content": "Responda com um único objeto JSON."},
        {"role": "user", "content": "Resuma esta nota de lançamento como {título, data, marcadores}: ..."},
    ],
    response_format={"type": "json_object"},
    extra_body={"thinking_mode": "non-thinking"},
)

Combine com validação usando Pydantic ou Zod no cliente.

Construa a coleção no Apidog

Para controle e repetição:

Baixe o Apidog e crie um projeto.
Adicione ambiente com {{DEEPSEEK_API_KEY}} como variável secreta.
Salve requisição POST para {{BASE_URL}}/chat/completions e cabeçalho Authorization: Bearer {{DEEPSEEK_API_KEY}}.
Parametrize model e thinking_mode para testes A/B.
Use o visualizador para inspecionar usage.reasoning_tokens e evitar custos desnecessários.

Se já usa a coleção GPT-5.5 do Apidog, basta duplicar, trocar base URL/modelo e rodar comparações.

Tratamento de Erros

Principais códigos e ações:

Código	Significado	Solução
400	Requisição inválida	Verifique JSON, `messages` e `tools`.
401	Chave inválida	Regenere em platform.deepseek.com.
402	Saldo insuficiente	Recarregue a conta.
403	Modelo não permitido	Verifique escopo da chave e nome do modelo.
422	Parâmetro fora do intervalo	Confira `max_tokens` e `thinking_mode`.
429	Limite de taxa	Espere e tente novamente com jitter exponencial.
500	Erro do servidor	Tente novamente; se persistir, veja a página de status.
503	Sobrecarga	Tente V4-Flash ou aguarde 30 segundos.

Implemente retentativa para erros 429/5xx com recuo exponencial. Erros 4xx são bugs de lógica, ajuste antes de tentar novamente.

Padrões de Controle de Custo

Use V4-Flash como padrão. Só mude para V4-Pro quando comprovar aumento de qualidade.
Controle thinking_max via flag. Só ative quando precisão máxima for necessária.
Limite max_tokens. 2.000 tokens de saída bastam para a maioria dos casos.
Registre usage toda chamada. Monitore picos de tokens de raciocínio para detectar desvios de prompt.

Migrando de modelos DeepSeek mais antigos

Mude apenas o ID do modelo:

-  model="deepseek-chat"
+  model="deepseek-v4-pro"

Compare respostas no Apidog antes de aplicar em produção.

FAQ (Perguntas Frequentes)

A API DeepSeek V4 está pronta para produção? Sim. Desde 23/04/2026, baseada na mesma infraestrutura robusta dos modelos anteriores.
O V4 suporta formato Anthropic? Sim. Use https://api.deepseek.com/anthropic/v1/messages com payload Anthropic.
Qual o contexto máximo? 1 milhão de tokens nos dois modelos; thinking_max requer pelo menos 384K.
Como contar tokens antes de enviar? Use o tokenizador OpenAI para estimar, mas confie na contagem usage da resposta para produção.
Fine-tuning via API? Não disponível via API no lançamento. Faça fine-tuning apenas via checkpoints no Hugging Face.
Existe trial/gratuito? Não há tier gratuito fixo, mas novos registros podem receber crédito de teste.

DEV Community: Lucas

Ghostty Deixando o GitHub: Impacto para Criadores de Ferramentas de Desenvolvedores

Resumo

O que Hashimoto anunciou

Por que o problema central é confiabilidade

1. O usuário

2. O motivo

3. O tom

Como auditar sua própria ferramenta

1. Quantos usuários poderiam escrever o mesmo diário sobre você?

2. Sua confiabilidade está melhorando ou piorando?

3. Sua página de status reduz ou aumenta a desconfiança?

4. Seu uptime mede a experiência certa?

O custo real do “sempre GitHub”

Como reduzir lock-in na prática

Use adaptadores

Separe CI da plataforma de hospedagem

Espelhe antes de precisar

Alternativas de forja

A lição para equipes de API

1. Simule tudo que você depende

2. Teste contra múltiplos provedores

3. Desacople release da hospedagem

Um fluxo resiliente com Apidog

O que os desenvolvedores estão concluindo

“Finalmente alguém disse”

“Foi só uma interrupção”

“Migrar é caro”

“Isso também me afeta?”

Checklist prático para sua stack

Perguntas frequentes

Para onde o Ghostty está se mudando?

O GitHub é realmente tão pouco confiável?

Devo mover meus repositórios para fora do GitHub agora?

Isso afeta GitHub Copilot ou GitHub Actions?

O que isso significa para ferramentas de IA que dependem da API do GitHub?

Isso é uma tendência de saída do GitHub?

O que significa “ferramenta de desenvolvedor” aqui?

Como Usar a API Mistral Medium 3.5? Guia Completo

TL;DR

O que mudou no Medium 3.5

Pré-requisitos

Endpoint e autenticação

Parâmetros principais

Cliente Python

Cliente Node.js

Streaming de respostas

Chamada de ferramenta

Modo JSON e saída estruturada

Entrada de visão

Crie uma coleção no Apidog

Tratamento de erros

Controle de custo

1. Use Medium 3 como padrão e escale para 3.5

2. Defina max_tokens

3. Reduza prompts de sistema

4. Registre usage

5. Use visão seletivamente

Comparando o Medium 3.5 com outros níveis da Mistral

Migrando de outro provedor

Casos de uso práticos

Revisão de código

QA em documentos longos

Extração multimodal

Agentes com ferramentas

FAQ

Qual é o ID do modelo na API?

O Medium 3.5 é compatível com OpenAI?

Posso executar o Medium 3.5 localmente?

Ele suporta streaming com chamadas de ferramenta?

Como contar tokens antes de enviar?

Qual contexto devo planejar para produção?

Existe nível gratuito?

Plataforma API para Workflow API Design-First

TL;DR

Introdução

O que design-first significa na prática

Antes de escrever código

Durante o desenvolvimento

Após a implementação

2. Defina `max_tokens`

4. Registre `usage`