DEV Community: Lucas

Por que a Detecção de Imagens por IA Falha (e o Que Usar em Vez Disso)

Lucas — Thu, 21 May 2026 09:50:24 +0000

Envie uma foto para quase qualquer “detector de imagem de IA” hoje e você receberá um veredito confiante: 94% humano, ou 88% IA. O número parece uma medição, mas normalmente é uma inferência estatística frágil. A detecção post-hoc — treinar um classificador para identificar imagens geradas por IA depois do fato — tem um problema estrutural: o alvo muda o tempo todo, e quem gera imagens tem incentivo para ficar à frente dos detectores.

Experimente o Apidog hoje

Isso importa para além da curiosidade. Equipes estão incorporando integridade de conteúdo diretamente em produtos: endpoints de upload que rejeitam imagens manipuladas, pipelines de moderação que sinalizam mídia sintética e verificações de conformidade que precisam de trilha de auditoria defensável.

💡 Esses são problemas de API. Se você vai integrar uma etapa de detecção de IA em um pipeline, trate essa etapa como um contrato verificável: entradas claras, saídas explícitas, estados inconclusivos e testes para falhas comuns.

TL;DR

A detecção post-hoc de imagens de IA não deve ser sua única linha de defesa. Ela perde para a corrida armamentista entre geradores e detectores, generaliza mal para modelos não vistos, produz falsos positivos contra trabalho humano real e falha com operações comuns como corte, redimensionamento ou recompressão.

A base mais confiável é proveniência primeiro:

verificar metadados assinados, como Credenciais de Conteúdo C2PA;
procurar marcas d’água incorporadas no momento da geração, como SynthID;
usar classificadores apenas como sinal fraco;
combinar contexto, histórico da conta e revisão humana em decisões de alto risco.

Por que a detecção post-hoc continua falhando

A detecção não é inútil. Um bom classificador pode ajudar a:

priorizar uma fila de moderação;
sinalizar imagens sintéticas óbvias;
identificar falsificações de baixo esforço;
fornecer um sinal adicional em um pipeline maior.

O erro é tratar a saída como veredito final.

1. A corrida armamentista não tem linha de chegada

Todo detector aprende padrões estatísticos dos geradores usados no treinamento: artefatos de frequência, ruído, distribuição de cores, texturas e outras “impressões digitais”.

Quando o detector vai para produção, ele descreve o passado. A próxima geração de modelos tenta justamente remover esses artefatos.

Na prática:

Detector treinado em:
- Gerador A
- Gerador B
- Gerador C

Usuário envia imagem de:
- Gerador D
- Gerador E ajustado por comunidade
- Imagem gerada + editada + recomprimida

O detector pode até retornar uma pontuação confiante, mas essa confiança não significa que ele viu padrões comparáveis no treinamento.

2. Classificadores não generalizam bem para modelos não vistos

Um detector treinado em uma família de geradores tende a falhar em outra. Um classificador ajustado para saídas GAN antigas pode performar mal em modelos de difusão. Um modelo treinado em checkpoints do ano passado pode tropeçar nos deste ano.

Essa lacuna de generalização é brutal porque novos modelos surgem continuamente. A precisão anunciada em benchmarks normalmente mede desempenho contra modelos conhecidos e testados. O upload real de amanhã pode vir de um modelo que não estava no conjunto de validação.

Para desenvolvedores, isso muda a forma de modelar a API. Evite respostas binárias como:

{
  "is_ai": true
}

Prefira algo que preserve incerteza:

{
  "classification": {
    "label": "possibly_ai_generated",
    "score": 0.72,
    "confidence": "medium",
    "model_version": "detector-2026-05",
    "limitations": [
      "classifier_score_is_not_proof",
      "unknown_generator_generalization_risk"
    ]
  }
}

3. Falsos positivos punem trabalho humano real

Um falso negativo deixa conteúdo sintético passar. Isso é ruim.

Um falso positivo acusa uma pessoa real de ter enviado conteúdo falso. Isso costuma ser pior.

Em produtos reais, falsos positivos afetam:

fotógrafos em marketplaces;
designers enviando portfólios;
estudantes e pesquisadores;
criadores de conteúdo;
clientes submetendo documentos ou imagens para análise.

A lição prática: não rejeite automaticamente uploads com base apenas em pontuação de detector.

Um fluxo mais seguro:

Upload recebido
   ↓
Verificação de proveniência
   ↓
Verificação de marca d'água
   ↓
Classificador post-hoc
   ↓
Contexto da conta / histórico
   ↓
Decisão:
- aceitar
- marcar como desconhecido
- enviar para revisão humana
- rejeitar somente com evidência forte

Se você quer entender os limites práticos dessas ferramentas antes de construir, veja o guia sobre como verificar se uma imagem é gerada por IA.

4. Corte, redimensionamento e recompressão quebram muitos sinais

Detectores dependem de padrões sutis no nível do pixel. Esses padrões são frágeis.

Operações comuns podem degradar o sinal:

salvar novamente como JPEG;
cortar bordas;
redimensionar;
adicionar ruído leve;
capturar tela;
passar por compressão de CDN;
publicar em redes sociais;
reenviar por aplicativo de mensagem.

Isso não é ataque sofisticado. É o fluxo normal da internet.

Por isso, teste seu pipeline com transformações reais:

# Exemplo com ImageMagick: recompressão JPEG
magick input.png -quality 75 output-quality-75.jpg

# Redimensionamento
magick input.png -resize 1024x1024 resized.jpg

# Corte simples
magick input.png -crop 90%x90%+0+0 cropped.jpg

# Ruído leve
magick input.png -attenuate 0.3 +noise Gaussian noisy.jpg

Depois valide se a API ainda retorna resultados úteis:

POST /image-integrity/check
Content-Type: multipart/form-data

file=@output-quality-75.jpg

A resposta deve deixar claro quando a evidência ficou fraca:

{
  "status": "inconclusive",
  "signals": {
    "c2pa": "not_found",
    "watermark": "not_found",
    "classifier": {
      "score": 0.61,
      "confidence": "low"
    }
  },
  "recommended_action": "manual_review_if_high_risk"
}

5. As “pistas” visuais desaparecem

Por um tempo, era comum identificar imagens de IA por mãos com dedos extras, texto ilegível, fundos derretidos ou reflexos incoerentes. Esse conselho perde valor a cada geração de modelo.

Artefatos visuais são bugs. E bugs são corrigidos.

Não baseie sua estratégia de verificação em “procurar mãos estranhas”. Isso pode ajudar em uma revisão humana, mas não é uma arquitetura confiável.

O custo real de errar isso

Em produto, erro de detecção vira risco operacional.

Exemplos:

Um marketplace rejeita automaticamente fotos reais e perde colaboradores.
Uma plataforma de notícias aceita uma imagem sintética como “real” porque o detector deu baixa probabilidade de IA.
Uma plataforma acadêmica sinaliza um portfólio humano como gerado por máquina.
Um sistema de seguros toma decisão com base em uma pontuação probabilística que mudaria após recompressão.

O problema não é apenas a imprecisão. É apresentar uma pontuação probabilística como autoridade.

Regra prática:

Pontuação de classificador = evidência fraca
Credencial assinada válida = evidência forte
Ausência de evidência = desconhecido, não falso

Use proveniência primeiro

A detecção pergunta:

“Esta imagem parece gerada por IA?”

A proveniência pergunta:

“Qual é o histórico documentado desta imagem, e posso verificá-lo criptograficamente?”

Essa segunda pergunta é melhor para sistemas de produção.

Credenciais de Conteúdo C2PA: metadados de origem assinados

A Coalition for Content Provenance and Authenticity é um padrão aberto para anexar proveniência à mídia de forma verificável.

Na prática, um manifesto C2PA pode registrar:

origem do arquivo;
ferramenta que criou ou editou a imagem;
alterações aplicadas;
assinatura criptográfica;
histórico de cadeia de custódia.

Usuários finais veem isso como Credenciais de Conteúdo, geralmente indicadas por um marcador “CR”.

A vantagem é que você não infere origem a partir de artefatos. Você verifica uma declaração assinada no momento da criação ou edição.

Como modelar isso em uma API

Um endpoint de verificação pode retornar algo assim:

{
  "provenance": {
    "c2pa_manifest": "valid",
    "issuer": "example-tool",
    "signed_at": "2026-05-12T14:32:00Z",
    "actions": [
      {
        "type": "created",
        "tool": "camera_or_generator"
      },
      {
        "type": "edited",
        "tool": "image_editor"
      }
    ]
  },
  "integrity": {
    "tamper_evident": true,
    "signature_valid": true
  }
}

Mas C2PA não é mágico:

é opt-in;
depende de ferramentas que escrevam o manifesto;
metadados podem ser removidos;
plataformas sociais e CDNs podem recomprimir arquivos e destruir o contêiner com as credenciais.

Portanto, a ausência de C2PA deve retornar unknown, não fake.

{
  "provenance": {
    "c2pa_manifest": "not_found"
  },
  "status": "unknown",
  "message": "Nenhuma credencial C2PA foi encontrada. Isso não prova que a imagem é falsa."
}

SynthID: marca d’água no momento da geração

Onde os metadados C2PA podem ser removidos, uma marca d’água vive dentro dos pixels.

O SynthID do Google DeepMind incorpora um sinal invisível, detectável por máquina, em uma imagem no momento em que ela é gerada. Ele foi projetado para sobreviver a transformações comuns como capturas de tela, cortes, ajustes de cor e recompressão.

C2PA e SynthID são complementares:

Sinal	O que oferece	Limitação
C2PA	Histórico rico, assinado e verificável	Pode ser removido em trânsito
SynthID	Sinal mais durável dentro da imagem	Só existe em geradores que integram a marca d’água
Classificador	Sinal adicional para triagem	Frágil, probabilístico e sujeito a falsos positivos

Um resultado combinado pode ser:

{
  "signals": {
    "c2pa": {
      "status": "not_found"
    },
    "watermark": {
      "provider": "synthid",
      "status": "detected",
      "confidence": "high"
    },
    "classifier": {
      "score": 0.84,
      "confidence": "medium"
    }
  },
  "final_assessment": "ai_generated_with_strong_watermark_evidence"
}

Captura assinada e pipelines autenticados

A proveniência também pode começar antes da IA. Algumas câmeras e aplicativos assinam fotos no momento da captura, criando uma cadeia de custódia desde o sensor.

Para seus sistemas, aplique o mesmo princípio:

registre quem enviou a imagem;
registre quando o upload ocorreu;
registre de qual conta autenticada veio;
registre qual endpoint recebeu o arquivo;
assine saídas geradas ou transformadas pelo seu serviço;
proteja chaves de assinatura como segredo crítico.

Exemplo de evento de auditoria:

{
  "event": "image_uploaded",
  "image_id": "img_123",
  "account_id": "acct_456",
  "uploaded_at": "2026-05-12T15:10:31Z",
  "source_ip_hash": "sha256:...",
  "endpoint": "POST /v1/uploads",
  "file_sha256": "9c56cc51...",
  "auth_method": "oauth2"
}

E para uma transformação:

{
  "event": "image_transformed",
  "image_id": "img_123",
  "output_id": "img_789",
  "operation": "resize",
  "parameters": {
    "width": 1200,
    "height": 800
  },
  "signed_by": "provenance-key-2026-05",
  "signature": "base64..."
}

O mesmo cuidado aplicado para manter chaves de API fora do código cliente e extensões deve valer para chaves de assinatura de proveniência. Uma chave vazada transforma “verificado” em “com aparência de verificado”.

A indústria está convergindo para proveniência

Esta não é uma posição marginal. Em maio de 2026, a OpenAI anunciou que estava adotando C2PA e SynthID para proveniência de conteúdo: imagens do ChatGPT, Codex e da API OpenAI passaram a carregar metadados C2PA e marca d’água SynthID. A OpenAI também lançou uma ferramenta de verificação chamada Verify para procurar esses sinais de proveniência em imagens enviadas.

O ponto arquitetural é importante: a resposta não foi apenas lançar um classificador post-hoc melhor. Foi combinar metadados assinados, marca d’água e verificação.

Defesa em profundidade: combine sinais fracos

Não existe um oráculo único para responder “esta imagem é IA?”. O caminho implementável é coletar sinais independentes e combinar pesos.

Um pipeline em camadas:

Verificação C2PA
- Se válido, é evidência forte.
- Se ausente, resultado é inconclusivo.
Verificação de marca d’água
- Procure SynthID ou sinal equivalente.
- Se presente, aumenta a confiança.
- Se ausente, não conclua automaticamente.
Classificador post-hoc
- Use para triagem.
- Nunca use como veredito isolado.
Contexto de conta
- Histórico de upload.
- Reputação da conta.
- Consistência de local, tempo e dispositivo.
- Repetição da mesma imagem em outras fontes.
Revisão humana
- Obrigatória para decisões de alto risco:
  - banimento;
  - acusação;
  - rejeição com impacto financeiro;
  - remoção pública;
  - decisão acadêmica ou legal.

Exemplo de contrato de resposta

{
  "image_id": "img_123",
  "status": "needs_review",
  "risk_level": "medium",
  "signals": {
    "c2pa": {
      "status": "valid",
      "weight": "high"
    },
    "watermark": {
      "status": "not_detected",
      "weight": "medium"
    },
    "classifier": {
      "label": "possibly_ai_generated",
      "score": 0.68,
      "weight": "low"
    },
    "account_context": {
      "account_age_days": 18,
      "previous_violations": 0,
      "weight": "medium"
    }
  },
  "decision": {
    "automated_action": "none",
    "recommended_next_step": "manual_review"
  }
}

Comparação: detecção post-hoc vs. proveniência

Dimensão	Detecção post-hoc (classificador)	Proveniência e marca d'água
Pergunta central	“Isso parece gerado por IA?”	“Qual é o histórico assinado e verificável desta imagem?”
Confiabilidade ao longo do tempo	Decai; todo novo gerador a erode	Estável; uma assinatura criptográfica não enfraquece porque os modelos melhoram
Generaliza para novos modelos	Mal; a lacuna de generalização é estrutural	Sim; não depende de reconhecer um gerador específico
Quem deve cooperar	Ninguém, o que é sua única vantagem real	As ferramentas de geração e edição devem escrever credenciais ou marcas d'água
O que a derrota	Um corte, recompressão, captura de tela, ruído, ajuste adversarial ou qualquer modelo não visto	Remoção de metadados no upload (C2PA); a remoção de marca d'água é mais difícil, mas não impossível
Risco de falso positivo	Alto; sinaliza erroneamente trabalho humano genuíno	Baixo; uma credencial ausente ou inválida é relatada como “desconhecida”, não “falsa”
Modo de falha	Confiante e errado	Inconclusivo e honesto (“nenhuma proveniência encontrada”)
Melhor função	Triagem e um sinal fraco dentro de um sistema em camadas	A camada primária e confiável quando presente
Trajetória da indústria	Confiança decrescente como resposta autônoma	Adoção ativa (C2PA, SynthID, movimento da OpenAI em 2026)

O nicho honesto da detecção é triagem. A camada base deve ser proveniência. Como nenhuma das duas é completa, combine as duas com contexto e revisão humana.

Controles de processo e política

As ferramentas são metade do sistema. A outra metade é como seu produto responde à incerteza.

1. Trate “desconhecido” como estado de primeira classe

Não force tudo para real ou fake.

Use pelo menos três estados:

verified
contradicted
unknown

Exemplo:

{
  "status": "unknown",
  "reason": "no_verifiable_provenance_found",
  "allowed_actions": [
    "accept_with_low_trust",
    "request_additional_evidence",
    "manual_review"
  ]
}

2. Ajuste a resposta ao risco

Um fluxo de baixo risco pode aceitar automação. Uma decisão de alto risco deve exigir evidência forte e revisão humana.

Baixo risco:
- exibir aviso
- reduzir prioridade
- enviar para fila secundária

Alto risco:
- exigir C2PA válido ou evidência equivalente
- revisão humana
- registro de auditoria
- explicação para o usuário

3. Seja transparente com usuários e operadores

Não mostre “IA detectada” quando o sistema só tem uma probabilidade.

Melhor:

Credenciais de Conteúdo verificadas.

ou:

Nenhuma proveniência verificável encontrada.

ou:

Classificador estimou 70% de probabilidade de geração por IA. Esse resultado não é prova.

4. Escreva proveniência nas suas próprias saídas

Se sua plataforma gera, edita ou transforma imagens, anexe credenciais e/ou marcas d’água quando possível.

Isso ajuda sistemas downstream e reduz dependência de detectores frágeis.

5. Versione suas integrações

C2PA, SynthID e ferramentas de verificação evoluem. Modele verificações como dependências versionadas.

{
  "verification_pipeline": {
    "version": "2026-05-01",
    "checks": [
      {
        "name": "c2pa",
        "version": "1.0"
      },
      {
        "name": "synthid",
        "version": "1.0"
      },
      {
        "name": "classifier",
        "version": "detector-2026-05"
      }
    ]
  }
}

Isso facilita adicionar novos provedores sem reescrever toda a infraestrutura.

Checklist de implementação

Antes de colocar uma verificação de imagem em produção, valide:

[ ] A API retorna unknown quando não há evidência suficiente.
[ ] A pontuação do classificador nunca é usada como única base para rejeição de alto impacto.
[ ] O pipeline verifica C2PA quando disponível.
[ ] O pipeline verifica marcas d’água quando disponível.
[ ] Transformações comuns foram testadas: corte, resize, JPEG, screenshot e compressão.
[ ] Eventos de auditoria registram upload, usuário, hash do arquivo e decisão.
[ ] Chaves de assinatura são protegidas fora do cliente.
[ ] Decisões de alto risco exigem revisão humana.
[ ] A resposta da API explica quais sinais foram usados.
[ ] O pipeline é versionado para suportar novos padrões.

Conclusão

A detecção post-hoc de imagens de IA não é inútil. Ela só não deve carregar sozinha uma decisão de integridade.

A recomendação prática para desenvolvedores é: construa com proveniência primeiro. Verifique C2PA, procure marcas d’água, mantenha classificadores como sinais fracos de triagem e nunca aja automaticamente com base em uma única pontuação quando a decisão afeta uma pessoa real.

Projete isso como qualquer integração crítica de API: contrato explícito, estados inconclusivos, versionamento, logs de auditoria e testes contra falhas comuns.

💡 O Apidog oferece um espaço de trabalho para projetar, simular e testar endpoints de verificação antes da produção. Construa sua camada de integridade com base em registros verificáveis, não em suposições que podem quebrar na próxima recompressão.

Qwen 3.7 vs GPT-5.5 vs Opus 4.7: Comparativo 2026

Lucas — Thu, 21 May 2026 09:08:08 +0000

Três laboratórios lançaram modelos carro-chefe com cinco semanas de diferença, e as tabelas de classificação continuam mudando. Qwen3.7-Max-Preview, GPT-5.5 e Claude Opus 4.7 aparecem no topo dos principais benchmarks, mas escolher um deles para um produto real exige olhar para raciocínio, codificação, contexto, custo, disponibilidade e latência — não apenas para uma manchete.

Experimente o Apidog hoje

A afirmação de que o Qwen3.7-Max ficou em #1 no Artificial Analysis Intelligence Index é verdadeira, mas incompleta. O GPT-5.5 tem a maior pontuação bruta reportada, o Claude Opus 4.7 lidera em preferência humana no LM Arena, e o Qwen ainda está em prévia. Este guia compara os três com foco prático: quando usar cada um, quais métricas validar e como testar os modelos lado a lado antes de colocar algo em produção.

TL;DR

Use este resumo como ponto de partida:

GPT-5.5: melhor escolha para agentes de codificação, automação de terminal e fluxos sensíveis a tokens.
Claude Opus 4.7: melhor para grandes bases de código, qualidade conversacional e preferência humana.
Qwen3.7-Max-Preview: promissor para contexto longo e custo, mas ainda não é uma escolha segura para produção por estar em prévia.
Benchmark bruto: GPT-5.5 lidera com 60 no Artificial Analysis Intelligence Index.
Tabela pública do Artificial Analysis: Qwen3.7-Max aparece em #1 geral com 57.
Preferência humana: Claude Opus 4.7 lidera no LM Arena.
Codificação real: GPT-5.5 lidera no SWE-bench Verified; Claude Opus 4.7 lidera no SWE-bench Pro.

Os três modelos em um relance

Antes de comparar pontuações, verifique o status de lançamento. Isso muda diretamente se você pode usar o modelo hoje em produção.

Qwen3.7-Max-Preview

Qwen3.7-Max é o modelo de raciocínio carro-chefe da Alibaba, apresentado em meados de maio de 2026. Ele usa raciocínio estendido, possui janela de contexto de 1 milhão de tokens e é focado em codificação agêntica, uso de ferramentas e raciocínio de longo contexto.

O ponto crítico: ele ainda é uma prévia. Até o final de maio de 2026, não há endpoint público de API nem pesos abertos. O acesso ocorre via Alibaba Cloud Model Studio e Qwen Studio.

A Alibaba também indicou que o Qwen3.7-Plus será aberto, enquanto o Qwen3.7-Max permanecerá proprietário. Se pesos abertos fazem parte do seu requisito técnico, isso importa.

GPT-5.5

GPT-5.5 é o modelo de raciocínio da OpenAI lançado em 23 de abril de 2026. Ele é focado em fluxos agênticos: terminal, navegador, chamadas de ferramentas e execução autônoma de tarefas.

A OpenAI oferece níveis diferentes de esforço de raciocínio. Os números públicos do Artificial Analysis usam a variante xhigh. Na API, a janela de contexto chega a 1 milhão de tokens; dentro do Codex, o limite é menor, em torno de 400 mil tokens. O modelo está disponível hoje via API da OpenAI.

Claude Opus 4.7

Claude Opus 4.7 é o modelo carro-chefe da Anthropic, lançado em 16 de abril de 2026. Ele é posicionado para engenharia de software avançada, principalmente tarefas difíceis em grandes bases de código.

O modelo usa raciocínio adaptativo, possui janela de contexto de 1 milhão de tokens e está disponível via API da Anthropic, Amazon Bedrock e Google Vertex AI. Entre os três, é o que tem maior histórico recente em produção e mais dados independentes de preferência humana.

Benchmarks de raciocínio e inteligência

Artificial Analysis Intelligence Index

O Artificial Analysis Intelligence Index combina avaliações de raciocínio, conhecimento, matemática e codificação.

Em meados de maio de 2026:

Qwen3.7-Max: 57, listado como #1 de 218 modelos na tabela geral.
GPT-5.5 xhigh: 60, maior pontuação bruta entre os três.
Claude Opus 4.7 max: 57, listado como #3 em sua categoria rastreada.

A leitura prática é:

Se você está olhando para a posição geral da tabela, o Qwen aparece em #1.
Se você está olhando para a pontuação bruta, o GPT-5.5 lidera.
Se você quer uma decisão de produto, trate GPT-5.5 e Qwen como co-líderes nesse índice, com Claude Opus 4.7 muito próximo.

Uma ressalva importante: o Artificial Analysis observou que o Qwen3.7-Max gerou 97 milhões de tokens de saída durante a avaliação, bem acima da média aproximada de 26 milhões. Isso pode aumentar custo e latência em produção.

LM Arena: preferência humana

O LM Arena Text Leaderboard mede preferência humana em comparações cegas.

Em meados de maio de 2026:

Claude Opus 4.7: ~1.492 Elo, #4 geral, com mais de 13.000 votos.
GPT-5.5: ~1.478 Elo, #11.
Qwen3.7-Max-Preview: ~1.475 Elo, #14, ainda preliminar e com menos de 4.000 votos.

Para produtos conversacionais, suporte ao cliente, copilotos internos e assistentes voltados para usuários finais, essa métrica pode ser mais útil do que benchmarks acadêmicos. Nesse cenário, o Claude Opus 4.7 é o mais forte dos três.

Capacidade de codificação

Todos os três modelos são posicionados para desenvolvimento de software, mas os dados públicos não são igualmente completos.

No SWE-bench Verified, de acordo com o rastreamento da tabela de classificação do SWE-bench de maio de 2026:

GPT-5.5: 88.7%
Claude Opus 4.7: 87.6%
Qwen3.7-Max-Preview: sem resultado padronizado publicado

No SWE-bench Pro:

Claude Opus 4.7: ~64%
GPT-5.5: ~59%
Qwen3.7-Max-Preview: sem resultado público

Interpretação prática:

Use GPT-5.5 para agentes que executam comandos, iteram em terminal e precisam controlar tokens.
Use Claude Opus 4.7 para refatorações grandes, PRs complexos e raciocínio arquitetural.
Use Qwen3.7-Max-Preview em avaliações internas, mas não assuma desempenho de SWE-bench até haver dados públicos.

Se você está comparando agentes integrados a IDEs, veja também a análise de Cursor Composer 2.5 contra Opus 4.7 e GPT-5.5.

Janela de contexto

Todos os três modelos chegam perto de 1 milhão de tokens:

