Nota do autor: colocar o comando de execução de cenários do Apidog no CLAUDE.md, para que o Claude Code execute testes automatizados de API com base em cenários prontos, determine o resultado pelo código de saída e, usando a interface de vídeo Seedance como exemplo, projete asserções relacionadas a cobrança e moderação.
Se você já usa o Claude Code para escrever código de API, provavelmente já passou por esta situação: depois de alterar um campo, ainda é preciso ir até o Apidog, clicar manualmente para rodar o cenário uma vez e depois voltar para contar o resultado ao Claude Code. A abordagem apresentada neste artigo é colocar o comando de execução de cenários do Apidog CLI no CLAUDE.md, para que o Claude Code rode os testes por conta própria e leia o código de saída por conta própria, transformando o teste automatizado de API com Claude Code em um ciclo fechado.
Este não é mais um artigo introdutório sobre Claude Code. Os passos de operação do Apidog citados aqui vêm do tutorial do fabricante publicado oficialmente pela Apidog, e as regras de cobrança e moderação do Seedance vêm do texto original da documentação do APIYI; ambos terão a fonte indicada de forma explícita no corpo do texto, para você conferir por conta própria.
Valor central: ao terminar a leitura, você vai saber como fixar o comando de execução no CLAUDE.md, por que determinar aprovação ou reprovação pelo código de saída em vez da conclusão verbal do modelo, onde o token deve ficar e quais asserções realmente significativas devem ser escritas para uma interface de vídeo assíncrona.

Pontos-chave do Apidog para testes automatizados da API do Claude Code
Antes de colocar a mão na massa, vale dividir toda a solução em alguns pontos de decisão fundamentais. A tabela abaixo resume as restrições centrais dos tutoriais do fabricante e da documentação da APIYI que têm relação com esta solução — cada uma delas afeta diretamente a capacidade de o teste se reproduzir de forma estável.
| Ponto | Descrição | Valor |
|---|---|---|
| Comando de execução gravado no CLAUDE.md | O Claude Code lê o CLAUDE.md na raiz do repositório, e o formato do comando é apidog run -t ID do cenário -e ID do ambiente -r cli |
Toda sessão roda com o mesmo comando, sem depender da memória |
| Decidir o resultado pelo código de saída | Código de saída 0 indica que todas as asserções passaram; diferente de 0 indica que houve falhas | Evita que o modelo “diga que passou” quando na verdade não passou |
| Copiar os IDs da página CI/CD | O ID do cenário e o ID do ambiente são obtidos na página CI/CD do cenário correspondente no Apidog | Impede que o modelo invente um ID e o cenário acabe não sendo encontrado |
| O token não vai para o arquivo | Faça login na sua máquina com apidog login e não escreva --access-token no CLAUDE.md |
Evita que o token vaze ao ser enviado junto com o repositório |
| Separar os dois tipos de endpoint | O modelo de texto que move o Claude Code e a interface de vídeo testada não são o mesmo endpoint | Configuração clara e cobrança rastreável |
Como o Claude Code lê o CLAUDE.md
Segundo o tutorial do fabricante do Apidog, a ferramenta em si é o pacote npm apidog-cli, e o Claude Code lê o CLAUDE.md na raiz do repositório como descrição do projeto quando inicia. Ou seja, o comando de execução, as regras de decisão e as proibições que você escreve nesse arquivo passam a ser o contexto de cada sessão do Claude Code. Se você não tem certeza de quais arquivos de instrução foram carregados nesta sessão, execute /memory dentro do Claude Code para verificar.
Esse detalhe é o que determina a estabilidade da solução. Em vez de repetir “por favor, rode o cenário do Apidog para mim” em cada conversa, é melhor fixar o comando de uma vez. Depois de terminar de alterar o código, o Claude Code chama apidog run conforme as instruções do CLAUDE.md e decide, com base na saída do terminal, se continua corrigindo ou encerra a tarefa.
Detalhes sobre o código de saída e o formato de relatório do Apidog CLI
O tutorial do fabricante enfatiza que o formato de relatório -r cli precisa ser mantido, porque o Claude Code depende da saída do terminal para decidir o próximo passo. Se você também quiser um relatório que possa abrir no navegador, adicione html ao parâmetro -r; o arquivo gerado fica no diretório ./apidog-reports. Atenção: é “adicionar”, não “substituir” — remover o relatório cli faz o Claude Code perder a base para ler o resultado.
O código de saída é o juiz de toda a solução. Vale seguir a ordem de verificação sugerida no tutorial: primeiro confirme que o comando apidog run realmente aparece no terminal; depois olhe o código de saída — quando o código diverge da conclusão verbal do modelo, vale o código de saída; se aparecer a mensagem de que o cenário não foi encontrado, volte ao CLAUDE.md e verifique se o ID está correto.

