---
title: "URL base, interfaces e autenticação"
description: "URL base da 1折AI, interfaces disponíveis, como escrever os cabeçalhos de requisição, e quando adicionar /v1 em cada ferramenta."
headingIds: {"Interfaces disponíveis":"section-1","Quando adicionar /v1":"section-2","Cabeçalhos de autenticação":"section-3","Verificar se a chave de API está funcionando":"section-4","Limites de taxa":"section-5","Rede":"section-6"}
---

<aside className="docs-publication" data-pagefind-ignore>

Documentação mantida por [1ZheAI](https://1zheai.com/en/editorial/#publisher). [Fontes e correções](https://1zheai.com/en/editorial/).

Encontrou um erro? [Contate o suporte](mailto:support@1zheai.com) com o endereço da página e uma descrição. Não envie chaves de API ou credenciais de conta.

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

```text
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:

```json
{"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](/pt/docs/pricing-explained/#section-3).

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:

<CodeGroup>
```text title="Anthropic 原生"
x-api-key: sk-你的Key
anthropic-version: 2023-06-01
content-type: application/json
```
```text title="Bearer（两种协议都支持）"
Authorization: Bearer sk-你的Key
content-type: application/json
```
</CodeGroup>

- 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

```bash
curl https://1zheai.com/v1/models \
  -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):

```json
{"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](/pt/docs/troubleshooting/).

## 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](/pt/docs/troubleshooting/).

## 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`.