Qwen3.7-Max: 1 milhão de tokens.
Claude Opus 4.7: 1 milhão de tokens.
GPT-5.5: 1 milhão de tokens na API; ~922 mil efetivos medidos pelo Artificial Analysis; 400 mil no Codex.

Isso permite incluir repositórios grandes, documentação extensa, logs longos ou transcrições completas. Porém, não valide apenas o número anunciado. Para contexto longo, teste:

Recuperação de informação no início, meio e fim do prompt.
Capacidade de citar trechos corretos.
Consistência entre múltiplos arquivos.
Latência total com contexto máximo.
Custo real por execução.

Preço

A comparação de preço é desigual porque o Qwen3.7-Max-Preview ainda não tem preço público de API.

Segundo o Artificial Analysis:

Modelo	Entrada / 1M tokens	Saída / 1M tokens	Cache de entrada
GPT-5.5 xhigh	US$ 5.00	US$ 30.00	US$ 0.50
Claude Opus 4.7 max	US$ 6.25	US$ 25.00	US$ 0.50
Qwen3.7-Max-Preview	Não anunciado	Não anunciado	Não anunciado

A geração anterior Qwen3.6-Max-Preview custava cerca de US$ 1.30 por milhão de tokens de entrada e US$ 7.80 por milhão de saída via Alibaba Cloud. Se o Qwen3.7-Max ficar próximo disso, será competitivo em custo. Mas isso ainda não é preço confirmado.

Para estimar custo real, não use apenas a tabela de preço. Calcule:

custo_total =
  (tokens_entrada / 1_000_000 * preco_entrada)
+ (tokens_saida / 1_000_000 * preco_saida)
- economia_de_cache

Também registre a média de tokens de saída por tarefa. Um modelo barato por token pode sair caro se gerar respostas muito longas.

Para otimizações práticas, veja o guia sobre como reduzir os custos de tokens de agente a partir da CLI.

Disponibilidade e abertura

Essa é a categoria mais objetiva:

GPT-5.5: disponível via API OpenAI e Codex. Proprietário, sem pesos abertos, pronto para produção.
Claude Opus 4.7: disponível via API Anthropic, Amazon Bedrock e Google Vertex AI. Proprietário, pronto para produção, com bom alcance em nuvem.
Qwen3.7-Max-Preview: apenas prévia. Sem endpoint público de API e sem pesos abertos para o Max.

Se você precisa colocar algo em produção agora, GPT-5.5 e Claude Opus 4.7 são as opções viáveis. O Qwen3.7-Max é mais adequado para avaliação, planejamento de roadmap e testes controlados.

Para acesso atual, veja como usar a API Qwen 3.7 e como usar o Qwen 3.7 gratuitamente.

Latência

Segundo o Artificial Analysis:

Claude Opus 4.7: ~27 segundos até o primeiro token.
GPT-5.5 xhigh: ~101 segundos até o primeiro token.
GPT-5.5: ~65.9 tokens/s de saída.
Claude Opus 4.7: ~49.4 tokens/s de saída.
Qwen3.7-Max: sem dados públicos comparáveis.

Para produtos interativos, tempo até o primeiro token costuma ser mais importante. Para processamento em lote, throughput total pode pesar mais.

Em produção, teste pelo menos três cenários:

1. Prompt curto + resposta curta
2. Prompt longo + resposta curta
3. Prompt longo + resposta longa

Registre:

- tempo até o primeiro token
- tempo total
- tokens de entrada
- tokens de saída
- custo estimado
- taxa de erro
- qualidade da resposta

Tabela de comparação completa

Critério	Qwen3.7-Max-Preview	GPT-5.5	Claude Opus 4.7
Fornecedor	Alibaba	OpenAI	Anthropic
Lançado	Prévia, meados de maio de 2026	23 de abril de 2026	16 de abril de 2026
Índice de Inteligência AA	57 (#1 / 218 geral)	60 (maior pontuação)	57 (#3 na categoria)
Elo de texto LM Arena	~1.475 (#14, preliminar)	~1.478 (#11)	~1.492 (#4)
SWE-bench Verificado	Não publicado	88.7%	87.6%
SWE-bench Pro	Não publicado	~59%	~64%
Janela de contexto	1.0M tokens	1M API / ~922K efetivo / 400K Codex	1.0M tokens
Preço de entrada (por 1M)	Não anunciado (Qwen3.6-Max: ~$1.30)	$5.00	$6.25
Preço de saída (por 1M)	Não anunciado (Qwen3.6-Max: ~$7.80)	$30.00	$25.00
Velocidade de saída	Não publicado	~65.9 tok/s	~49.4 tok/s
Tempo até o primeiro token	Não publicado	~101 s (xhigh)	~27 s
Disponibilidade	Somente prévia (Model Studio / Qwen Studio)	Disponibilidade Geral (API OpenAI, Codex)	Disponibilidade Geral (API Anthropic, Bedrock, Vertex)
Pesos abertos	Não (Max proprietário; Plus será aberto)	Não	Não
Modelo de raciocínio	Sim (raciocínio estendido)	Sim (raciocínio estendido)	Sim (raciocínio adaptativo)

Fontes: páginas de modelo do Artificial Analysis, LM Arena, SWE-bench e anúncios de fornecedores, atualizados em meados de maio de 2026. Os números mudam com frequência; verifique as tabelas ao vivo antes de tomar decisões finais.

Casos de uso práticos

1. Agente de codificação autônomo

Escolha GPT-5.5 se o agente precisa:

executar comandos de terminal;
iterar em erros de build/teste;
manter custo de tokens baixo;
resolver issues reais do GitHub;
operar por muitas etapas.

Escolha Claude Opus 4.7 se a tarefa exige mais entendimento arquitetural do que automação de shell.

2. Refatoração de uma base legada grande

Escolha Claude Opus 4.7 quando você precisa:

analisar centenas de arquivos;
manter contexto de arquitetura;
gerar alterações de PR com qualidade;
entender dependências entre módulos;
trabalhar com tarefas difíceis de SWE-bench Pro.

3. Análise de documentos longos

Todos os três são fortes por causa da janela de ~1 milhão de tokens.

Use:

Claude Opus 4.7 para resumos e respostas que humanos tendem a preferir.
GPT-5.5 para pipelines já integrados à API OpenAI.
Qwen3.7-Max-Preview para pilotos sensíveis a custo, desde que o status de prévia seja aceitável.

4. Chat e assistentes para clientes

Escolha Claude Opus 4.7 se a métrica principal é satisfação do usuário. O Elo do LM Arena favorece o Opus entre os três.

Use GPT-5.5 como alternativa forte quando streaming, automação e integração com ferramentas forem mais importantes.

5. Processamento em alto volume

Se você processa milhões de tokens por dia, priorize custo real por tarefa:

custo_por_tarefa = custo_total / numero_de_tarefas_concluidas_com_sucesso

Até o preço do Qwen3.7-Max ser público, compare GPT-5.5 e Claude Opus 4.7 com sua proporção real de entrada/saída:

prompts longos + respostas curtas: vantagem tende ao GPT-5.5;
respostas longas: vantagem tende ao Claude Opus 4.7.

Como testar os três na prática

Benchmarks são genéricos. Sua aplicação não é. O teste mais útil é executar o mesmo conjunto de prompts nos modelos candidatos e comparar resultado, custo e latência.

Uma matriz simples de avaliação:

Teste	O que medir
Prompt real de usuário	qualidade e preferência humana
Issue de código real	correção e diffs gerados
Documento longo	recuperação de contexto
Loop com ferramenta	estabilidade e custo
Resposta longa	tokens de saída e latência
Execução repetida	consistência

Você pode usar o Apidog para criar requisições para cada endpoint de chat, salvar os prompts em um workspace e executar comparações lado a lado. Isso facilita medir tempo de resposta, inspecionar payloads e repetir os mesmos testes quando os modelos forem atualizados.

Exemplo de checklist para cada requisição:

[ ] Mesmo prompt
[ ] Mesma temperatura
[ ] Mesmo limite de saída
[ ] Mesmo contexto
[ ] Tempo total registrado
[ ] Tokens de entrada registrados
[ ] Tokens de saída registrados
[ ] Custo estimado calculado
[ ] Resposta avaliada por critérios fixos

Para começar, baixe o Apidog e configure uma coleção com uma requisição por modelo.

Escolhas por caso de uso

Use esta decisão rápida:

Agentes de codificação e terminal: GPT-5.5.
Grandes bases de código: Claude Opus 4.7.
Produtos conversacionais: Claude Opus 4.7.
Benchmark bruto de inteligência: GPT-5.5.
Contexto longo com foco em custo: Qwen3.7-Max-Preview, com ressalvas.
Produção hoje: GPT-5.5 ou Claude Opus 4.7.
Avaliação de roadmap: inclua Qwen3.7-Max-Preview.

Se você também está considerando o modelo do Google, veja o que é o Gemini 3.5 e a comparação entre Gemini 3.5, GPT-5.5 e Opus 4.7.

Conclusão

Não há um vencedor único.

GPT-5.5 tem a maior pontuação bruta no Artificial Analysis Intelligence Index, lidera o SWE-bench Verified e é eficiente em tokens.
Claude Opus 4.7 lidera em preferência humana, vence no SWE-bench Pro e é forte para grandes bases de código.
Qwen3.7-Max-Preview aparece em #1 na tabela geral do Artificial Analysis e tem contexto longo, mas ainda está em prévia.

A manchete “Qwen é #1” é correta, mas parcial. Para decidir tecnicamente, rode seus próprios prompts, meça custo real, latência e qualidade, e compare os modelos no mesmo fluxo. Uma tarde de testes no Apidog tende a ser mais útil do que semanas olhando apenas para rankings.

Como Usar Qwen 3.7 Grátis?

Lucas — Thu, 21 May 2026 08:57:25 +0000

A Alibaba lançou o Qwen 3.7 discretamente. Os modelos de prévia Qwen3.7-Max-Preview e Qwen3.7-Plus-Preview apareceram primeiro em uma arena pública de modelos em 14 de maio de 2026, sem post oficial e sem API pública. A confirmação veio no Alibaba Cloud Summit em Hangzhou, em 20 de maio. Se você quer testar o modelo sem pagar, o ponto prático é separar acesso realmente gratuito de testes pagos com rótulo “free”.

Experimente o Apidog hoje

Este guia mostra as formas confirmadas de usar o Qwen 3.7 sem custo em maio de 2026. Para cada caminho, veja o que dá para fazer, quais são os limites e quando vale a pena usar.

💡 Se você pretende integrar o modelo em um app, uma ferramenta como o Apidog ajuda a enviar a requisição, inspecionar respostas em streaming e salvar chamadas antes de levar para produção. Se ainda está avaliando o modelo, veja também o guia sobre o que é o Qwen 3.7, com arquitetura e benchmarks.

TL;DR

Em maio de 2026, o Qwen 3.7 ainda está em prévia. O acesso gratuito real está limitado a:

Qwen Chat (chat.qwen.ai): conta gratuita, modelos de prévia disponíveis e limites de taxa.
Arenas públicas de modelos: testes A/B cegos para comparar respostas e votar.
Créditos de API da Alibaba Cloud: teste por tempo limitado para novas contas, não uma camada gratuita permanente.

O que não existe hoje para o Qwen 3.7:

pesos abertos para rodar localmente;
execução via Ollama ou LM Studio;
camada gratuita no OpenRouter;
endpoint público gratuito em agregadores.

Essas opções existem ou existiram para versões anteriores, como Qwen 3.6, mas não para o Qwen 3.7 neste momento.

O que o Qwen 3.7 é

Antes de escolher um caminho de acesso, confirme qual modelo você está testando.

O Qwen 3.7 foi apresentado em duas variantes de prévia:

Qwen3.7-Max-Preview: modelo principal, voltado para tarefas longas de agente.
Qwen3.7-Plus-Preview: variante menor e mais equilibrada, voltada para raciocínio e codificação com menor custo.

Segundo a Alibaba, o Qwen3.7-Max-Preview sustentou uma tarefa única por cerca de 35 horas e realizou mais de 1.000 chamadas de ferramentas em testes internos. Ambos os modelos têm janela de contexto de 1 milhão de tokens e, durante a prévia, operam apenas no modo de pensamento. Pesquisa na web e interpretador de código estão desativados por enquanto.

O detalhe mais importante: o Qwen3.7-Max-Preview é proprietário. Os pesos não são públicos e a Alibaba não divulgou a contagem de parâmetros. A Alibaba afirmou que a variante Plus será open source, mas, em maio de 2026, nenhum peso do Qwen 3.7 foi lançado.

Portanto, se um tutorial diz para “baixar o Qwen 3.7” e rodar localmente, provavelmente ele está confundindo o modelo com o Qwen 3.6 ou antecipando um lançamento que ainda não ocorreu.

Caminho 1: Qwen Chat

A forma gratuita mais direta de usar o Qwen 3.7 é o app oficial em chat.qwen.ai.

Como usar

Acesse chat.qwen.ai.
Entre como convidado para um teste rápido ou crie uma conta gratuita.
Faça login com Google, GitHub, Apple ou e-mail para obter limites maiores e histórico salvo.
Abra o seletor de modelos.
Escolha Qwen3.7-Max-Preview ou Qwen3.7-Plus-Preview.
Use o modo de pensamento, que durante a prévia é o modo principal disponível.

O que dá para testar

Você pode usar o Qwen Chat para:

refatorar funções;
revisar código;
explicar erros;
resumir documentos;
analisar imagens;
testar prompts longos;
comparar raciocínio com outros modelos.

Exemplo de prompt prático para desenvolvedores:

Refatore esta função JavaScript para reduzir complexidade ciclomática.
Explique as mudanças e aponte possíveis efeitos colaterais.

[código aqui]

Outro exemplo:

Analise este contrato de API e identifique inconsistências entre nomes de campos,
tipos esperados e possíveis erros de validação.

[cole o schema ou documentação aqui]

Limites

Há duas limitações principais:

Ferramentas desativadas

Pesquisa na web e interpretador de código não estão ativos nos modelos de prévia. O modelo não navega em tempo real nem executa código em sandbox.
Limites de taxa

O Qwen Chat não publica números exatos. Uso intenso pode atingir limite. Conta logada tem mais margem que sessão de convidado, mas nenhuma opção é ilimitada.

Quando usar

Use o Qwen Chat se você quer avaliar qualidade sem escrever integração. É o melhor ponto de partida para desenvolvedores, estudantes, escritores técnicos e equipes comparando modelos.

Se depois você quiser chamar o modelo via código, veja o guia sobre como usar a API do Qwen 3.7.

Caminho 2: arenas públicas de modelos

O Qwen 3.7 apareceu publicamente em placares de arenas antes de ter API pública. Nessas plataformas, você envia um prompt, recebe duas respostas anônimas e vota na melhor.

Como testar

O fluxo típico é:

Abra uma arena pública de modelos.
Escolha o modo “battle” ou comparação lado a lado.
Envie um prompt.
Compare as duas respostas.
Vote na melhor.
Em alguns casos, veja quais modelos responderam depois da votação.

Em modo cego, você não escolhe o modelo. Isso reduz viés, mas também impede garantir que uma resposta específica veio do Qwen 3.7.

Algumas arenas também oferecem modo direto, em que você seleciona um modelo nomeado. Qwen3.7-Max-Preview e Qwen3.7-Plus-Preview apareceram como opções selecionáveis.

Bons prompts para comparar modelos

Use prompts que revelem diferenças práticas:

Explique este bug de concorrência em Go e proponha uma correção segura.

[código aqui]

Escreva um plano de migração de uma API REST para uma arquitetura orientada a eventos.
Inclua riscos, etapas e critérios de rollback.

Compare duas abordagens para cache em uma API Node.js:
Redis compartilhado vs cache local em memória.
Inclua trade-offs operacionais.

Limites

A arena é boa para avaliação, não para produção.

Você não terá:

API;
upload de arquivos;
histórico confiável;
controle total do modelo;
throughput previsível.

Além disso, em modo cego, uma resposta pode ou não vir do Qwen 3.7.

Quando usar

Use arenas para comparação direta. É útil se você quer saber como o Qwen 3.7 se comporta contra outros modelos de ponta em prompts reais.

Para uma comparação estruturada, veja Qwen 3.7 vs GPT-5.5 vs Opus 4.7.

Caminho 3: execução local com Ollama ou LM Studio

Este caminho ainda não está disponível para o Qwen 3.7.

Por que não funciona

Para rodar um modelo localmente, você precisa dos pesos. Esses arquivos contêm os parâmetros treinados do modelo.

No caso do Qwen 3.7:

Qwen3.7-Max-Preview é proprietário;
a Alibaba não liberou seus pesos;
Qwen3.7-Plus foi prometido como open source;
em maio de 2026, nenhum peso do Qwen 3.7 foi publicado.

Logo, não há nada para baixar e nada para carregar no Ollama ou no LM Studio.

Se você encontrar um comando como este:

ollama run qwen3.7

verifique o nome real do modelo. É muito provável que o tutorial esteja apontando para Qwen 3.6 ou para outro modelo da família Qwen.

O que usar localmente hoje

Se você precisa de inferência local, offline e sem custo de API, use a geração anterior. O Qwen 3.6 tem pesos abertos, incluindo:

modelo denso de 27B;
variante mixture-of-experts de 35B;
licença Apache 2.0.

Você pode baixá-los pelo Hugging Face e rodar via Ollama ou LM Studio.

O caminho prático é:

quer especificamente Qwen 3.7? Use Qwen Chat.
quer um modelo Qwen local e gratuito hoje? Use Qwen 3.6.
quer Qwen 3.7 local? Aguarde os pesos do Qwen3.7-Plus.

Quando usar

Execução local é ideal para:

requisitos fortes de privacidade;
protótipos offline;
ambientes sem dependência de API;
controle total sobre dados;
custo zero por token.

Mas, por enquanto, esse caso é atendido pelo Qwen 3.6, não pelo Qwen 3.7.

Caminho 4: agregadores de API

Agregadores como OpenRouter permitem chamar vários modelos com uma única chave de API. Alguns modelos ficam disponíveis em camadas gratuitas. Para o Qwen 3.7, essa opção ainda não existe.

Estado atual

Em maio de 2026:

o OpenRouter lista vários modelos Qwen;
as entradas mais recentes param na geração Qwen 3.6;
não há Qwen3.7-Max;
não há Qwen3.7-Plus;
não há endpoint gratuito do Qwen 3.7.

Outros agregadores estão na mesma situação. Uma listagem de terceiros só deve aparecer depois que a API oficial estiver ativa.

O que dá para fazer agora

Você pode construir seu protótipo usando um modelo Qwen mais antigo e deixar o ID do modelo configurável.

Exemplo simples em JavaScript:

const model = process.env.MODEL_ID || "qwen/qwen-3.6";

const response = await fetch("https://api.exemplo.com/v1/chat/completions", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model,
    messages: [
      {
        role: "user",
        content: "Explique este erro e sugira uma correção."
      }
    ]
  })
});

Quando o Qwen 3.7 for listado, você troca apenas a variável:

MODEL_ID=qwen/qwen-3.7-plus-preview

Isso evita acoplar o código a um modelo específico antes da disponibilidade real.

Atenção com camadas gratuitas

Camadas gratuitas em agregadores podem ter:

logs de prompts e respostas;
capacidade compartilhada;
latência variável;
limites de taxa;
regras diferentes para uso comercial.

Não envie dados confidenciais por endpoints gratuitos sem revisar os termos.

Quando usar

Use agregadores se você quer alternar entre modelos facilmente e prototipar com baixo custo. Para Qwen 3.7, esse caminho é “aguarde”, não “use agora”.

Caminho 5: créditos gratuitos da Alibaba Cloud

A última rota é o teste com créditos para novas contas no Alibaba Cloud Model Studio, plataforma que hospeda a API oficial do Qwen.

O que são esses créditos

Provedores de nuvem normalmente oferecem créditos iniciais ou um bloco de tokens gratuitos para novas contas. Quando a API pública do Qwen 3.7 estiver disponível após o summit, esses créditos deverão poder ser usados para chamadas reais.

Isso permite testar a API sem cobrança imediata.

Mas há uma diferença importante:

Créditos gratuitos não são uma camada gratuita permanente.

Eles expiram. O limite acaba. Depois disso, passam a valer os preços padrão.

A geração estável do Qwen 3.6 já é cobrada por milhão de tokens na mesma plataforma. O preço do Qwen 3.7 deve ser anunciado quando a API estiver disponível.

Como usar de forma segura

Para evitar surpresa de custo:

Crie uma conta separada para teste.
Verifique a validade dos créditos.
Defina alertas de billing.
Defina limites de uso, se a plataforma permitir.
Teste com prompts pequenos antes de enviar contexto longo.
Registre tokens de entrada e saída.
Só depois integre em um fluxo automatizado.

Exemplo de checklist para testes de API:

[ ] Endpoint confirmado
[ ] Modelo correto selecionado
[ ] Chave de API em variável de ambiente
[ ] Timeout configurado
[ ] Retry com backoff
[ ] Logging sem dados sensíveis
[ ] Limite de custo configurado
[ ] Teste com payload mínimo
[ ] Teste com payload real

Quando usar

Use créditos se você já está pronto para escrever integração real e aceita migrar para uso pago caso o modelo funcione bem.

Não use essa opção se seu requisito é custo zero permanente.

A mesma lógica vale para outros provedores. Veja também o guia sobre como usar o Gemini 3.5 gratuitamente.

Comparação dos caminhos gratuitos do Qwen 3.7

Caminho	Realmente gratuito?	O que você obtém	Principais limites	Melhor para
Qwen Chat (chat.qwen.ai)	Sim	Modelo de prévia completo, UI de chat, imagem e documento	Limites de taxa; ferramentas desativadas	Avaliar o modelo sem código
Arenas públicas	Sim	Comparação cega ou nomeada em caixa de chat	Sem API, sem arquivos, throughput compartilhado	Comparar modelos diretamente
Ollama ou LM Studio	Não para 3.7	Nada ainda; não há pesos do Qwen 3.7	Pesos não publicados	Use Qwen 3.6 localmente
OpenRouter e agregadores	Não para 3.7	Nenhum modelo Qwen 3.7 listado	Sem API pública disponível	Aguarde ou use modelos Qwen anteriores
Créditos Alibaba Cloud	Teste temporário	Chamadas reais de API dentro do crédito	Créditos expiram; depois é pago	Testar integração oficial

Decisão rápida

Use esta regra:

Quero testar a qualidade do Qwen 3.7 sem código
→ Qwen Chat

Quero comparar contra outros modelos
→ Arena pública

Quero rodar localmente
→ Não dá com Qwen 3.7; use Qwen 3.6

Quero API gratuita permanente
→ Não existe para Qwen 3.7

Quero testar a API oficial sem custo imediato
→ Créditos Alibaba Cloud, com limite e expiração

Conclusão

O acesso gratuito ao Qwen 3.7 ainda é limitado porque o modelo está em prévia.

O resumo prático:

Qwen Chat é o melhor caminho gratuito agora. Use conta gratuita, escolha Qwen3.7-Max-Preview ou Qwen3.7-Plus-Preview e avalie o modelo com prompts reais.
Arenas públicas são úteis para comparação. Elas não substituem API, mas ajudam a comparar respostas sem cadastro.
Você não pode rodar Qwen 3.7 localmente. Nenhum peso do Qwen 3.7 foi publicado.
Não há camada gratuita de API em agregadores. OpenRouter e similares ainda não listam Qwen 3.7.
Créditos da Alibaba Cloud são teste, não gratuidade permanente. Use para validar integração, mas acompanhe custos.

Quando a API do Qwen 3.7 estiver totalmente pública, as opções devem aumentar. Até lá, comece pelo Qwen Chat. Se for avançar para API, teste as chamadas no Apidog: envie a requisição, inspecione a resposta, salve como caso reutilizável e gere documentação para sua equipe. Você também pode baixar o Apidog gratuitamente.

Como Usar a API Qwen 3.7? Guia Completo

Lucas — Thu, 21 May 2026 08:56:14 +0000

A equipe Qwen da Alibaba lançou o Qwen3.7-Max-Preview em meados de maio de 2026, e a pergunta prática para desenvolvedores é: como chamar esse modelo a partir do seu próprio código? O modelo é um sistema de raciocínio carro-chefe com janela de contexto de 1 milhão de tokens e rastreamentos explícitos de cadeia de pensamento, útil para backends de agentes, análise de documentos longos e geração de código. Porém, como ainda está em “preview”, o acesso é restrito, a superfície da API pode mudar e você deve confirmar IDs de modelo e endpoints antes de colocar qualquer integração em produção.

Experimente o Apidog hoje

TL;DR

O Qwen3.7-Max-Preview é o modelo de raciocínio carro-chefe da Alibaba, lançado em prévia em 14 de maio de 2026, com janela de contexto de 1 milhão de tokens. Durante a prévia, a forma mais direta de testá-lo é pelo Qwen Chat (chat.qwen.ai). Para integração via API, o caminho é o Alibaba Cloud Model Studio, também conhecido como DashScope, usando um endpoint compatível com OpenAI: você configura uma URL base, envia sua chave como Bearer token e chama /chat/completions.