Teste automatizado de API com Claude Code: início rápido
Esta seção segue a ordem “preparar o ambiente → escrever o CLAUDE.md → configurar permissões → executar a primeira vez”. Como é um tutorial online, todos os comandos aparecem como código inline, e você pode copiá-los um a um no terminal para executar.
Primeiro passo: configurar o endereço de acesso ao modelo no Claude Code
O próprio Claude Code consome tokens para funcionar, e as chamadas ao endpoint de vídeo sob teste depois gastam outra cota. Por isso, primeiro é importante distinguir bem os dois tipos de URL base. Ao usar a APIYI, o Claude Code utiliza o protocolo nativo da Anthropic, e o endereço é https://api.apiyi.com; não acrescente /v1 no final, caso contrário será montado /v1/v1/messages e a requisição falhará. Somente para clientes compatíveis com o protocolo OpenAI o endereço é https://api.apiyi.com/v1.
Na prática, configure as variáveis de ambiente no shell em que o Claude Code será iniciado: defina ANTHROPIC_BASE_URL com o endereço nativo da Anthropic e ANTHROPIC_AUTH_TOKEN com o token que você criou na plataforma. Para os modelos da linha Claude, recomenda-se colocar o token no grupo ClaudeCode, separado do token usado depois pelo endpoint de vídeo.
🚀 Início rápido: a prática recomendada oficialmente é criar tokens separados no console da APIYI, em apiyi.com, um para o Claude Code e outro para o endpoint sob teste. Novos usuários têm cota de teste gratuita, suficiente para executar o primeiro cenário e só depois decidir qual modelo usar a longo prazo.
Etapa 2: Gravar as instruções de teste no CLAUDE.md
De acordo com o tutorial do fornecedor, o conteúdo relacionado a testes no CLAUDE.md deve incluir os itens a seguir; basta escrever cada um deles em uma frase clara:
- Comando de execução: o teste de regressão usa
apidog run -t <场景ID> -e <环境ID> -r cli, e os dois IDs devem ser preenchidos diretamente com os valores reais copiados da página de CI/CD do Apidog. - Regra de decisão: o resultado é determinado pelo código de saída do comando. 0 significa que tudo passou; um valor diferente de 0 indica que há falhas. Não use um resumo em linguagem natural como conclusão.
- Proibições: não invente nem modifique IDs de cenário ou de ambiente; não adicione
--access-tokenao comando. - Requisitos de relatório: mantenha
-r cli; se precisar de um relatório no navegador, adicionehtml. Os artefatos ficam em./apidog-reports. - Observação sobre região: se o projeto estiver implantado na região europeia do Apidog, o comando também precisa incluir
--api-base-url api.eu.apidog.com. Esse é o endereço regional do próprio Apidog e não tem relação com o endereço de acesso ao modelo.
Etapa 3: Login e configuração de permissões
O gerenciamento de tokens é a parte mais propensa a problemas. A recomendação do tutorial do fornecedor é executar apidog login uma vez na máquina local para concluir o login, e deixar claro que o token não deve ser gravado no CLAUDE.md, nem deve aparecer --access-token nesse arquivo. O CLAUDE.md normalmente é commitado junto com o repositório, então gravar um token nele equivale a expô-lo publicamente.
Por padrão, o Claude Code pergunta antes de executar comandos Bash. Se você quiser que ele execute os testes automaticamente, pode adicionar Bash(apidog run *) à lista de permissões allow em .claude/settings.json, liberando apenas esse tipo de comando. O tutorial também lembra que --dangerously-skip-permissions só é adequado para ambientes descartáveis como CI, não para a máquina local que fica ligada todos os dias.
| Item de configuração | Prática recomendada | Prática não recomendada | Fonte |
|---|---|---|---|
| Login no Apidog | apidog login na máquina local |
Gravar --access-token no CLAUDE.md |
Tutorial do fornecedor |
| Permissão de comando | allow Bash(apidog run *) |
Manter --dangerously-skip-permissions ativo na máquina local |
Tutorial do fornecedor |
| ID do cenário | Copiar da página de CI/CD | Deixar o modelo adivinhar ou gerar | Tutorial do fornecedor |
| Endereço do Claude Code | ANTHROPIC_BASE_URL sem /v1 |
Com /v1, causa duplicação de caminho |
Documentação da APIYI |
| Grupo do token | ClaudeCode para Claude, SeeDance2 para vídeo |
Usar um único token para todos os grupos | Documentação da APIYI |
Passo 4: Fazer a primeira execução funcionar e conferir
Depois de concluir a configuração, peça ao Claude Code para executar um teste de regressão. Seguindo a ordem de verificação do tutorial do fornecedor, você precisa confirmar com seus próprios olhos três coisas: o terminal exibiu o comando apidog run completo; o comando retornou um código de saída claro; e, se houver falha, a saída do terminal mostra exatamente qual asserção não passou. Só quando as três coisas são atendidas é que esse ciclo fechado realmente se estabelece.
💡 Dica técnica: Na primeira execução bem-sucedida, você pode alterar de propósito o valor esperado de alguma asserção para errado, confirmando que o código de saída vai se tornar diferente de 0 e que o Claude Code vai continuar a investigação com base nisso. Esse passo verifica se a regra “com base no código de saída” realmente está em vigor.
Claude Code na Prática: Testes Automatizados de API — Design de Asserções para a Interface de Vídeo Seedance
Os testes de interfaces de texto são mais intuitivos; é a interface de vídeo assíncrona que realmente põe à prova o design de asserções. Esta seção usa a série Seedance já disponível na APIYI como exemplo para explicar o que deve e o que não deve ser asserido em cenários do Apidog.
Modelos, grupos e preços do Seedance
De acordo com a documentação do APIYI, os IDs de modelo disponíveis para o Seedance são doubao-seedance-2-5-260628, doubao-seedance-2-0-260128, doubao-seedance-2-0-fast-260128 e doubao-seedance-2-0-mini-260615. O token de acesso usado para invocar esses modelos precisa pertencer ao grupo SeeDance2; caso contrário, a API retorna o erro “não há canal disponível para este modelo”. A interface de vídeo em teste e o modelo de texto que aciona o Claude Code são dois endpoints diferentes. Não basta alterar o campo model para que os dois passem a funcionar do mesmo jeito: no cenário com o Apidog, é preciso configurar separadamente as requisições de envio e de consulta conforme a documentação do Seedance.
A tabela abaixo traz os preços por uso da tabela geral de preços (atualizada em 2026-11-16), em dólares / 1 milhão de tokens. Modelos e preços devem ser conferidos na lista de modelos da plataforma.
| Modelo | Entrada | Saída | Leitura de cache | Plataformas disponíveis |
|---|---|---|---|---|
doubao-seedance-2-5-260628 |
70 | 70 | N/D | APIYI apiyi.com |
doubao-seedance-2-0-260128 |
46 | 46 | N/D | APIYI |
doubao-seedance-2-0-fast-260128 |
37 | 37 | N/D | APIYI |
doubao-seedance-2-0-mini-260615 |
23 | 23 | N/D | APIYI |
A documentação também traz um exemplo de conversão para um vídeo de 5 segundos em 720p: cerca de 1.3721 dólares para o 2.5 e cerca de 0.9074 dólares para o 2.0 padrão. Vale destacar que isso é apenas um exemplo de conversão do preço por milhão de tokens para uma única gravação de vídeo; não se trata de duas tabelas de preços diferentes.
Cinco asserções recomendadas
As cinco asserções abaixo são baseadas no texto original da documentação e podem ser colocadas diretamente no cenário do Apidog:
- A tarefa tem ID: após o envio bem-sucedido da requisição, a resposta deve conter o ID da tarefa, do qual depende a consulta periódica (polling) subsequente; sem ID, considera-se falha.
- Duração passada explicitamente: o texto original da documentação afirma que o valor padrão de duration na versão 2.5 é -1; a requisição de teste deve passar a duração explicitamente, caso contrário os custos de diferentes rodadas não podem ser comparados.
- Erro de parâmetro não gera cobrança: o texto original da documentação afirma que erros de parâmetro HTTP 400 não são cobrados; pode-se construir uma requisição sem um campo obrigatório, afirmar que o código de status é 400 e confirmar no log que não houve cobrança.
- Bloqueio de moderação não gera cobrança: o texto original da documentação afirma que erros com prefixo
PUBLIC_são bloqueios de moderação de conteúdo do upstream, também não cobrados. A asserção apenas identifica esse tipo de código de erro e o distingue do erro de parâmetro como dois tipos de falha. - Só a soma dos dois logs é o preço total: o texto original da documentação afirma que um vídeo tem dois registros de cobrança no log — uma pré-cobrança no envio e um ajuste para mais ou para menos após a conclusão — e o custo total é a soma dos dois.
Quanto ao valor da pré-cobrança, o texto original da documentação indica cerca de 0,09 dólar/segundo para a série 2.0 e cerca de 0,135 dólar/segundo para a 2.5, com liquidação pelo token real após a conclusão. Portanto, a asserção de custo não pode olhar apenas o primeiro log, que é somente o valor pré-cobrado.

