URL base, interfaces e autenticação

URL base da 1折AI, interfaces disponíveis, como escrever os cabeçalhos de requisição, e quando adicionar /v1 em cada ferramenta.

Todas as requisições são enviadas para o mesmo domínio, com dois conjuntos de caminhos por protocolo.

1
https://1zheai.com

Interfaces disponíveis

Interface	Protocolo	Uso
`POST /v1/messages`	Nativo Anthropic	Conversação. Claude Code, Anthropic SDK, Cline (modo Anthropic) usam esta
`POST /v1/chat/completions`	Compatível OpenAI	Conversação. OpenAI SDK, Cursor, Cherry Studio (modo OpenAI) usam esta
`GET /v1/models`	Compatível OpenAI	Lista os modelos que sua chave de API (API key) pode usar
`POST /v1/messages/count_tokens`	Nativo Anthropic	Conta o número de tokens de um trecho de entrada, sem gerar conversa, sem cobrança

O corpo da requisição de count_tokens é igual ao de /v1/messages (model, messages, pode incluir system e tools), e a resposta tem apenas um campo:

1
{"input_tokens":19}

count_tokens conta apenas o conteúdo que você envia. Ao chamar de fato usando SDK, curl ou ferramentas de terceiros, cada requisição também inclui um trecho de prompt de sistema, cobrado como tokens de entrada (Claude Code não inclui), veja cobrança do prompt de sistema.

Recursos exclusivos do Claude, como Prompt Caching, extended thinking e chamadas de ferramentas, funcionam de forma mais estável com o /v1/messages nativo. A interface compatível com OpenAI é adequada para cenários em que você já tem código OpenAI e apenas deseja trocar o modelo.

Quando adicionar /v1

Ferramentas diferentes interpretam a URL base de maneiras distintas; este é o erro mais comum na integração:

Ferramenta / SDK	O que preencher	Motivo
Claude Code (`ANTHROPIC_BASE_URL`)	`https://1zheai.com`	A própria ferramenta monta `/v1/messages`
Anthropic SDK (`base_url`)	`https://1zheai.com`	Idem
OpenAI SDK (`base_url`)	`https://1zheai.com/v1`	O SDK só monta `/chat/completions`
Cursor (Override OpenAI Base URL)	`https://1zheai.com/v1`	Igual ao OpenAI SDK
Cherry Studio	`https://1zheai.com`	Adiciona automaticamente `/v1/...`
Cline (OpenAI Compatible)	`https://1zheai.com/v1`	Igual ao OpenAI SDK

Regra: ferramentas da linha Anthropic usam o endereço raiz, ferramentas da linha OpenAI usam até /v1. O sintoma típico de preencher errado é 404.

Cabeçalhos de autenticação

A chave de API vai no cabeçalho da requisição; as duas formas abaixo são aceitas:

Anthropic 原生
Bearer（两种协议都支持）

x-api-key: sk-你的Key
anthropic-version: 2023-06-01
content-type: application/json

Authorization: Bearer sk-你的Key
content-type: application/json

Ao chamar /v1/messages, inclua anthropic-version conforme o protocolo oficial; o valor atual é 2023-06-01. Nos testes, funciona mesmo sem incluir, mas os SDKs e ferramentas oficiais incluem — ao escrever requisições manualmente, inclua também.
O ANTHROPIC_AUTH_TOKEN do Claude Code envia Authorization: Bearer, e o ANTHROPIC_API_KEY envia x-api-key; aceitamos as duas formas.
Quando precisar de recursos beta, inclua o cabeçalho anthropic-beta conforme a documentação oficial. Incluir um valor não reconhecido não gera erro, portanto, para saber se um recurso beta está ativo, confira o efeito real na resposta.

Verificar se a chave de API está funcionando

1
curl https://1zheai.com/v1/models \
2
  -H "Authorization: Bearer sk-你的Key"

Retornar a lista de modelos indica que a chave de API e o endereço estão corretos. Retornar 401 indica problema na chave de API; a resposta tem este formato (testado em 2026-10-15):

1
{"error":{"code":"","message":"Invalid token (request id: 202610150244361675490398268d9d6eKJPmcph)","type":"authentication_error"}}

Ao solicitar /v1/models com os cabeçalhos x-api-key e anthropic-version, a resposta é a lista de modelos no formato Anthropic (data[].id, display_name, has_more); é exatamente este formato que a descoberta automática de modelos do Claude Code lê.

Para outros casos, veja códigos de erro e solução de problemas.

Limites de taxa

Atualmente não há limite de taxa definido para chaves de API. Ao receber 429, normalmente é alta carga no upstream; tente novamente mais tarde e, em tarefas em lote, use backoff exponencial. Detalhes em códigos de erro e solução de problemas.

Rede

Em caso de timeout de conexão ou erro de TLS, primeiro confirme a rede usada pelo terminal: se houver proxy global ativo, desative o proxy e tente a conexão direta novamente; em redes corporativas com lista branca de saída, é necessário liberar 1zheai.com.