Como a camada 3.7 ainda está em prévia, confirme sempre o ID exato do modelo e o endpoint na documentação oficial antes de lançar. Enquanto a disponibilidade se estabiliza, use o Apidog para testar, documentar e simular o endpoint.

Como acessar o Qwen 3.7 agora

O Qwen disponibiliza modelos por diferentes interfaces, mas elas não ficam disponíveis ao mesmo tempo. No final de maio de 2026, o cenário prático é este:

1. Qwen Chat

Use chat.qwen.ai para avaliação rápida.

Passos:

Crie ou acesse uma conta Qwen.
Abra o seletor de modelos.
Escolha qwen3.7-max-preview, se disponível.
Ative o Modo de Pensamento para visualizar o raciocínio.

Esse caminho é gratuito, com limites de uso durante a prévia. Ele serve para testar prompts e entender o comportamento do modelo, mas não é uma API para integração.

2. Alibaba Cloud Model Studio / DashScope

Para integração real, use o Alibaba Cloud Model Studio. Ele expõe modelos Qwen por uma API compatível com OpenAI, o que permite reaproveitar código que já usa o SDK da OpenAI, alterando principalmente:

base_url
chave de API
model

Modelos como qwen3.6-max-preview e a família qwen-max já seguem esse padrão. A camada qwen3.7-max-preview pode ainda não estar disponível publicamente via API quando você ler este artigo, então valide a lista atual no console do Model Studio.

3. Endpoint compatível com OpenAI

A estrutura geral é:

POST {DASHSCOPE_BASE_URL}/chat/completions
Authorization: Bearer {DASHSCOPE_API_KEY}
Content-Type: application/json

Exemplo de URL base para Singapura:

https://dashscope-intl.aliyuncs.com/compatible-mode/v1

Como o identificador do modelo pode mudar durante a prévia, use a documentação oficial do Qwen e a lista de modelos do Model Studio como fonte da verdade.

Para uma alternativa de custo zero enquanto aguarda o acesso à API, veja também o guia sobre como usar o Qwen 3.7 gratuitamente.

Métodos de acesso em um relance

Método	Acesso à API	Custo	Melhor para
Qwen Chat (chat.qwen.ai)	Não	Gratuito, com limite de taxa	Avaliação rápida e teste de prompts
Alibaba Cloud Model Studio / DashScope	Sim, compatível com OpenAI	Pague por token	Integração em produção
Qwen no Hugging Face	Pesos, quando lançados	Gratuito em self-host	Modelos de peso aberto, não a prévia Max
Gateways de terceiros	Varia	Varia	Roteamento multi-modelo

Importante: modelos Qwen de peso aberto podem chegar ao Hugging Face, mas a camada Max-Preview é proprietária. Não espere pesos para download de qwen3.7-max-preview.

Obtendo uma chave de API do Qwen 3.7

O acesso à API passa por uma conta Alibaba Cloud.

Passos:

Crie uma conta Alibaba Cloud.
Acesse o console do Model Studio em modelstudio.console.alibabacloud.com.
Ative o Model Studio para sua conta e região.
Abra a seção de chaves de API.
Gere uma chave.
Copie a chave e armazene-a como segredo.

As chaves são restritas à região. Uma chave criada para Singapura não autentica contra o endpoint de Pequim.

Escolha a URL base correta:

Região	URL base
Singapura	`https://dashscope-intl.aliyuncs.com/compatible-mode/v1`
EUA (Virgínia)	`https://dashscope-us.aliyuncs.com/compatible-mode/v1`
Pequim (China)	`https://dashscope.aliyuncs.com/compatible-mode/v1`

Nunca commite a chave no repositório. Use variável de ambiente:

# macOS / Linux
export DASHSCOPE_API_KEY="sk-your-key-here"

# Windows PowerShell
setx DASHSCOPE_API_KEY "sk-your-key-here"

No código, leia DASHSCOPE_API_KEY em tempo de execução. Esse padrão facilita rotação de chaves e evita vazamento de segredo. O mesmo cuidado aparece em integrações com outros modelos, como no guia da API do Gemini 3.5.

Sua primeira requisição: Python, curl e JavaScript

O Model Studio expõe o Qwen por uma API compatível com OpenAI. Você pode usar:

SDK da OpenAI apontando para a URL base do DashScope
chamada HTTP direta

Antes de rodar os exemplos, confirme se qwen3.7-max-preview é o ID aceito pela API na sua região. Durante a prévia, uma camada anterior como qwen3.6-max-preview pode estar ativa enquanto a 3.7 ainda não foi liberada via API.

Python com o SDK da OpenAI

Instale:

pip install openai

Envie uma requisição:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["DASHSCOPE_API_KEY"],
    base_url="https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
)

response = client.chat.completions.create(
    model="qwen3.7-max-preview",
    messages=[
        {
            "role": "system",
            "content": "Você é um assistente de codificação preciso."
        },
        {
            "role": "user",
            "content": "Escreva uma função Python que inverte uma lista encadeada."
        },
    ],
)

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

A estrutura segue o padrão Chat Completions:

system: define comportamento e contexto
user: mensagem do usuário
choices[0].message.content: texto gerado pelo modelo

curl

Use curl para validar rapidamente chave, endpoint e ID do modelo:

curl 'https://dashscope-intl.aliyuncs.com/compatible-mode/v1/chat/completions' \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "qwen3.7-max-preview",
    "messages": [
      {
        "role": "user",
        "content": "Explique idempotência em APIs REST em duas frases."
      }
    ]
  }'

Se estiver tudo correto, a resposta será um JSON com a conclusão. Se falhar, verifique principalmente:

região do endpoint
chave de API
ID do modelo
permissão da conta para acessar a prévia

JavaScript / Node.js

Instale:

npm install openai

Exemplo:

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.DASHSCOPE_API_KEY,
  baseURL: "https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
});

const response = await client.chat.completions.create({
  model: "qwen3.7-max-preview",
  messages: [
    {
      role: "user",
      content: "Liste três desvantagens do GraphQL em relação ao REST.",
    },
  ],
});

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

A vantagem do endpoint compatível com OpenAI é manter a mesma estrutura de requisição em diferentes linguagens.

Respostas em streaming

Para interfaces voltadas ao usuário, prefira streaming. Assim você não espera a conclusão completa antes de exibir saída.

Em Python:

stream = client.chat.completions.create(
    model="qwen3.7-max-preview",
    messages=[
        {
            "role": "user",
            "content": "Resuma o teorema CAP."
        },
    ],
    stream=True,
)

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

Em Node.js:

const stream = await client.chat.completions.create({
  model: "qwen3.7-max-preview",
  messages: [
    {
      role: "user",
      content: "Resuma o teorema CAP.",
    },
  ],
  stream: true,
});

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

Streaming é especialmente útil em modelos de raciocínio, porque eles podem levar mais tempo antes de produzir a resposta final. Com streaming, você pode exibir progresso, um indicador de digitação ou a resposta conforme ela é gerada.

O parâmetro de raciocínio e pensamento

O Qwen3.7-Max-Preview é um modelo de raciocínio. Ele pode produzir uma cadeia de pensamento explícita em blocos <think> antes da resposta final. Isso pode ajudar em tarefas como:

matemática multi-passos
geração e revisão de código
planejamento
análise de documentos
depuração de raciocínio

Em modelos Qwen recentes servidos pelo DashScope, o comportamento de pensamento pode ser controlado por um flag como enable_thinking. Confirme o nome exato do parâmetro na referência atual da API, porque controles de raciocínio podem mudar entre versões.

Exemplo conceitual:

response = client.chat.completions.create(
    model="qwen3.7-max-preview",
    messages=[
        {
            "role": "user",
            "content": (
                "Um trem parte às 14h a uma velocidade média de 60 mph. "
                "Um segundo trem parte às 15h a 75 mph na mesma rota. "
                "Quando o segundo alcança o primeiro?"
            ),
        },
    ],
    extra_body={
        "enable_thinking": True
    },
)

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

Use esse recurso com critério:

Pensamento custa tokens e latência. O rastro de raciocínio é saída gerada.
Ative para problemas difíceis. Ele faz mais sentido em tarefas multi-passos.
Desative para tarefas simples. Classificação, formatação e respostas curtas normalmente não precisam disso.
Decida se vai exibir o rastro. Alguns produtos mostram <think>; outros removem e exibem apenas a resposta final.

Se você está comparando modelos de raciocínio, veja a análise Qwen 3.7 vs GPT-5.5 vs Opus 4.7. Para agentes que consomem muitos tokens, as técnicas do artigo sobre como reduzir custos de tokens de agentes também se aplicam.

Tratamento de erros e limites de taxa

Falhas comuns em uma integração com o Qwen:

Status HTTP	Significado	O que fazer
400	Requisição inválida: JSON malformado ou parâmetro inválido	Verifique corpo, ID do modelo e nomes dos campos
401	Chave de API inválida ou ausente	Confira a chave e se ela corresponde à região do endpoint
403	Sem acesso ao modelo	Confirme se sua conta tem acesso à prévia
404	Modelo não encontrado	Verifique se o ID do modelo existe na região usada
429	Limite de taxa ou cota excedida	Aplique retry com backoff e verifique limites da conta
500 / 503	Erro do lado do servidor	Tente novamente com backoff exponencial

Em modelos em prévia, 403 e 404 são mais frequentes porque acesso e identificadores ainda podem mudar. Se você receber esses erros, investigue primeiro permissão e model.

Exemplo de retry em Python:

import os
import time
from openai import OpenAI, RateLimitError, APIStatusError

client = OpenAI(
    api_key=os.environ["DASHSCOPE_API_KEY"],
    base_url="https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
)

def ask_qwen(prompt, max_retries=4):
    for attempt in range(max_retries):
        try:
            response = client.chat.completions.create(
                model="qwen3.7-max-preview",
                messages=[
                    {
                        "role": "user",
                        "content": prompt,
                    }
                ],
            )
            return response.choices[0].message.content

        except RateLimitError:
            wait = 2 ** attempt
            print(f"Limite de taxa atingido. Tentando novamente em {wait}s...")
            time.sleep(wait)

        except APIStatusError as e:
            print(f"Erro da API {e.status_code}: {e.message}")
            raise

    raise RuntimeError("Falha após tentativas")

Regra prática:

retry com backoff para 429 e 5xx
falha rápida para 400, 401, 403 e 404
logue o corpo do erro em ambiente de desenvolvimento
exponha mensagens seguras e genéricas para usuários finais

Testando e simulando a API do Qwen com Apidog

APIs em prévia são instáveis por natureza: acesso restrito, IDs de modelo em mudança e limites de taxa apertados. Em vez de testar apenas executando o aplicativo inteiro e lendo logs, isole o endpoint e valide cada requisição.

O Apidog ajuda nesse ciclo.

Um fluxo prático:

Crie uma requisição POST /chat/completions.
Configure a URL base do DashScope.
Adicione o header Authorization: Bearer {{DASHSCOPE_API_KEY}}.
Salve o corpo JSON com model e messages.
Execute testes manuais para validar resposta e erros.
Salve cenários reutilizáveis.
Crie uma simulação do endpoint enquanto a prévia real não está disponível.

Exemplo de corpo para salvar no Apidog:

{
  "model": "qwen3.7-max-preview",
  "messages": [
    {
      "role": "user",
      "content": "Explique cache aside em arquiteturas distribuídas."
    }
  ]
}

A simulação é especialmente útil durante a prévia. O servidor mock do Apidog pode retornar respostas realistas com base no esquema da API, sem depender da chave real, de limite de taxa ou da disponibilidade do modelo.

Assim, seu frontend, agente ou backend pode desenvolver contra um endpoint substituto. Quando a API real estiver pronta, você troca a URL base da simulação pela URL do DashScope e mantém a estrutura da requisição.

Para fluxos schema-first, veja o passo a passo do modo spec-first.

O mesmo padrão funciona para outras APIs de modelo, incluindo Qwen, Gemini e a API do ERNIE 5.1. Quanto mais instável for o endpoint real, mais valor você ganha ao testar e simular antes de integrar.

Conclusão

Chamar o Qwen 3.7 é simples quando você conhece o caminho: use o endpoint compatível com OpenAI do DashScope, configure a URL base correta, envie a chave como Bearer token e chame /chat/completions.

A parte difícil é a prévia: acesso restrito, IDs de modelo em mudança e disponibilidade variável. Por isso, confirme sempre a documentação oficial antes de lançar e mantenha seu código preparado para erros, retries e troca de modelo.

Pare de adivinhar o que o Qwen retorna e comece a testar o endpoint de forma controlada. Baixe o Apidog para projetar o endpoint do Qwen, enviar requisições reais, salvar cenários reutilizáveis e simular a API enquanto você constrói.

O Que é Qwen 3.7? Novo Modelo de IA da Alibaba

Lucas — Thu, 21 May 2026 08:51:16 +0000

A equipe Qwen da Alibaba lançou seu novo modelo carro-chefe, e a comunidade de IA já está testando onde ele se encaixa em fluxos reais de desenvolvimento. O Qwen3.7-Max apareceu primeiro em um placar público antes do anúncio oficial e depois foi apresentado na Alibaba Cloud Summit 2026. Ele mira casos de uso com agentes: tarefas longas, uso intensivo de ferramentas, janela de contexto de 1 milhão de tokens e bom desempenho em rankings públicos de inteligência.

Experimente o Apidog hoje

Se você desenvolve software, a pergunta prática não é apenas “quão bom é o modelo?”, mas “como eu testo, valido e integro isso com segurança?”. Em algum momento, você vai chamar o modelo por trás de uma API, validar respostas, simular retornos enquanto o app ainda está em desenvolvimento e observar falhas. É nesse ciclo que o Apidog ajuda. Este artigo foca no Qwen 3.7 para você decidir se ele deve entrar na sua pilha.

TL;DR

Qwen 3.7 é a nova família de modelos carro-chefe da Alibaba, liderada pelo Qwen3.7-Max-Preview.

Pontos principais:

Modelo proprietário de raciocínio.
Janela de contexto de 1 milhão de tokens.
Modo de pensamento estendido.
Pontuação relatada de 57 no Índice de Inteligência da Artificial Analysis.
Aproximadamente 1.475 Elo no placar de texto do LM Arena.
Em meados de maio de 2026, a variante Max estava em pré-visualização.
O acesso via API estava sendo implementado na Alibaba Cloud.
Nenhum modelo Qwen 3.7 de código aberto havia sido lançado ainda.

O que é Qwen 3.7?

Qwen 3.7 é a geração mais recente de grandes modelos de linguagem da Qwen, divisão de IA da Alibaba. O lançamento principal é o Qwen3.7-Max-Preview, descrito pela Alibaba como seu modelo de agente mais avançado até agora.

O sufixo Max indica a camada superior da família. Em gerações recentes, a Alibaba lançou um modelo Max como carro-chefe e variantes menores ou mais acessíveis em paralelo.

Na prática, o Qwen3.7-Max-Preview é um modelo de raciocínio. Isso significa que ele é projetado para trabalhar em problemas passo a passo antes de entregar uma resposta final. Esse tipo de comportamento costuma ser útil em tarefas como:

resolver problemas de lógica;
revisar e refatorar código;
planejar ações com ferramentas;
analisar grandes volumes de texto;
executar fluxos de agente com múltiplas etapas.

A contrapartida é custo e latência: raciocínio estendido geralmente consome mais tokens e demora mais do que uma resposta direta.

Duas datas são importantes:

O modelo apareceu no placar de texto do LM Arena por volta de 14 de maio de 2026, ainda com nome de pré-visualização.
O anúncio formal aconteceu na Alibaba Cloud Summit 2026, em 20 de maio, com chegada à plataforma de API da Alibaba em 19 de maio.

Como a versão disponível carrega o sufixo -Preview, trate detalhes de API, preço e disponibilidade como sujeitos a mudanças.

A linha de variantes do Qwen 3.7

Neste ponto, vale separar o que está confirmado do que ainda é especulação.

Confirmado

Qwen3.7-Max-Preview existe, foi anunciado e é o modelo principal da geração.
Ele é o foco das alegações de raciocínio, agentes e contexto longo.
Seus pesos são fechados.

Não confirmado

Qwen 3.7 Plus: gerações anteriores tiveram variantes Plus, mas nenhum Qwen3.7-Plus havia sido anunciado formalmente em meados de maio de 2026.
Modelos Qwen 3.7 open source: a Alibaba já abriu variantes de gerações anteriores, mas nenhum peso Qwen 3.7 estava disponível no GitHub da QwenLM ou no Hugging Face nesse período.

A leitura segura para desenvolvedores é simples: quando alguém fala em “Qwen 3.7” hoje, provavelmente está falando do Qwen3.7-Max-Preview, um modelo proprietário acessado via serviço hospedado.

Como pensar na janela de contexto de 1 milhão de tokens

O Qwen3.7-Max-Preview tem uma janela de contexto de 1 milhão de tokens, segundo a Artificial Analysis.

Essa janela representa o volume máximo de texto que o modelo pode considerar em uma única chamada, incluindo:

prompt do usuário;
histórico da conversa;
documentos colados no prompt;
trechos de código;
instruções de sistema;
resposta gerada.

Em termos práticos, 1 milhão de tokens pode comportar algo como:

um repositório de código de tamanho médio;
vários PDFs longos;
um histórico extenso de chat;
documentação interna de produto;
logs e rastros de execução.

Mas não use contexto longo por padrão. Para implementar com eficiência, aplique uma regra simples:

Use contexto mínimo por padrão.
Aumente o contexto apenas quando a tarefa realmente exigir.

Exemplo de estratégia:

1. Envie apenas os arquivos relevantes para uma tarefa de código.
2. Resuma documentos longos antes de reenviá-los.
3. Use busca ou RAG quando o conjunto de dados for grande, mas a pergunta for específica.
4. Reserve o contexto de 1M para análises globais, auditorias e tarefas de agente.

Duas ressalvas:

Contexto grande não garante atenção perfeita. Modelos podem perder detalhes quando a janela fica cheia.
Contexto grande custa caro. Cada token enviado pode ser cobrado.

A janela de 1 milhão de tokens coloca o Qwen 3.7 no mesmo patamar de modelos fronteira atuais, mas não elimina a necessidade de engenharia de prompt e controle de custo.

Modo de raciocínio e pensamento estendido

O Qwen3.7-Max-Preview é um modelo de raciocínio. Isso muda como você deve usá-lo em produção.

Para tarefas simples, como classificação curta ou reescrita pequena, o raciocínio estendido pode ser excesso. Para tarefas complexas, ele pode ser justamente o diferencial.

Use raciocínio estendido quando a tarefa envolver:

múltiplas etapas;
tomada de decisão;
análise de código;
uso de ferramentas;
planejamento;
verificação de hipóteses;
execução autônoma.

Evite em tarefas como:

normalização de texto;
extração simples de campos;
respostas curtas de FAQ;
classificação binária;
pequenos ajustes de copy.

Segundo a Artificial Analysis, durante a avaliação do Índice de Inteligência, o Qwen3.7-Max gerou cerca de 97 milhões de tokens, bem acima da média aproximada de 24 milhões para modelos no benchmark. Isso reforça um ponto prático: modelos de raciocínio podem ser mais caros e lentos.

Ao testar esse tipo de modelo, evite asserções frágeis baseadas no texto exato da explicação. Prefira validar:

campos estruturados;
resposta final;
formato JSON;
presença de decisões esperadas;
ausência de erros críticos;
consistência com regras de negócio.

Exemplo de contrato esperado para uma resposta estruturada:

{
  "decision": "approve | reject | needs_review",
  "confidence": 0.0,
  "reason": "string",
  "next_actions": ["string"]
}

Depois, valide o schema em vez de comparar texto livre linha por linha.

Para uma configuração prática de chamadas e inspeção de respostas, veja o guia sobre como usar a API Qwen 3.7.

Benchmarks do Qwen 3.7: onde ele se posiciona

Benchmarks de modelos recém-lançados precisam ser lidos com cuidado. Alguns vêm de terceiros independentes, outros vêm do fornecedor, e uma versão Preview pode mudar antes do lançamento estável.

Até meados de maio de 2026, estes eram os números relatados.

Índice de Inteligência da Artificial Analysis

O Índice de Inteligência da Artificial Analysis combina avaliações de raciocínio, conhecimento, matemática e codificação.

O Qwen3.7-Max obteve 57 pontos, segundo a Artificial Analysis. Esse resultado foi relatado como:

aumento de 5 pontos sobre os 52 do Qwen 3.6 Max Preview;
resultado #1 entre 218 modelos classificados no placar público.

Esse é um resultado forte, mas não deve ser usado sozinho para decisão de arquitetura. Um índice composto comprime vários aspectos em um único número.

Elo de texto do LM Arena

O LM Arena mede preferência humana. Usuários comparam duas respostas anônimas e escolhem a melhor. Esses votos geram uma classificação Elo.

O Qwen3.7-Max-Preview entrou no placar de texto do LM Arena com aproximadamente 1.475 Elo, ficando perto de #13 no geral, segundo a cobertura do placar.

Ele teve melhor posição em categorias específicas, incluindo matemática e codificação.

A diferença entre os dois rankings importa:

Índice de Inteligência mede desempenho em tarefas avaliadas.
LM Arena Elo mede preferência humana entre respostas.

Um modelo pode liderar em um e não dominar o outro. Esse parece ser o caso do Qwen 3.7: muito forte em pontuação composta, mas não necessariamente o preferido absoluto em respostas gerais.

Alegações de agente

A Alibaba destacou resultados relacionados a agentes, incluindo:

execução autônoma de tarefas por até 35 horas;
mais de 1.000 chamadas de ferramenta em uma única execução sem queda de desempenho.

Esses números devem ser tratados como alegações do fornecedor até que terceiros reproduzam os testes. Ainda assim, eles mostram claramente o posicionamento do modelo: tarefas longas, uso de ferramentas e execução de fluxos complexos.

Como o Qwen 3.7 se compara ao GPT-5.5, Claude Opus 4.7 e Gemini 3.5

A tabela abaixo resume a comparação em alto nível. Valores não confirmados ou não divulgados são mantidos assim para evitar extrapolação.

Especificação	Qwen3.7-Max-Preview	GPT-5.5	Claude Opus 4.7	Gemini 3.5
Fornecedor	Alibaba (Qwen)	OpenAI	Anthropic	Google DeepMind
Tipo	Modelo de raciocínio	Modelo de raciocínio	Modelo de raciocínio	Modelo de raciocínio
Janela de contexto	1M tokens	~1M tokens	~1M tokens (faixa relatada)	~1M+ tokens
Pesos	Proprietário	Proprietário	Proprietário	Proprietário
Índice de Inteligência AA	57 (relatado #1)	Não declarado aqui	Não declarado aqui	Não declarado aqui
Estágio de lançamento	Pré-visualização	Estável	Estável	Estável
Modo de raciocínio / pensamento	Sim	Sim	Sim	Sim
Principal força	Tarefas de agente de longo horizonte	Agentes autônomos, uso de ferramentas	Código com qualidade de produção	Contexto longo, eficiência de custo

Leitura prática:

Se você precisa de um modelo estável e globalmente disponível hoje, os modelos ocidentais podem ser mais previsíveis.
Se você quer testar raciocínio longo e agentes com forte pontuação composta, o Qwen3.7-Max merece avaliação.
Se você depende de auto-hospedagem, o Qwen 3.7 ainda não resolve isso, porque não havia pesos abertos.
Se seu caso envolve custo, disponibilidade regional ou integração com Alibaba Cloud, vale acompanhar a implementação da API.

Para uma comparação mais focada em números, veja Qwen 3.7 vs GPT-5.5 vs Opus 4.7.

Se sua avaliação inclui modelos do Google, veja também o que é Gemini 3.5 e Gemini 3.5 vs GPT-5.5 vs Opus 4.7.

Para acompanhar outros modelos chineses, o resumo sobre o que é ERNIE 5.1 cobre o carro-chefe concorrente da Baidu.

Como acessar o Qwen 3.7 hoje

Em meados de maio de 2026, existem dois caminhos práticos e um terceiro para acompanhar.

1. Qwen Chat

A forma mais rápida de testar é pela interface oficial:

https://chat.qwen.ai

Use esse caminho para:

testar prompts;
comparar respostas;
observar o modo de pensamento;
validar se o modelo serve para seu caso antes de escrever código.

Uma abordagem simples:

1. Escolha uma tarefa real do seu produto.
2. Execute o mesmo prompt no Qwen Chat.
3. Verifique qualidade, latência percebida e consistência.
4. Só depois leve o teste para API.

2. API da Alibaba Cloud

O Qwen3.7-Max chegou à plataforma de API da Alibaba em 19 de maio de 2026, com acesso mais amplo em implementação.

Como é uma versão de pré-visualização, verifique sempre a documentação atual da Alibaba Cloud para confirmar:

nome exato do modelo;
endpoint;
autenticação;
limites de uso;
preço;
disponibilidade regional;
formato de resposta;
suporte a modo de raciocínio.

Um fluxo de integração recomendado:

1. Crie uma chave de API na plataforma da Alibaba Cloud.
2. Configure uma chamada mínima para o modelo.
3. Defina um contrato de resposta esperado.
4. Registre prompts e respostas em ambiente de teste.
5. Adicione validação de schema.
6. Teste timeouts, retries e respostas inválidas.
7. Só então conecte ao fluxo principal do produto.

Exemplo genérico de estrutura para uma chamada de modelo via API:

curl -X POST "https://SEU_ENDPOINT_DE_MODELO" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.7-max-preview",
    "messages": [
      {
        "role": "system",
        "content": "Você é um assistente técnico. Responda em JSON válido."
      },
      {
        "role": "user",
        "content": "Analise este erro e sugira a causa provável."
      }
    ]
  }'