O que não vale a pena escrever como teste
O bloqueio pela moderação é uma fronteira de conformidade, não um caso de teste para “furar”. A documentação recomenda explicitamente não repetir a mesma instrução em retentativas depois de uma falha de moderação, então o cenário também não deve incluir etapas de retry em loop nem de sondar as regras de moderação. Da mesma forma, imagens de referência com rostos de pessoas reais são rejeitadas pelo upstream: é preciso primeiro colocá-las no acervo e só depois referenciá-las via asset://. Isso é uma pré-condição de conformidade e deve entrar nas instruções de preparação dos dados de teste, não como um caso de teste.
📊 Nota sobre os dados: as regras de cobrança e de moderação do Seedance acima foram tiradas do texto original da documentação do APIYI. Vale conferir a descrição mais recente na página do Seedance no centro de documentação em apiyi.com antes de fixá-las nas asserções.
Escolha do modelo que dirige o Claude Code e custo
Rodar testes com o Claude Code também consome tokens, e o modelo escolhido impacta direto o custo do dia a dia. A tabela abaixo traz os preços dos três modelos Claude na tabela geral de preços, também em dólares por 1 milhão de tokens; todos suportam os endpoints chat e messages.
| Modelo | Entrada | Saída | Leitura de cache | Grupo |
|---|---|---|---|---|
claude-opus-5-5 |
4 | 20 | 0.2 | ClaudeCode, Claude_Reverse, Claude_Enterprise, Default, SVIP |
claude-sonnet-5-5 |
2 | 10 | 0.1 | O mesmo |
claude-haiku-5-5 |
0.1 até 100 mil tokens, 0.5 acima disso | 0.5 | 0.01 | ClaudeCode, Claude_Enterprise, Default, SVIP |
Repare que a linha do Haiku não tem o grupo Claude_Reverse: se o seu token estiver só nesse grupo, mudar para o Haiku vai te deixar sem canal disponível. Uma abordagem comum é usar o modelo mais leve nas tarefas estruturadas do dia a dia — rodar a regressão, ler códigos de saída — e trocar para um modelo mais forte quando aparecer uma falha complexa que exige investigação mais profunda.
💰 Otimização de custo: como o modelo que dirige e a interface testada são cobrados dos dois lados, vale olhar os logs de uso no console do APIYI por token e medir separadamente o consumo do Claude Code e o consumo do Seedance, para descobrir de que lado o custo de teste está pesando mais.
Perguntas Frequentes (FAQ)
Q1: O que é a solução Apidog para testes automatizados de API com Claude Code?
É basicamente colocar o comando de execução de cenário do Apidog CLI no arquivo CLAUDE.md na raiz do repositório, deixar o Claude Code executar `apidog run` por conta própria depois de terminar as alterações no código, e usar o código de saída para decidir se os testes passaram — assim você não precisa clicar em “executar” manualmente.
Q2: Por que usar o código de saída como referência em vez da conclusão do Claude Code?
O resumo em linguagem natural do modelo pode ter desvios, enquanto o código de saída é um resultado determinístico dado pela ferramenta de testes. O tutorial do fornecedor diz claramente que, quando os dois divergem, prevalece o código de saída: 0 significa tudo aprovado, e qualquer valor diferente de 0 indica que há falhas.
Q3: Precisa adicionar /v1 no endereço de acesso do Claude Code?
Não. O Claude Code usa o protocolo nativo da Anthropic, e o endereço é `https://api.apiyi.com`; adicionar `/v1` faria com que ele fosse montado como `/v1/v1/messages`. Apenas clientes compatíveis com OpenAI é que usam o endereço com `/v1`.
Q4: Onde colocar o token do Apidog?
Na sua máquina, basta fazer login com `apidog login`. O tutorial do fornecedor exige explicitamente que você não escreva `–access-token` no CLAUDE.md nem coloque o token nesse arquivo, para evitar que ele vaze junto com o repositório de código.
Q5: Como começar a chamar o Seedance para testar a interface de vídeo?
Depois de se registrar em APIYI apiyi.com, crie um token pertencente ao grupo `SeeDance2`, configure as requisições de envio e consulta conforme a documentação do Seedance, e adicione ao cenário do Apidog asserções como o ID da tarefa, a duração explícita, a classificação dos códigos de erro e os dois logs de cobrança. O crédito gratuito de teste para novos usuários dá para rodar o primeiro cenário do início ao fim.
Q6: O Claude Code diz que não encontra o cenário, o que fazer?
Primeiro confirme o comando que está sendo executado de fato no terminal, depois volte ao CLAUDE.md e verifique o ID do cenário e o ID do ambiente. Copie novamente da página de CI/CD desse cenário no Apidog — não deixe o modelo adivinhar. Para projetos na região europeia, confirme também se foi adicionado `–api-base-url api.eu.apidog.com`.
Q7: Quais são as limitações dessa solução?
Primeiro, cobrança dupla: o Claude Code e a interface testada consomem tokens separadamente; segundo, seja comedido com as permissões liberadas — na sua máquina, libere apenas `Bash(apidog run *)`; terceiro, o bloqueio por moderação e o uso de imagens de referência com rostos reais são limites de conformidade, e só podem ser identificados e tratados antecipadamente — não podem ser projetados como casos de teste voltados a contornar restrições.
Testes automatizados da API do Claude Code — Principais conclusões
- Comando fixado: grave
apidog run -t -e -r clino CLAUDE.md e execute sempre o mesmo comando a cada sessão. - O código de saída é o juiz: 0 significa aprovado, qualquer valor diferente de 0 significa falha; se houver conflito com a conclusão falada, vale o código de saída.
- Isolamento do token: faça login na máquina local com
apidog login; nem o token nem--access-tokenentram no CLAUDE.md. - Permissões mínimas: libere apenas
Bash(apidog run *); o parâmetro que ignora permissões serve só para CI. - Não confunda os endereços: o Claude Code usa o endereço nativo sem
/v1; só a compatibilidade com OpenAI leva/v1. - Asserções de vídeo: ID da tarefa, duração explícita, 400 e a classificação
PUBLIC_, além do preço total somando as duas linhas de log. - Como começar: crie na APIYI tokens de grupo separados para
ClaudeCodeeSeeDance2e rode o primeiro cenário com a cota gratuita.
Resumo
A combinação dos testes automatizados da API do Claude Code com o Apidog se resume a três pontos:
- Deixe comandos e regras no arquivo: o CLAUDE.md carrega o comando de execução, as regras de julgamento e as proibições, enquanto o token fica a cargo do
apidog login. - Deixe o código de saída decidir: mantenha a saída de
-r clie confira comando, código de saída e ID na ordem do tutorial do fornecedor. - Faça as asserções refletirem a cobrança real: nas APIs assíncronas de vídeo, valide o status da tarefa, diferencie erro de parâmetro de bloqueio por moderação, some as duas linhas de log de cobrança e passe a duração explicitamente.
Sugiro começar com o cenário mais simples de API de texto para fechar o ciclo completo e, depois, ir adicionando as asserções das APIs assíncronas como a Seedance. Recomendo usar a APIYI, em apiyi.com, para gerenciar com a mesma conta os tokens e o consumo do Claude Code e do modelo testado: assim os custos dos dois lados ficam visíveis de imediato, o que facilita otimizar continuamente o gasto com testes.
📚 Materiais de referência
- Tutorial da Apidog (fabricante): como usar o Apidog CLI no Claude Code: autoria de INEZA Felin-Michel; a data da versão é a exibida no site
- Link:
apidog.com/blog/apidog-cli-in-claude-code -
Descrição: fonte para a escrita do CLAUDE.md, regras de códigos de saída, configuração de permissões e ordem de verificação
-
Apresentação oficial do Apidog CLI: posicionamento da CLI para agentes e CI, além de parâmetros regionais
- Link:
docs.apidog.com/en/introduction-to-apidog-cli-605134m0 -
Descrição: inclui a explicação sobre
--api-base-urlpara a região europeia -
Documentação do Seedance 2 da APIYI: ID do modelo, agrupamento, cobrança e regras de moderação
- Link:
docs.apiyi.com/api-capabilities/seedance2/overview -
Descrição: base para o design das asserções de vídeo deste artigo
-
Tabela geral de preços dos modelos da APIYI: preços por uso e agrupamento de cada modelo
- Link:
docs.apiyi.com/models -
Descrição: modelos e preços estão sujeitos ao conteúdo mais recente desta página
-
Notas de protocolo da APIYI: diferença entre o endpoint nativo da Anthropic e o endpoint compatível com OpenAI
- Link:
docs.apiyi.com/llms.txt - Descrição: explica por que o endpoint do Claude Code não pode incluir
/v1
Autor: Equipe técnica da APIYI
Contato técnico: fale conosco pela página inicial do site da APIYI; há mais materiais no Centro de Documentação em docs.apiyi.com