O endpoint e o payload exatos devem ser confirmados na documentação oficial da Alibaba Cloud, já que a disponibilidade de modelos em pré-visualização pode mudar.

Para um passo a passo mais detalhado, veja como usar a API Qwen 3.7.

3. Pesos abertos

Se o seu plano é auto-hospedar, a resposta honesta é: ainda não.

Em meados de maio de 2026:

nenhum modelo Qwen 3.7 open source havia sido lançado;
nenhum peso Qwen 3.7 estava disponível para download;
a variante Max era proprietária.

A Alibaba pode seguir o padrão de abrir variantes abaixo do carro-chefe, mas isso ainda não estava confirmado. Até lá, trate qualquer nome, tamanho ou data como especulação.

Para acompanhar opções gratuitas ou de baixo custo, veja o guia sobre como usar o Qwen 3.7 gratuitamente.

Como testar uma integração com Qwen 3.7

Antes de colocar um modelo de raciocínio em produção, defina critérios de aceitação. Isso evita avaliar respostas apenas “no olho”.

1. Defina o caso de uso

Exemplos:

- Revisar pull requests.
- Resumir documentos longos.
- Gerar planos de execução.
- Classificar tickets de suporte.
- Criar consultas SQL.
- Orquestrar ferramentas internas.

2. Escolha o formato de saída

Para aplicações, prefira resposta estruturada.

Exemplo:

{
  "summary": "string",
  "risk_level": "low | medium | high",
  "issues": [
    {
      "type": "string",
      "description": "string",
      "suggested_fix": "string"
    }
  ]
}

3. Valide o schema

Não dependa de texto livre se o resultado vai alimentar outro sistema.

Checklist:

[ ] A resposta é JSON válido?
[ ] Todos os campos obrigatórios existem?
[ ] Os enums usam valores permitidos?
[ ] A resposta cabe no limite de tamanho?
[ ] O modelo recusou quando deveria?
[ ] O modelo inventou dados?

4. Teste falhas

Inclua cenários negativos:

- prompt ambíguo;
- entrada muito longa;
- código incompleto;
- instruções conflitantes;
- dados malformados;
- timeout;
- resposta não JSON;
- resposta parcialmente correta.

5. Monitore custo e latência

Para modelos de raciocínio, acompanhe:

- tokens de entrada;
- tokens de saída;
- tempo total de resposta;
- taxa de erro;
- taxa de retries;
- custo por tarefa;
- qualidade por tipo de tarefa.

O Qwen 3.7 pode ser interessante para tarefas longas, mas você provavelmente não quer usá-lo para tudo. Uma arquitetura comum é rotear tarefas simples para modelos mais baratos e reservar o Qwen3.7-Max para fluxos complexos.

Onde o Apidog entra no fluxo

Qualquer integração com Qwen 3.7 vai passar por uma API. Você precisa projetar, testar e observar essas chamadas.

Com o Apidog, você pode:

criar uma coleção de requisições para o endpoint do modelo;
documentar headers, payloads e exemplos;
simular respostas enquanto o backend ainda não está pronto;
validar contratos de resposta;
executar testes automatizados;
inspecionar chamadas reais;
compartilhar a coleção com o time.

Um fluxo prático:

1. Crie uma requisição para o endpoint Qwen 3.7.
2. Configure autenticação e headers.
3. Salve exemplos de payload por caso de uso.
4. Defina exemplos de resposta esperada.
5. Adicione testes para status code, schema e campos críticos.
6. Execute a coleção em ambiente de teste.
7. Compare saídas entre versões de prompt.

Você também pode baixar o Apidog e montar uma coleção de requisições do Qwen 3.7 para validar sua integração antes de levá-la para produção.

Conclusão

Qwen 3.7 é uma entrada relevante na fronteira de IA, especialmente para desenvolvedores avaliando agentes e tarefas longas.

Resumo prático:

Qwen3.7-Max-Preview é o novo carro-chefe da Alibaba.
É um modelo proprietário de raciocínio com contexto de 1 milhão de tokens.
Obteve 57 pontos no Índice de Inteligência da Artificial Analysis, relatado como #1 nesse placar.
Ficou em torno de 1.475 Elo no texto do LM Arena.
O posicionamento principal é trabalho de agente: tarefas longas, uso de ferramentas e análise de grandes contextos.
Em meados de maio de 2026, ainda era uma versão de pré-visualização.
Nenhum peso aberto do Qwen 3.7 havia sido lançado.
Variantes, tamanhos e datas não confirmadas devem ser tratados como especulação.

Se o Qwen 3.7 entrar na sua lista de modelos, o próximo passo é testar com um caso real do seu produto. Defina o contrato de resposta, valide schema, monitore custo e latência, e compare resultados com alternativas.

O Apidog pode ajudar a transformar esse teste em uma integração controlada: requisições documentadas, mocks, testes automatizados e inspeção de chamadas em um só lugar.

Criar API Detector de Imagens IA com C2PA e Classificador

Lucas — Thu, 21 May 2026 08:17:48 +0000

Alguém envia uma foto para o seu produto e afirma que ela veio de uma câmera. Seu backend consegue validar isso? Em vez de “confiar nos olhos”, construa um endpoint que combine dois sinais independentes: um manifesto C2PA/Content Credentials validado criptograficamente e um classificador de imagem gerada por IA. O resultado é um veredito mais útil e auditável do que qualquer sinal isolado.

Experimente o Apidog hoje

Neste tutorial, você vai implementar um serviço FastAPI com POST /verify. Ele recebe uma imagem, tenta extrair e validar o manifesto C2PA, chama uma API hospedada de detecção de IA e retorna um JSON com veredito, confiança e sinais brutos. Como é uma API, também vamos desenhar o contrato OpenAPI primeiro e usar o Apidog para mockar e testar o endpoint antes do backend estar pronto.

TL;DR

Você vai construir:

um endpoint POST /verify com upload multipart/form-data;
leitura de Content Credentials com c2pa-python;
chamada a um classificador hospedado, como Sightengine;
uma função de decisão que retorna:
- provavelmente_autêntico;
- provavelmente_ia;
- incerto;
um contrato OpenAPI para mock e testes no Apidog.

Por que usar dois sinais?

Não existe uma propriedade única em um arquivo que prove “foi feito por humano” ou “foi feito por IA”. Existem pistas.

Sinal 1: proveniência C2PA

C2PA, da Coalition for Content Provenance and Authenticity, é um padrão aberto para anexar metadados assinados criptograficamente a arquivos de mídia. Esses metadados são conhecidos para usuários finais como Content Credentials.

Quando uma câmera, editor ou gerador compatível cria ou altera uma imagem, ele pode escrever um manifesto com o histórico da mídia e assiná-lo. Se o manifesto estiver presente e válido, você tem uma declaração forte sobre a origem e as transformações da imagem.

Limitação: C2PA é opt-in e frágil. Screenshots, recodificações e uploads em algumas plataformas podem remover o manifesto. Portanto, ausência de manifesto não significa que a imagem é falsa nem que é verdadeira.

Sinal 2: classificador estatístico

Um classificador analisa os pixels e estima a probabilidade de a imagem ter sido gerada por IA. Ele funciona mesmo sem metadados, mas retorna probabilidade, não prova.

Limitação: pode errar em imagens comprimidas, editadas ou fora da distribuição de treinamento.

A combinação ideal é:

“O que a criptografia prova, o que o modelo estima e quão forte é a conclusão combinada.”

Para entender melhor falhas de abordagem de sinal único, veja por que a detecção de imagem de IA falha.

Arquitetura

                ┌─────────────────────────────┐
   image  ──▶   │   FastAPI  POST /verify      │
                │                              │
                │   1. validate upload         │
                │   2. ┌──────────────────┐    │
                │      │ C2PA manifest     │    │  provenance signal
                │      │ c2pa-python       │    │
                │      └──────────────────┘    │
                │   3. ┌──────────────────┐    │
                │      │ classifier API    │    │  statistical signal
                │      │ hosted detector   │    │
                │      └──────────────────┘    │
                │   4. combine into verdict    │
                └─────────────────────────────┘
                              │
                              ▼
                   JSON verdict + confidence

O fluxo:

Validar tipo e tamanho do arquivo.
Ler o manifesto C2PA localmente.
Enviar a imagem para um classificador hospedado.
Combinar os sinais em um veredito único.

Instale as dependências:

pip install fastapi "uvicorn[standard]" python-multipart httpx c2pa-python

Requisitos principais:

Python 3.10+;
FastAPI;
Uvicorn;
python-multipart;
httpx;
c2pa-python.

Implementando o sinal C2PA

A Content Authenticity Initiative mantém ferramentas C2PA open source sob a organização contentauth.

Você verá dois nomes:

c2patool: CLI para inspecionar e adicionar manifestos. O repositório independente foi arquivado; a CLI vive no projeto Rust c2pa-rs.
c2pa-python: binding Python da biblioteca Rust c2pa-rs. É o que vamos usar no serviço.

Crie provenance.py:

# provenance.py
import json
import c2pa


def read_provenance(image_path: str) -> dict:
    """
    Lê e valida o manifesto C2PA de uma imagem.
    Retorna um dict normalizado com o que foi encontrado.
    """
    try:
        with c2pa.Reader(image_path) as reader:
            manifest_store = json.loads(reader.json())
    except c2pa.C2paError as err:
        if str(err).startswith("ManifestNotFound"):
            return {
                "has_manifest": False,
                "validation": "none",
                "detail": "Nenhum manifesto C2PA presente nesta imagem.",
            }

        return {
            "has_manifest": True,
            "validation": "error",
            "detail": f"Não foi possível analisar o manifesto: {err}",
        }

    active_label = manifest_store.get("active_manifest")
    manifests = manifest_store.get("manifests", {})
    active = manifests.get(active_label, {})

    validation_status = manifest_store.get("validation_status", [])
    validation = "valid" if not validation_status else "invalid"

    claim_generator = active.get("claim_generator", "unknown")
    signature_issuer = active.get("signature_info", {}).get("issuer", "unknown")

    return {
        "has_manifest": True,
        "validation": validation,
        "claim_generator": claim_generator,
        "signature_issuer": signature_issuer,
        "validation_status": validation_status,
        "detail": "Manifesto lido com sucesso.",
    }

Pontos importantes:

Reader é usado como context manager para liberar recursos corretamente.
reader.json() retorna o manifesto completo em JSON.
ManifestNotFound é esperado na maioria das imagens.
Manifesto ausente não é erro.
validation_status vazio indica validação bem-sucedida.
validation_status preenchido indica problema de assinatura, hash ou integridade.

Implementando o classificador

Este exemplo usa Sightengine porque a API HTTP é documentada e retorna uma pontuação clara em type.ai_generated.

O padrão é o mesmo para outros fornecedores: trocar URL, parâmetros e campo de leitura.

Para comparar alternativas, veja melhores APIs de detecção de imagem de IA.

Crie classifier.py:

# classifier.py
import httpx

SIGHTENGINE_URL = "https://api.sightengine.com/1.0/check.json"


async def classify_image(
    image_bytes: bytes,
    filename: str,
    api_user: str,
    api_secret: str,
    timeout_seconds: float = 8.0,
) -> dict:
    """
    Envia a imagem para o detector hospedado.
    Retorna um dict normalizado com a pontuação de IA.
    """
    data = {
        "models": "genai",
        "api_user": api_user,
        "api_secret": api_secret,
    }

    files = {
        "media": (filename, image_bytes),
    }

    try:
        async with httpx.AsyncClient(timeout=timeout_seconds) as client:
            response = await client.post(SIGHTENGINE_URL, data=data, files=files)
            response.raise_for_status()
            payload = response.json()
    except httpx.TimeoutException:
        return {"available": False, "reason": "classifier_timeout"}
    except httpx.HTTPStatusError as err:
        return {
            "available": False,
            "reason": f"classifier_http_{err.response.status_code}",
        }
    except httpx.HTTPError as err:
        return {"available": False, "reason": f"classifier_error: {err}"}

    if payload.get("status") != "success":
        return {
            "available": False,
            "reason": payload.get("error", {}).get("message", "unknown_error"),
        }

    ai_score = payload.get("type", {}).get("ai_generated")

    if ai_score is None:
        return {"available": False, "reason": "missing_score_in_response"}

    return {
        "available": True,
        "ai_score": float(ai_score),
    }

Decisões de implementação:

a função é assíncrona;
o timeout é explícito;
falhas retornam available: False;
uma falha do classificador não deve derrubar o endpoint;
a pontuação deve ser tratada como estimativa, não como prova.

Para contexto adicional, veja como verificar se uma imagem é gerada por IA.

Projetando o contrato `POST /verify`

Antes de escrever a rota, defina o contrato da API.

Com o Apidog, você pode:

criar o endpoint visualmente;
importar um arquivo OpenAPI;
gerar um servidor mock;
compartilhar o contrato com frontend;
salvar cenários de teste.

Request

POST /verify recebe multipart/form-data com um campo:

image: File

Response

Exemplo de resposta:

{
  "verdict": "provavelmente_ia",
  "confidence": 0.86,
  "signals": {
    "provenance": {
      "has_manifest": true,
      "validation": "valid",
      "claim_generator": "SomeImageTool/2.1",
      "signature_issuer": "Some Issuing CA"
    },
    "classifier": {
      "available": true,
      "ai_score": 0.91
    }
  },
  "explanation": "Um manifesto C2PA válido nomeia uma ferramenta de imagem de IA, e o classificador pontuou a imagem como provavelmente gerada por IA.",
  "checked_at": "2026-05-21T09:30:00Z"
}

verdict deve ser um destes valores:

provavelmente_autêntico;
provavelmente_ia;
incerto.

Use três estados. Quando os sinais discordam ou são fracos, incerto é o resultado correto.

Esquema OpenAPI

components:
  schemas:
    VerifyResponse:
      type: object
      required: [verdict, confidence, signals, checked_at]
      properties:
        verdict:
          type: string
          enum: [provavelmente_autêntico, provavelmente_ia, incerto]
        confidence:
          type: number
          format: float
          minimum: 0
          maximum: 1
        signals:
          type: object
          properties:
            provenance:
              type: object
              properties:
                has_manifest:
                  type: boolean
                validation:
                  type: string
                  enum: [valid, invalid, error, none]
                claim_generator:
                  type: string
                signature_issuer:
                  type: string
            classifier:
              type: object
              properties:
                available:
                  type: boolean
                ai_score:
                  type: number
                  format: float
        explanation:
          type: string
        checked_at:
          type: string
          format: date-time

Se você prefere um fluxo spec-first, veja o passo a passo do modo spec-first.

Combinando os sinais

Crie verdict.py:

# verdict.py


def combine_signals(provenance: dict, classifier: dict) -> dict:
    """
    Combina proveniência e classificador em um único veredito.
    """
    has_manifest = provenance.get("has_manifest", False)
    validation = provenance.get("validation", "none")
    generator = (provenance.get("claim_generator") or "").lower()

    classifier_ok = classifier.get("available", False)
    ai_score = classifier.get("ai_score")

    ai_keywords = (
        "firefly",
        "dall-e",
        "dalle",
        "midjourney",
        "stable",
        "gpt",
        "gemini",
        "imagen",
        "generat",
    )

    generator_looks_ai = any(keyword in generator for keyword in ai_keywords)

    # 1. Manifesto válido que nomeia uma ferramenta de IA.
    if has_manifest and validation == "valid" and generator_looks_ai:
        return _verdict(
            "provavelmente_ia",
            0.95,
            "Um manifesto C2PA válido nomeia uma ferramenta de imagem de IA.",
        )

    # 2. Manifesto válido de câmera ou ferramenta não-IA.
    if has_manifest and validation == "valid" and not generator_looks_ai:
        if classifier_ok and ai_score is not None and ai_score > 0.85:
            return _verdict(
                "incerto",
                0.55,
                "O manifesto parece autêntico, mas o classificador discorda.",
            )

        return _verdict(
            "provavelmente_autêntico",
            0.9,
            "Um manifesto C2PA válido de uma ferramenta não-IA está presente.",
        )

    # 3. Manifesto presente, mas inválido ou com erro.
    if has_manifest and validation in ("invalid", "error"):
        return _verdict(
            "incerto",
            0.6,
            "A imagem possui um manifesto C2PA que falhou na validação.",
        )

    # 4. Sem manifesto: usar classificador.
    if classifier_ok and ai_score is not None:
        if ai_score >= 0.7:
            return _verdict(
                "provavelmente_ia",
                round(ai_score, 2),
                "Sem dados de proveniência; o classificador pontuou a imagem como provavelmente gerada por IA.",
            )

        if ai_score <= 0.3:
            return _verdict(
                "provavelmente_autêntico",
                round(1 - ai_score, 2),
                "Sem dados de proveniência; o classificador pontuou a imagem como provavelmente autêntica.",
            )

        return _verdict(
            "incerto",
            0.5,
            "Sem dados de proveniência e a pontuação do classificador é inconclusiva.",
        )

    # 5. Sem manifesto e sem classificador.
    return _verdict(
        "incerto",
        0.0,
        "Sem dados de proveniência e o classificador estava indisponível.",
    )


def _verdict(verdict: str, confidence: float, explanation: str) -> dict:
    return {
        "verdict": verdict,
        "confidence": confidence,
        "explanation": explanation,
    }

Essa política é conservadora:

manifesto válido tem peso alto;
manifesto inválido não prova falsidade, mas gera alerta;
conflito entre sinais vira incerto;
sem sinais, a confiança é 0.0.

Ajuste os thresholds conforme seu risco. Uma rede social, uma seguradora e uma redação provavelmente terão políticas diferentes.

Criando o app FastAPI

Crie main.py:

# main.py
import os
import tempfile
from datetime import datetime, timezone

from fastapi import FastAPI, UploadFile, File, HTTPException
from fastapi.responses import JSONResponse

from provenance import read_provenance
from classifier import classify_image
from verdict import combine_signals

app = FastAPI(
    title="API de Detecção de Imagens de IA",
    version="1.0.0",
)

ALLOWED_TYPES = {"image/jpeg", "image/png", "image/webp"}
MAX_BYTES = 12 * 1024 * 1024

SIGHTENGINE_USER = os.environ.get("SIGHTENGINE_API_USER", "")
SIGHTENGINE_SECRET = os.environ.get("SIGHTENGINE_API_SECRET", "")


@app.post("/verify")
async def verify(image: UploadFile = File(...)):
    # 1. Validar tipo.
    if image.content_type not in ALLOWED_TYPES:
        raise HTTPException(
            status_code=415,
            detail=f"Tipo não suportado {image.content_type}. Envie JPEG, PNG ou WebP.",
        )

    # 2. Ler e validar tamanho.
    image_bytes = await image.read()

    if len(image_bytes) == 0:
        raise HTTPException(status_code=400, detail="Arquivo vazio.")

    if len(image_bytes) > MAX_BYTES:
        raise HTTPException(
            status_code=413,
            detail="O arquivo excede o limite de 12 MB.",
        )

    # 3. Ler proveniência.
    # c2pa-python precisa de um caminho de arquivo.
    suffix = os.path.splitext(image.filename or "")[1] or ".img"

    with tempfile.NamedTemporaryFile(suffix=suffix, delete=False) as tmp:
        tmp.write(image_bytes)
        tmp_path = tmp.name

    try:
        provenance = read_provenance(tmp_path)
    finally:
        os.unlink(tmp_path)

    # 4. Chamar classificador.
    if SIGHTENGINE_USER and SIGHTENGINE_SECRET:
        classifier = await classify_image(
            image_bytes=image_bytes,
            filename=image.filename or "upload",
            api_user=SIGHTENGINE_USER,
            api_secret=SIGHTENGINE_SECRET,
        )
    else:
        classifier = {
            "available": False,
            "reason": "classifier_not_configured",
        }

    # 5. Combinar sinais.
    result = combine_signals(provenance, classifier)

    return JSONResponse(
        {
            "verdict": result["verdict"],
            "confidence": result["confidence"],
            "signals": {
                "provenance": {
                    key: provenance.get(key)
                    for key in (
                        "has_manifest",
                        "validation",
                        "claim_generator",
                        "signature_issuer",
                    )
                },
                "classifier": {
                    "available": classifier.get("available", False),
                    "ai_score": classifier.get("ai_score"),
                },
            },
            "explanation": result["explanation"],
            "checked_at": datetime.now(timezone.utc).isoformat(),
        }
    )

Execute localmente:

uvicorn main:app --reload

Endpoint:

http://127.0.0.1:8000/verify

Configure as credenciais do classificador:

export SIGHTENGINE_API_USER="seu_usuario"
export SIGHTENGINE_API_SECRET="seu_secret"

Esse design segue um padrão comum de produto API-first: uma capacidade central exposta por uma API pequena e bem definida. Para contexto, veja software headless.

Testando com curl

Teste com uma imagem local:

curl -X POST http://127.0.0.1:8000/verify \
  -F "image=@./foto.jpg"

Resposta esperada:

{
  "verdict": "incerto",
  "confidence": 0.5,
  "signals": {
    "provenance": {
      "has_manifest": false,
      "validation": "none",
      "claim_generator": null,
      "signature_issuer": null
    },
    "classifier": {
      "available": true,
      "ai_score": 0.48
    }
  },
  "explanation": "Sem dados de proveniência e a pontuação do classificador é inconclusiva.",
  "checked_at": "2026-05-21T09:30:00+00:00"
}

Teste erro de tipo:

curl -X POST http://127.0.0.1:8000/verify \
  -F "image=@./arquivo.txt"

Se o content_type for detectado como não suportado, o endpoint retorna 415.

Mockando o endpoint no Apidog

O frontend não precisa esperar o backend ficar pronto.

Fluxo recomendado:

Crie o endpoint POST /verify no Apidog.
Defina o body como multipart/form-data.
Adicione o campo image como arquivo.
Defina o schema VerifyResponse.
Crie exemplos de resposta.
Gere o mock server.
Entregue a URL mock para o frontend.

Crie exemplos para:

provavelmente_autêntico com manifesto válido de câmera;
provavelmente_ia com manifesto que nomeia ferramenta de IA;
incerto com classificador indisponível;
erro 413 para arquivo grande;
erro 415 para tipo não suportado.

Assim, o frontend consegue implementar upload, loading, estados de erro e painel de resultado antes do backend real existir.

Quando o backend for lançado, basta trocar a base URL.

Testando o backend real no Apidog

Depois que o serviço estiver rodando:

Crie uma request POST /verify.
Aponte para http://127.0.0.1:8000/verify.
Em Body, escolha form-data.
Adicione image.
Defina o tipo como File.
Selecione uma imagem local.
Envie.

Adicione asserções:

status HTTP é 200;
verdict existe;
verdict está entre provavelmente_autêntico, provavelmente_ia e incerto;
confidence é número entre 0 e 1;
signals.provenance.has_manifest é booleano;
signals.classifier.available é booleano.

Monte um cenário com múltiplos uploads:

imagem com Content Credentials;
JPEG comum sem manifesto;
arquivo grande;
arquivo não-imagem renomeado como .jpg;
imagem com classificador indisponível.

Isso transforma testes manuais em uma suíte repetível.

Reforço e casos limite

Arquivos corrompidos

Um arquivo pode declarar image/jpeg e ainda assim ser inválido. Para reforçar, decodifique a imagem antes de processar.

Exemplo com Pillow:

pip install pillow

from PIL import Image, UnidentifiedImageError
from io import BytesIO


def validate_image_bytes(image_bytes: bytes) -> None:
    try:
        with Image.open(BytesIO(image_bytes)) as img:
            img.verify()
    except UnidentifiedImageError:
        raise ValueError("Arquivo não é uma imagem válida.")

Você pode chamar essa função antes da etapa C2PA e retornar 400 se falhar.

Manifesto ausente

Esse é o caso mais comum.

Não trate como erro. Não retorne 500. Não conclua que a imagem é falsa.

Siga para o classificador.

Classificador indisponível

Assuma que a dependência externa falhará.

Boas práticas:

timeout curto;
tratamento de erro HTTP;
retorno available: False;
veredito degradado para incerto quando necessário.

Manifesto inválido

Manifesto presente não significa manifesto confiável.

Sempre verifique validation_status.

array vazio: manifesto validado;
array preenchido: falha de validação.

Um manifesto inválido deve gerar alerta, não prova automática.

Arquivos grandes e abuso

Aplique:

limite de tamanho;
rate limiting;
autenticação se o endpoint não for público;
observabilidade por status e motivo de falha;
limites de timeout em chamadas externas.

O exemplo usa 12 MB:

MAX_BYTES = 12 * 1024 * 1024

Privacidade

Você está processando imagens de usuários.

Evite:

logar bytes da imagem;
persistir arquivos temporários;
enviar imagens a terceiros sem consentimento ou base legal;
esconder o uso de classificador externo da política de privacidade.

O que cada sinal detecta e perde

Cenário	Sinal de proveniência C2PA	Sinal do classificador
Imagem de IA de ferramenta que escreve Content Credentials	Detecta: manifesto nomeia o gerador	Geralmente detecta artefatos
Imagem de IA com metadados removidos	Perde: nenhum manifesto	Detecta pelos pixels
Foto real de câmera que assina Content Credentials	Confirma manifesto válido	Pode dar falso positivo
Foto real sem metadados	Sem sinal	Melhor palpite probabilístico
Imagem com manifesto forjado ou adulterado	Detecta via `validation_status`	Pode ou não detectar
Gerador novo fora do treino do classificador	Detecta apenas se houver manifesto	Pode falhar
Foto real fortemente editada com IA	Manifesto pode registrar histórico	Pode ficar ambíguo

A proveniência é precisa, mas esparsa. O classificador é amplo, mas probabilístico. O veredito combinado é mais útil do que qualquer coluna sozinha.

Casos de uso

Plataformas de conteúdo gerado por usuário

Use /verify no upload e mapeie resultados:

provavelmente_autêntico: permitir;
provavelmente_ia: rotular ou revisar;
incerto: enviar para revisão humana.

Redações e fact-checking

Um editor pode obter em uma única chamada:

manifesto C2PA, se houver;
validação criptográfica;
pontuação do classificador;
explicação legível.

Seguros e sinistros

Antes de um analista humano revisar evidências fotográficas, o sistema pode sinalizar:

imagens provavelmente geradas;
manifestos adulterados;
ausência de sinais fortes.

Pipelines internos de assets

Equipes que precisam manter imagens de IA fora de bibliotecas internas podem usar o endpoint como gate de ingestão.

CMS com proveniência

À medida que mais câmeras e editores adotam Content Credentials, um CMS pode exibir selos de proveniência verificada e recorrer ao classificador quando não houver manifesto.

Conclusão

Detectar imagens geradas por IA não exige um teste perfeito. Exige combinar sinais independentes e comunicar incerteza.

Neste tutorial, você implementou:

leitura e validação de manifesto C2PA;
chamada a classificador hospedado;
função de decisão com três vereditos;
endpoint FastAPI POST /verify;
contrato OpenAPI;
mock e testes com Apidog.

O ponto principal: incerto não é falha do produto. É uma resposta honesta quando os sinais não sustentam uma conclusão forte.

Para construir isso com menos bloqueio entre backend e frontend, modele o contrato /verify, gere um mock server e salve cenários de teste no Apidog.

Como Verificar se uma Imagem é Gerada por IA (Guia 2026)

Lucas — Thu, 21 May 2026 06:13:16 +0000

A OpenAI publicou o post "Avançando a proveniência de conteúdo para um ecossistema de IA mais seguro e transparente". O anúncio reúne quatro mudanças importantes para quem precisa verificar imagens: participação no Comitê Diretor do C2PA, uso da marca d'água SynthID do Google em imagens geradas, prévia de uma ferramenta pública para identificar imagens da OpenAI e acesso a um classificador de detecção de imagens DALL-E 3 pelo Programa de Acesso a Pesquisadores.

Experimente o Apidog hoje

Se você desenvolve produtos que recebem imagens de usuários, a pergunta prática é: como integrar uma verificação confiável no seu fluxo? A resposta curta é usar uma pilha de métodos: metadados de proveniência, marcas d'água, classificadores, inspeção visual e busca reversa.

💡 Se você é desenvolvedor, “verificar uma imagem” normalmente significa chamar uma API de detecção, validar a resposta e decidir como seu produto deve reagir. Esse tipo de integração pode ser modelado, testado e depurado no Apidog antes de ir para produção.

TL;DR

Para verificar se uma imagem foi gerada por IA, siga esta ordem:

Obtenha o arquivo original. Capturas de tela e arquivos reenviados podem remover metadados importantes.
Verifique Credenciais de Conteúdo C2PA. Procure um manifesto assinado de origem e edição.
Escaneie marcas d'água invisíveis. Use detectores como o SynthID para identificar conteúdo de modelos compatíveis.
Execute um classificador ou API de detecção. Use a pontuação como probabilidade, não como veredito.
Faça inspeção visual. Procure erros em mãos, texto, reflexos, sombras e detalhes.
Use busca reversa de imagem. Verifique onde a imagem apareceu primeiro.
Combine as evidências. Retorne um nível de confiança: alto, médio, baixo ou indeterminado.

Nenhum método isolado é conclusivo. C2PA e marcas d'água são fortes quando presentes, mas podem estar ausentes. Classificadores funcionam em mais casos, mas geram falsos positivos. A decisão deve ser baseada em evidências combinadas.

Por que detectar imagens de IA é difícil

Modelos atuais geram imagens muito melhores do que os de poucos anos atrás. Erros clássicos como seis dedos, texto ilegível e acessórios derretidos ainda aparecem, mas são menos confiáveis como sinal.

Por isso, a indústria avançou para duas abordagens mais robustas:

Proveniência: anexar ao arquivo um histórico assinado de criação e edição.
Marca d'água invisível: inserir um sinal estatístico nos pixels.

Ambas dependem da cooperação do gerador. Ambas podem falhar se a imagem for recodificada, capturada por tela, editada agressivamente ou gerada por um modelo sem suporte.

A melhor estratégia é executar os métodos em camadas. Se um método forte retorna positivo, você pode ter alta confiança. Se todos retornam vazio ou discordam, o resultado correto é indeterminado.

Método 1: verificar Credenciais de Conteúdo C2PA

C2PA significa Coalition for Content Provenance and Authenticity. É um padrão aberto, apoiado por empresas como Adobe, Microsoft, Google, OpenAI, BBC e fabricantes de câmeras.

Na prática, o C2PA adiciona ao arquivo um manifesto assinado criptograficamente. Esse manifesto pode indicar:

qual ferramenta criou a imagem;
quando ela foi criada;
se houve uso de IA;
quais edições foram feitas;
se o histórico foi adulterado.

A marca voltada ao usuário é Credenciais de Conteúdo.

Como verificar C2PA

Peça o arquivo original.
Abra um verificador como contentcredentials.org.
Arraste ou carregue a imagem.
Leia o resultado.

Você pode encontrar três situações:

Manifesto válido: há dados verificáveis de origem e edição.
Sem Credenciais de Conteúdo: o arquivo não contém manifesto.
Manifesto inválido ou adulterado: os dados existem, mas a integridade falhou.

Um manifesto válido com indicação de IA é uma evidência forte de que a imagem foi gerada ou editada por IA. Um manifesto válido de câmera pode ser uma evidência forte de fotografia real, desde que o histórico faça sentido.

Limitações do C2PA

O C2PA é forte, mas frágil. Ele pode ser perdido por:

capturas de tela;
conversões de formato;
operações de “salvar como”;
uploads em plataformas que removem metadados;
remoção deliberada.

Também há uma limitação conceitual: o C2PA verifica a integridade do manifesto, não a verdade da cena. Uma imagem encenada pode ter um manifesto válido.

Use C2PA como evidência de origem e edição, não como prova absoluta de realidade.

Método 2: detectar marcas d'água invisíveis como SynthID

O SynthID, do Google DeepMind, insere um sinal imperceptível nos pixels de imagens geradas por modelos compatíveis, como Gemini e Imagen.

A vantagem sobre metadados é que o sinal está nos pixels. Ele pode sobreviver a:

capturas de tela;
cortes;
compressão;
ajustes de cor;
salvamentos sucessivos.

Segundo o Google, o SynthID já foi aplicado a bilhões de conteúdos de IA em diferentes formatos. Com o anúncio da OpenAI, imagens geradas pela OpenAI também passam a usar SynthID, aumentando a cobertura do detector.

Como verificar SynthID

Abra o portal público do Detector SynthID.
Envie a imagem.
Verifique se há marca d'água detectada.
Se disponível, analise as regiões destacadas como mais prováveis.

Você pode ler mais na página SynthID do Google DeepMind.

Limitações do SynthID

A detecção por marca d'água é assimétrica:

resultado positivo: forte evidência de IA;
resultado negativo: não prova que a imagem é humana.

Motivos:

o SynthID só detecta modelos que usam SynthID;
modelos como Midjourney, Stable Diffusion ou modelos próprios podem não usar essa marca;
edições agressivas podem degradar o sinal;
modelos de código aberto podem ser executados sem marca d'água.

Use SynthID como um “sim” forte quando positivo, mas não como um “não” quando negativo.

Método 3: usar um classificador ou API de detecção de ML

Quando não há C2PA nem marca d'água detectável, use um classificador de detecção.

Esses modelos são treinados com imagens reais e sintéticas para identificar padrões estatísticos, como:

ausência de ruído natural de sensor;
artefatos em domínio de frequência;
texturas geradas;
padrões invisíveis ao olho humano.

O retorno normalmente é uma probabilidade, por exemplo:

{
  "ai_probability": 0.87,
  "label": "likely_ai_generated"
}

Esse resultado significa “87% provável de ter sido gerado por IA”, não “é falso”.

Exemplo de fluxo com API

Um endpoint típico pode funcionar assim:

curl -X POST "https://api.exemplo.com/v1/detect-image" \
  -H "Authorization: Bearer $API_KEY" \
  -F "image=@foto.jpg"

Resposta esperada:

{
  "prediction": "ai_generated",
  "confidence": 0.94,
  "model": "image-detector-v3"
}

No seu backend, evite decisões binárias simples. Prefira faixas:

function classifyDetection(score) {
  if (score >= 0.9) return "alta_confiança_ia";
  if (score >= 0.65) return "possível_ia";
  if (score <= 0.2) return "provável_real";
  return "indeterminado";
}

Para desenvolvedores avaliando provedores, este resumo das melhores APIs de detecção de imagem de IA para desenvolvedores compara precisão, preços e modelos suportados.

Se você preferir controlar o pipeline, este guia sobre como criar sua própria API de detecção de imagem de IA cobre treinamento e disponibilização de um classificador.

Você pode configurar e reproduzir chamadas de teste no Apidog, usando ambientes salvos para validar se a API responde da mesma forma em desenvolvimento, staging e produção. Se a detecção estiver conectada a um agente de IA, o depurador de agente de IA do Apidog ajuda a rastrear o que o modelo enviou e recebeu.

Limitações dos classificadores

Classificadores são úteis, mas probabilísticos.

Principais riscos:

Falsos positivos: fotos reais podem ser marcadas como IA.
Modelos novos: detectores podem falhar em geradores lançados depois do treinamento.
Edições adversárias: recompressão, ruído e filtros podem alterar a pontuação.
Pontuação intermediária: 60% ou 70% geralmente significa incerteza.

Nunca acuse alguém de fraude, plágio ou manipulação com base em uma única pontuação.

Veja mais em: por que a detecção de imagem por IA falha.

Método 4: inspeção visual manual

Use inspeção visual como apoio, não como prova principal.

Procure por:

Mãos e dedos: dedos extras, fundidos ou dobrados de forma incorreta.
Texto: placas, livros e logotipos com letras distorcidas.
Dentes e joias: padrões irregulares, brincos diferentes, correntes fundidas.
Acessórios: óculos, relógios e cintos conectados de forma ilógica.
Reflexos: espelhos, água e óculos de sol que não refletem a cena.
Sombras: direções inconsistentes ou iluminação impossível.
Fundos: objetos misturados, arquitetura incoerente, texturas repetidas.
Pele: aparência plástica, sem poros ou assimetria.
Dimensões: tamanhos de arquivo compatíveis com padrões conhecidos de geradores.

Regra prática

Um erro visual claro pode reforçar a hipótese de IA.

A ausência de erro visual não prova que a imagem é real.

Modelos de ponta já produzem mãos corretas, texto legível e iluminação consistente com frequência. Se alguém quiser enganar, provavelmente escolherá a melhor saída entre várias gerações.

Método 5: busca reversa de imagem

A busca reversa não detecta IA diretamente. Ela verifica histórico e contexto.

Use Google Imagens, TinEye ou serviço similar para procurar:

onde a imagem apareceu primeiro;
se há versões anteriores;
se ela vem de banco de imagens;
se está em portfólios de fotógrafos;
se aparece em comunidades de arte de IA;
se foi reutilizada em contexto falso.

Casos úteis:

uma imagem apresentada como notícia atual apareceu anos antes;
uma foto de perfil aparece em dezenas de contas não relacionadas;
a imagem vem de uma galeria “feita com Midjourney”;
não há nenhum rastro online de uma pessoa supostamente real.

Busca reversa é especialmente útil para detectar deturpação de contexto, mesmo quando a imagem não é gerada por IA.

Comparação dos métodos

Método	Confiabilidade	Detecta	Não detecta	Esforço / custo
Credenciais de Conteúdo C2PA	Máxima, quando presente	Origem, edição, envolvimento de IA, manifesto assinado	Capturas de tela, recodificação, metadados removidos	Baixo; ferramentas gratuitas no navegador
Marca d'água invisível, como SynthID	Alta, quando presente	Imagens de modelos com marca d'água compatível	Modelos sem marca d'água, arquivos muito degradados	Baixo; portal gratuito
Classificador / API de ML	Moderada; probabilística	Padrões estatísticos de IA em qualquer imagem	Modelos novos, edições adversárias, falsos positivos	Baixo a médio; ferramenta gratuita ou API paga
Inspeção visual manual	Baixa em modelos atuais	Erros óbvios em imagens fracas	Imagens bem geradas ou curadas	Baixo; requer prática
Busca reversa	Moderada; indireta	Origem, histórico, reutilização e contexto	Imagens novas nunca publicadas	Baixo; gratuito

Como combinar os métodos em um veredito

Use um fluxo de decisão simples:

Você tem o arquivo original?
- Sim: verifique C2PA.
- Não: registre que a evidência de proveniência pode ter sido perdida.
Há manifesto C2PA válido?
- IA declarada: alta confiança de IA.
- Câmera/fonte confiável sem IA: forte evidência de foto real.
- Sem manifesto: continue.
SynthID deu positivo?
- Sim: alta confiança de IA.
- Não: continue.
Classificador retornou pontuação extrema?
- Acima de ~90%: forte indício de IA, especialmente com outro sinal.
- Abaixo de ~20%: inclina para real.
- Meio do intervalo: indeterminado.
Há erros visuais claros?
- Sim: reforça IA.
- Não: não conclui nada.
Busca reversa confirma origem?
- Fonte humana confiável: reforça foto real.
- Galeria de IA ou prompt compartilhado: reforça IA.
- Contexto incompatível: indica manipulação ou uso enganoso.
Retorne nível de confiança.

Exemplo de saída para produto:

{
  "result": "likely_ai_generated",
  "confidence_level": "high",
  "evidence": [
    "SynthID positivo",
    "Classificador retornou 0.94",
    "Sem credenciais C2PA disponíveis"
  ],
  "recommendation": "enviar para revisão manual"
}

Evite respostas como:

{
  "result": "fake"
}

Prefira explicar a evidência.

Implementação sugerida em um produto

Se você está adicionando detecção de imagem a uma aplicação, um pipeline seguro pode ser:

flowchart TD
  A[Upload da imagem] --> B[Validar arquivo original]
  B --> C[Verificar C2PA]
  C --> D{C2PA conclusivo?}
  D -->|Sim| H[Gerar decisão com alta confiança]
  D -->|Não| E[Verificar SynthID]
  E --> F{SynthID positivo?}
  F -->|Sim| H
  F -->|Não| G[Chamar API de classificador]
  G --> I[Aplicar regras de pontuação]
  I --> J[Adicionar inspeção manual se necessário]
  J --> K[Registrar evidências e nível de confiança]

Uma estrutura mínima de decisão no backend:

function decideImageStatus({ c2pa, synthId, classifierScore }) {
  const evidence = [];

  if (c2pa?.aiGenerated === true) {
    evidence.push("C2PA indica geração por IA");
    return { status: "likely_ai_generated", confidence: "high", evidence };
  }

  if (c2pa?.cameraSource === true && c2pa?.valid === true) {
    evidence.push("C2PA válido indica origem de câmera");
    return { status: "likely_real", confidence: "high", evidence };
  }

  if (synthId?.detected === true) {
    evidence.push("SynthID detectado");
    return { status: "likely_ai_generated", confidence: "high", evidence };
  }

  if (classifierScore >= 0.9) {
    evidence.push(`Classificador alto: ${classifierScore}`);
    return { status: "likely_ai_generated", confidence: "medium", evidence };
  }

  if (classifierScore <= 0.2) {
    evidence.push(`Classificador baixo: ${classifierScore}`);
    return { status: "likely_real", confidence: "medium", evidence };
  }

  evidence.push(`Pontuação inconclusiva: ${classifierScore}`);
  return { status: "undetermined", confidence: "low", evidence };
}

O ponto principal: registre o motivo da decisão. Isso ajuda em auditoria, suporte e revisão humana.

Conclusão

Verificar se uma imagem foi gerada por IA em 2026 exige uma pilha de métodos, não uma única ferramenta.

Resumo prático:

Comece por C2PA, porque é o sinal mais forte quando presente.
Depois teste marcas d'água invisíveis, como SynthID.
Use classificadores de ML como probabilidade, não como veredito.
Use inspeção visual apenas para reforçar evidências claras.
Use busca reversa para validar origem e contexto.
Retorne sempre um nível de confiança.
Quando os sinais forem fracos ou conflitantes, diga indeterminado.

Se você está construindo esse fluxo em um produto, conecte uma API de detecção, teste com imagens reais e valide as respostas antes de automatizar decisões. Baixe o Apidog para projetar, depurar e testar essa integração em um único espaço de trabalho.

O que é DESIGN.md para Agentes de Programação?

Lucas — Thu, 21 May 2026 04:24:16 +0000

Agentes de codificação são rápidos, confiantes e inicialmente alheios à arquitetura da sua base de código. Se você entregar ao Claude Code, Codex ou Cursor um ticket vago, ele pode gerar código que compila, passa em testes simples e ainda assim viola limites importantes entre domínio, aplicação, infraestrutura e HTTP. Um DESIGN.md reduz esse risco ao registrar a intenção arquitetônica no lugar onde o agente realmente pode ler: o próprio repositório.

Experimente o Apidog hoje

TL;DR

DESIGN.md é um arquivo Markdown no repositório que documenta decisões arquitetônicas, invariantes e restrições de design para humanos e agentes de codificação. Ele responde a:

Por que este sistema é estruturado dessa forma?

Enquanto isso:

README.md explica o que o projeto é e como começar.
AGENTS.md explica como agentes devem construir, testar e trabalhar no projeto.
CLAUDE.md contém instruções específicas para Claude Code.
DESIGN.md registra o raciocínio arquitetônico que não é óbvio lendo apenas o código.

Introdução

O problema aparece rápido em equipes que adotam agentes de codificação.

Você pede a um agente para adicionar um endpoint de reembolso em um serviço de pagamentos. Ele cria um handler funcional, chama o banco diretamente no controller, ignora um erro do gateway e inventa um novo tipo de moeda porque não percebeu que já existia um no domínio.

O diff parece limpo. Os testes passam. Mas o código está errado em pontos que só alguém com contexto arquitetônico percebe.

O agente não é necessariamente ruim em programar. Ele só não conhece decisões que vivem:

na cabeça de engenheiros seniores;
em páginas antigas do Notion;
em threads do Slack;
em ADRs esquecidos;
ou em padrões implícitos espalhados pelo código.

DESIGN.md resolve isso tornando explícitas as regras que o agente não consegue inferir com segurança.

O que `DESIGN.md` realmente é

DESIGN.md é um registro em texto puro do porquê seu código é organizado de determinada forma.

Ele não substitui o README, não é um tutorial de setup e não deve virar uma wiki genérica. Ele deve capturar decisões como:

“A camada de domínio nunca importa o framework web.”
“Dinheiro é sempre representado como inteiro em unidades menores, nunca float.”
“Chamadas ao gateway de pagamento passam pelo padrão outbox.”
“O agregado Account é o único caminho de escrita no livro-razão.”
“A especificação OpenAPI é a fonte de verdade para contratos de API.”

Essas regras são difíceis de inferir lendo arquivos isolados. O código mostra o resultado da decisão, mas não explica a decisão.

Um agente pode ver que Account.debit() existe. Mas, sem contexto, ele pode criar outro caminho de escrita para saldo porque não sabe que aquele método é deliberadamente o único ponto permitido.

A ideia tem relação com práticas conhecidas como ARCHITECTURE.md e ADRs. A diferença é o público: DESIGN.md é escrito para humanos e agentes de codificação. Por isso, deve ser:

direto;
declarativo;
fácil de escanear;
focado em invariantes;
mantido dentro do repositório.

`DESIGN.md` vs `AGENTS.md` vs `CLAUDE.md` vs `README.md`

Esses arquivos se complementam. Não coloque tudo em um só.

Arquivo	Público	Responde a	Frequência de mudança	Tamanho recomendado
`README.md`	Humanos	O que é o projeto e como começar	Muda com funcionalidades	Médio
`AGENTS.md`	Agentes de codificação	Como buildar, testar, lintar e contribuir	Muda com ferramentas	Curto
`CLAUDE.md`	Claude Code	Instruções específicas para Claude	Muda com ferramentas	Curto
`DESIGN.md`	Agentes, engenheiros e revisores	Por que a arquitetura é assim e o que não pode quebrar	Muda raramente	Médio e denso

O projeto agents.md descreve AGENTS.md como um formato aberto para orientar agentes de codificação. Ele é operacional: comandos, testes, estilo, convenções de commit.

A documentação de memória do Claude Code descreve CLAUDE.md como um arquivo de instruções para o Claude. Ela também recomenda manter esse arquivo curto. Se você já usa AGENTS.md, uma configuração comum é fazer o CLAUDE.md importar esse conteúdo.

Exemplo:

@AGENTS.md

O que não cabe bem em AGENTS.md ou CLAUDE.md é justificativa arquitetônica profunda. Para isso, use DESIGN.md.

Uma estrutura prática:

repo/
  README.md
  AGENTS.md
  CLAUDE.md
  DESIGN.md
  api/openapi.yaml
  src/

No AGENTS.md, adicione uma referência curta:

## Arquitetura

Antes de alterar camadas, contratos de API, persistência, transações ou integrações externas, leia `DESIGN.md`.

No CLAUDE.md, se necessário:

@AGENTS.md
@DESIGN.md

Se você quer estruturar melhor o contexto do Claude nesses arquivos, veja Fluxos de trabalho do Claude Code.

O que colocar em `DESIGN.md`

Inclua regras que um agente não consegue inferir com segurança do código.

Um bom DESIGN.md deve cobrir:

Forma do sistema
- camadas;
- módulos;
- direção das dependências.
Invariantes
- regras que devem ser sempre verdadeiras.
Decisões-chave e justificativa
- o que foi escolhido;
- por que foi escolhido.
Alternativas rejeitadas
- o que a equipe decidiu não fazer;
- por que não deve ser reintroduzido.
Regras de domínio e dados
- moeda;
- datas;
- IDs;
- soft delete;
- multi-tenancy.
Fonte de verdade do contrato da API
- onde está o OpenAPI;
- o que é gerado;
- o que não deve ser editado manualmente.
Onde colocar novo código
- mapa prático para endpoints, casos de uso, integrações e middlewares.
O que não tocar
- código gerado;
- módulos legados;
- migrações aplicadas.

Modelo de `DESIGN.md` para uma API de pagamentos

Use este modelo como ponto de partida:

# DESIGN.md: Serviço de API de Pagamentos

Este arquivo registra a intenção arquitetônica e as decisões por trás dela.

Leia antes de gerar ou modificar código. Se uma alteração entrar em conflito
com uma regra abaixo, sinalize o conflito em vez de contorná-lo.

## Forma do sistema

Arquitetura em camadas. Dependências apontam apenas para dentro:

http -> app -> domain <- infra

- `domain/` não importa `http/`, `app/` nem frameworks.
- `infra/` implementa interfaces declaradas em `domain/` ou `app/`.
- `http/` nunca acessa banco de dados ou gateway de pagamento diretamente.
- `http/` chama casos de uso em `app/`.

## Invariantes

- Uma entrada de livro-razão é imutável após escrita.
- Correções financeiras são novas entradas compensatórias.
- Saldo é derivado das entradas do livro-razão.
- Dinheiro é inteiro em unidades menores, mais código ISO-4217.
- Nunca use `float` para dinheiro.
- Toda chamada externa a gateway de pagamento é idempotente por `idempotency_key`.
- Saldos não ficam negativos sem uma `OverdraftPolicy` explícita.

## Decisões-chave

### Padrão Outbox para chamadas de gateway

Handlers escrevem uma intenção na mesma transação de banco da alteração de negócio.
Um worker processa essa intenção e chama o gateway.

Justificativa: o gateway pode expirar sob carga. Chamadas inline tornam latência,
retries e tratamento de falhas difíceis de controlar.

Regra: não chame o gateway diretamente de um handler HTTP.

### Único caminho de escrita por agregado

Apenas `Account.post_entry()` escreve no livro-razão.

Justificativa: múltiplos caminhos de escrita já causaram desvio de saldo.

Regra: adicione comportamento ao agregado, não queries paralelas de escrita.

## Alternativas rejeitadas

- Lazy-loading de ORM entre agregados.
- Saldo persistido como coluna mutável.
- Uso de `float` para valores monetários.
- Webhooks síncronos executados na thread da requisição.
- Edição manual de tipos gerados a partir do OpenAPI.

## Regras de dados e domínio

- Todos os timestamps são UTC.
- Timestamps são formatados como RFC 3339 na borda HTTP.
- IDs são ULIDs gerados na camada de aplicação.
- Soft delete não é usado.
- Toda query multi-tenant deve ter escopo por `tenant_id`.
- Um método de repositório sem escopo de tenant é bug.

## Contrato da API

- `api/openapi.yaml` é a fonte de verdade.
- Tipos de request/response são gerados a partir do OpenAPI.
- Não edite manualmente arquivos em `http/generated/`.
- Para endpoints novos ou alterados:
  1. atualize `api/openapi.yaml`;
  2. regenere os tipos;
  3. implemente o handler;
  4. adicione testes de contrato.

- Respostas de erro seguem RFC 9457 (`problem+json`).
- Use o helper `problem()`.
- Não crie envelopes de erro ad-hoc.

## Onde o novo código vai

- Novo endpoint:
  - rota em `http/routes/`;
  - DTO em `http/dto/`;
  - caso de uso em `app/usecases/`;
  - regra de negócio em `domain/`.

- Nova integração externa:
  - interface em `app/ports/`;
  - implementação em `infra/clients/`.

- Cross-cutting concerns:
  - autenticação, logging e idempotência ficam em middleware;
  - não implemente inline em handlers.

## Fora do escopo

- `http/generated/`: código gerado. Não editar manualmente.
- `legacy/billing_v1/`: congelado. Não estender.
- `migrations/`: nunca edite migração já aplicada. Crie uma nova.

## Em caso de dúvida

Se uma solicitação exigir quebrar uma regra deste arquivo, sinalize o conflito
e proponha a menor alternativa compatível com o design.

A seção “Em caso de dúvida” é importante. Ela diz ao agente como agir quando a tarefa conflita com a arquitetura. Sem isso, o agente tende a contornar a regra para completar o ticket.

Como agentes realmente consomem `DESIGN.md`

Agentes não têm um parser especial para DESIGN.md. Eles leem o arquivo como contexto.

Por isso, você precisa tornar o arquivo fácil de encontrar.

Para Claude Code

No CLAUDE.md:

@DESIGN.md

Ou, se você centraliza instruções em AGENTS.md:

@AGENTS.md
@DESIGN.md

Para agentes que usam `AGENTS.md`

No AGENTS.md:

## Design e arquitetura

Leia `DESIGN.md` antes de alterar:

- camadas;
- contratos de API;
- modelos de domínio;
- transações;
- integrações externas;
- persistência;
- autenticação;
- multi-tenancy.

Escreva para recuperação, não para leitura linear

Prefira:

- `http/` nunca acessa o banco diretamente.

Em vez de:

Idealmente, tentamos manter uma separação razoável entre a camada HTTP e as
partes internas do sistema, embora em alguns casos seja aceitável...

Agentes seguem melhor regras curtas, absolutas e testáveis.

Equipes que constroem fluxos autônomos com agentes dependem desse ciclo de contexto e correção. Veja também construa seu próprio Claude Code.

Antipadrões

1. Repetir o código

Evite frases como:

UserService gerencia usuários.

Isso o agente já vê no código.

Prefira registrar intenção:

`UserService` não aplica regras de autorização. Autorização fica em `app/policies/`.

2. Transformar `DESIGN.md` em tutorial

Comandos de setup, instruções de build e scripts pertencem a README.md, CONTRIBUTING.md ou AGENTS.md.

Não coloque isso em DESIGN.md:

npm install
npm run dev
npm test

3. Documentar aspiração como realidade

Errado:

O sistema usa CQRS.

Se apenas parte do sistema usa CQRS, escreva:

Meta: novas escritas passam por casos de uso em `app/usecases/`.

Atual: `legacy/` ainda possui handlers que acessam repositórios diretamente.
Não estenda esse padrão.

4. Não definir dono

Sem dono, o arquivo vira ficção.

Adicione ao template de PR:

- [ ] Esta mudança altera uma decisão em `DESIGN.md`?
- [ ] Se sim, atualizei `DESIGN.md` na mesma PR.

5. Sincronizar linha a linha com o código

Não tente documentar cada classe, função ou pacote. Isso apodrece rápido.

Documente decisões que mudam pouco:

limites de camada;
invariantes;
formatos de erro;
política de transação;
fonte de verdade do contrato;
regras de domínio.

6. Contradizer `AGENTS.md`

Evite duplicar regras operacionais em vários arquivos.

Bom:

AGENTS.md -> comandos, testes, lint, fluxo de contribuição
DESIGN.md -> arquitetura, invariantes, decisões

Ruim:

AGENTS.md diz para usar problem+json.
DESIGN.md diz para usar outro envelope de erro.

`DESIGN.md` para APIs e backend

Em APIs e serviços backend, DESIGN.md costuma ter alto impacto porque muitos erros de agentes acontecem em áreas invisíveis:

contratos HTTP;
idempotência;
transações;
consistência;
autenticação;
multi-tenancy;
paginação;
erros;
integrações externas.

Declare a fonte de verdade do contrato

Se sua API usa OpenAPI, seja explícito:

`api/openapi.yaml` é a fonte de verdade do contrato HTTP.
Handlers, DTOs, testes e documentação devem estar em conformidade com esse arquivo.

Também declare o que não fazer:

Não edite manualmente tipos gerados em `http/generated/`.
Atualize o OpenAPI, regenere os tipos e depois implemente.

Se você projeta o contrato primeiro no Apidog e exporta o OpenAPI para o repositório, o agente passa a ter um alvo claro. O raciocínio por trás de design-first para agentes é abordado em projetando APIs para agentes de IA.

Defina limites de transação

Exemplo:

Chamadas externas nunca acontecem dentro de uma transação de banco.
Use outbox para efeitos colaterais externos.

Sem essa regra, o agente tende a implementar a versão ingênua:

await db.transaction(async () => {
  await paymentGateway.charge(...)
  await orderRepository.markPaid(...)
})

A versão alinhada ao design seria:

await db.transaction(async () => {
  await orderRepository.markPaymentPending(orderId)

  await outboxRepository.enqueue({
    type: "payment.charge.requested",
    payload: {
      orderId,
      idempotencyKey,
    },
  })
})

Defina idempotência como invariante

Para pagamentos, pedidos e provisionamento, escreva:

Endpoints que criam efeitos externos devem exigir `Idempotency-Key`.
Retries com a mesma chave não podem duplicar cobrança, pedido ou provisionamento.

Padronize erros

Exemplo:

Todas as respostas de erro seguem RFC 9457 (`application/problem+json`).
Use o helper `problem()`.
Não crie formatos de erro específicos por endpoint.

Isso evita respostas inconsistentes como:

{ "error": "Invalid request" }

em um endpoint e:

{ "message": "Invalid request", "code": 400 }

em outro.

Proteja multi-tenancy

Exemplo:

Toda query deve ter escopo por `tenant_id`.
Um método de repositório sem `tenant_id` é bug de segurança.

Essa regra é crítica porque uma query isolada pode parecer correta, mas ainda assim vazar dados entre tenants.

Defina regras de versionamento

Exemplo:

Remover campo, renomear campo ou alterar semântica de resposta é breaking change.
Breaking changes exigem nova versão da API.
Campos novos opcionais são permitidos em versões menores.

Sem isso, agentes podem “limpar” respostas e quebrar clientes.

Exemplo de fluxo prático

Para adicionar um endpoint novo com agente:

Atualize o contrato OpenAPI.
Gere os tipos.
Peça ao agente para ler DESIGN.md.
Peça para implementar apenas nos locais definidos.
Rode testes.
Revise o diff contra os invariantes.

Prompt útil:

Leia `DESIGN.md` antes de implementar.

Adicione o endpoint POST /refunds conforme `api/openapi.yaml`.

Restrições:
- não edite arquivos gerados;
- não chame gateway diretamente do handler;
- use o padrão outbox;
- preserve idempotência por Idempotency-Key;
- use problem+json para erros.

Se alguma solicitação conflitar com `DESIGN.md`, pare e explique.

Esse tipo de prompt funciona melhor quando DESIGN.md já contém as regras como absolutos.

Para validar a API gerada contra o contrato, Baixe o Apidog e use o fluxo design-first com exportação OpenAPI, depuração e testes de endpoint.

Conclusão

DESIGN.md é um guardrail simples para agentes de codificação.

Use-o para registrar:

por que a arquitetura existe;
quais invariantes não podem ser quebrados;
quais alternativas já foram rejeitadas;
onde novos códigos devem ser colocados;
qual arquivo é a fonte de verdade do contrato da API.

Ele não substitui AGENTS.md, CLAUDE.md ou README.md. Ele complementa esses arquivos com o contexto que agentes normalmente não têm.

Para backend e APIs, o maior ganho é declarar a especificação OpenAPI como autoritativa. Assim, agentes deixam de inventar schemas e passam a implementar contra um contrato explícito.

Projete esse contrato primeiro. Baixe o Apidog para criar APIs com abordagem design-first, exportar OpenAPI e validar se endpoints gerados por agentes realmente seguem o contrato.

Perguntas Frequentes

`DESIGN.md` é um padrão oficial como `AGENTS.md`?

Não. AGENTS.md é um formato definido e amplamente adotado. DESIGN.md é uma convenção de comunidade, semelhante a ARCHITECTURE.md e ADRs.

Use como um padrão prático, não como uma especificação formal.

Preciso de `DESIGN.md` se já tenho `AGENTS.md` ou `CLAUDE.md`?

Sim, se sua arquitetura possui restrições não óbvias.

AGENTS.md e CLAUDE.md devem continuar curtos e operacionais. Coloque decisões arquitetônicas em DESIGN.md e apenas referencie esse arquivo.

Para o arquivo operacional, veja como escrever arquivos AGENTS.md.

Como `DESIGN.md` difere de `ARCHITECTURE.md`?

A diferença principal está no público e no estilo.

ARCHITECTURE.md costuma ser escrito para humanos. DESIGN.md é escrito para humanos e agentes, então tende a ser mais declarativo, mais focado em invariantes e mais fácil de usar como contexto em ferramentas de codificação.

Qual deve ser o tamanho de `DESIGN.md`?

O suficiente para cobrir decisões importantes. Curto o suficiente para cada linha importar.

Como regra prática:

2 a 4 páginas focadas funcionam bem;
listas são melhores que longos parágrafos;
invariantes são melhores que explicações genéricas;
corte qualquer coisa que apenas repita o código.

Como faço o agente realmente ler `DESIGN.md`?

Referencie-o no arquivo que o agente já carrega.

Para Claude Code:

@DESIGN.md

Para AGENTS.md:

Leia `DESIGN.md` antes de mudanças estruturais, contratos de API, persistência ou integrações externas.

O agente sempre seguirá `DESIGN.md`?

Não. Arquivos de instrução são contexto, não enforcement rígido.

Mas regras claras aumentam muito a chance de adesão. Além disso, revisores podem apontar violações diretamente:

Isso quebra a regra de caminho único de escrita em `DESIGN.md`.
Corrija mantendo o design.

Esse feedback costuma produzir correções melhores e mais rápidas.

`DESIGN.md` ajuda com contratos de API?

Sim. Um dos usos mais valiosos é declarar que a especificação OpenAPI é autoritativa.

Exemplo:

`api/openapi.yaml` é a fonte de verdade.
Não invente schemas no handler.
Não edite tipos gerados manualmente.

Projetar esse contrato primeiro em uma ferramenta como Apidog dá ao agente um alvo explícito.

Onde `DESIGN.md` deve ficar?

Na raiz do repositório:

repo/
  README.md
  AGENTS.md
  CLAUDE.md
  DESIGN.md

Em monorepos, use:

repo/
  DESIGN.md              # regras globais
  services/payments/DESIGN.md
  services/billing/DESIGN.md

O arquivo global define regras do sistema. Arquivos locais definem decisões específicas de cada serviço.

Como Usar o Claude Design Grátis?

Lucas — Thu, 21 May 2026 03:59:01 +0000

O Claude Design chamou atenção porque transforma um prompt em um pitch deck, landing page ou mockup mobile em segundos. O problema: é pago, roda na nuvem e fica preso ao ecossistema da Anthropic. Se você quer o mesmo fluxo de trabalho sem pagar pelo produto Claude Design, a alternativa prática é usar o Open Design localmente.

Experimente o Apidog hoje

O Open Design recria o fluxo de design baseado em artefatos, roda na sua máquina e pode usar agentes de IA que você já utiliza, como Claude Code, Codex, Gemini CLI ou Cursor. Neste guia, você verá como instalar, conectar um agente e transformar o protótipo gerado em algo mais próximo de um produto real usando APIs mockadas com o Apidog.

💡 Uma ferramenta de design gera a interface. Para transformar essa interface em produto, você precisa conectá-la a dados reais ou simulados. É aí que uma plataforma de API como o Apidog entra no fluxo.

TL;DR: como usar o Claude Design gratuitamente

Claude Design é uma ferramenta paga e fechada da Anthropic. Para obter uma experiência parecida gratuitamente, instale o Open Design, uma alternativa open source Apache-2.0 com mais de 48.000 estrelas no GitHub.

O Open Design:

roda localmente, via Docker ou auto-hospedado;
usa um agente de codificação como motor de IA;
suporta Claude Code, Codex, Gemini CLI, Cursor Agent, OpenCode, Qwen, GitHub Copilot CLI e outros;
exporta artefatos para HTML, PDF, PPTX, ZIP, Markdown e MP4;
não cobra pelo software.

Você paga apenas pelo modelo de IA usado. Se apontar o Open Design para um agente que você já assina ou para um modelo local via Ollama, o custo adicional pode ser zero.

A ressalva: você não está usando o Claude Design oficial

Claude Design é um produto da Anthropic. Ele roda na nuvem, tem código fechado e não oferece auto-hospedagem nem troca livre de modelo.

Portanto, “usar Claude Design gratuitamente” normalmente significa uma destas duas coisas:

obter o mesmo fluxo de trabalho: descrever um design e receber um artefato pronto;
manter controle sobre dados, hospedagem e modelo de IA.

O Open Design resolve esses dois pontos. Ele não é o Claude Design oficial, mas implementa um fluxo semelhante com uma arquitetura aberta.

O que é Open Design?

Open Design, ou OD, é um ambiente de design local-first e open source. O repositório GitHub o descreve como uma alternativa aberta e nativa de agentes ao Claude Design.

A arquitetura tem três partes:

Camada	Função
Front-end web	Interface de chat e canvas, construída em Next.js
Daemon local	Servidor Node.js com SQLite para projetos, conversas e artefatos
Runtime de agente	Executa um agente CLI de codificação dentro da pasta do projeto

A parte mais importante é o runtime de agente. O Open Design não traz um modelo próprio. Ele detecta agentes instalados no seu PATH e usa esses agentes para gerar arquivos, layouts e artefatos.

Exemplos de agentes compatíveis:

Claude Code
Codex
Cursor Agent
Gemini CLI
OpenCode
Qwen
GitHub Copilot CLI
Kimi

Se você quer entender melhor esse tipo de arquitetura, leia também sobre a arquitetura de harness do agente Claude Code.

O Open Design também inclui:

habilidades para tipos de entrega, como dashboards, landing pages, apps mobile, e-mails, decks e carrosséis;
sistemas de design inspirados em estilos como Linear, Stripe, Vercel, Notion e Apple;
preview em iframe sandboxed;
exportação para HTML, PDF, PPTX, ZIP, Markdown e MP4.

Essa abordagem de guiar agentes com arquivos estruturados é parecida com o uso de arquivos DESIGN.md para agentes de codificação.

Como instalar o Open Design

Você pode instalar o Open Design de três formas. Escolha conforme seu nível de controle.

Opção 1: aplicativo desktop

Use esta opção se você quer começar rápido, sem terminal.

Acesse open-design.ai ou a página de releases no GitHub.
Baixe o instalador para macOS ou Windows.
Instale e abra o aplicativo.

Na primeira execução, o aplicativo:

verifica agentes de codificação instalados;
carrega habilidades e sistemas de design;
cria a pasta de runtime para os projetos.

Essa é a melhor opção para designers, PMs ou devs que só querem testar o fluxo.

Opção 2: Docker

Use Docker se você quer uma instalação isolada, reproduzível ou compartilhada em uma máquina da equipe.

git clone https://github.com/nexu-io/open-design.git
cd open-design/deploy
docker compose up -d

Depois, abra:

http://localhost:7456

Se precisar revisar o básico de docker compose, consulte a documentação oficial do Docker.

Opção 3: a partir do código-fonte

Use esta opção se você quer modificar habilidades, sistemas de design ou acompanhar a branch main.

Pré-requisitos:

Node.js próximo da versão 24;
pnpm 10.33.x.

Instalação:

git clone https://github.com/nexu-io/open-design.git
cd open-design
corepack enable
corepack pnpm --version    # confirme se retorna 10.33.x
pnpm install
pnpm tools-dev run web

Comandos úteis:

Comando	O que faz
`pnpm tools-dev run web`	Inicia daemon e web em primeiro plano
`pnpm tools-dev start web`	Inicia daemon e web em segundo plano
`pnpm tools-dev status`	Mostra serviços em execução
`pnpm tools-dev logs`	Acompanha logs
`pnpm tools-dev stop`	Para tudo

Se você ainda não usa pnpm, o corepack enable ajuda a fixar a versão correta.

Como conectar um motor de IA

Depois de instalar, o Open Design precisa de um motor. Há dois caminhos principais.

Caminho A: usar um agente CLI

Este é o caminho recomendado para quem já usa ferramentas de IA no terminal.

Instale um agente suportado e confirme que ele está no PATH.

Exemplo:

which claude
which gemini
which codex

Se quiser uma experiência próxima ao Claude Design, use o Claude Code, pois ambos rodam sobre modelos da Anthropic. Codex, Gemini CLI e Cursor Agent seguem a mesma lógica.

O daemon do Open Design detecta o agente automaticamente. Você não precisa editar arquivos de configuração.

Se precisar configurar o Claude Code, veja o guia de configuração do SDK do agente Claude e plano Claude.

Caminho B: usar o proxy BYOK

Se você não quer instalar um agente CLI, use o proxy compatível com OpenAI incluído no Open Design.

Você pode conectar chaves de:

Anthropic;
OpenAI;
Azure OpenAI;
Google Gemini;
Ollama;
servidor local compatível.

Esse caminho cobra por token quando você usa APIs pagas. Trate as chaves com cuidado; as boas práticas de segurança de chaves de API em extensões de editor também se aplicam aqui.

Para custo zero real, conecte um modelo local via Ollama.

Gere seu primeiro artefato

Com o motor conectado, o fluxo é simples.

Escolha uma habilidade

Exemplos: landing page SaaS, dashboard, tela mobile, e-mail de marketing ou pitch deck.
Escolha um sistema de design

Você pode usar estilos inspirados em Linear, Stripe, Vercel, Notion ou Apple.

Se não escolher, o Open Design oferece direções visuais como Editorial, Minimal Moderno, Utilidade Tech, Brutalista e Quente Suave.
Escreva o briefing

Exemplo:

   Crie uma página de preços para uma ferramenta de API voltada a desenvolvedores.

Outro exemplo:

   Faça um pitch deck estilo revista para uma rodada seed de uma startup de infraestrutura dev.

Responda ao formulário de descoberta

O Open Design pergunta sobre público, tom, superfície, contexto de marca e objetivo. Não pule essa etapa.
Acompanhe o plano

O agente exibe uma lista de tarefas e marca os itens conforme trabalha.
Revise o preview

O resultado aparece em um iframe sandboxed. Esse isolamento é importante para código gerado por IA, como discutido em o que o CubeSandbox significa para agentes de IA.
Exporte

Use HTML, PDF, PPTX, ZIP, Markdown ou MP4, conforme o tipo de entrega.

Personalize habilidades e sistemas de design

Depois de gerar os primeiros artefatos, vale adaptar o Open Design ao seu fluxo.

Editar habilidades

Cada habilidade é uma pasta com um arquivo SKILL.md e ativos de suporte.

Você pode:

mudar checklists;
adicionar padrões de layout;
incluir regras específicas da sua empresa;
remover estilos que não fazem sentido para seu produto.

Na próxima geração, o agente seguirá sua versão.

Criar um sistema de design próprio

Um sistema de design no Open Design é um arquivo Markdown com regras de:

cores;
tipografia;
espaçamento;
componentes;
movimento;
tom de voz.

Fluxo prático:

Pegue as diretrizes da sua marca.
Transforme tokens e regras em Markdown.
Salve na pasta design-systems.
Gere novos artefatos usando esse sistema.

Isso evita repetir instruções de marca em todo prompt.

Trocar modelos com BYOK

O proxy BYOK permite alternar modelos conforme o trabalho:

modelo mais caro para apresentação de cliente;
modelo mais barato para rascunhos;
modelo local para experimentos offline.

Se você está comparando modelos, veja a comparação entre Gemini 3.5 vs GPT-5.5 vs Opus 4.7.

Usar o servidor MCP

O Open Design inclui um servidor Model Context Protocol. Outros agentes podem consultar seus arquivos de design, artefatos e sistemas de design sem exportação manual.

Isso permite um fluxo mais integrado:

o Open Design gera a interface;
outro agente lê o artefato;
o agente usa o contexto para implementar, refatorar ou conectar APIs.

Do protótipo ao produto com Apidog

O Open Design gera uma interface. Mas uma interface com dados hardcoded ainda é só um protótipo.

Exemplo: você gerou um dashboard com:

gráfico de uso;
painel de faturamento;
página de configurações;
tabela de eventos.

Para isso virar produto, você precisa de endpoints como:

GET /usage
GET /billing/invoices
GET /account/settings
GET /events

É aqui que o Apidog entra no fluxo.

Com o Apidog, você pode:

desenhar a API visualmente;
definir schemas em modo spec-first;
gerar uma especificação OpenAPI;
criar um mock server automaticamente;
testar endpoints antes do backend estar pronto.

Um fluxo prático:

Open Design → gera a UI
Apidog → define contratos de API
Apidog Mock Server → fornece dados realistas
Frontend → consome endpoints mockados
Backend → implementa seguindo a spec
Apidog Tests → valida regressões

Exemplo de contrato para um endpoint de uso:

{
  "period": "2026-05",
  "requests": 128430,
  "errors": 132,
  "latency_p95_ms": 241
}

Com um mock server, o front-end deixa de depender de dados fixos no componente e passa a consumir uma API realista.

Quando o backend estiver pronto, você usa o Apidog para testes automatizados e validação contínua. O modo spec-first no Apidog ajuda a manter design de API e implementação sincronizados.

O Apidog também inclui um depurador de agente de IA para inspecionar como agentes chamam seus endpoints.

A combinação fica direta:

Open Design para gerar o front-end;
Apidog para projetar, mockar e testar a API;
agente de IA para conectar as duas partes.

Você pode baixar o Apidog e criar o primeiro endpoint mockado enquanto o Open Design renderiza o primeiro artefato.

Open Design vs. Claude Design vs. Figma

Fator	Open Design	Claude Design	Figma
Preço	Grátis, Apache 2.0	Assinatura paga	Plano gratuito + planos pagos
Código-fonte	Aberto	Fechado	Fechado
Hospedagem	Local, auto-hospedado ou Vercel	Apenas nuvem	Nuvem
Motor de IA	Agente, BYOK ou modelo local	Modelos da Anthropic	Manual + recursos de IA
Saída	Código, decks, imagens, vídeo	Artefatos de design	Arquivos editáveis
Offline	Sim, com modelo local	Não	Limitado
Melhor para	Devs e equipes que querem controle	Experiência hospedada rápida	Design visual manual

Claude Design vence em conveniência. Figma vence em controle visual e colaboração madura. Open Design vence em liberdade, extensibilidade e controle de modelo.

Erros comuns

1. Não ter agente no `PATH`

Se o Open Design não encontra motor, verifique:

which claude
which gemini
which codex

Se nada aparecer, instale um agente suportado ou configure o proxy BYOK.

2. Usar versão errada de Node ou pnpm

Para instalação via código-fonte, use Node próximo da versão 24 e pnpm 10.33.x.

corepack enable
corepack pnpm --version

3. Esperar custo zero com API paga

O Open Design é gratuito. A API de modelo pode não ser.

Para custo zero adicional:

use um agente que você já assina;
use uma cota gratuita;
rode um modelo local via Ollama.

4. Pular o formulário de descoberta

O formulário melhora o primeiro rascunho. Responda com contexto suficiente sobre:

público;
objetivo;
tom;
marca;
restrições.

5. Tratar o preview como produção

A saída do Open Design é um ponto de partida. Antes de lançar:

revise o código;
remova placeholders;
conecte APIs reais ou mockadas;
adicione testes;
valide segurança e acessibilidade.

Para a camada de API, use testes de API para garantir que os endpoints continuem corretos.

6. Usar uma versão antiga

O Open Design evolui rápido. Se algo da documentação não aparece na sua instalação:

atualize o binário;
ou, se estiver usando código-fonte, puxe a branch main.

Conclusão

Você não consegue usar o produto Claude Design oficial gratuitamente. Mas consegue usar um fluxo parecido com o Open Design: escrever um briefing, gerar um artefato e exportar o resultado.

Resumo prático:

Open Design é uma alternativa open source Apache-2.0 ao fluxo do Claude Design.
Roda via app desktop, Docker ou código-fonte.
Usa agentes como Claude Code, Codex, Gemini CLI e Cursor.
Pode funcionar offline com Ollama.
Permite editar habilidades e sistemas de design em Markdown.
O protótipo gerado precisa de APIs para virar produto.
O Apidog ajuda a projetar, mockar e testar essas APIs.

Próximo passo: instale o Open Design, conecte um agente e gere uma interface. Depois baixe o Apidog, crie a API por trás desse artefato e inicie um mock server.

Segurança da Documentação API: Sua Especificação Está Segura no Git?

Lucas — Thu, 21 May 2026 03:54:21 +0000

A segurança da documentação da API costuma ficar fora das auditorias. A API recebe autenticação, rate limit e testes; já a especificação OpenAPI, o Swagger UI e os guias de autenticação muitas vezes ficam em um repositório Git ou host estático sem revisão contínua. Em 20 de maio de 2026, o GitHub confirmou que invasores roubaram dados de cerca de 3.800 repositórios internos após uma extensão VS Code maliciosa ser instalada no laptop de um funcionário. Use esse incidente como gatilho para uma checagem prática: se alguém alterasse silenciosamente sua documentação publicada, você perceberia antes que seus consumidores copiassem endpoints, tokens ou fluxos errados para produção?

Experimente o Apidog hoje

TL;DR

Documentação de API segura precisa de quatro propriedades verificáveis:

Controle de acesso: quem pode ler a documentação.
Versionamento: qual versão da API cada consumidor está usando.
Integridade: se o conteúdo publicado corresponde à fonte aprovada.
Trilha de auditoria: quem alterou o quê e quando.

Docs-as-code no Git funciona bem para APIs públicas e pipelines disciplinados. Vira risco quando o repositório é público sem controle de acesso, quando a especificação diverge da API real ou quando um exemplo adulterado chega aos consumidores sem detecção.

Uma camada gerenciada como o Apidog adiciona proteção por senha, listas de permissões por IP e e-mail, domínio personalizado, versionamento e documentação sincronizada com o design da API como fonte da verdade.

Por que a violação do GitHub deve fazer você revisar sua documentação de API

Antes de mudar sua arquitetura, entenda o alerta. Segundo a cobertura do BleepingComputer, o grupo TeamPCP exfiltrou repositórios internos do GitHub e colocou o conjunto de dados à venda. A extensão maliciosa veio do marketplace oficial do VS Code e foi executada no dispositivo de um funcionário. O GitHub informou que não encontrou evidências de dados de clientes afetados fora dos repositórios internos, e a investigação continuava em andamento.

O ponto para equipes de API é direto: sua documentação também é uma superfície de ataque.

Muitas equipes publicaram um Swagger UI no GitHub Pages, apontaram um CNAME e nunca mais revisaram o fluxo. O repositório é público. O último merge vira a documentação ativa. Commits de documentação recebem menos atenção do que código de produção.

Isso é perigoso porque documentação de API é instrução executável para outros desenvolvedores. Consumidores copiam:

URLs de endpoints
payloads de exemplo
cabeçalhos de autenticação
fluxos OAuth
exemplos de token
snippets de código

Se um invasor muda essas instruções, ele não está apenas alterando texto. Ele está influenciando código que será executado em produção.

Esse padrão aparece em outros incidentes: uma pequena mudança em uma superfície confiável pode se propagar. Veja também nosso artigo sobre lições de segurança de API da violação da Vercel.

Este guia cobre:

Como documentação comprometida prejudica consumidores de API.
Quando docs-as-code no Git é adequado.
Quando docs-as-code vira risco.
Como aplicar uma checklist de documentação segura.
Como o Apidog ajuda a fechar lacunas de controle de acesso, versionamento e integridade.

Para temas relacionados, veja também:

O que pode dar errado quando sua documentação é comprometida

Modele sua documentação como uma cadeia:

Fonte da documentação
        ↓
Repositório Git
        ↓
Pipeline de build
        ↓
Host publicado
        ↓
Consumidor da API

Se qualquer etapa for comprometida, os consumidores podem receber instruções erradas.

1. Um endpoint adulterado pode chegar ao código de produção

Exemplo: sua documentação mostra este endpoint:

https://api.payments.acme.com/v2/charge

Um invasor altera para:

https://api-payments-acme.example.net/v2/charge

A página continua renderizando. O YAML continua válido. O CI pode continuar verde. Mas o próximo consumidor que copiar o endpoint pode enviar dados sensíveis para o domínio errado.

O mesmo vale para uma especificação OpenAPI:

paths:
  /v2/payment-intents:
    post:
      summary: Create a payment intent
      servers:
        - url: https://api.acme-pay.com
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentIntentRequest'
      responses:
        '201':
          description: Payment intent created

Uma alteração mínima no campo servers.url pode redirecionar clientes gerados automaticamente:

 servers:
-  - url: https://api.acme-pay.com
+  - url: https://api-acme-pay.example.net

Se seus consumidores geram SDKs a partir da especificação, o risco aumenta:

openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-fetch \
  -o ./client

Uma especificação adulterada pode virar cliente adulterado.

2. Endpoints internos podem vazar

Repositórios de documentação acumulam rotas que não deveriam ser públicas:

paths:
  /admin/users:
    get:
      summary: Internal admin user list

  /debug/session:
    post:
      summary: Debug session inspector

  /partners/reconcile:
    post:
      summary: Partner-only reconciliation endpoint

Se o repositório for público, esses endpoints viram um mapa para atacantes.

Mesmo se o repositório for privado, uma violação pode expor a especificação inteira. O invasor passa a conhecer:

rotas
parâmetros
formatos de payload
nomes de headers
esquemas de autenticação
endpoints de administração ou parceiros

Para revisar esse tipo de superfície antes que alguém faça isso por você, use uma checklist como a lista de verificação de testes de segurança de API para 2026.

3. GitHub Pages público não é controle de acesso

GitHub Pages é ótimo para documentação pública. Mas ele não controla quem lê.

Se sua documentação é destinada apenas a clientes, parceiros ou times internos, um URL “difícil de adivinhar” não basta.

URLs vazam por:

histórico do navegador
headers Referer
logs de proxy
favoritos compartilhados
chats internos
ferramentas de analytics
tickets de suporte

Se qualquer pessoa com o link consegue acessar, isso não é documentação privada.

4. Documentação desatualizada também é um problema de segurança

Nem todo incidente exige um invasor.

Às vezes a API muda e a documentação não:

- POST /v1/users
+ POST /v2/users

Ou o payload muda:

 {
-  "name": "Ana"
+  "fullName": "Ana Silva"
 }

Quando a documentação diverge da API real, consumidores implementam contra um contrato falso. Se a documentação também pode ser adulterada, fica ainda pior: você não sabe se o erro é drift operacional ou alteração maliciosa.

Pergunta prática:

Se um endpoint mudou na documentação publicada há uma hora, você consegue provar quem mudou, por qual revisão e a partir de qual fonte?

Se não, sua documentação não é verificável.

Quando docs-as-code no Git é uma boa escolha

Docs-as-code é uma prática válida. Manter OpenAPI e Markdown no Git pode funcionar muito bem quando há disciplina.

Um fluxo comum:

openapi.yaml
docs/*.md
        ↓
Pull Request
        ↓
Review obrigatório
        ↓
CI valida a especificação
        ↓
Build do Swagger UI ou Redoc
        ↓
Deploy em host estático

Ferramentas como Redoc funcionam bem nesse modelo.

Use docs-as-code quando:

a API é totalmente pública;
não há endpoints internos no repositório publicado;
branches são protegidas;
PRs exigem revisão;
commits de documentação são revisados com o mesmo rigor do código;
o pipeline usa dependências e actions fixadas;
secrets de deploy têm escopo mínimo;
a especificação é validada contra a API real;
alguém é dono da atualização da documentação.

Exemplo de validação mínima no CI:

name: Validate OpenAPI

on:
  pull_request:
    paths:
      - "openapi.yaml"

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Validate OpenAPI spec
        run: npx @redocly/cli lint openapi.yaml

Você também pode bloquear alterações sensíveis com revisão extra:

name: Detect sensitive OpenAPI changes

on:
  pull_request:
    paths:
      - "openapi.yaml"

jobs:
  diff:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Show changed server URLs
        run: |
          git fetch origin main
          git diff origin/main...HEAD -- openapi.yaml | grep -E "servers:|url:" || true

Isso não substitui revisão humana, mas ajuda a destacar mudanças que merecem atenção.

Quando docs-as-code vira risco

O mesmo modelo começa a falhar quando uma destas condições aparece:

a documentação deveria ser privada, mas está em host público;
endpoints internos estão misturados com endpoints públicos;
muitas pessoas ou contas de serviço têm acesso de escrita;
PRs de documentação são aprovados automaticamente;
tokens de CI e deploy não são auditados;
a especificação é editada manualmente e diverge da API;
ninguém valida se o site publicado corresponde à fonte revisada;
não há logs confiáveis da etapa de deploy.

A violação do GitHub se encaixa nesse alerta. O Git dá histórico e transparência, mas não garante confidencialidade se o repositório for exfiltrado.

Para comparar abordagens de documentação auto-hospedada, veja a comparação de documentação de API auto-hospedada.

Resumo prático:

mantenha docs-as-code se sua API é pública e seu pipeline é controlado;
reconsidere se você precisa de acesso restrito, versionamento gerenciado ou garantia de que a documentação publicada vem da fonte correta.

Checklist: o que “documentação de API segura” significa

Use esta checklist para auditar sua configuração atual.

1. Controle de acesso

Perguntas:

A documentação é pública de propósito?
Quem consegue acessá-la hoje?
Você consegue revogar acesso em menos de um minuto?
Clientes, parceiros e times internos têm níveis diferentes de acesso?
Existe senha, allowlist de IP, allowlist de e-mail ou SSO?

Sinal de risco:

“Ela é privada porque ninguém tem o link.”

Isso não é controle de acesso.

2. Versionamento

Perguntas:

A documentação da API v1 continua disponível?
A documentação da v2 está separada da v1?
Consumidores antigos conseguem encontrar o contrato correto?
Você sabe o que a documentação dizia em uma data específica?

Estrutura recomendada:

/docs/v1
/docs/v2
/docs/beta

Ou versões publicadas lado a lado em uma plataforma de documentação.

3. Integridade

Perguntas:

A documentação publicada vem de uma fonte controlada?
Existe revisão antes de publicar?
Alterações em servers.url, autenticação e exemplos de token recebem atenção especial?
Você consegue detectar diferença entre fonte revisada e site publicado?

Exemplo de campos que merecem revisão cuidadosa em OpenAPI:

servers:
  - url: https://api.example.com

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

paths:
  /oauth/token:
    post:
      summary: Exchange authorization code for access token

4. Trilha de auditoria

Perguntas:

Quem alterou a documentação?
O que mudou?
Quando mudou?
Quem aprovou?
Qual versão foi publicada?
O deploy foi feito por qual pipeline ou usuário?

O Git cobre parte disso no repositório. Mas você também precisa de rastreabilidade na publicação.

Como o Apidog ajuda a implementar documentação segura

Apidog é uma plataforma de API para projetar, depurar, testar, simular e documentar APIs. Para acompanhar na prática, baixe o Apidog e abra um projeto com uma definição de API.

1. Publique documentação a partir de uma fonte controlada

No Apidog, a documentação é gerada a partir do design da API no projeto. Você define endpoints, schemas e autenticação, e o Apidog gera automaticamente a documentação.

Fluxo básico:

Design da API no Apidog
        ↓
Endpoints, schemas e auth
        ↓
Publicar documentação
        ↓
Site interativo com exemplos e console de teste

A vantagem é reduzir drift. A documentação não precisa ser um Markdown solto que evolui separado da definição da API.

2. Aplique controle de acesso real

Ao publicar documentação no Apidog, você pode escolher métodos de acesso:

Público: qualquer pessoa com o link pode ler.
Proteção por senha: acesso mediante senha compartilhada.
Lista de permissões de IP: restrição por IPs ou faixas, como escritório ou VPN.
Lista de permissões de e-mail: acesso por e-mails ou domínios permitidos.
Login personalizado: autenticação própria com JWT emitido pelo seu servidor.

Exemplo de regra por domínio:

*@suaempresa.com

Isso permite cobrir uma organização inteira sem cadastrar cada usuário manualmente.

O Apidog documenta essas opções no guia para controlar o acesso à documentação da API.

3. Use domínio personalizado

Você pode publicar a documentação em um domínio próprio, como:

developer.suaempresa.com

O Apidog suporta domínio personalizado via CNAME DNS ou proxy reverso.

Domínio personalizado não substitui autenticação, mas ajuda a manter a documentação em uma superfície governada pela sua organização.

4. Mantenha OpenAPI sincronizado com o design da API

O Apidog trata o design da API como fonte da verdade e mantém a documentação sincronizada com ele.

Ele importa:

OpenAPI 3.0
OpenAPI 3.1
Swagger 2.0

Também suporta importações programadas para manter uma especificação externa atualizada.

Se hoje você mantém um openapi.yaml manualmente no Git, revise se ele ainda representa a API real. Equipes que vêm do SwaggerHub podem usar o guia para migrar documentação de API do SwaggerHub para o Apidog.

5. Publique múltiplas versões

O Apidog suporta versionamento da documentação. Isso permite manter versões lado a lado:

API v1 → documentação v1
API v2 → documentação v2
API beta → documentação beta

Isso evita que consumidores da v1 leiam, sem perceber, instruções da v2.

Comparação rápida de opções

Propriedade	GitHub Pages Público (Swagger UI / Redoc)	Docs auto-hospedados em seu próprio servidor	Docs gerenciados (Apidog)
Controle de acesso	Nenhum; apenas obscuridade de URL	O que você construir e mantiver	Embutido: senha, IP, e-mail, login personalizado
Versionamento	Manual; builds ou branches separadas	Manual	Embutido; versões publicadas lado a lado
Integridade	Revisão + histórico do Git, se imposto	Depende do seu pipeline	Docs gerados a partir do design de API controlado
Trilha de auditoria	Histórico do Git para o repositório, não para a implantação	Depende do seu logging	Histórico de mudanças no design e na documentação publicada
Custo de manutenção	Baixo para configurar, mas exige manutenção contínua do pipeline	Alto; você mantém toda a pilha	Baixo; a plataforma cuida da hospedagem e dos portões
Melhor adequação	APIs totalmente públicas com pipeline disciplinado	Equipes com requisitos estritos de auto-hospedagem	Equipes que precisam de controle de acesso sem sobrecarga operacional

Não existe uma resposta universal.

Use GitHub Pages público quando:

a API é realmente pública;
a especificação não contém endpoints internos;
o pipeline é revisado e protegido.

Use auto-hospedagem quando:

há requisitos rígidos de residência, isolamento ou infraestrutura;
sua equipe consegue manter autenticação, logs, CI/CD e hardening.

Use uma camada gerenciada quando:

você precisa restringir acesso rapidamente;
quer versionamento sem manter infraestrutura;
precisa reduzir drift entre design e documentação publicada.

Para aprofundar a comparação, veja:

Plano de ação para auditar sua documentação

Execute esta revisão em uma sessão curta com o time de API.

1. Liste todos os locais publicados

- GitHub Pages
- Swagger UI interno
- Redoc público
- Portal de desenvolvedores
- Wiki interna
- Postman collection pública
- Repositórios com openapi.yaml
- PDFs ou guias antigos

2. Classifique cada documentação

Pública
Parceiros
Clientes
Interna
Restrita por produto/plano

3. Verifique controle de acesso

Para cada item, responda:

Quem pode ler?
Como revogar acesso?
Existe autenticação real?
Existe senha, IP allowlist, e-mail allowlist ou SSO?

4. Verifique integridade

Qual é a fonte da verdade?
Quem aprova mudanças?
O site publicado corresponde à fonte?
Mudanças em endpoints e auth são revisadas?

5. Verifique versionamento

A v1 ainda tem documentação própria?
A v2 sobrescreveu a v1?
Consumidores antigos sabem qual versão usar?

6. Verifique trilha de auditoria

Consigo ver alterações dos últimos 90 dias?
Consigo identificar autor e aprovador?
Consigo saber quando uma versão foi publicada?

Conclusão

A violação do GitHub não é motivo para abandonar docs-as-code ou deixar de usar GitHub. Ela é um lembrete para auditar uma superfície que muitos times ignoram: a documentação da API.

Seu próximo passo:

Liste onde sua documentação está publicada.
Classifique cada publicação por público.
Valide controle de acesso, versionamento, integridade e auditoria.
Corrija primeiro a maior lacuna.

Se a lacuna principal for controle de acesso, teste publicar a documentação de um projeto no Apidog com senha, allowlist de IP ou allowlist de e-mail. Isso permite transformar documentação de API de “site estático esquecido” em uma superfície governada e verificável.

Ferramentas de API Auto-Hospedadas: Vale a Pena Deixar a Nuvem?

Lucas — Thu, 21 May 2026 03:04:48 +0000

Ferramentas de API auto-hospedadas (self-hosted) deixaram de ser apenas um requisito de conformidade de nicho. Depois que o GitHub confirmou que invasores roubaram dados de aproximadamente 3.800 repositórios internos por meio de uma extensão VS Code maliciosa instalada no laptop de um funcionário, a pergunta ficou mais prática: onde suas especificações OpenAPI, coleções, dados de teste e segredos de ambiente realmente vivem?

Experimente o Apidog hoje

Para muitas equipes, a resposta é: “na nuvem de um fornecedor, e não sei exatamente onde”. Isso não é automaticamente errado. Ferramentas de API com sincronização em nuvem são úteis para colaboração. Mas você deve decidir isso conscientemente, especialmente quando a sua ferramenta de API armazena especificações, payloads, tokens e variáveis de ambiente.

TL;DR

Use ferramentas de API self-hosted, on-premise ou offline quando você precisa manter especificações OpenAPI, coleções, dados de teste e credenciais dentro da infraestrutura que controla. Isso é especialmente importante para setores regulados, redes air-gapped, dados de clientes, segredos de produção e requisitos de residência de dados.

A nuvem ainda faz sentido para equipes distribuídas, colaboração em tempo real e projetos de baixa sensibilidade. O ponto não é “nuvem ou self-hosted para tudo”, mas classificar seus dados de API e escolher o local correto para cada classe.

O Apidog oferece produto em nuvem, implantação on-premise/self-hosted e modo offline, permitindo escolher onde seus dados de API residem.

O que aconteceu no GitHub e por que isso importa para APIs

Em 20 de maio de 2026, o GitHub confirmou que invasores roubaram dados de aproximadamente 3.800 repositórios internos. O ponto de entrada não foi uma vulnerabilidade zero-day na plataforma principal. Foi uma extensão VS Code maliciosa executada no dispositivo de um funcionário.

Com as permissões desse funcionário, os invasores acessaram a rede interna do GitHub. O grupo de ameaças, rastreado como TeamPCP, já era conhecido por ataques à cadeia de suprimentos em ecossistemas como npm, PyPI e PHP. Relatórios indicaram que os dados roubados foram colocados à venda em fóruns clandestinos por mais de US$ 50.000. O GitHub afirmou que não encontrou evidências de impacto em dados de clientes armazenados fora de seus repositórios internos.

No mês anterior, a Wiz divulgou a CVE-2026-3854, uma falha crítica de execução remota de código na infraestrutura interna do Git do GitHub. A SecurityWeek documentou a vulnerabilidade e seu escopo.

Para equipes de API, o ponto principal é este: a plataforma que hospeda seu código muitas vezes também hospeda a fonte de verdade da sua API.

Isso inclui:

especificações OpenAPI e Swagger;
coleções de requisições;
arquivos .env.example;
workflows CI/CD com tokens de deploy;
fixtures de teste;
definições de mock server;
scripts Terraform para gateways de API;
exemplos de payloads e respostas.

No caso do GitHub, os dados roubados eram internos do próprio GitHub, não repositórios de clientes. Essa distinção importa. Ainda assim, o padrão de ataque é relevante: uma extensão comprometida em um ambiente de desenvolvimento pode se tornar acesso a dados internos.

Se você quer revisar essa superfície, veja também:

Faça um inventário: o que sua ferramenta de API sincroniza?

Antes de decidir entre nuvem, self-hosted ou offline, liste o que sai da máquina dos desenvolvedores.

Use uma tabela simples:

| Tipo de dado | Exemplo | Sensibilidade | Pode ir para nuvem? |
|---|---|---:|---|
| OpenAPI | openapi.yaml | Média/Alta | Depende |
| Coleções | requisições salvas | Média | Depende |
| Tokens | Authorization Bearer | Alta | Não |
| Dados de teste | payloads reais | Alta | Não, se contiver PII |
| Mocks | respostas simuladas | Média | Depende |
| Comentários | discussões do workspace | Baixa/Média | Depende |

1. Especificações de API

Uma especificação OpenAPI expõe endpoints, parâmetros, schemas, autenticação e fluxos de erro. Ela não é uma senha, mas é um mapa da API.

Para reduzir risco:

remova endpoints internos de documentação pública;
separe specs públicas e privadas;
versionne specs sensíveis em repositórios com acesso mínimo;
revise exemplos de payload antes de compartilhar.

2. Coleções e exemplos salvos

Coleções frequentemente acumulam dados reais:

{
  "email": "cliente.real@empresa.com",
  "accountId": "acc_123456",
  "internalHost": "http://billing.internal.local"
}

Antes de sincronizar coleções:

substitua dados reais por dados sintéticos;
remova hosts internos;
remova IDs reais de contas;
apague respostas capturadas com dados de usuários.

3. Variáveis de ambiente e segredos

Este é o ponto mais crítico. Muitas equipes salvam estes valores em clientes de API:

API_TOKEN=eyJhbGciOi...
OAUTH_CLIENT_SECRET=...
DATABASE_URL=mysql://user:pass@host/db

Se esses ambientes são sincronizados com a nuvem, suas credenciais podem passar a residir em infraestrutura de terceiros.

Medidas práticas:

nunca sincronize tokens de produção;
use variáveis locais para segredos;
crie ambientes separados para dev, staging e prod;
rotacione tokens que já foram compartilhados;
use secret managers quando possível.

Se você já teve problemas de sincronização de ambientes, veja o diagnóstico sobre problemas de sincronização de ambiente do Postman.

4. Dados de teste e mocks

Mocks e testes podem revelar regras de negócio. Exemplo:

pm.test("cliente premium pode solicitar limite acima de 50000", () => {
  pm.expect(response.json().approved).to.eql(true);
});

Isso pode ser útil para QA, mas também pode expor lógica sensível.

Boas práticas:

use fixtures sintéticas;
separe testes internos de exemplos públicos;
evite copiar respostas reais de produção;
revise mocks antes de publicá-los.

5. Metadados do workspace

Comentários, nomes de serviços, histórico de alterações e membros do workspace formam um mapa organizacional.

Individuais, parecem dados menores. Em conjunto, podem revelar:

serviços em desenvolvimento;
nomes internos de produtos;
estrutura de times;
dependências entre sistemas;
prioridades de roadmap.

Para uma análise mais profunda dessa superfície, veja: o Postman é seguro?

Onde a sincronização em nuvem aumenta a superfície de ataque

Ferramentas de API em nuvem adicionam pontos de exposição. Isso não significa que o fornecedor seja inseguro. Significa que seus dados passam a existir em mais lugares.

O fornecedor vira um alvo

Um SaaS multi-tenant que armazena specs, coleções e credenciais de várias empresas é um alvo valioso. Você passa a depender de:

postura de segurança do fornecedor;
ciclo de patches;
resposta a incidentes;
controles internos;
segurança dos dispositivos dos funcionários do fornecedor.

Account takeover escala rapidamente

Se uma conta de workspace for comprometida, o invasor pode acessar:

coleções compartilhadas;
ambientes sincronizados;
variáveis;
exemplos;
documentação interna.

Aplique MFA, mas não pare nisso. Sessões roubadas e tokens OAuth ainda podem contornar parte da proteção.

Checklist mínimo:

- [ ] MFA obrigatório
- [ ] SSO para contas corporativas
- [ ] revisão periódica de membros
- [ ] remoção automática de ex-funcionários
- [ ] menor privilégio por projeto
- [ ] ambientes de produção fora de workspaces amplos

Workspaces tendem a ficar abertos demais

Padrões comuns:

contratado adicionado e nunca removido;
workspace “Engenharia” com acesso amplo;
ambiente de produção compartilhado com quem só precisava de staging;
dados antigos esquecidos em coleções.

Crie uma rotina mensal:

1. Exportar lista de membros.
2. Remover usuários inativos.
3. Revisar permissões por projeto.
4. Procurar variáveis com nomes como TOKEN, SECRET, PASSWORD.
5. Rotacionar segredos expostos.

Extensões e integrações são código de terceiros

O incidente do GitHub mostra esse vetor. Extensões, plugins e integrações podem rodar com permissões amplas no ambiente do desenvolvedor.

Reduza risco:

aprove extensões usadas pela equipe;
bloqueie extensões desconhecidas em máquinas corporativas;
evite armazenar tokens permanentes em ferramentas extensíveis;
prefira tokens com escopo mínimo e expiração curta.

Logs, telemetria e sub-processadores

Ferramentas em nuvem podem gerar logs, telemetria e relatórios de erro. Dependendo da implementação, isso pode capturar:

headers;
corpos de requisição;
URLs internas;
tokens em Authorization;
payloads de teste.

Compare com a análise sobre a violação da Vercel e o que ela ensinou às equipes de API.

O objetivo não é eliminar a nuvem. É mapear quais terceiros podem tocar dados sensíveis e reduzir esse mapa quando necessário.

Quando conformidade torna self-hosted obrigatório

Para setores regulados, a escolha entre nuvem e self-hosted pode ser definida por auditoria, contrato ou legislação.

Residência e soberania de dados

Regulamentos como GDPR e leis nacionais de localização de dados podem restringir onde dados pessoais residem.

Se seus payloads de teste contêm dados pessoais de residentes da UE, armazená-los em um banco de dados multi-tenant fora da região adequada pode gerar risco de conformidade.

Referência: European Data Protection Board

Frameworks regulatórios

Self-hosted, on-premise ou offline costuma ser mais adequado quando você lida com:

HIPAA;
PCI DSS;
FedRAMP;
CMMC;
ambientes air-gapped;
dados de defesa;
dados financeiros sensíveis.

Veja também: ferramentas de teste de API air-gapped para ambientes seguros

Obrigações contratuais

Mesmo sem regulação formal, contratos empresariais podem limitar sub-processadores.

Se você copia payloads de um cliente para uma ferramenta de API em nuvem, pode estar processando dados desse cliente em um fornecedor não aprovado.

Auditoria e cadeia de custódia

Auditores perguntam:

Quem pode acessar esses dados e como você prova?

Com self-hosted, a resposta tende a ser mais objetiva:

servidores sob seu controle;
rede sob suas políticas;
logs internos;
IAM corporativo;
backup e retenção definidos por você.

Com SaaS multi-tenant, parte da resposta sempre depende do fornecedor.

Como decidir: nuvem, self-hosted ou offline?

Use uma matriz por classe de dados, não por preferência geral.

Fator	Ferramentas de API sincronizadas com a nuvem	Self-hosted / on-premise / offline
Configuração e manutenção	Minutos; fornecedor gerencia tudo	Você provisiona, aplica patches, faz backup, monitora
Colaboração em tempo real	Forte; construído para equipes distribuídas	Funciona, mas dentro da sua rede ou VPN
Controle de residência de dados	Limitado às regiões e política do fornecedor	Total; você escolhe a localização exata
Superfície de ataque	Nuvem do fornecedor, autenticação de conta, sub-processadores	Apenas o seu perímetro
Adequação à conformidade (HIPAA, PCI, FedRAMP)	Depende das certificações do fornecedor	Forte; os dados nunca saem do seu controle
Modelo de custo	Assinatura por assento	Licença mais sua infraestrutura e tempo de operação
Funciona air-gapped ou offline	Não	Sim
Recuperação de desastres	Responsabilidade do fornecedor	Sua responsabilidade projetar e testar

Escolha self-hosted ou offline quando

você armazena tokens de produção;
payloads contêm dados de clientes;
há dados regulados ou contratuais;
a rede é restrita ou air-gapped;
segurança/jurídico exige cadeia de custódia;
você precisa controlar região, backup e retenção;
um fornecedor já concentra dados críticos demais.

Escolha nuvem quando

colaboração em tempo real é prioridade;
o time é pequeno e não tem capacidade operacional;
os dados são públicos ou de baixa sensibilidade;
a velocidade de adoção é mais importante;
o risco regulatório é baixo.

Uma abordagem madura costuma ser híbrida:

- Offline: segredos locais e testes com tokens reais
- Self-hosted: specs internas, dados de clientes, ambientes restritos
- Nuvem: documentação pública, exemplos sintéticos, colaboração de baixo risco

Como manter a fonte de verdade da API dentro do seu perímetro com Apidog

Se você quer controlar onde seus dados de API residem, escolha uma ferramenta que suporte mais de um modelo de implantação.

O Apidog é uma plataforma de API para design, depuração, teste, mocking e documentação. Ele oferece produto em nuvem, implantação self-hosted/on-premise e modo offline.

Opção 1: implantação on-premise/self-hosted

O Apidog oferece uma implantação totalmente auto-hospedada e on-premise para empresas.

De acordo com a documentação de auto-hospedagem do Apidog, as opções incluem:

configuração Docker autônoma;
aplicação, MySQL e Redis em hosts controlados por você;
modelo híbrido com aplicação no seu ambiente e banco/cache em serviços gerenciados que você controla;
Kubernetes para implantações empresariais.

Nesse modelo, você mantém sob seu controle:

especificações OpenAPI;
coleções;
dados de teste;
variáveis de ambiente;
documentação;
permissões de usuários;
logs de acesso.

A edição self-hosted também suporta test runners auto-hospedados, permitindo que testes automatizados de API executem dentro da sua rede, sem rotear tráfego sensível por terceiros.

Opção 2: Offline Space

Você não precisa de uma implantação on-premise completa para manter trabalho sensível local.

Segundo a documentação do Offline Space do Apidog, todos os dados permanecem na máquina local e não são carregados para a nuvem.

Isso é útil para:

tokens pessoais;
credenciais temporárias;
testes em redes restritas;
APIs internas;
debugging com payloads sensíveis;
trabalho individual que não deve ser sincronizado.

No Offline Space, variáveis de ambiente e globais ficam locais, não são sincronizadas e não são compartilhadas com membros da equipe.

Fluxo prático recomendado

Use este fluxo para classificar seus projetos:

1. Liste todos os workspaces/projetos de API.
2. Identifique se há tokens, PII, dados de clientes ou endpoints internos.
3. Classifique cada projeto: baixo, médio ou alto risco.
4. Mova projetos de alto risco para self-hosted ou offline.
5. Mantenha na nuvem apenas exemplos sintéticos ou documentação pública.
6. Revise permissões e segredos mensalmente.

Para começar, baixe o Apidog e ative o Offline Space no aplicativo desktop, ou revise a documentação de auto-hospedagem se estiver avaliando uma implantação empresarial.

Conclusão

A violação do GitHub não prova que a nuvem é insegura. Ela mostra que ambientes de desenvolvimento, extensões e fornecedores conectados ao seu fluxo de trabalho fazem parte da sua superfície de ataque.

A decisão prática é:

inventarie o que sua ferramenta de API sincroniza;
remova dados reais de exemplos e mocks;
nunca sincronize segredos de produção;
use MFA, SSO e revisão de membros;
separe dados por sensibilidade;
use self-hosted ou offline para dados regulados, segredos e clientes;
use nuvem para colaboração de baixo risco.

O próximo passo para esta semana: escolha um workspace de API, liste todos os ambientes e procure variáveis como TOKEN, SECRET, PASSWORD, CLIENT_SECRET e DATABASE_URL. Se elas existem e estão sincronizadas, mova esses valores para armazenamento local, rotacione os segredos e defina uma política clara.

Se parte da resposta for manter dados dentro do seu perímetro, o Apidog oferece implantação self-hosted/on-premise e modo offline. Baixe o Apidog para começar.

Como proteger chaves API de extensões VS Code maliciosas

Lucas — Thu, 21 May 2026 02:38:24 +0000

Em 20 de maio de 2026, o GitHub confirmou que invasores roubaram dados de aproximadamente 3.800 repositórios internos. O ponto de entrada não foi uma zero-day nos servidores do GitHub, mas uma extensão do VS Code comprometida instalada no laptop de um funcionário. Como a extensão rodava com as permissões do desenvolvedor, ela pôde ler arquivos do workspace, configurações e credenciais locais. A lição para quem trabalha com APIs é direta: proteja suas chaves assumindo que a máquina de desenvolvimento e as ferramentas instaladas nela podem ser comprometidas.

Experimente o Apidog hoje

TL;DR

Para proteger chaves de API contra extensões de IDE comprometidas ou repositórios vazados:

Não armazene credenciais ativas no código-fonte.
Não commite arquivos .env.
Use .gitignore como higiene, não como controle de segurança.
Separe chaves por ambiente: desenvolvimento, staging e produção.
Use menor privilégio e credenciais de curta duração.
Rotacione chaves em um cronograma.
Mantenha segredos fora do workspace sempre que possível.

Ferramentas como o Apidog ajudam ao armazenar credenciais de API em variáveis de ambiente com valores apenas locais, em vez de espalhá-las como texto simples no repositório ou no diretório de trabalho.

Por que a violação do GitHub é um alerta para desenvolvedores

O incidente do GitHub segue um padrão comum de ataque à cadeia de suprimentos. O grupo de ameaças, rastreado como TeamPCP, já havia trojanizado pacotes em ecossistemas como npm, PyPI e PHP. Desta vez, a carga maliciosa chegou por meio de uma extensão do VS Code.

Segundo o relatório do TechCrunch, os invasores exfiltraram dados de cerca de 3.800 repositórios internos e passaram a vender o conjunto de dados por mais de US$ 50.000 em fóruns clandestinos. O GitHub afirma não ter evidências de que dados de clientes armazenados fora desses repositórios internos tenham sido afetados, e a investigação segue em andamento.

O ponto importante: uma extensão do VS Code é código executado dentro do editor com permissões do usuário. Ela pode:

listar arquivos;
abrir arquivos;
ler conteúdo;
observar alterações;
fazer requisições de rede.

Isso não é uma vulnerabilidade por si só. É parte do modelo de extensões. O problema aparece quando uma extensão maliciosa usa esse acesso para procurar credenciais.

Em um projeto típico, ela pode encontrar:

.env;
config/secrets.yml;
tokens hardcoded em scripts;
~/.aws/credentials;
.npmrc com token de autenticação;
chaves SSH;
arquivos de configuração de ferramentas internas.

O mesmo padrão apareceu em campanhas anteriores, como o worm npm “Mini Shai-Hulud”, associado ao TeamPCP, que coletava credenciais de desenvolvedores, CI/CD, nuvem e ferramentas de IA em máquinas infectadas.

Esse tipo de exposição também se conecta a padrões abordados nas lições de segurança de API da violação da Vercel e no guia de segurança da cadeia de suprimentos npm.

A pergunta prática é: se uma extensão maliciosa rodasse agora no seu editor, quais segredos ela conseguiria ler?

Chaves hardcoded e arquivos `.env` commitados são riscos permanentes

A maioria dos vazamentos de credenciais não começa com um ataque sofisticado. Ela começa com algo simples:

uma chave colada no código “só para testar”;
um .env commitado por engano;
um token salvo em um script temporário;
uma credencial real usada em ambiente local.

Exemplo clássico de chave hardcoded:

import requests

# Teste rápido do endpoint de pagamentos
STRIPE_KEY = "sk_live_51Qk2mNExampleKeyDoNotShipThis"

response = requests.post(
    "https://api.stripe.com/v1/charges",
    auth=(STRIPE_KEY, ""),
    data={"amount": 2000, "currency": "usd", "source": "tok_visa"},
)

print(response.json())

Essa chave agora está:

no arquivo local;
visível para qualquer extensão com acesso ao workspace;
possivelmente no histórico Git;
disponível para qualquer pessoa ou ferramenta que clone ou escaneie o repositório.

Mover a chave para um .env é melhor do que hardcoding, mas não resolve tudo:

# .env
DATABASE_URL=postgres://app_user:Zk7%2BqN9wLx@db.internal:5432/payments
STRIPE_SECRET_KEY=sk_live_51Qk2mNExampleKeyDoNotShipThis
OPENAI_API_KEY=sk-proj-aB3dEf9hKlMnOpQrStUvWxYz1234567890
AWS_ACCESS_KEY_ID=AKIA4EXAMPLE7QRSTUVW
AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
JWT_SIGNING_SECRET=8f2a91c4e7b6d3508f2a91c4e7b6d350

O .env evita que a credencial fique no código-fonte, mas o arquivo ainda está em texto simples no workspace. Para uma extensão maliciosa, não há diferença relevante entre ler app.py e ler .env.

O pior cenário é commitar esse arquivo. Isso pode acontecer facilmente:

cp .env.example .env
# preenche com chaves reais
git add .
git commit -m "configura ambiente local"

Agora as credenciais podem estar no histórico do repositório para sempre. Mesmo que você remova o arquivo em outro commit, o valor antigo continua disponível no histórico.

Para mais contexto sobre esse risco, veja o artigo sobre documentação de API e segurança de repositórios Git.

`.gitignore` não é controle de segurança

Adicionar .env ao .gitignore é necessário, mas não suficiente.

O .gitignore apenas instrui o Git a ignorar arquivos não rastreados durante operações como git add. Ele não protege o arquivo no disco e não remove segredos já commitados.

Principais falhas:

Não afeta arquivos já rastreados

Se .env já foi commitado, adicionar .env ao .gitignore não resolve. O Git continuará rastreando o arquivo.

Você precisaria executar:

   git rm --cached .env
   git commit -m "remove .env do controle de versão"

Mesmo assim, o segredo continuará no histórico.

Não protege o arquivo local

O arquivo .env ainda está no seu disco, em texto simples. Uma extensão comprometida lê o sistema de arquivos, não o índice do Git.

Pode ser ignorado manualmente

Um desenvolvedor ainda pode executar:

   git add -f .env

E commitar o arquivo apesar da regra.

Para verificar se .env já apareceu no histórico:

# Lista commits que tocaram o arquivo
git log --all --full-history --oneline -- .env

# Procura possíveis segredos no histórico
git log -p --all -- .env | grep -iE "key|secret|token|password"

Se houver retorno, trate a credencial como comprometida.

A correção deve incluir:

rotacionar a chave;
remover o arquivo do histórico com uma ferramenta como git filter-repo;
revisar onde o segredo ativo deve viver;
impedir que credenciais reais fiquem no workspace novamente.

Use .gitignore, mas entenda seu papel: ele previne erros simples. Ele não é uma fronteira de segurança.

Escopo, separação, expiração e rotação

Você não consegue garantir que uma credencial nunca será exposta. Mas consegue reduzir o impacto quando isso acontecer.

1. Delimite segredos por ambiente

Nunca use a mesma chave em desenvolvimento, staging e produção.

Use credenciais separadas:

dev     -> chave sandbox, dados falsos
staging -> chave de teste, ambiente isolado
prod    -> chave real, acesso mínimo necessário

Se uma chave de desenvolvimento vazar, o invasor deve alcançar apenas um sandbox.

2. Separe ambientes de verdade

Separar ambientes não é apenas trocar valores de variáveis.

Garanta que:

o banco de desenvolvimento não seja réplica da produção;
staging use modo de teste do provedor de pagamento;
dados reais não estejam disponíveis em ambientes locais;
uma configuração de dev não possa apontar facilmente para produção.

Quando a separação é real, você consegue responder rapidamente: “qual ambiente essa chave acessa?” e “qual é o raio de impacto?”.

3. Use menor privilégio

Uma chave deve ter apenas as permissões necessárias.

Exemplos:

frontend público: somente leitura;
job de relatórios: leitura apenas dos recursos necessários;
integração de pagamento: acesso limitado ao provedor e ao ambiente correto;
automação de CI: permissões específicas para build/deploy.

Evite chaves com privilégios amplos como padrão.

Se estiver decidindo entre chaves estáticas e tokens, a comparação entre chaves de API versus OAuth ajuda a avaliar quando tokens OAuth de curta duração são mais adequados.

4. Prefira credenciais de curta duração

Uma chave que expira em uma hora tem valor limitado para um invasor. Uma chave que nunca expira continua útil até alguém perceber.

Quando possível:

use tokens emitidos sob demanda;
defina expiração curta;
evite chaves permanentes;
limite chaves long-lived aos casos realmente necessários.

5. Rotacione em um cronograma

Não espere uma violação para aprender a rotacionar credenciais.

Defina uma política simples:

produção de alto privilégio -> mensal
produção de baixo risco     -> trimestral
desenvolvimento/staging     -> conforme risco e uso

A rotação programada reduz a janela de exploração e mantém o processo praticado.

Um checklist mínimo de rotação:

1. Criar nova chave.
2. Atualizar consumidores.
3. Validar tráfego com a nova chave.
4. Revogar chave antiga.
5. Registrar data e responsável.

Para um panorama mais amplo, veja o resumo de ferramentas de gerenciamento de chaves de API.

Mantenha credenciais em variáveis de ambiente do Apidog

O Apidog possui extensão para VS Code e servidor MCP próprios. O ponto aqui não é afirmar que uma ferramenta cliente é imune a ataques de cadeia de suprimentos. Nenhuma é.

O ponto é reduzir onde os segredos ficam expostos.

Em um fluxo comum de desenvolvimento de APIs, você precisa de:

token Bearer;
chave de API;
string de conexão;
senha de serviço;
segredo JWT.

O hábito comum é salvar tudo isso em .env, scripts ou arquivos de configuração. Isso coloca credenciais ativas em texto simples dentro do workspace.

O Apidog muda esse fluxo ao permitir que você use variáveis de ambiente gerenciadas no cliente de API.

Use variáveis em vez de texto simples

No Apidog, você pode armazenar credenciais como variáveis de ambiente.

Em vez de escrever o token diretamente no header:

Authorization: Bearer sk-proj-aB3dEf9hKlMnOpQrStUvWxYz1234567890

Use uma variável:

Authorization: Bearer {{access_token}}

A requisição referencia o nome da variável, e o Apidog resolve o valor no momento do envio.

Isso evita que o segredo literal fique salvo em um arquivo .env ou em uma definição de requisição versionada junto ao código.

Use valores locais para segredos

O Apidog diferencia valores compartilhados/iniciais e valores locais/atuais.

Na prática:

valor compartilhado: pode sincronizar com o projeto e ser visível para a equipe;
valor local: permanece na máquina do desenvolvedor e não é enviado.

Para tokens, senhas e chaves reais, use valores locais.

Assim, a equipe pode compartilhar a estrutura:

access_token
db_password
payment_api_key

Mas cada desenvolvedor preenche seu próprio valor local. O projeto não transporta os segredos reais.

Separe ambientes no Apidog

O gerenciamento de ambientes do Apidog permite definir ambientes como:

Desenvolvimento
Staging
Produção

Cada ambiente pode ter:

URL base própria;
variáveis próprias;
credenciais próprias.

Exemplo:

Desenvolvimento:
  base_url = https://api-dev.example.com
  payment_api_key = chave_sandbox

Produção:
  base_url = https://api.example.com
  payment_api_key = chave_producao

Você não precisa editar a requisição para alternar credenciais. Basta trocar o ambiente ativo.

Isso reduz erros como usar chave de produção em testes locais ou enviar uma requisição de staging com credenciais reais.

Use Segredos de Cofre quando produção não deve tocar o cliente

Para equipes que exigem um limite mais rígido, o plano Enterprise do Apidog oferece o recurso de Segredo de Cofre.

Ele permite buscar segredos de:

HashiCorp Vault;
Azure Key Vault;
AWS Secrets Manager.

Nesse modelo, o Apidog armazena o caminho e os metadados do cofre. Os valores reais são buscados sob demanda, criptografados no cliente local e não compartilhados com colegas pelo projeto.

Esse fluxo mantém credenciais de produção no gerenciador de segredos dedicado, que é onde elas devem estar.

Para testar o fluxo de variáveis, baixe o Apidog, crie um projeto, abra o Gerenciamento de Ambiente e adicione suas credenciais como variáveis com valores apenas locais.

Importante: mover segredos para o Apidog reduz credenciais em texto simples no workspace, mas não torna sua máquina imune a uma ferramenta comprometida. Continue auditando extensões, usando menor privilégio, separando ambientes e rotacionando chaves.

Conclusão

A violação do GitHub reforça um ponto prático: a máquina do desenvolvedor é um alvo valioso. Ela concentra código, ferramentas confiáveis, arquivos de configuração e credenciais locais.

Você não consegue tornar esse ambiente perfeitamente seguro, mas pode reduzir o que um invasor encontra.

Comece com uma auditoria simples:

grep -RniE "key|secret|token|password" .
git log -p --all | grep -iE "key|secret|token|password"

Depois:

identifique segredos expostos;
trate-os como comprometidos;
rotacione as chaves;
remova credenciais do histórico quando necessário;
mova valores ativos para um local mais seguro;
separe ambientes;
aplique menor privilégio;
defina rotação periódica.

Você também pode baixar o Apidog e mover seu próximo conjunto de credenciais de API para variáveis de ambiente com valores locais, em vez de mantê-las em arquivos de texto simples.

Para continuar, leia também sobre ferramentas de API auto-hospedadas após a violação do GitHub e ferramentas de gerenciamento de chaves de API.

FAQ

Uma extensão do VS Code pode realmente ler meu arquivo `.env` e minhas chaves de API?

Sim. Uma extensão do VS Code roda com as permissões da sua conta de usuário. Ela pode listar diretórios, abrir arquivos e ler conteúdo, incluindo .env, arquivos de configuração e credenciais como ~/.aws/credentials.

Esse acesso é normal para muitas extensões. O risco é uma extensão maliciosa usar o mesmo acesso para coletar segredos.

Adicionar `.env` ao `.gitignore` é suficiente?

Não. O .gitignore apenas impede que arquivos não rastreados sejam adicionados automaticamente pelo Git. Ele não protege o arquivo no disco e não remove segredos já commitados.

Use .gitignore, mas não dependa dele como controle de segurança.

O que fazer se eu encontrar uma chave de API no histórico do Git?

Trate a chave como comprometida.

Faça o seguinte:

rotacione a chave imediatamente;
remova o arquivo ou valor do histórico com git filter-repo ou ferramenta equivalente;
coordene o force push com a equipe;
mova a credencial ativa para fora de arquivos em texto simples;
revise permissões e escopo da nova chave.

Veja também o guia de ferramentas de gerenciamento de chaves de API.

Como armazenar chaves de API no Apidog reduz minha exposição?

O Apidog permite armazenar credenciais como variáveis de ambiente e referenciá-las por nome nas requisições. Assim, o segredo literal não precisa ficar em um arquivo .env dentro do repositório.

Variáveis também podem ter valores apenas locais, que permanecem na máquina do desenvolvedor e não sincronizam com colegas ou servidores do projeto.

Isso reduz a quantidade de segredos ativos em texto simples no workspace.

O Apidog também tem extensão para VS Code. Isso é um risco?

Sim, qualquer ferramenta cliente pode ser parte da superfície de ataque. O objetivo não é afirmar que uma extensão é imune, mas reduzir onde os segredos residem.

Manter credenciais em variáveis locais ou em integrações com cofre expõe menos chaves em texto simples caso alguma ferramenta local seja comprometida.

Qual é a diferença entre delimitar e rotacionar chaves?

Delimitar define o que a chave pode acessar. Por exemplo, uma chave de desenvolvimento acessa apenas sandbox, e uma chave somente leitura não pode modificar dados.

Rotacionar troca o valor da chave para que a anterior pare de funcionar.

Você precisa dos dois: escopo reduz o impacto; rotação reduz a janela de exploração.

Com que frequência devo rotacionar chaves de API?

Use um cronograma fixo. Um ponto de partida razoável:

produção de alto privilégio -> mensal
menor risco                 -> trimestral
desenvolvimento/staging     -> conforme uso e risco

Ajuste conforme requisitos internos, compliance e criticidade da credencial.

Chaves de produção devem estar em laptops de desenvolvedores?

Idealmente, não.

Credenciais de produção devem viver no menor número possível de lugares, normalmente em um gerenciador de segredos e no ambiente de execução de produção.

Desenvolvedores devem usar chaves de desenvolvimento ou staging com dados não produtivos. Se um laptop for comprometido, o invasor deve alcançar apenas um ambiente limitado.