# 1折AI · Documentação completa
# Documentação da 1ZheAI
Source: https://1zheai.com/pt/docs/
Markdown: https://1zheai.com/pt/docs/index.md
---
title: "Documentação da 1ZheAI"
description: "Ponto de entrada para uso da API de modelos, contas prontas e recarga de assinaturas; avisos de compra, pedidos e regras de pós-venda."
headingIds: {"Integração da API de Modelos":"section-1","O que você deseja fazer":"section-2","Consulta e Suporte":"section-3","Perguntas mais comuns antes de usar":"section-4","Consulta rápida para desenvolvedores":"section-5"}
---
Comece pelo que precisa: conectar uma API de modelos, comprar uma conta de IA ou ativar uma assinatura em uma conta existente.
Confirme a plataforma, o plano de assinatura, o conteúdo entregue e os cuidados no primeiro acesso.Verifique as condições da conta, os dados necessários e o processo de ativação.Confirme a região, a validade, a forma de resgate e a conta aplicável.Entenda as regras de cancelamento, falhas na entrega, banimento de conta e reembolso.
## Integração da API de Modelos
A 1折AI oferece APIs Claude e OpenAI / GPT, com suporte a Anthropic Messages, OpenAI Responses e Chat Completions. As interfaces mais usadas incluem: o `/v1/messages` nativo da Anthropic e o `/v1/chat/completions` compatível com OpenAI. No seu código e ferramentas, normalmente basta alterar dois pontos: Base URL e chave de API (API key).
```text
Anthropic Base URL https://1zheai.com
OpenAI Base URL https://1zheai.com/v1
API Key sk-...（在控制台创建）
```
A entrada e a saída do Claude são cobradas com o desconto de cada modelo; a leitura e a gravação de cache são cobradas ao preço oficial original, sem desconto. Os preços e unidades de cobrança de GPT, MiMo e modelos de geração de imagens estão em [Modelos e preços](https://1zheai.com/en/pricing/).
Claude, GPT, MiMo e modelos de geração de imagens já estão disponíveis; a lista completa está em [Modelos suportados](/pt/docs/models/).
## O que você deseja fazer
Claude Code, Codex CLI, Cursor, Cline, Cherry Studio e CC Switch. Primeiro veja o escopo de suporte e depois configure seguindo os passos.Comece com Anthropic SDK, OpenAI SDK ou curl e continue entendendo a saída em streaming.Documentação legível por máquina, lista de páginas e instruções de tarefa de integração de IA copiáveis.Registre-se, crie uma chave de API e conclua a primeira requisição.
## Consulta e Suporte
Encontre endpoints, protocolos, exemplos e escopo de compatibilidade.Veja custos, registros de chamadas e caminhos de resolução de problemas.
## Perguntas mais comuns antes de usar
Verifique os campos retornados e o uso; essas verificações não podem provar por si só a origem do modelo.
Como ativar o cache, como verificar acertos e quanto economiza após um acerto.
O que significam 401, 404, 429 e 5xx.
Formas de pagamento, reembolso em 7 dias, regras de fatura.
## Consulta rápida para desenvolvedores
| Sua tarefa | Veja diretamente |
| --- | --- |
| Escrever código pela primeira vez | [Exemplo completo e executável](/pt/docs/code-examples/) |
| Migrar de outra plataforma | [Guia de migração](/pt/docs/migration/) |
| Consultar modelos e protocolos | [Consulta de modelos](/pt/docs/api-models/) · [Referência da interface](/pt/docs/api-reference/) |
| Lidar com timeouts e limitação de taxa | [Timeout e retry](/pt/docs/retries/) |
| Encontrar dúvidas comuns | [FAQ de integração](/pt/docs/faq/) |
---
# Início rápido
Source: https://1zheai.com/pt/docs/quickstart/
Markdown: https://1zheai.com/pt/docs/quickstart.md
---
title: "Início rápido"
description: "Crie uma chave de API da 1zheai, faça a primeira chamada a Claude / GPT com curl ou SDK e integre em clientes comuns."
headingIds: {"Também é possível começar pelo GPT":"section-1","Próximos passos":"section-2"}
---
Objetivo: obter uma chave de API (API key) em 5 minutos e concluir a primeira requisição a Claude ou GPT.
Abra [1zheai.com/register](https://1zheai.com/register?lng=pt) para se registrar. As chamadas são cobradas por consumo de saldo, portanto é necessário recarregar primeiro. O saldo é contabilizado em dólares (USD), com suporte a WeChat Pay, Alipay, Stripe (cartão de crédito) e USDT; os métodos específicos e os limites de valor são definidos pela página de pedido da carteira. Após a recarga, dentro de 7 dias é possível solicitar o reembolso do principal não utilizado pela mesma via de pagamento; a parte já consumida e as taxas de processamento de pagamento não são reembolsadas. As regras estão em [Recarga, reembolso e fatura](/pt/docs/billing/).
Entre no [console](https://1zheai.com/console?lng=pt), no menu lateral clique em "Chave de API", depois clique em "Criar chave de API" no canto superior direito, informe um nome e salve. A chave de API começa com `sk-`; na lista, clique no ícone de copiar para copiá-la e guarde-a. Detalhes em [Obter e gerenciar chaves de API](/pt/docs/api-keys/).
Coloque a chave de API em uma variável de ambiente e use o curl para chamar a interface nativa da Anthropic:
```bash title="macOS / Linux"
export ONEZHE_API_KEY="sk-你的Key"
curl https://1zheai.com/v1/messages \
-H "x-api-key: $ONEZHE_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-sonnet-5-5",
"max_tokens": 128,
"messages": [{"role": "user", "content": "用一句话解释什么是 HTTP"}]
}'
```
```powershell title="Windows PowerShell"
$env:ONEZHE_API_KEY = "sk-你的Key"
$body = @{
model = "claude-sonnet-5-5"
max_tokens = 128
messages = @(@{ role = "user"; content = "用一句话解释什么是 HTTP" })
} | ConvertTo-Json -Depth 5
Invoke-RestMethod -Uri "https://1zheai.com/v1/messages" -Method Post `
-Headers @{ "x-api-key" = $env:ONEZHE_API_KEY; "anthropic-version" = "2023-06-01" } `
-ContentType "application/json; charset=utf-8" `
-Body ([System.Text.Encoding]::UTF8.GetBytes($body))
```
`ONEZHE_API_KEY` é apenas um nome de variável de exemplo; qualquer nome pode ser usado.
Em caso de sucesso, retorna HTTP 200, com estrutura idêntica à oficial. Observe dois pontos: se `model` corresponde ao modelo solicitado e a quantidade de tokens em `usage`. Abaixo está a resposta real testada em 2026-10-15:
```json
{
"model": "claude-sonnet-5-5",
"id": "msg_011Cg3G8HQmyTrnqSBX6o6Pw",
"type": "message",
"role": "assistant",
"content": [
{
"type": "text",
"text": "HTTP(超文本传输协议)是一种基于请求-响应模式的应用层协议,用于在客户端(如浏览器)和服务器之间传输网页、图片、API 数据等内容。"
}
],
"container": null,
"stop_reason": "end_turn",
"stop_sequence": null,
"stop_details": null,
"usage": {
"input_tokens": 530,
"cache_creation_input_tokens": 0,
"cache_read_input_tokens": 0,
"cache_creation": {
"ephemeral_5m_input_tokens": 0,
"ephemeral_1h_input_tokens": 0
},
"output_tokens": 69,
"output_tokens_details": {"thinking_tokens": 0},
"service_tier": "standard",
"inference_geo": "global"
},
"input_transformations": [],
"diagnostics": null,
"context_management": {"applied_edits": []}
}
```
`input_tokens` é maior do que a própria pergunta em algumas centenas, pois é o prompt de sistema anexado a cada requisição desse tipo de cliente (curl, SDK, ferramentas de terceiros), cobrado como entrada; o Claude Code não o anexa, veja [Cobrança do prompt de sistema](/pt/docs/pricing-explained/#section-3).
Em seguida, no menu lateral do console, em "Log de chamadas", é possível ver esta chamada: horário, chave de API utilizada (coluna "Token"), modelo, tokens de entrada / saída, leitura e escrita de cache e custo.
## Também é possível começar pelo GPT
Se você usa a OpenAI SDK ou pretende integrar ao Codex, pode escolher diretamente o protocolo GPT. Primeiro defina o `ONEZHE_API_KEY` mencionado acima no mesmo terminal e depois execute:
```bash
curl --fail-with-body https://1zheai.com/v1/chat/completions \
-H "Authorization: Bearer $ONEZHE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"gpt-5.6-sol","messages":[{"role":"user","content":"用一句话解释 HTTP。"}]}'
```
Este é um exemplo de shell em macOS / Linux; no Windows, execute diretamente [exemplos multiplataforma em Python / Node.js](/pt/docs/code-examples/). O texto está em `choices[0].message.content`; se o modelo não estiver na sua lista, consulte primeiro [modelos disponíveis](/pt/docs/api-models/). O Codex requer Responses; integre conforme [tutorial de configuração do Codex](/pt/docs/quickstart-codex/).
## Próximos passos
Integre nas ferramentas que você usa com frequência:
Duas variáveis de ambiente são suficientes.
Use-o se não quiser editar manualmente os arquivos de configuração.
Formas de definir Base URL personalizada e suas restrições.
Se você já tem código OpenAI, altere apenas o base_url.
Se a requisição falhar, consulte primeiro [códigos de erro e solução de problemas](/pt/docs/troubleshooting/). Para conferir os campos retornados e o consumo, veja [verificar modelo e uso](/pt/docs/verify-model/).
---
# Obter e gerenciar chaves de API
Source: https://1zheai.com/pt/docs/api-keys/
Markdown: https://1zheai.com/pt/docs/api-keys.md
---
title: "Obter e gerenciar chaves de API"
description: "Como criar chaves de API que começam com sk- no console da 1zheai, além de armazená-las, rotacioná-las e conter danos em caso de vazamento."
headingIds: {"Criar uma chave de API":"section-1","Uma chave de API por ferramenta":"section-2","Onde armazenar":"section-3","O que fazer se vazar":"section-4","Perguntas frequentes":"section-5"}
---
Uma chave de API (API key) corresponde a uma permissão de chamada, e o custo é debitado do saldo da sua conta. Esta página explica como criar, onde armazenar e o que fazer em caso de incidente.
## Criar uma chave de API
Abra [1zheai.com/console](https://1zheai.com/console?lng=pt).
No menu lateral, clique em "Chave de API" e depois em "Criar chave de API" no canto superior direito. Preencha um nome que deixe claro o propósito, como `claude-code-macbook`, `ci-staging`; os demais campos podem ficar com os valores padrão e mesmo assim funcionarão. Clique em "Salvar alterações".
Itens configuráveis no formulário:
| Campo do formulário | Padrão | Descrição |
|---|---|---|
| Nome | Vazio | Diferencia as chaves de API nos registros de chamadas |
| Data de expiração | Nunca expira | Opções de 1 hora, 1 dia, 1 mês, ou data e hora específicas |
| Quantidade | 1 | Cria várias de uma vez; um sufixo aleatório é adicionado automaticamente ao nome |
| Alternador "Cota ilimitada" | Ativado | Ao desativar, aparece "Cota (USD)"; esta chave de API poderá gastar no máximo esse valor em dólares |
| Restrição de modelos (em "Configurações avançadas") | Vazio, significa que todos os modelos podem ser usados | Após selecionar modelos, esta chave de API só poderá chamar esses modelos |
| Lista branca de IPs (em "Configurações avançadas") | Vazio, significa sem restrição | Permite chamadas apenas dos IPs ou faixas CIDR listados |
As chaves de API começam com `sk-`. Após copiar, guarde-as em um gerenciador de senhas ou variável de ambiente; não as cole em conversas, capturas de tela ou repositórios de código.
## Uma chave de API por ferramenta
Recomenda-se criar uma chave de API separada para cada ferramenta e cada máquina. Os três benefícios:
- Os registros de chamadas são diferenciados por chave de API, permitindo ver de relance quanto cada ferramenta gastou.
- Se uma chave de API for vazada, basta excluir apenas aquela, sem afetar as demais ferramentas.
- Cada pessoa da equipe é responsável pela própria chave de API; ao sair da equipe ou trocar de máquina, exclua a chave correspondente.
## Onde armazenar
```bash title="Shell 配置（macOS / Linux）"
# 写进 ~/.zshrc 或 ~/.bashrc，只在本机生效
export ONEZHE_API_KEY="sk-你的Key"
```
```powershell title="Windows（当前用户，持久）"
[Environment]::SetEnvironmentVariable("ONEZHE_API_KEY", "sk-你的Key", "User")
# 重新打开终端后生效
```
```bash title=".env（项目本地）"
# .env 要写进 .gitignore
ONEZHE_API_KEY=sk-你的Key
```
O `.claude/settings.json` de nível de projeto do Claude Code geralmente é commitado no repositório, e a documentação oficial do Claude Code também recomenda explicitamente não escrever credenciais ali. Coloque a chave de API no `~/.claude/settings.json` de nível de usuário, ou no `.claude/settings.local.json` do projeto que não é commitado.
## O que fazer se vazar
1. Encontre-a na lista de "Chave de API", clique no ícone "Desativar" da coluna "Ações", ou selecione "Excluir" no menu "⋯". Após desativar, ela deixa de funcionar imediatamente; usá-la novamente retornará 401 `Invalid token`.
2. Crie uma nova chave de API e substitua-a onde estava sendo usada.
3. Abra os registros de chamadas (menu "Registros de chamadas" do console), clique em "Expandir", preencha "Nome do token" com o nome desta chave de API para filtrar e verifique se há chamadas recentes que não foram iniciadas por você.
## Perguntas frequentes
Sim, a chave de API não é vinculada a uma ferramenta. Porém, se você misturar o uso, os registros não mostrarão quem gastou o quê, então ainda assim é recomendável criar chaves separadas.
Na maioria dos casos, sim. Causas comuns: espaços ou quebras de linha copiados junto, chave de API já excluída, preenchida no campo errado da ferramenta. Para a verificação item a item, consulte [códigos de erro e solução de problemas](/pt/docs/troubleshooting/).
Por padrão, nunca expira. Ao criar ou editar, é possível definir um horário em "Data de expiração"; após expirar, as chamadas retornam 401 `Invalid token`, a mesma resposta de quando a chave de API está incorreta. A coluna "Expira" da lista mostra a data de expiração de cada chave de API.
---
# Modelos suportados
Source: https://1zheai.com/pt/docs/models/
Markdown: https://1zheai.com/pt/docs/models.md
---
title: "Modelos suportados"
description: "Consulte a disponibilidade, IDs de modelo, interfaces e preços dos modelos Claude, GPT, MiMo e de geração de imagens."
headingIds: {"Lista de modelos":"section-1","Ambas as interfaces podem ser usadas":"section-2","Modelos OpenAI / GPT":"section-3","Modelos MiMo":"section-4","Consulte a lista mais recente pela interface":"section-5","Como escolher":"section-6","Perguntas frequentes":"section-7","Modelos de imagem e consulta pela interface":"section-8"}
---
Os modelos Claude, GPT, MiMo e de geração de imagens já estão disponíveis. Abaixo estão listados os IDs de modelo do Claude e do GPT; a disponibilidade completa segue o catálogo de modelos e o que a interface retorna.
Consulte [modelos e preços públicos](https://1zheai.com/en/pricing/) para ver os preços; usuários logados podem acessar [Console · Modelos](https://1zheai.com/model-catalog?lng=pt) para consultar os modelos e ver como integrar.
## Lista de modelos
O `model` na requisição deve ser exatamente igual ao ID da tabela abaixo, incluindo o sufixo de data.
| ID do modelo | Série | Descrição |
|---|---|---|
| `claude-fable-5-1` | Fable 5.1 | |
| `claude-fable-5` | Fable 5 | |
| `claude-opus-5-5` | Opus 5.5 | |
| `claude-opus-5` | Opus 5 | |
| `claude-opus-4-8` | Opus 4.8 | |
| `claude-opus-4-7` | Opus 4.7 | |
| `claude-opus-4-6` | Opus 4.6 | |
| `claude-opus-4-5-20251101` | Opus 4.5 | ID de versão fixa com data |
| `claude-sonnet-5-5` | Sonnet 5.5 | |
| `claude-sonnet-5` | Sonnet 5 | |
| `claude-sonnet-4-6` | Sonnet 4.6 | |
| `claude-sonnet-4-5-20250929` | Sonnet 4.5 | ID de versão fixa com data |
| `claude-haiku-5-5` | Haiku 5.5 | |
| `claude-haiku-4-5-20251001` | Haiku 4.5 | ID de versão fixa com data |
O preço unitário de cada modelo (entrada, saída, leitura de cache, escrita de cache) está na [página de preços](https://1zheai.com/en/pricing/). As capacidades, o tamanho do contexto e as notas de lançamento de cada modelo seguem a [documentação oficial de modelos da Anthropic](https://platform.claude.com/docs/en/about-claude/models/overview).
## Ambas as interfaces podem ser usadas
Os modelos da tabela acima podem ser chamados tanto pela interface nativa da Anthropic `/v1/messages` quanto pela interface compatível com OpenAI `/v1/chat/completions`, com a mesma escrita de ID de modelo. Quando precisar de parâmetros exclusivos do Claude, como cache, thinking e chamada de ferramentas, use a interface nativa; veja [Base URL e autenticação](/pt/docs/base-url/).
## Modelos OpenAI / GPT
- `gpt-5.6-luna`
- `gpt-5.6-sol`
- `gpt-5.6-terra`
- `gpt-6-astra`
O GPT pode ser usado com o [SDK da OpenAI](/pt/docs/quickstart-openai-sdk/) e o [Codex CLI](/pt/docs/quickstart-codex/). A interface e a forma de cobrança de cada modelo seguem o [catálogo de modelos do console](https://1zheai.com/model-catalog?lng=pt).
## Modelos MiMo
Os IDs, interfaces suportadas e unidades de cobrança dos modelos de texto e voz do MiMo estão em [modelos e preços](https://1zheai.com/en/pricing/). O texto é cobrado por token e a voz pela unidade de cobrança do modelo correspondente; não aplique as regras de cache e desconto do Claude.
## Consulte a lista mais recente pela interface
Os modelos são adicionados ou removidos conforme os lançamentos oficiais; o que vale é o que a interface retorna:
```bash title="用你的 Key 查"
curl https://1zheai.com/v1/models \
-H "Authorization: Bearer sk-你的Key"
```
```bash title="公开价格接口（不需要 Key）"
curl -s https://1zheai.com/api/pricing | jq -r '.data[].model_name'
```
## Como escolher
Se não souber qual escolher, pode começar assim:
| Cenário | Sugestão |
|---|---|
| Programação do dia a dia, uso principal no Claude Code | `claude-sonnet-5-5` |
| Refatorações complexas, problemas difíceis de depurar | `claude-opus-5-5` |
| Subtarefas, resumos, classificação e outras tarefas leves | `claude-haiku-5-5` |
Para saber como mapear os três níveis opus / sonnet / haiku do Claude Code para modelos específicos, veja [integração com o Claude Code](/pt/docs/quickstart-claude-code/).
## Perguntas frequentes
Primeiro confira a grafia do ID e o sufixo de data e, em seguida, use o `/v1/models` acima para confirmar que sua chave de API (API key) consegue ver esse modelo. Nomes de modelo personalizados de outros provedores (por exemplo, com prefixo ou sufixo adicionado) não funcionam aqui.
Quando o modelo não existe ou não está disponível no momento, o gateway retorna HTTP 404. Na resposta nativa da Anthropic, o `error.type` é `not_found_error`; na resposta compatível com OpenAI, o `error.code` é `model_not_found`.
Primeiro confira o ID e a lista de modelos disponíveis da chave; não repita a mesma tentativa com um ID incorreto. O 503 só pode ser retornado quando o modelo existe, mas não há um serviço upstream saudável no momento; veja [códigos de erro e resolução de problemas](/pt/docs/troubleshooting/).
Em condições normais, o `model` da resposta é o ID que você solicitou. Se não corresponder, envie o horário da requisição e a resposta para support@1zheai.com; também pode seguir o procedimento em [verificar modelo e uso](/pt/docs/verify-model/).
## Modelos de imagem e consulta pela interface
O catálogo público, em 2026-10-16, lista `gpt-image-1.5` e `chatgpt-image-latest`. Veja [integração de geração de imagens](/pt/docs/api-images/); as permissões e parâmetros reais seguem sua chave e o catálogo de modelos.
Para exemplos completos da API de modelos, os dois formatos de resposta e o método de depuração quando a lista está vazia, veja [consultar API de modelos disponíveis](/pt/docs/api-models/).
---
# Migrar de outros serviços para 1折AI
Source: https://1zheai.com/pt/docs/migration/
Markdown: https://1zheai.com/pt/docs/migration.md
---
title: "Migrar de outros serviços para 1折AI"
description: "Migre item por item endereço, chave, modelo, protocolo e recursos, mantendo a configuração original reversível."
headingIds: {"Verifique as quatro configurações juntas":"section-1","Valide na ordem":"section-2","Escopo de aplicação das variáveis de ambiente":"section-3","Reverta quando a troca falhar":"section-4"}
---
Salve a configuração original antes de migrar. Primeiro valide em um terminal ou ambiente de desenvolvimento separado; confirme o sucesso antes de alterar ferramentas habituais ou serviços em produção.
## Verifique as quatro configurações juntas
| Configuração | Como escrever em 1折AI | Omissões comuns |
| --- | --- | --- |
| OpenAI Base URL | `https://1zheai.com/v1` | Escrever `/chat/completions` a mais, ou omitir `/v1` |
| Anthropic Base URL | `https://1zheai.com` | O SDK adiciona `/v1` mais uma vez |
| Chave da API | Chave criada no console deste site | Reutilizar a chave do provedor anterior |
| ID do modelo | ID completo retornado por `/v1/models` neste site | Reutilizar nomes com prefixo `vendor/` ou sufixo personalizado |
Requisições HTTP originais exigem o caminho completo do endpoint; SDKs e ferramentas de desktop geralmente exigem apenas a Base URL. Siga o [tutorial da ferramenta correspondente ](/pt/docs/integrations/).
## Valide na ordem
Faça uma chamada conforme a [interface de consulta de modelos ](/pt/docs/api-models/). Em caso de falha, corrija primeiro o endereço, as credenciais ou as condições de acesso; não ajuste vários parâmetros de negócio ao mesmo tempo.
Escolha [Chat Completions ](/pt/docs/api-chat-completions/), [Responses ](/pt/docs/api-responses/) ou [Messages ](/pt/docs/api-messages/). Mantenha o protocolo exigido pelo cliente original e remova primeiro os parâmetros opcionais.
Valide em sequência o streaming, o histórico de múltiplas rodadas, as chamadas de ferramentas e os demais recursos necessários. Adicione apenas um por vez e mantenha respostas de erro comparáveis. Texto comum bem-sucedido não significa que todos os recursos de arquivos, busca e modelos auxiliares do Agent sejam compatíveis.
Confirme o horário da requisição e o modelo nos [logs de chamada ](/pt/docs/usage-logs/). Reinicie terminais, IDEs ou serviços em segundo plano que precisam recarregar a configuração, para que não continuem usando variáveis de ambiente antigas.
## Escopo de aplicação das variáveis de ambiente
O `export` no terminal afeta apenas o shell atual e os processos filhos iniciados depois. Aplicações de desktop, contêineres, tarefas agendadas e serviços do sistema podem usar outro conjunto de ambiente; configure as credenciais onde o programa realmente é executado.
Campos de mesmo nome em arquivos de configuração também podem sobrescrever variáveis de ambiente. Ferramentas como Claude Code e Codex consultam seus próprios tutoriais; não empilhe todas as variáveis de provedores na configuração global do shell.
## Reverta quando a troca falhar
Restaure a configuração de provedor, endereço e modelo salva anteriormente e reinicie o cliente. Se você está migrando um negócio em produção, valide primeiro com poucas requisições e depois amplie o escopo; mantenha a forma de alternância de configuração na camada da aplicação para facilitar a recuperação do serviço.
Em caso de dúvida sobre se um recurso está disponível, consulte o catálogo de modelos ou contate o suporte. Não assuma que este site oferece o mesmo serviço apenas porque outras plataformas fornecem Embeddings, Batch ou algum modelo de imagem proprietário.
---
# Perguntas frequentes sobre acesso à API
Source: https://1zheai.com/pt/docs/faq/
Markdown: https://1zheai.com/pt/docs/faq.md
---
title: "Perguntas frequentes sobre acesso à API"
description: "Encontre rapidamente perguntas frequentes sobre URL base, modelos, streaming, clientes, tempo limite e monitoramento de disponibilidade."
headingIds: {"Endereço, chaves e modelos":"section-1","Requisições e clientes":"section-2","Status do serviço e ajuda":"section-3"}
---
## Endereço, chaves e modelos
No SDK da OpenAI, preencha `https://1zheai.com/v1`; nos SDKs da Anthropic e no Claude Code, preencha `https://1zheai.com`. Ao usar curl diretamente, informe o caminho completo da requisição. Algumas ferramentas de desktop completam o caminho automaticamente; consulte a [tabela de correspondência de endereços](/pt/docs/base-url/).
Sim. O acesso a este site usa uma chave de API criada no console deste site; a assinatura de clientes de consumo e as credenciais de API deste site são formas de acesso diferentes. A ferramenta também precisa suportar provedor ou endereço de API personalizado.
A lista exibe os modelos visíveis para a chave atual, não a taxa de sucesso de inferência em tempo real. Verifique também o protocolo da interface, os parâmetros opcionais e o status do upstream; consulte a [interface de consulta de modelos](/pt/docs/api-models/).
Copie o ID completo da lista de modelos deste site. Diferentes provedores podem usar prefixos, apelidos e versões de data diferentes; não tente renomear por suposição. Consulte o [guia de migração](/pt/docs/migration/) para os passos de migração.
## Requisições e clientes
Primeiro confirme o protocolo de resposta. Chat Completions lê `choices[].message.content`; Messages percorre blocos de texto de `content`; Responses percorre `output` ou usa `output_text` do SDK. Respostas de chamadas de ferramentas também podem não conter texto comum.
Conversas com múltiplas rodadas exigem que o cliente envie o histórico. Reutilizar a mesma chave repetidamente não cria automaticamente uma sessão no servidor. As extensões relacionadas a sessão do Responses precisam ser confirmadas separadamente; não dependa delas por padrão.
Também é necessário confirmar o evento de término ou o estado final. Erros no meio do fluxo, interrupções de streaming e truncamento de saída podem ocorrer depois que parte do texto já foi recebida. Consulte [saída em streaming](/pt/docs/streaming/) para detalhes.
Não é recomendado. O tempo limite pode ocorrer depois que a requisição já foi processada. Primeiro consulte os logs de chamada e, em seguida, execute as tentativas com número limitado de vezes, backoff e tempo total de espera, evitando que o SDK e a aplicação cada um façam uma rodada de tentativas. Consulte [tempo limite e tentativas](/pt/docs/retries/).
Não compile a chave em scripts de navegador nem em repositórios públicos. Mantenha as credenciais no seu servidor e chame a interface a partir dele; o navegador conecta apenas ao seu próprio backend. As variáveis de ambiente no código de demonstração são para o servidor ou terminal local.
## Status do serviço e ajuda
O monitoramento verifica a acessibilidade HTTP do site oficial, do console e da entrada da API; não representa a taxa de sucesso de inferência de cada modelo. O monitoramento é implantado no mesmo servidor que a aplicação; em caso de falha da máquina inteira, o monitoramento também fica pausado; os dados históricos começam a ser acumulados a partir da ativação.
Forneça a data e o fuso horário do ocorrido, a versão do cliente, o ID do modelo, o caminho completo da requisição, o código de status HTTP, o ID da requisição e as informações de erro com dados sensíveis removidos. Remova chaves, cabeçalhos de autenticação e conteúdo de conversas privadas; você pode organizar as informações conforme o [modelo de relato de problemas](/pt/docs/troubleshooting/).
---
# Guia de Compras da Loja
Source: https://1zheai.com/pt/docs/store-guide/
Markdown: https://1zheai.com/pt/docs/store-guide.md
---
title: "Guia de Compras da Loja"
description: "Entenda as diferenças entre contas prontas, recarga de assinatura e cartões-presente, faça o pedido seguindo as instruções do produto e acompanhe a entrega."
headingIds: {"Verificação antes do pedido":"section-1","Pedido e entrega":"section-2","O que é obrigatório saber antes de comprar":"section-3","Convidar amigos para comprar":"section-4"}
---
Escolha uma conta de IA, um serviço de assinatura ou um cartão-presente na loja. Leia a descrição do produto antes de fazer o pedido.
| O que você precisa | Serviço escolhido | Onde consultar |
| --- | --- | --- |
| Chamar modelos em código ou ferramentas | API de modelos | [Início rápido da API](/pt/docs/quickstart/) |
| Comprar uma conta de terceiros já existente | Conta pronta | [Compra e uso de contas prontas](/pt/docs/account-guide/) |
| Ativar assinatura na sua conta de terceiros | Recarga de assinatura | [Condições e processo de recarga](/pt/docs/subscription-guide/) |
| Obter códigos ou links de resgate | Cartão-presente | [Instruções de resgate e uso](/pt/docs/gift-card-guide/) |
As chaves de API deste site não podem fazer login no ChatGPT, Claude ou Grok; comprar membros de plataformas de terceiros também não equivale a recarregar o saldo da API deste site.
## Verificação antes do pedido
Confira nome do produto, especificação, região, duração da assinatura, estoque atual, forma de entrega e instruções de compra. Especificações não exibidas no catálogo ou não compráveis ainda não foram abertas; não pague seguindo o fluxo de páginas de demonstração ou de outros vendedores.
Se o produto suporta renovação, alteração de e-mail, uso por várias pessoas ou clientes específicos, a descrição do produto escolhido é a referência. Quando não houver menção clara, entre em contato com o suporte para confirmar antes; essas capacidades não são incluídas por padrão.
## Pedido e entrega
1. Escolha produto e especificação na [loja online](https://1zheai.com/en/store/).
2. Após entrar, confira preço de fechamento, quantidade e instruções de compra. Produtos de recarga também exigem preencher os dados solicitados no formulário.
3. Leia as regras de risco e pós-venda, marque a confirmação de forma ativa e então faça o pedido; o pedido é pago com o saldo da carteira deste site.
4. Consulte status, conteúdo entregue ou dados a complementar em [meus pedidos](https://1zheai.com/store-orders?lng=pt). Saldo recarregado com sucesso não significa que o produto foi comprado ou que a recarga foi concluída.
Produtos de entrega automática com estoque, produtos de entrega manual e recargas ativadas após o pedido têm formas de tratamento diferentes. Não há promessa unificada de entrega imediata ou prazo fixo de conclusão; a página de fechamento e o pedido são a referência.
## O que é obrigatório saber antes de comprar
Após entrega normal de conta pronta ou recarga bem-sucedida, se a conta for banida pela plataforma de terceiros, não há reembolso por banimento. Podemos auxiliar na apelação, mas não garantimos o resultado da reversão. Entrega não conforme, recarga sem sucesso ou situações em que a responsabilidade legal cabe a este site são tratadas pelas regras de pós-venda correspondentes.
[Regras de transação e pós-venda](/pt/docs/store-rules/) · [Solução de problemas de pedido](/pt/docs/store-orders/)
## Convidar amigos para comprar
Produtos da loja podem participar de comissão conforme a especificação. Escopo de participação, atribuição e condições de liquidação estão em [recompensas de convite e comissão da loja](/pt/docs/affiliate-guide/).
---
# Compra e Uso de Contas Prontas
Source: https://1zheai.com/pt/docs/account-guide/
Markdown: https://1zheai.com/pt/docs/account-guide.md
---
title: "Compra e Uso de Contas Prontas"
description: "Especificações, conteúdo da entrega, primeiro login e riscos de banimento a confirmar antes de comprar contas prontas de ChatGPT, Claude e Grok."
headingIds: {"Confirmar Antes da Compra":"section-1","Após Receber a Conta":"section-2","Uso Diário e Renovação":"section-3","Banimentos e Serviós Pós-Venda":"section-4"}
---
Uma conta pronta entrega uma conta de plataforma de terceiros conforme descrito na listagem do produto selecionado. Se uma assinatura está incluída, o nível da assinatura e a duração restante são todos determinados por esse produto e pelo pedido; não julgue apenas pelo nome da plataforma.
## Confirmar Antes da Compra
- Se uma assinatura está incluída, e o nível específico (por exemplo, Pro, Max) e a duração; especificações não exibidas não estão disponíveis para venda.
- Região, método de login e conteúdo da entrega; se é fornecido acesso ao e-mail, recebimento de código de verificação ou capacidade de alteração de e-mail.
- Se é uma entrega única ou possui arranjos de renovação separados; não assuma que renovação automática, encaminhamento de e-mail ou lembretes de renovação estão incluídos.
- Se é permitido uso em equipe, compartilhado ou transferido, bem como os próprios termos e restrições regionais da plataforma de terceiros.
## Após Receber a Conta
1. Em [Meus Pedidos ](https://1zheai.com/store-orders?lng=pt) verifique o produto, as especificações e as informações de entrega, e guarde o número do pedido em local seguro.
2. Siga as instruções de login daquele produto para acessar a plataforma correspondente, e verifique se a conta consegue fazer login, seu nível de assinatura e seu período de validade.
3. Altere a senha, recupere informações ou ative a verificação de segurança da maneira permitida pelo produto; para itens que não podem ser alterados, entre em contato com o suporte primeiro para confirmar.
4. Se as informações entregues forem inválidas, as especificações não corresponderem ou o login falhar, mantenha capturas de tela com informações redigidas e mensagens de erro, e explique a situação pelo canal de suporte do site oficial. Não compartilhe publicamente senhas de conta, códigos de verificação ou códigos de recuperação.
## Uso Diário e Renovação
Cumpra os termos de uso da plataforma. A conta pode estar sujeita a restrições regionais, de volume de uso, de verificação de identidade ou de controle de risco; a compra não inclui nenhuma garantia de contornar restrições, realizar verificação de identidade em seu nome ou nunca ser banida. A verificação de identidade deve ser concluída pelo usuário real conforme exigido pela plataforma; não envie documentos de identidade ou códigos de verificação ao atendimento ao cliente, a menos que exista outro processo legítimo explícito e necessário.
Quando a renovação for necessária, primeiro confirme o método suportado pelo produto atual; não aplique recargas destinadas à sua própria conta diretamente em uma conta pronta, e não empilhe assinaturas incompatíveis por conta própria.
## Banimentos e Serviós Pós-Venda
Após uma conta pronta ter sido entregue normalmente ou uma recarga ter sido bem-sucedida, se a conta for banida pela plataforma de terceiros, nenhum reembolso é emitido devido ao banimento. Podemos auxiliar com um recurso, mas não prometemos um resultado de desbanimento. Falha em entregar conforme acordado, recarga sem sucesso, ou situações em que este site deve assumir responsabilidade conforme a lei são tratadas de acordo com as regras de pós-venda correspondentes.
[Regras Detalhadas de Transação ](/pt/docs/store-rules/) · [Solução de Problemas de Pedidos ](/pt/docs/store-orders/)
---
# Condições e processo de recarga de assinatura
Source: https://1zheai.com/pt/docs/subscription-guide/
Markdown: https://1zheai.com/pt/docs/subscription-guide.md
---
title: "Condições e processo de recarga de assinatura"
description: "Antes de recarregar com sua própria conta, verifique elegibilidade, dados necessários, avisos de segurança e forma de processamento do pedido."
headingIds: {"Verifique primeiro as condições da conta":"section-1","Processo do pedido":"section-2","Segurança dos dados":"section-3","Em processamento, falhas e reembolsos":"section-4"}
---
A recarga de assinatura ativa o plano escolhido em uma conta de plataforma de terceiros que já é sua; não entrega uma nova conta. A disponibilidade do produto, as plataformas e os níveis suportados são os exibidos atualmente na [loja](https://1zheai.com/en/store/). Este artigo não indica que todas as plataformas ou especificações já estejam abertas.
## Verifique primeiro as condições da conta
Confira a região, o tipo de conta, o status atual da assinatura, pendências, histórico de reembolsos e restrições de renovação exigidos pelo produto escolhido. As condições podem variar conforme o canal; não é exigido universalmente que todas as contas sejam Free, nem é garantido universalmente que seja possível empilhar, fazer upgrade ou estender uma assinatura existente.
Se já houver assinatura ativa, pendências, restrições da plataforma ou incerteza sobre a elegibilidade da conta, entre em contato com o suporte primeiro. Não faça pedidos repetidos para testar e não substitua as instruções deste site pelas orientações de outro vendedor.
## Processo do pedido
1. Escolha a especificação específica e confirme preço, duração, conta aplicável e forma de ativação.
2. Preencha no formulário de checkout deste site os dados exigidos pela especificação, como identificador da conta ou Organization ID; os campos variam conforme o produto.
3. Confira a conta de destino e os dados, leia os avisos de risco e envie o pedido.
4. Acompanhe o progresso em [Meus pedidos](https://1zheai.com/store-orders?lng=pt). Atualize os dados apenas quando o pedido original indicar que é possível corrigi-los; não compre novamente.
5. Quando o pedido mostrar conclusão, faça login na plataforma de terceiros e verifique o nível da assinatura e a validade; se ainda não estiver atualizado, atualize a página ou faça login novamente e confira de novo; se ainda houver divergência, entre em contato com o suporte.
## Segurança dos dados
Algumas especificações podem exigir dados de sessão de login, como Session JSON. Esses dados podem permitir acesso à sua conta e são tão sensíveis quanto uma senha. Envie-os apenas no formulário dedicado do pedido correspondente neste site; não os envie por chat online, e-mail, capturas de tela públicas ou sites de consulta de contas de terceiros. Envie-os apenas depois de compreender o escopo da autorização e aceitar os requisitos do produto; se não puder aceitar, não compre essa especificação.
Não envie senhas, códigos de verificação, chaves de API ou sessões de login completas em mensagens comuns de atendimento. Após o processamento, verifique e gerencie os dispositivos e sessões de login conforme o método fornecido pela plataforma de terceiros.
## Em processamento, falhas e reembolsos
O processamento começa após o pagamento; depois de entrar na fase de processamento, não é possível cancelar diretamente. Aviso de tempo esgotado ou falha não equivale a reembolso, nem equivale a ativação com certeza não realizada. Mantenha o pedido original, aguarde a atualização de status ou entre em contato com o suporte para conferir, evitando cobranças duplicadas ou ativações duplicadas. O resultado e o destino do reembolso seguem o pedido e o extrato da carteira deste site; não há garantia de devolução sempre pela mesma via.
Após a entrega normal de uma conta pronta ou a recarga bem-sucedida, se a conta for banida pela plataforma de terceiros, o reembolso não é feito por causa do banimento. Podemos auxiliar na apelação, mas não garantimos o resultado da reversão. Entrega não conforme, recarga não bem-sucedida ou situações em que a responsabilidade legal seja deste site são tratadas conforme as regras de pós-venda correspondentes.
[Regras de transação e pós-venda](/pt/docs/store-rules/) · [Solução de problemas de pedido](/pt/docs/store-orders/)
---
# Aviso de Resgate de Cartão-Presente
Source: https://1zheai.com/pt/docs/gift-card-guide/
Markdown: https://1zheai.com/pt/docs/gift-card-guide.md
---
title: "Aviso de Resgate de Cartão-Presente"
description: "Verifique a região, o período de validade, as contas elegíveis e as regras de entrega do cartão antes da compra e do resgate."
headingIds: {"Confirmar Antes da Compra":"section-1","Como Usar Após a Receção":"section-2","Cancelamento e Pós-Venda":"section-3"}
---
Os cartões-presente são entregues como código de resgate ou link de resgate; recargas de assinatura podem, em vez disso, ser ativadas diretamente por meio do processo de pedido. Estes são dois métodos de entrega diferentes — nem todas as recargas devem ser entendidas como a receção de um código de cartão e depois o resgate num site externo.
## Confirmar Antes da Compra
Verifique a plataforma, a região, a moeda ou valor nominal, o nível da assinatura, o período de validade e as condições de conta elegíveis indicados no produto. Se são suportadas assinaturas existentes, assinaturas móveis, resgates acumulados ou oferta de presente, deve ser revisto item a item na descrição do produto; não trate os períodos de validade ou condições de resgate de outros comerciantes como compromissos deste site.
Quando a loja não tem cartões-presente disponíveis para compra, isto significa que as compras não estão abertas no momento. Quando as regras da plataforma ou o estado de fornecimento mudarem, a exibição real do produto prevalecerá.
## Como Usar Após a Receção
1. Verifique o conteúdo entregue em [Os Meus Pedidos ](https://1zheai.com/store-orders?lng=pt); não partilhe publicamente o código de resgate nem capturas de ecrã que o contenham.
2. Confirme que está com sessão iniciada na conta de destino correta e, em seguida, vá ao ponto de resgate designado de acordo com a descrição do produto; tenha cuidado com sites desconhecidos que solicitem transferências adicionais ou palavras-passe.
3. Verifique novamente a região e o estado da conta antes de resgatar e confirme os benefícios efetivamente creditados após o resgate.
4. Se encontrar um código já utilizado, um código inválido, uma incompatibilidade de região ou benefícios não creditados, guarde o número do pedido, o conteúdo do erro e capturas de ecrã redigidas e contacte o suporte; não volte a comprar para resolver o problema.
## Cancelamento e Pós-Venda
Pedidos que ainda não começaram a ser processados podem ser cancelados através do ponto de entrada fornecido com o pedido; não são suportados reembolsos diretos após a entrega de um código de resgate. Para problemas, contacte o suporte para verificação. Casos de não entrega conforme acordado, entrega inválida ou situações em que este site tem responsabilidade legal serão tratados de acordo com as regras de pós-venda aplicáveis. Proibições de cartões-presente, restrições de resgate e condições de reembolso são regidos pelo aviso específico desse produto; as regras de reembolso de saldo da API não se aplicam.
[Regras de Transação e Pós-Venda ](/pt/docs/store-rules/) · [Resolução de Problemas de Pedidos ](/pt/docs/store-orders/)}
---
# Status do pedido e solução de problemas
Source: https://1zheai.com/pt/docs/store-orders/
Markdown: https://1zheai.com/pt/docs/store-orders.md
---
title: "Status do pedido e solução de problemas"
description: "Consulte o conteúdo entregue, o andamento do processamento, correções de dados e registros de reembolso, evitando pedidos duplicados."
headingIds: {"Significado dos status":"section-1","Perguntas frequentes":"section-2","O pagamento foi debitado, mas não recebi a conta ou a assinatura":"section-3","Preenchi os dados incorretamente":"section-4","O pedido mostra concluído, mas a plataforma ainda não tem a assinatura":"section-5","A conta foi banida ou foi solicitada verificação de identidade":"section-6","Onde ficam os reembolsos":"section-7","O que devo fornecer ao entrar em contato com o suporte":"section-8"}
---
Em[Meus pedidos](https://1zheai.com/store-orders?lng=pt)selecione o pedido correspondente. O histórico de compras, o conteúdo entregue e o andamento do processamento são baseados nesse pedido; registros de recarga de saldo não são pedidos de produto.
## Significado dos status
| Status | O que significa | Próximo passo |
| --- | --- | --- |
| Aguardando entrega | O pedido foi criado, mas a entrega ainda não foi concluída | Verifique a forma de entrega e as instruções do pedido; se houver opção de cancelamento disponível, solicite o cancelamento |
| Em processamento | Está sendo processado manualmente ou ativado por um canal parceiro | Mantenha o pedido original, não compre novamente; forneça ou corrija os dados conforme as instruções |
| Entregue | O conteúdo entregue ou o resultado da ativação foi fornecido | Para contas prontas, verifique o login e as especificações; para recarga por terceiros, verifique a assinatura; para gift cards, resgate conforme as instruções |
| Cancelado | O pedido original foi encerrado | Verifique o motivo do cancelamento e o extrato da carteira; o reembolso depende do registro real |
O progresso detalhado da recarga por terceiros pode indicar aguardando fornecimento, aguardando ativação, dados que precisam de correção ou reembolso em processamento. Esses progressos são diferentes do status final de conclusão; não julgue o resultado da ativação ou do reembolso com base em um único erro.
## Perguntas frequentes
### O pagamento foi debitado, mas não recebi a conta ou a assinatura
Abra primeiro os detalhes do pedido para verificar o status e o conteúdo entregue. Entregas manuais e recargas por terceiros nem sempre são concluídas imediatamente; se o prazo indicado na descrição do produto for ultrapassado, o status não for atualizado por muito tempo ou houver exibição anormal, entre em contato com o suporte e não faça outro pagamento.
### Preenchi os dados incorretamente
Atualize apenas quando o pedido original exibir a opção de correção, verifique a conta de destino antes de enviar. Se não houver opção ou o pedido já estiver entregue, entre em contato com o suporte primeiro; não há garantia de que uma assinatura já ativada possa ser transferida.
### O pedido mostra concluído, mas a plataforma ainda não tem a assinatura
Confirme se você está logado na conta de destino enviada, atualize a página ou faça login novamente e verifique as configurações de assinatura. Se ainda houver divergência, mantenha uma captura de tela com dados ocultados e o número do pedido e entre em contato com o suporte; não compre outro pedido por conta própria.
### A conta foi banida ou foi solicitada verificação de identidade
Use os canais oficiais da plataforma de terceiros para recorrer ou verificar. Após entrega normal ou recarga por terceiros bem-sucedida, não há reembolso por banimento; podemos auxiliar no recurso, mas não garantimos a reversão do banimento. Anomalias como não entrega conforme acordado são tratadas de forma separada conforme[regras de pós-venda](/pt/docs/store-rules/).
### Onde ficam os reembolsos
Verifique o motivo do cancelamento do pedido e o extrato da carteira. Saldo devolvido para a carteira é diferente de reembolso para o método de pagamento original; reembolsos com status em processamento ainda não foram concluídos, não envie a mesma solicitação novamente.
### O que devo fornecer ao entrar em contato com o suporte
Número do pedido, produto e especificação, horário e fuso horário do ocorrido, status do pedido, mensagem de erro com dados ocultados. Não envie senhas, códigos de verificação, Session JSON completo, códigos de resgate ou chaves de API.
---
# Regras de transação e pós-venda da loja
Source: https://1zheai.com/pt/docs/store-rules/
Markdown: https://1zheai.com/pt/docs/store-rules.md
---
title: "Regras de transação e pós-venda da loja"
description: "Diferencia cancelamento, falha na entrega, falha na ativação e banimento de conta por fase do pedido; saldo da API de modelo é tratado separadamente pelas regras de recarga."
headingIds: {"Informações antes do pedido":"section-1","Cancelamento e reembolso tratados por fase do pedido":"section-2","Risco de banimento deve ser compreendido separadamente":"section-3","Diferença em relação ao reembolso de saldo da API":"section-4","Quando precisar de pós-venda":"section-5"}
---
## Informações antes do pedido
Preço, especificações, quantidade, região, duração, método de entrega e avisos de risco são exibidos no produto ou no fluxo de checkout. Leia tudo antes de confirmar; em caso de condições não claras, entre em contato com o suporte primeiro. O pedido preserva as especificações e os avisos de risco confirmados no momento da compra; atualizações posteriores em páginas não alteram o registro de confirmação de pedidos históricos.
Este site é o ponto de entrada para a compra de produtos e a solicitação de pós-venda. Quando há parceiros de fornecimento envolvidos, este site verifica e trata com base no pedido; não faça pagamentos separados a fornecedores desconhecidos e não é necessário registrar uma conta de distribuição por conta própria.
## Cancelamento e reembolso tratados por fase do pedido
| Situação | Como tratar |
| --- | --- |
| Aguardando entrega e o pedido oferece opção de cancelamento | Pode solicitar cancelamento pelo pedido original; após sucesso, verifique o extrato de reembolso na carteira |
| Em processamento ou resultado de ativação pendente de confirmação | Não é possível cancelar diretamente; mantenha o pedido original aguardando verificação, não compre novamente |
| Impossível fazer login, entrega inválida ou especificação não corresponde | Forneça o número do pedido e comprovação com dados mascarados; o suporte verificará a situação da entrega |
| Recarga por terceiros falhou ou dados incorretos | Corrija conforme as instruções do pedido original ou entre em contato com o suporte; aviso de falha não significa reembolso concluído |
| Conta pronta entregue normalmente ou recarga por terceiros concluída com sucesso, e posteriormente banida por plataforma de terceiros | Não há reembolso por banimento; podemos auxiliar na apelação, sem prometer desbanimento |
| Gift card já entregue | Não suporta reembolso direto; entregas inválidas e outras anomalias ainda podem ser verificadas com o suporte |
## Risco de banimento deve ser compreendido separadamente
Após a entrega normal de uma conta pronta ou a conclusão bem-sucedida da recarga por terceiros, se a conta for banida por uma plataforma de terceiros, não haverá reembolso por causa do banimento. Podemos auxiliar na apelação, mas não prometemos o resultado do desbanimento. Entrega não conforme, recarga por terceiros não concluída com sucesso, ou situações em que a responsabilidade cabe legalmente a este site, serão tratadas pelas regras de pós-venda correspondentes.
Plataformas de terceiros podem ajustar termos, restringir acesso ou exigir verificação de identidade; este site não garante que não ocorrerá controle de risco, que não haverá banimento ou que a apelação será aprovada. Não confunda o banimento após entrega normal com entrega não conforme ou falha na ativação. As explicações acima não excluem responsabilidades que a legislação determine caber a este site.
## Diferença em relação ao reembolso de saldo da API
O reembolso do principal não utilizado da API de modelo é tratado de acordo com[Recarga, reembolso e fatura](/pt/docs/billing/). Se um produto da loja pode ser cancelado e como o reembolso é feito segue a fase do pedido e as regras do produto correspondente, sem aplicar diretamente a regra de 7 dias do saldo da API. Cancelamento de pedido com retorno à carteira e reembolso de recarga de carteira pelo mesmo caminho são duas operações diferentes.
## Quando precisar de pós-venda
A partir de[Meus pedidos](https://1zheai.com/store-orders?lng=pt), mantenha o número do pedido e forneça especificações do produto, horário do ocorrido, status do pedido, status exibido pela plataforma de terceiros e captura de tela do erro com dados mascarados. Entre em contato pelos canais de suporte divulgados no site oficial ou no console; não forneça senhas, códigos de verificação, sessões completas, códigos de troca ou imagens originais de documentos. Para localizar o problema específico, consulte[Solução de problemas de pedido](/pt/docs/store-orders/).
---
# Recompensas de Convite e Comissões da Loja
Source: https://1zheai.com/pt/docs/affiliate-guide/
Markdown: https://1zheai.com/pt/docs/affiliate-guide.md
---
title: "Recompensas de Convite e Comissões da Loja"
description: "Entenda a atribuição de convite das comissões da loja, os produtos elegíveis, as condições de liquidação e os status de comissão."
headingIds: {"Como participar":"section-1","Quais pedidos geram comissão":"section-2","Quando é liquidado":"section-3","Onde consultar":"section-4"}
---
Pedidos de produtos participantes podem gerar recompensas por indicação. O administrador configura a participação de cada produto de contas, ativação de assinaturas e cartões-presente; nem todos os produtos geram comissão automaticamente.
## Como participar
Copie seu próprio link de registro a partir da entrada de convite da [carteira](https://1zheai.com/wallet?lng=pt) no painel. Quando um amigo se registra por meio desse link, a relação de convite registrada pelo sistema é mantida. Ao fazer um pedido, a atribuição da comissão é determinada com base nessa relação; clicar posteriormente no link de outra pessoa não altera a atribuição, e o número do convidado não é enviado no formulário do pedido.
Amigos que já possuem uma relação de convite estabelecida e compram produtos elegíveis para comissão após a ativação da funcionalidade também seguem as regras de novos pedidos. Pedidos históricos anteriores à ativação da funcionalidade não recebem comissões da loja retroativamente. Compras realizadas por você mesmo não contam como seu próprio convite para comissão.
## Quais pedidos geram comissão
O administrador configura uma comissão fixa por produto, por especificação; preencher 0 indica não participação. Especificações cuja comissão real ainda não foi configurada não distribuem recompensas. No momento do pedido, são registrados o convidado, o produto, a quantidade e o valor da comissão; ajustes posteriores no preço ou na comissão do produto não alteram registros já criados.
As comissões da loja e as recompensas de registro são dois tipos de registros distintos. Recarregar a carteira de um amigo não equivale a comprar um produto e não gera automaticamente uma comissão da loja. A distribuição da recompensa de registro segue as configurações existentes de recompensa de convite do administrador.
## Quando é liquidado
| Situação do pedido | Tratamento da comissão |
| --- | --- |
| Aguardando entrega, em processamento ou com resultado de ativação pendente de confirmação | Apenas registra a comissão estimada; não pode ser transferida para o saldo |
| Conta pronta ou gift card entregues com sucesso, recarga concluída | Liquidado pelo sistema e creditado no saldo de recompensas |
| Pedido cancelado e reembolsado | A comissão estimada é anulada; nenhuma recompensa é distribuída |
| Envio duplicado do pedido ou notificação de conclusão processada repetidamente | O mesmo pedido é liquidado apenas uma vez |
Um pedido com erro ou tempo esgotado não significa que foi entregue; não se deve julgar se a comissão foi gerada com base em apenas um resultado de processamento. Banimentos ocorridos após a entrega normal da conta ou após o sucesso da recarga são tratados segundo as [regras de pós-venda da loja](/pt/docs/store-rules/).
Se a conta que recebe as recompensas for desativada ou atingir o limite de valor do sistema, a comissão permanece em estado pendente de liquidação e será retentada quando as condições forem restauradas; isso não afeta a entrega do pedido do comprador. Quando o pagamento do sistema e a funcionalidade de recompensas estão suspensos, a liquidação também fica suspensa.
## Onde consultar
A seção "Comissões recentes da loja" na carteira exibe produto, especificação, quantidade, valor e status dos pedidos elegíveis recentes:
- **Pendente de liquidação**: valor estimado, ainda não incluído nas recompensas disponíveis.
- **Creditado**: já incluído no saldo de recompensas; não some novamente com as recompensas disponíveis.
- **Anulado**: esta comissão não será mais distribuída.
As recompensas disponíveis mantêm a entrada existente de transferência para saldo e o requisito mínimo de transferência, e podem ser usadas em consumo da API de modelos. Recompensas não são um valor de saque em dinheiro nem equivalem a fundos disponíveis já recarregados na loja; a loja ainda valida conforme suas próprias regras de elegibilidade de fundos.
O convidado só pode visualizar registros de comissão atribuídos a ele. Os registros não exibem a identidade do comprador, número do pedido, senha da conta ou código de troca. Para conferir uma comissão, forneça o número do registro de comissão, o produto e o horário do ocorrido pelos canais de suporte divulgados no site oficial; não solicite dados de login do comprador.
---
# Tutorial de integração de ferramentas com Claude e GPT
Source: https://1zheai.com/pt/docs/integrations/
Markdown: https://1zheai.com/pt/docs/integrations.md
---
title: "Tutorial de integração de ferramentas com Claude e GPT"
description: "Tutoriais de configuração de API e escopo de suporte para Claude Code, Codex CLI, OpenCode, OpenClaw, WorkBuddy, Hermes Agent, Cursor, Cline, Cherry Studio e CC Switch."
headingIds: {"Ferramentas de programação":"section-1","Assistente de desktop":"section-2","Mais clientes e métodos de importação":"section-3","Plataformas de Agent":"section-4","Gerenciamento de configuração":"section-5","Outras ferramentas com API personalizada":"section-6","Como confirmar que a configuração está correta":"section-7"}
---
Acesse o tutorial da ferramenta que você está usando. Os status abaixo foram organizados a partir da documentação de integração existente e não representam que todas as versões das ferramentas tenham sido verificadas de ponta a ponta. Após atualizar a ferramenta, refaça a verificação de chamada presente na página.
## Ferramentas de programação
Integração nativa Anthropic. Variáveis de ambiente, arquivos de configuração e perguntas frequentes.Chamada de modelos OpenAI / GPT pela interface Responses.Diferenciação entre configurações v1 e v2, provedor OpenAI compatível personalizado.Integração compatível com OpenAI. Verifique primeiro o escopo de aplicação das chaves personalizadas e as diferenças de interface.Use preferencialmente o modo Anthropic; também é fornecida a configuração OpenAI Compatible.
## Assistente de desktop
Adicione um provedor personalizado no cliente de chat.Adicione um endereço personalizado pelas configurações do modelo; atenção à URL completa e ao interruptor de protocolo.
## Mais clientes e métodos de importação
Importação por link ou JSON da área de transferência; há configuração manual de reserva.Código QR de provedor para Android; o conteúdo da chave é ocultado por padrão.Campos de provedor personalizados e configuração de modelos.Endpoint YAML do administrador e chaves individuais por usuário.Configuração Anthropic da extensão do VS Code.
O protocolo de um clique serve apenas para operações já suportadas publicamente pelo cliente. O protocolo de abrir conversa do ChatWise não equivale à importação de chave; o LibreChat exige configuração do administrador. Não trate todas as ferramentas como se usassem o mesmo link de importação.
## Plataformas de Agent
Configure o provedor Anthropic personalizado e o modelo de Agent padrão.Configure Chat Completions por meio do assistente de modelos ou de um provider nomeado.Os tutoriais de OpenCode, OpenClaw, WorkBuddy e Hermes Agent foram conferidos com as configurações oficiais; a verificação de ponta a ponta neste site ainda não foi concluída. Confira a versão real conforme o tutorial e valide a chamada.
## Gerenciamento de configuração
Gerencie a configuração de provedores do Claude Code e reduza trocas manuais.
## Outras ferramentas com API personalizada
Verifique primeiro se a ferramenta permite definir endereço da API, chave e ID do modelo; em seguida, escolha a configuração conforme o protocolo:
| Protocolo suportado pela ferramenta | Interface deste site | Próximo passo |
| --- | --- | --- |
| Anthropic Messages | `/v1/messages` | Confira se o cliente adiciona automaticamente `/v1`; consulte [explicação do endereço](/pt/docs/base-url/) |
| OpenAI Chat Completions | `/v1/chat/completions` | Normalmente, preencha o Base URL com `https://1zheai.com/v1`; exceto em campos de endpoint completo |
| OpenAI Responses | `/v1/responses` | Preencha o Base URL com `https://1zheai.com/v1`; consulte [Codex CLI](/pt/docs/quickstart-codex/) |
| Suporta apenas login com conta oficial | Não usa a chave de API deste site | Confira se a ferramenta possui outra opção de provedor personalizado |
## Como confirmar que a configuração está correta
1. Escolha o protocolo e o Base URL conforme o tutorial; se cada ferramenta precisa de `/v1`, consulte a [tabela de correspondência de endereços](/pt/docs/base-url/).
2. Selecione um modelo disponível atualmente entre os [modelos suportados](/pt/docs/models/).
3. Faça uma requisição curta e verifique se a ferramenta retorna normalmente.
4. Confira a chamada correspondente nos [logs de chamada](/pt/docs/usage-logs/); não julgue por qual provedor a requisição passou apenas pelo conteúdo da resposta.
Em caso de problemas, consulte primeiro [códigos de erro e solução de problemas](/pt/docs/troubleshooting/). Ao escrever seu próprio programa, acesse o [guia de desenvolvimento](/pt/docs/guides/).
---
# Integração do Claude Code
Source: https://1zheai.com/pt/docs/quickstart-claude-code/
Markdown: https://1zheai.com/pt/docs/quickstart-claude-code.md
---
title: "Integração do Claude Code"
description: "Conecte o Claude Code ao 1折AI: use ANTHROPIC_BASE_URL e ANTHROPIC_AUTH_TOKEN (variáveis de ambiente ou settings.json), com instruções para Windows, mapeamento de modelos, extensão do VS Code e erros comuns."
headingIds: {"Caminho mais curto":"section-1","Passos completos":"section-2","Por que usar ANTHROPIC_AUTH_TOKEN":"section-3","Mapeamento de modelos":"section-4","Extensão do VS Code":"section-5","Configurações opcionais":"section-6","Perguntas frequentes":"section-7"}
---
O Claude Code precisa apenas de duas variáveis: `ANTHROPIC_BASE_URL` aponta para nós e `ANTHROPIC_AUTH_TOKEN` recebe sua chave de API (API key). Não é necessário fazer login em uma conta da Anthropic.
## Caminho mais curto
Se você já instalou o Claude Code e tem uma chave de API em mãos, escreva as duas linhas abaixo em `~/.claude/settings.json` e depois execute `claude`:
```json title="~/.claude/settings.json"
{
"env": {
"ANTHROPIC_BASE_URL": "https://1zheai.com",
"ANTHROPIC_AUTH_TOKEN": "sk-你的Key"
}
}
```
Se o arquivo já existir, mescle esses dois itens ao `env` existente, sem sobrescrever as demais configurações.
## Passos completos
Se já estiver instalado, pode pular. Os comandos abaixo vêm da [documentação oficial de instalação do Claude Code](https://code.claude.com/docs/en/setup):
```bash title="macOS / Linux"
curl -fsSL https://claude.ai/install.sh | bash
```
```powershell title="Windows PowerShell"
irm https://claude.ai/install.ps1 | iex
```
```bash title="Homebrew"
brew install --cask claude-code
```
```bash title="npm（需要 Node.js 22+）"
npm install -g @anthropic-ai/claude-code
```
Ao instalar com npm, não adicione `sudo`.
Crie uma nova chave de API no [console](https://1zheai.com/console?lng=pt); recomendamos usar uma dedicada ao Claude Code desta máquina. Veja [obter e gerenciar chaves de API](/pt/docs/api-keys/).
Localização do settings.json: no macOS / Linux é `~/.claude/settings.json`; no Windows é `%USERPROFILE%\.claude\settings.json`.
```json title="settings.json（推荐）"
{
"env": {
"ANTHROPIC_BASE_URL": "https://1zheai.com",
"ANTHROPIC_AUTH_TOKEN": "sk-你的Key"
}
}
```
```bash title="macOS / Linux 环境变量"
# 写进 ~/.zshrc 或 ~/.bashrc，然后重开终端
export ANTHROPIC_BASE_URL="https://1zheai.com"
export ANTHROPIC_AUTH_TOKEN="sk-你的Key"
```
```powershell title="Windows PowerShell"
# 持久写入当前用户，重开终端后生效
[Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "https://1zheai.com", "User")
[Environment]::SetEnvironmentVariable("ANTHROPIC_AUTH_TOKEN", "sk-你的Key", "User")
# 只在当前窗口生效
$env:ANTHROPIC_BASE_URL = "https://1zheai.com"
$env:ANTHROPIC_AUTH_TOKEN = "sk-你的Key"
```
```bat title="Windows CMD"
setx ANTHROPIC_BASE_URL "https://1zheai.com"
setx ANTHROPIC_AUTH_TOKEN "sk-你的Key"
```
Preencha `ANTHROPIC_BASE_URL` com o endereço raiz, sem adicionar `/v1`; o Claude Code monta `/v1/messages` automaticamente.
Execute `claude` no diretório do projeto e, dentro dele, digite `/status`. Observe duas linhas:
- a linha da base URL mostra `https://1zheai.com`
- a linha das credenciais mostra que a origem é `ANTHROPIC_AUTH_TOKEN`
Em seguida, faça uma pergunta e verifique no [log de chamadas](/pt/docs/usage-logs/) se há um novo registro. Se houver, a conexão está funcionando.
Se preferir não entrar na interface interativa, também é possível testar uma vez em modo não interativo (testado em 2026-10-15, retornou `ok`):
```bash
claude -p "say ok" --model claude-sonnet-4-6
```
## Por que usar ANTHROPIC_AUTH_TOKEN
O Claude Code tem duas variáveis que podem receber a chave de API; a diferença é a seguinte ([explicação oficial](https://code.claude.com/docs/en/authentication)):
| Variável | Forma de envio | Comportamento |
|---|---|---|
| `ANTHROPIC_AUTH_TOKEN` | `Authorization: Bearer <值>` | entra em vigor imediatamente após a definição, sem confirmação |
| `ANTHROPIC_API_KEY` | `x-api-key: <值>` | no modo interativo, na primeira vez exibe um aviso perguntando se você deseja usar essa chave de API |
Suportamos ambas; recomendamos `ANTHROPIC_AUTH_TOKEN`. **Defina apenas uma das duas**: se ainda houver um `ANTHROPIC_API_KEY` antigo da configuração oficial no sistema, remova-o para evitar mistura e erros 401.
Outras duas regras fáceis de errar:
- Quando o `env` em `settings.json` e um export no terminal definem a mesma variável, **o settings.json tem prioridade**. Se alterou a variável do terminal e não teve efeito, verifique primeiro o settings.json.
- Não escreva a chave de API no `.claude/settings.json` do projeto; esse arquivo costuma ser enviado ao repositório. Para diferenciar por projeto, use um `.claude/settings.local.json` que não seja enviado.
## Mapeamento de modelos
No Claude Code, `opus`, `sonnet`, `haiku` e `fable` são aliases; é possível especificar por variáveis de ambiente os modelos concretos a que eles correspondem. A faixa Haiku também é usada pelo Claude Code para executar algumas pequenas tarefas em segundo plano.
| Variável | Função | Valor de exemplo |
|---|---|---|
| `ANTHROPIC_MODEL` | modelo usado na inicialização | `claude-sonnet-5-5` |
| `ANTHROPIC_DEFAULT_OPUS_MODEL` | modelo apontado pelo alias `opus` | `claude-opus-5-5` |
| `ANTHROPIC_DEFAULT_SONNET_MODEL` | modelo apontado pelo alias `sonnet` | `claude-sonnet-5-5` |
| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | modelo usado pelo alias `haiku` e pelas tarefas em segundo plano | `claude-haiku-5-5` |
| `ANTHROPIC_DEFAULT_FABLE_MODEL` | modelo apontado pelo alias `fable` | `claude-fable-5-1` |
```json title="~/.claude/settings.json（带模型映射）"
{
"env": {
"ANTHROPIC_BASE_URL": "https://1zheai.com",
"ANTHROPIC_AUTH_TOKEN": "sk-你的Key",
"ANTHROPIC_MODEL": "claude-sonnet-5-5",
"ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-5-5",
"ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-5-5",
"ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-5-5"
}
}
```
O ID do modelo deve estar entre os [modelos suportados](/pt/docs/models/). Durante a execução também é possível alternar temporariamente com `/model claude-opus-5-5`.
## Extensão do VS Code
A extensão do VS Code do Claude Code verifica as credenciais antes de iniciar; a recomendação oficial é escrever as variáveis nas próprias configurações de usuário do VS Code (Paleta de comandos → Preferences: Open User Settings (JSON)):
```json title="VS Code settings.json"
{
"claudeCode.environmentVariables": [
{ "name": "ANTHROPIC_BASE_URL", "value": "https://1zheai.com" },
{ "name": "ANTHROPIC_AUTH_TOKEN", "value": "sk-你的Key" }
]
}
```
Se escritas apenas em `~/.claude/settings.json`, a verificação de login da própria extensão pode não conseguí-las ler.
## Configurações opcionais
| Variável | Função |
|---|---|
| `API_TIMEOUT_MS` | tempo limite da requisição; padrão 600000 (10 minutos); em tarefas longas, que tendem a estourar o limite, pode ser aumentado |
| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1` | desativa atualizações automáticas, telemetria, relatório de erros e outros tráfegos desnecessários. Atenção: definir como `0` ou `false` também conta como ativado; para desativar, é preciso remover esta variável |
| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1` | usado ao encontrar erros 400 como "Extra inputs are not permitted" |
| `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1` | faz com que a lista `/model` busque os modelos disponíveis em `/v1/models` |
`CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1` foi testado e está funcionando (Claude Code 2.1.296, 2026-10-15): após a inicialização, `[gatewayDiscovery] cached 14 models` aparece no log de debug, e os 14 modelos coincidem com os [modelos suportados](/pt/docs/models/).
Não defina `DISABLE_PROMPT_CACHING`; isso desativa o cache e a fatura fica visivelmente mais alta, veja [Prompt Caching](/pt/docs/prompt-caching/).
## Perguntas frequentes
O Claude Code não leu a chave de API. Verifique a grafia do nome da variável; se usa variáveis de ambiente, confirme que iniciou em um terminal recém-aberto; se usa settings.json, confirme que o JSON está correto (uma vírgula extra invalida tudo).
A chave de API foi copiada de forma incompleta, ou `ANTHROPIC_API_KEY` e `ANTHROPIC_AUTH_TOKEN` existem ao mesmo tempo e um deles é um valor antigo. Mantenha apenas um. Mais detalhes em [códigos de erro e solução de problemas](/pt/docs/troubleshooting/).
`ANTHROPIC_BASE_URL` contém `/v1` em excesso. Altere para `https://1zheai.com`.
Isso é o Claude Code executando pequenas tarefas em segundo plano na faixa Haiku. Para trocar por outro modelo, defina `ANTHROPIC_DEFAULT_HAIKU_MODEL`.
Remova (ou comente) as duas variáveis acima para voltar ao login oficial. Se costuma alternar, use [CC Switch](/pt/docs/quickstart-cc-switch/) e troque com um clique.
Não gera associação. Ao integrar ao 1折AI, o Claude Code usa nossa chave de API e não faz login na sua conta da Anthropic.
---
# Integração do Codex CLI
Source: https://1zheai.com/pt/docs/quickstart-codex/
Markdown: https://1zheai.com/pt/docs/quickstart-codex.md
---
title: "Integração do Codex CLI"
description: "Método de configuração para integrar o OpenAI Codex CLI com a 1折AI (model_providers em ~/.codex/config.toml), chamando modelos GPT por meio da Responses API."
headingIds: {"Arquivo de Configuração":"section-1","Instalando o Codex":"section-2","Perguntas Frequentes":"section-3"}
---
Os modelos OpenAI / GPT já estão ativos. O Codex CLI usa a OpenAI Responses API (`/v1/responses`) e se conecta usando a chave de API deste site. Para ver os modelos disponíveis e os preços, consulte o [catálogo de modelos](https://1zheai.com/model-catalog).
Primeiro, vamos esclarecer como configurar um provedor personalizado para o Codex. O formato vem da [documentação oficial de configuração do Codex](https://developers.openai.com/codex/config-reference).
## Arquivo de Configuração
A configuração do Codex fica em `~/.codex/config.toml`. Provedores personalizados só podem ser escritos neste arquivo de nível de usuário; a configuração `.codex/config.toml` `model_provider` em um projeto será ignorada.
```toml title="~/.codex/config.toml"
model_provider = "onezhe"
model = "gpt-6-astra"
[model_providers.onezhe]
name = "1折AI"
base_url = "https://1zheai.com/v1"
env_key = "ONEZHE_API_KEY"
wire_api = "responses"
```
O exemplo usa `gpt-6-astra`, que pode ser substituído por qualquer outro ID de modelo GPT suportado pela sua chave.
Significado de cada campo:
| Campo | Descrição |
|---|---|
| `model_provider` | Qual provedor usar, correspondente ao id em `[model_providers.]` abaixo. `openai`, `ollama`, `lmstudio` são nomes reservados e não podem ser usados |
| `base_url` | Deve incluir `/v1` |
| `env_key` | O Codex lê a chave de API desta variável de ambiente; o nome deve corresponder exatamente ao que você exporta |
| `wire_api` | A documentação oficial afirma que atualmente apenas `responses` é suportado; também é o padrão quando omitido |
Em seguida, coloque a chave de API em uma variável de ambiente:
```bash title="macOS / Linux"
export ONEZHE_API_KEY="sk-你的Key"
```
```powershell title="Windows PowerShell"
[Environment]::SetEnvironmentVariable("ONEZHE_API_KEY", "sk-你的Key", "User")
```
## Instalando o Codex
Os comandos a seguir vêm da documentação oficial do Codex:
```bash title="npm"
npm install -g @openai/codex
```
```bash title="Homebrew"
brew install --cask codex
```
```bash title="macOS / Linux 脚本"
curl -fsSL https://chatgpt.com/codex/install.sh | sh
```
```powershell title="Windows"
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
```
## Perguntas Frequentes
O nome da variável em `env_key` não corresponde ao que você realmente exportou, ou você abriu o terminal antes de definir a variável de ambiente. Verifique novamente os nomes em ambos os lados e, em seguida, reabra o terminal e tente novamente.
Não. A documentação oficial de configuração do Codex afirma que `wire_api` aceita apenas `responses`. Serviços que fornecem apenas uma API Chat Completions precisam de uma ferramenta adicional de conversão de protocolo para se conectar ao Codex.
Verifique os modelos atuais no [catálogo de modelos](https://1zheai.com/model-catalog) e preencha o ID do modelo em `model`. Após iniciar o Codex, faça uma solicitação curta e verifique o modelo e o status no [log de chamadas](/pt/docs/usage-logs/).
---
# OpenCode com Claude API
Source: https://1zheai.com/pt/docs/quickstart-opencode/
Markdown: https://1zheai.com/pt/docs/quickstart-opencode.md
---
title: "OpenCode com Claude API"
description: "Tutorial de configuração do OpenCode para conectar ao Claude API da 1折AI, incluindo endereço, chave e modelo, com escolha de protocolo, exemplos de configuração, etapas de verificação e erros comuns."
headingIds: {"Configuração do OpenCode v1":"section-1","Configuração do OpenCode v2":"section-2","Verificação da conexão e resolução de problemas":"section-3","Custos e outras formas de conexão":"section-4"}
---
Use a funcionalidade de provedor personalizado do OpenCode para conectar à 1折AI. Primeiro [crie uma chave de API](/pt/docs/api-keys/) e confirme os [modelos disponíveis atualmente](/pt/docs/models/); os IDs de modelo abaixo são exemplos, ajuste-os conforme as permissões da sua chave.
Data de verificação da configuração oficial: 2026-10-15. A configuração abaixo foi organizada com base na documentação oficial; a verificação ponta a ponta neste site ainda não foi concluída; conclua primeiro uma breve pergunta e verificação de chamada de ferramenta antes de usá-la em tarefas longas. Modelos OpenAI / GPT já estão disponíveis, a lista de modelos e preços está em [descrição dos modelos](/pt/docs/models/).
## Configuração do OpenCode v1
Com base nos [Providers oficiais v1](https://opencode.ai/docs/providers/): execute `/connect`, escolha Other, insira o ID do provedor `onezhe` e preencha a chave de API deste site. No projeto `opencode.json`, faça merge:
```json
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"onezhe": {
"npm": "@ai-sdk/openai-compatible",
"name": "1折AI",
"options": { "baseURL": "https://1zheai.com/v1" },
"models": {
"claude-sonnet-4-6": { "name": "Claude Sonnet 4.6" }
}
}
}
}
```
Em seguida, `/models` selecione o modelo desse provedor. `/connect` apenas salva as credenciais, não substitui a configuração do provedor. Aqui é escolhido explicitamente o SDK de Chat Completions; não pode ser trocado incorretamente pelo `@ai-sdk/openai` usado para Responses. A documentação oficial também permite referenciar variáveis de ambiente através de `options.apiKey: "{env:ONEZHE_API_KEY}"`.
## Configuração do OpenCode v2
Com base nos [Providers oficiais v2](https://opencode.ai/v2/docs/providers), use os campos nativos v2, não podem ser misturados com o v1 acima. No projeto `opencode.jsonc`, faça merge:
```json
{
"$schema": "https://opencode.ai/config.json",
"providers": {
"onezhe": {
"name": "1折AI",
"env": ["ONEZHE_API_KEY"],
"package": "@opencode/ai/providers/openai-compatible",
"settings": { "baseURL": "https://1zheai.com/v1" },
"models": {
"claude-sonnet-4-6": { "name": "Claude Sonnet 4.6" }
}
}
}
}
```
Forneça `ONEZHE_API_KEY` no ambiente do processo que inicia o OpenCode e depois `/models` selecione `onezhe/claude-sonnet-4-6`. A principal diferença do v2 é `providers`, `package`, `settings`, em vez de `provider`, `npm`, `options` do v1. Primeiro use `opencode --version` para confirmar a versão principal utilizada.
Se quiser usar o Anthropic nativo, o v1 oficial permite sobrescrever `provider.anthropic.options.baseURL`, o exemplo inclui `/v1`; o v2 lista `@opencode/ai/providers/anthropic-compatible`. Este tutorial segue uma configuração compatível com OpenAI explícita; não pode trocar o protocolo com base no nome do modelo nem prometer que cache e chamadas de ferramenta já foram verificados.
## Verificação da conexão e resolução de problemas
1. Salve e recarregue a configuração, confirme que o provedor atualmente selecionado é `onezhe` ou o modelo personalizado que você adicionou.
2. Envie uma pergunta curta, confirme que consegue obter uma resposta; em seguida tente uma pequena tarefa reversível, confirme separadamente a chamada de ferramenta e a conversa com múltiplas rodadas.
3. Abra o [log de chamadas](/pt/docs/usage-logs/), verifique o horário da requisição, o modelo, o status e o uso. Uma resposta de texto bem-sucedida não significa que todas as capacidades dos Agentes já são compatíveis.
4. Ao encontrar 404, verifique se o endereço e o protocolo deste artigo são compatíveis; ao encontrar 401, verifique a origem da chave e se o processo leu as variáveis de ambiente; ao encontrar 429, consulte as informações de limitação de taxa antes de tentar novamente. Mais casos em [códigos de erro e resolução de problemas](/pt/docs/troubleshooting/).
A chave deve ser armazenada apenas no ambiente local ou no armazenamento de credenciais da ferramenta; não a envie para repositórios de código, capturas de tela ou logs públicos. Serviços em segundo plano podem não herdar as variáveis de ambiente do terminal; modelos auxiliares, busca e outras ferramentas também podem ter configurações de provedor independentes, que precisam ser verificadas separadamente.
## Custos e outras formas de conexão
Consulte os [preços em tempo real da Claude API](https://1zheai.com/en/pricing/) e as [regras de cobrança](/pt/docs/pricing-explained/). Para outros clientes, retorne ao [diretório de conexão de ferramentas](/pt/docs/integrations/); para escrever seu próprio programa, use o [SDK e guia de desenvolvimento](/pt/docs/guides/).
---
# Integração com o Cursor
Source: https://1zheai.com/pt/docs/quickstart-cursor/
Markdown: https://1zheai.com/pt/docs/quickstart-cursor.md
---
title: "Integração com o Cursor"
description: "Como usar uma chave de API personalizada da OpenAI e uma Base URL no Cursor para chamar os modelos Claude da 1折AI, e quais funcionalidades não usam a chave de API personalizada."
headingIds: {"Configuração":"section-1","Problemas conhecidos":"section-2","Perguntas frequentes":"section-3"}
---
O Cursor permite preencher sua própria chave de API (API key) nas configurações, e os modelos de chat usam essa chave de API para enviar solicitações. Abaixo está como integrar com a 1折AI, além de algumas restrições que você precisa conhecer antes de começar.
Entenda estes três pontos antes de começar:
- Na documentação oficial do Cursor, **a chave de API personalizada só se aplica aos modelos de chat; a conclusão com Tab sempre usa os próprios modelos do Cursor**.
- As solicitações passam primeiro pelos servidores do Cursor antes de serem enviadas ao endereço que você preencheu, portanto a Base URL precisa ser acessível pela internet pública (`https://1zheai.com/v1` funciona, mas um proxy local `localhost` não funciona).
- A opção "Override OpenAI Base URL" não consta na documentação oficial do Cursor; a descrição da interface abaixo vem do fórum do Cursor e de tutoriais da comunidade e pode mudar após atualizações do Cursor.
## Configuração
Cursor → **Cursor Settings** → **Models**, localize a área Keys.
```text
OpenAI API Key sk-你的Key（1折AI 的 Key）
Override OpenAI Base URL https://1zheai.com/v1
```
A Base URL deve incluir `/v1`.
Na lista de modelos, clique em **Add model**, insira o ID do modelo, por exemplo `claude-sonnet-5-5`, e ative a opção dele. Os IDs dos modelos estão em [modelos suportados](/pt/docs/models/).
No painel Chat, selecione o modelo recém-adicionado e envie uma mensagem. Após a resposta funcionar normalmente, verifique esta chamada nos [logs de chamadas](/pt/docs/usage-logs/) do console.
## Problemas conhecidos
Há relatos no fórum do Cursor de que, após configurar o Override OpenAI Base URL, modelos cujo nome começa com `claude-` podem ser tratados pelo Cursor como modelos Anthropic, sendo encaminhados para a chave de API da Anthropic ou retornando erro diretamente. Ao selecionar Claude, o ID do modelo começa com `claude-`; se encontrar esse problema, limpe primeiro a chave de API da Anthropic preenchida no Cursor e tente novamente.
Referência: [tópico do fórum 144899](https://forum.cursor.com/t/anthropic-models-break-when-override-openai-baseurl-is-set/144899), [tópico do fórum 146998](https://forum.cursor.com/t/override-anthropic-base-url-automatically-switches-on-when-using-anthropic-byok/146998).
## Perguntas frequentes
Não. Segundo a documentação oficial do Cursor, a conclusão com Tab sempre usa os modelos nativos do Cursor e não passa pela sua chave de API.
Primeiro confirme se a Base URL inclui `/v1`. Relatos da comunidade indicam que o botão Verify nem sempre aprova nomes de modelos que não são da OpenAI; você pode enviar diretamente uma mensagem no Chat para testar, considerando como critério se há registro nos logs de chamadas.
Os tutoriais da comunidade relatam amplamente que apenas o Chat usa a chave de API personalizada; funcionalidades como Agent, Apply e Inline Edit podem continuar usando o próprio backend do Cursor. Considere como critério o que você realmente vê registrado nos logs de chamadas.
Se seu objetivo principal é usar Claude para escrever código, [Claude Code](/pt/docs/quickstart-claude-code/) (linha de comando ou extensão do VS Code) e [Cline](/pt/docs/quickstart-cline/) oferecem suporte mais completo a endereços personalizados.
---
# Integração com o Cline
Source: https://1zheai.com/pt/docs/quickstart-cline/
Markdown: https://1zheai.com/pt/docs/quickstart-cline.md
---
title: "Integração com o Cline"
description: "Integração do 1折AI no plugin Cline do VS Code: via Base URL personalizada Anthropic ou via OpenAI Compatible."
headingIds: {"Forma 1: Anthropic (recomendada)":"section-1","Forma 2: OpenAI Compatible":"section-2","Perguntas frequentes":"section-3"}
---
O Cline é um plugin de agente de programação para o VS Code. Ambas as formas permitem integrar o 1折AI; a forma Anthropic é recomendada, pois as capacidades nativas do Claude (incluindo cache) são mais completas.
## Forma 1: Anthropic (recomendada)
Abra as configurações do Cline e selecione **Anthropic** em **API Provider**.
- **Anthropic API Key** (preencha a chave da API): `sk-你的Key`
- Marque **Use custom base URL** e preencha `https://1zheai.com` (não adicione `/v1`)
Selecione na lista suspensa de modelos um dos [modelos suportados pelo 1折AI](/pt/docs/models/), por exemplo `claude-sonnet-5-5`.
## Forma 2: OpenAI Compatible
Selecione **OpenAI Compatible** em **API Provider**.
| Campo | Valor |
|---|---|
| Base URL | `https://1zheai.com/v1` |
| API Key | `sk-你的Key` |
| Model ID | `claude-sonnet-5-5` |
Clique em **Verify** para confirmar a conexão e, em seguida, envie uma pequena tarefa no Cline.
Na Model Configuration, é possível preencher a janela de contexto e o comprimento máximo de saída; preencha os valores correspondentes ao modelo de acordo com a [documentação oficial de modelos da Anthropic](https://platform.claude.com/docs/en/about-claude/models/overview).
## Perguntas frequentes
A forma Anthropic usa o `/v1/messages` nativo, com as capacidades de cache, thinking etc. mais completas; a forma OpenAI Compatible usa o `/v1/chat/completions`, com vantagem na universalidade. Ao usar modelos Claude, prefira a forma Anthropic.
O endereço da forma Anthropic não deve conter `/v1`; o endereço da forma OpenAI Compatible deve conter `/v1`. Os dois são exatamente opostos.
---
# Integração com o Cherry Studio
Source: https://1zheai.com/pt/docs/quickstart-cherry-studio/
Markdown: https://1zheai.com/pt/docs/quickstart-cherry-studio.md
---
title: "Integração com o Cherry Studio"
description: "Adicione a 1折AI como um provedor personalizado no Cherry Studio escolhendo o endpoint Anthropic ou OpenAI e inserindo a URL base, a chave da API e os modelos."
headingIds: {"Importação em um clique":"section-1","Configuração":"section-2","Escolhendo o endpoint Anthropic ou OpenAI":"section-3","Perguntas frequentes":"section-4"}
---
O Cherry Studio é um cliente de chat de IA para desktop onde você pode adicionar a 1折AI como um provedor personalizado.
## Importação em um clique
No console, em **Chaves da API → Ferramentas → Cherry Studio**, selecione o protocolo Anthropic ou OpenAI e clique em **Abrir Cherry Studio**. Após confirmar a importação no aplicativo, busque os modelos, ative o provedor e faça um teste. Se já existir uma configuração com o mesmo nome, verifique o aviso de substituição. O link de importação contém a chave completa — não o encaminhe.
O navegador não pode confirmar se o aplicativo está instalado. Se ele não abrir, instale e inicie o cliente uma vez primeiro, ou use as etapas manuais abaixo. O formato do protocolo foi verificado em relação à implementação oficial, mas a inferência real ainda precisa ser verificada em relação à sua versão e modelo específicos.
## Configuração
Configurações (ícone de engrenagem) → **Serviços de modelo** → **+ Adicionar provedor** na parte inferior da lista.
| Campo | O que inserir |
|---|---|
| Nome do provedor | `1折AI` |
| Chave da API | `sk-你的Key` |
| Endpoint | Selecione **Anthropic** (recomendado) ou **OpenAI** |
| Endereço da API | `https://1zheai.com` |
Insira apenas a URL base no campo Endereço da API; o Cherry Studio anexará automaticamente `/v1/...` com base no protocolo selecionado. Não cole caminhos completos como `/v1/messages` ou `/v1/chat/completions`, e não adicione `#` no final (um `#` final significa que nenhum caminho será anexado automaticamente).
Clique em **Obter lista de modelos** e adicione os modelos que deseja usar da lista retornada; ou clique em **+** para inserir manualmente um ID de modelo, como `claude-sonnet-5-5`. Apenas os modelos adicionados à lista aparecerão no seletor de modelos no chat.
Ative a chave de ativação no canto superior direito da página do provedor, volte para a interface de chat e envie uma mensagem usando um modelo sob a 1折AI.
## Escolhendo o endpoint Anthropic ou OpenAI
| Endpoint | Melhor para |
|---|---|
| Anthropic | Usar capacidades nativas do Claude, como pensamento estendido; consulte a versão atual para as restrições de protocolo do Agente |
| OpenAI | Estar acostumado ao formato OpenAI, ou gerenciar junto com outros serviços compatíveis com OpenAI |
Ambos os endpoints usam a mesma chave da API e o mesmo conjunto de IDs de modelos.
## Perguntas frequentes
Primeiro verifique se a chave da API tem espaços extras; depois confirme se o endereço da API é `https://1zheai.com` sem nenhum caminho extra escrito. Se você não conseguir buscar a lista, isso não afeta o uso — inserir manualmente um ID de modelo também funciona.
O endereço da API foi inserido como um caminho completo, ou `#` foi adicionado no final. Altere de volta para a URL base `https://1zheai.com`.
---
# Integração com Dify
Source: https://1zheai.com/pt/docs/quickstart-dify/
Markdown: https://1zheai.com/pt/docs/quickstart-dify.md
---
title: "Integração com Dify"
description: "Configure a 1折AI usando o plugin oficial OpenAI-API-compatible do Dify, cobrindo a configuração do modelo, testes de conversa e solução de problemas da primeira chamada."
headingIds: {"Pré-requisitos":"section-1","Adicionando um modelo":"section-2","Começando pela primeira conversa":"section-3","Importando o Chatflow de exemplo":"section-4","Solução de problemas":"section-5","Obtendo ajuda na integração":"section-6","Escopo de verificação":"section-7","English / Русский":"section-8"}
---
Usuários do Dify podem configurar o endpoint compatível com OpenAI da 1折AI por meio do plugin oficial de modelo **OpenAI-API-compatible**. Primeiro verifique um modelo de texto e depois use-o nos fluxos de trabalho; não é necessário instalar plugins de terceiros não verificados.
## Pré-requisitos
- Um espaço de trabalho do Dify onde plugins de modelo possam ser instalados.
- Sua própria chave de API da 1折AI, além dos IDs de modelo que essa chave está autorizada a chamar. Verifique o [console](https://1zheai.com/console).
- Saldo disponível suficiente em sua conta. A solicitação de validação ao salvar um modelo e os testes de aplicativo podem incorrer em cobranças normais de API.
Não envie sua chave completa ao suporte ao cliente, não a escreva em descrições de fluxos de trabalho, capturas de tela ou repositórios públicos. Armazene-a apenas no campo de chave de API do Dify; se você usar um Dify hospedado por terceiros, essa instância mantém sua chave e encaminha as solicitações.
## Adicionando um modelo
1. No marketplace de plugins do Dify, localize **OpenAI-API-compatible** e confirme que o publicador é **langgenius**.
2. Abra os provedores de modelo nas configurações do espaço de trabalho, localize este plugin e adicione um modelo LLM.
3. Preencha os campos abaixo e salve. Os rótulos da interface podem variar conforme a versão do Dify.
| Campo | Como preencher |
| --- | --- |
| Nome do modelo | Copie o ID completo do modelo do console da 1折AI; não substitua pelo nome de exibição |
| Chave de API | Sua própria chave da 1折AI |
| URL base da API | `https://1zheai.com/v1` |
| Modo de conclusão | `Chat` |
| Nome do modelo no endpoint da API | Geralmente deixe em branco; se definido, deve corresponder ao ID real do modelo |
| Tamanho de contexto do modelo | Preencha de acordo com a capacidade real do modelo selecionado; não copie o comprimento de contexto de outro modelo |
Aqui você precisa de `/v1`. Não insira o `/v1/chat/completions` completo e não o duplique como `/v1/v1`. Não aplique instruções de outros clientes que exigem apenas o endereço raiz.
## Começando pela primeira conversa
Crie um aplicativo de chat em branco, selecione o modelo que você acabou de salvar e digite "Por favor, apresente em uma frase, em chinês, o que você pode fazer." Assim que uma resposta de texto completa for confirmada, verifique em seguida a saída em streaming.
Verifique o tempo de solicitação correspondente, o modelo e o resultado nos registros de chamadas do console da 1折AI. Não confie apenas no "Salvo com sucesso" do Dify como prova de que o aplicativo está conectado. Somente após o primeiro sucesso você deve configurar chamadas de ferramentas, entrada de visão ou recuperação de base de conhecimento; esses recursos dependem do modelo e da interface específicos, e uma conversa de texto bem-sucedida não significa que tudo esteja disponível.
## Importando o Chatflow de exemplo
[Baixe o modelo de Chatflow sem chave](/pt/docs/downloads/1zheai-dify-chatflow.yml) e, no Dify Studio, escolha **Criar → Importar arquivo DSL** para enviá-lo. O modelo é `User Input → LLM → Answer`, versão DSL 0.7.0, usando o plugin compatível oficial 0.0.68.
Primeiro adicione suas próprias credenciais seguindo as etapas acima. Após a importação, abra o nó LLM e confirme que seu provedor e modelo próprios estão selecionados, e não o modelo de teste do Dify. O ID de modelo de exemplo é `claude-haiku-4-5-20251001`; se não estiver disponível para sua conta, troque por um modelo ao qual você tenha acesso e verifique as configurações de capacidade. O modelo não contém chave de API e não fornece créditos de chamada gratuitos.
## Solução de problemas
| Sintoma | O que verificar primeiro |
| --- | --- |
| 503 / Sem contas disponíveis | O upstream atual pode estar com limite de taxa ou sem capacidade. Verifique primeiro o status do serviço e os registros de chamadas, tente novamente mais tarde com backoff ou entre em contato com o suporte; não tente novamente com alta frequência continuamente e não regenere chaves repetidamente |
| 401 / Chave inválida | Se há espaços extras, se a chave foi revogada e se uma chave de outra plataforma foi usada por engano |
| 404 | Se a URL base é exatamente `https://1zheai.com/v1`; se o ID do modelo existe |
| Modelo não permitido ou saldo insuficiente | As restrições de modelo da chave atual, o saldo disponível da conta e o modelo selecionado |
| Salvo com sucesso, mas o aplicativo não consegue chamar | Se o aplicativo selecionou o provedor e o modelo corretos; se o servidor do espaço de trabalho consegue acessar a API |
| Respostas normais funcionam, streaming falha | Verifique o suporte SSE do proxy, a versão do plugin e a configuração de uso de streaming; mantenha um erro redigido para solução de problemas |
| Chamadas de ferramentas ou visão falham | Primeiro confirme se o modelo selecionado realmente suporta essa capacidade; evite forçá-la apenas alternando interruptores do plugin |
Solicitações de um Dify auto-hospedado são enviadas pelo seu servidor; o fato de seu navegador poder abrir o site oficial não significa que o servidor do Dify consiga conectar-se à API.
## Obtendo ajuda na integração
Forneça a versão do Dify, a versão do plugin, o ID do modelo, o carimbo de data/hora do erro, o ID da solicitação e os detalhes do erro redigido por meio do atendimento ao cliente online do site oficial. Não envie a chave completa, dados de clientes ou prompts privados de seus fluxos de trabalho.
## Escopo de verificação
Em 2026-10-19, usando o plugin oficial 0.0.68, a conversa de texto e as chamadas em streaming do Haiku foram concluídas no Dify Cloud e conferidas com os registros do gateway. O DSL sem chave exportado foi importado no mesmo espaço de trabalho como um novo aplicativo. Após a importação, um novo teste encontrou um 503 causado por limite de taxa upstream, portanto esta rodada não é registrada como uma execução pós-importação aprovada.
Este é um teste interno com uma janela de tempo definida, não uma garantia contínua de disponibilidade. Espaços de trabalho novos, versões mais antigas do Dify, chamadas de ferramentas, visão e recuperação de base de conhecimento não foram verificados; conclua seu primeiro teste com sua própria chave com limite de taxa.
[Fonte do plugin oficial](https://github.com/langgenius/dify-official-plugins/tree/main/models/openai_api_compatible) · [Marketplace de plugins do Dify](https://marketplace.dify.ai/)
## English / Русский
**English:** Install the official OpenAI-API-compatible plugin by langgenius. Set API Base URL to `https://1zheai.com/v1`, use your own API key and an exact model ID available to your account, and select Chat mode. Test a simple conversation before adding tools or vision. Text and streaming calls were verified in Dify Cloud on 2026-10-19. DSL import into a new app in the same workspace succeeded; its subsequent run encountered an upstream-capacity 503. Fresh-workspace import and advanced capabilities remain unverified. Never share your key with support.
**Русский:** Установите официальный плагин OpenAI-API-compatible от langgenius. Укажите API Base URL `https://1zheai.com/v1`, собственный API-ключ и точный ID модели, доступной вашему аккаунту; выберите режим Chat. Сначала проверьте простой диалог, затем потоковый вывод. Текстовые и потоковые вызовы проверены в Dify Cloud 19 октября 2026 года. Импорт DSL в новое приложение того же рабочего пространства прошёл, но повторный вызов вернул 503 из-за недоступной мощности upstream. Новое рабочее пространство и расширенные функции ещё не проверены. Не отправляйте ключ службе поддержки. Доступность из конкретной сети и способы оплаты проверяются отдельно.
---
# WorkBuddy: integração com a API do Claude
Source: https://1zheai.com/pt/docs/quickstart-workbuddy/
Markdown: https://1zheai.com/pt/docs/quickstart-workbuddy.md
---
title: "WorkBuddy: integração com a API do Claude"
description: "Tutorial de configuração do endereço, chave e modelo do Claude API via 1折AI no WorkBuddy, incluindo seleção de protocolo, exemplos de configuração, etapas de verificação e erros comuns."
headingIds: {"Verificação da integração e resolução de problemas":"section-1","Custos e outras formas de integração":"section-2"}
---
Use a funcionalidade de fornecedor personalizado do WorkBuddy para conectar-se ao 1折AI. Primeiro, [crie uma chave de API](/pt/docs/api-keys/) e confirme os [modelos disponíveis atualmente](/pt/docs/models/); os IDs de modelo abaixo são exemplos — ajuste-os conforme as permissões da sua chave.
Data de verificação da configuração oficial: 2026-10-15. As configurações abaixo foram organizadas com base na documentação oficial; a verificação ponta a ponta neste site ainda não foi concluída — conclua primeiro uma breve pergunta e resposta e a verificação de chamada de ferramentas antes de usá-las em tarefas longas. Modelos OpenAI / GPT já estão disponíveis; a lista de modelos e preços está em [descrição dos modelos](/pt/docs/models/).
De acordo com a [configuração oficial dos modelos](https://www.workbuddy.cn/docs/workbuddy/From-Beginner-to-Expert-Guide/Function-Description/Model): Configurações → Modelos → Adicionar modelo → Personalizado/Custom. Preencha a chave deste site e o modelo `claude-sonnet-4-6`.
Utilize a configuração com o endereço completo da requisição: ative "Protocolo personalizado" nas configurações avançadas, preencha a URL com `https://1zheai.com/v1/chat/completions` e, após salvar, selecione esse modelo no seletor de modelos da conversa. A documentação oficial indica que, com essa opção ativada, a URL preenchida é usada diretamente, sem verificação de caminho nem complementação automática; quando desativada, o complemento é feito conforme o padrão `/chat/completions`. Portanto, a URL completa e a opção devem ser descritas em conjunto.
Aqui, "protocolo personalizado" não significa que uma requisição OpenAI possa ser convertida automaticamente em uma requisição Anthropic — não é possível preencher `/v1/messages` e então afirmar que o protocolo nativo do Claude está conectado. Prefira a interface gráfica; não fornecemos o formato manual `models.json` não verificado. A página oficial apresenta simultaneamente o caminho de configuração local atual e as instruções antigas de migração do `~/.codebuddy/models.json` — evite usar isso para escrever o caminho antigo como um caminho geral atual. As marcações de capacidade de ferramentas na interface também não substituem a verificação ponta a ponta deste site.
## Verificação da integração e resolução de problemas
1. Salve e recarregue a configuração; confirme que o fornecedor selecionado atualmente é `onezhe` ou o modelo personalizado que você adicionou.
2. Envie uma pergunta curta e confirme que uma resposta é retornada; em seguida, tente uma pequena tarefa reversível e confirme separadamente a chamada de ferramentas e a conversa com múltiplas rodadas.
3. Abra o [log de chamadas](/pt/docs/usage-logs/) e verifique o horário da requisição, o modelo, o status e o consumo. Uma resposta de texto bem-sucedida não significa que todas as capacidades de Agent estejam compatíveis.
4. Em caso de 404, verifique se o endereço e o protocolo deste artigo são compatíveis; em caso de 401, verifique a origem da chave e se o processo leu as variáveis de ambiente; em caso de 429, consulte as informações de limitação de taxa antes de tentar novamente. Mais cenários em [códigos de erro e resolução de problemas](/pt/docs/troubleshooting/).
A chave deve ser armazenada apenas no ambiente local ou no armazenamento de credenciais da ferramenta — não a envie para repositórios de código, capturas de tela ou logs públicos. Serviços em segundo plano podem não herdar as variáveis de ambiente do terminal; modelos auxiliares, busca e outras ferramentas também podem ter configurações de fornecedor independentes que precisam ser verificadas separadamente.
## Custos e outras formas de integração
Consulte os [preços em tempo real da API do Claude](https://1zheai.com/en/pricing/) e as [regras de cobrança](/pt/docs/pricing-explained/). Para outros clientes, retorne ao [diretório de integração de ferramentas](/pt/docs/integrations/); para escrever seu próprio programa, use o [SDK e guia de desenvolvimento](/pt/docs/guides/).
---
# Importação e configuração do Chatbox em um clique
Source: https://1zheai.com/pt/docs/quickstart-chatbox/
Markdown: https://1zheai.com/pt/docs/quickstart-chatbox.md
---
title: "Importação e configuração do Chatbox em um clique"
description: "Importe o Chatbox pela página da Chave de API e verifique o API Host, caminho, modelo e chave."
headingIds: {"Importação em um clique":"section-1","Área de transferência e configuração manual":"section-2","Solução de problemas":"section-3"}
---
A partir do Chatbox 1.15.1, há suporte a JSON de provedor e `chatbox://provider/import`. A versão desktop precisa ser instalada e iniciada uma vez antes. Para a versão web ou sistemas sem registro de protocolo, use a importação pela área de transferência.
## Importação em um clique
1. Abra **Chave de API** no console, encontre a chave que deseja usar e acesse **Ferramentas de uso → Chatbox**.
2. Selecione o modelo de chat disponível para esta chave e clique em **Abrir Chatbox**, permitindo que o navegador abra o aplicativo.
3. Confirme a importação no Chatbox e verifique o endereço do provedor e o modelo. Se já existir uma configuração com o mesmo nome, confirme primeiro o escopo da substituição.
4. Envie uma mensagem curta e confirme o modelo e o horário da solicitação nos registros de chamadas deste site.
## Área de transferência e configuração manual
Se o aplicativo não for aberto, copie o **Chatbox JSON** no mesmo painel e, na gestão de provedores das configurações do Chatbox, escolha importar pela área de transferência. Antes de compartilhar com outras pessoas, é obrigatório remover `settings.apiKey`.
| Campo | Valor |
| --- | --- |
| Tipo | OpenAI API compatible |
| API Host | `https://1zheai.com` |
| API Path | `/v1/chat/completions` |
| API Key | chave atual |
| Model ID | modelo de chat disponível para a chave atual |
Preencha Host e Path separadamente; não adicione `/v1` aos dois campos ao mesmo tempo. Se não houver modelo, obtenha primeiro a lista de modelos ou adicione manualmente; capacidades como imagens, embeddings e chamadas de ferramentas devem ser verificadas separadamente; não trate qualquer modelo como modelo de chat.
## Solução de problemas
- O aplicativo não abre: confirme que foi instalado e iniciado, desbloqueie este protocolo no navegador ou use a importação pela área de transferência.
- 401 após a importação: verifique se a chave é válida e se não há espaços.
- 404: confirme que o caminho final é `/v1/chat/completions` e que não houve concatenação duplicada.
- Modelo inexistente: use o ID exato da lista de modelos; não deduza pelo apelido de exibição.
Oficial: [protocolo de importação de configuração](https://docs.chatboxai.app/guides/providers/import-config), [código-fonte do cliente](https://github.com/chatboxai/chatbox/blob/main/src/renderer/utils/provider-config.ts).
verificado com o protocolo e materiais oficiais em 2026-10-19. Este site já implementou a geração de configuração e testes de regressão no frontend; não concluiu a verificação de inferência real em todos os clientes, sistemas e modelos. Após atualizar o cliente, verifique novamente. A integração personalizada não representa parceria oficial nem recomendação incorporada.
Mais: [Chave de API](/pt/docs/api-keys/), [lista de modelos](/pt/docs/models/), [registros de chamadas](/pt/docs/usage-logs/), [explicação de endereços](/pt/docs/base-url/).
---
# Importação por QR Code no RikkaHub
Source: https://1zheai.com/pt/docs/quickstart-rikkahub/
Markdown: https://1zheai.com/pt/docs/quickstart-rikkahub.md
---
title: "Importação por QR Code no RikkaHub"
description: "Importe provedores compatíveis com OpenAI por QR Code no RikkaHub para Android, configure modelos e resolva problemas."
headingIds: {"Configuração por QR Code":"section-1","Alternativa manual":"section-2","Resolução de problemas":"section-3"}
---
RikkaHub é um cliente de IA para Android. Este site usa seu formato de compartilhamento `ai-provider:v1:` para gerar um QR Code local, sem chamar sites de QR Code de terceiros.
## Configuração por QR Code
1. No console, **Chave da API → Ferramentas → RikkaHub**.
2. Em um ambiente privado, clique em **Exibir QR Code de importação**. O QR Code equivale à chave completa e não pode ser compartilhado por captura de tela.
3. No RikkaHub, em **Configurações → Configurações de provedor → Importar**, escolha a leitura por QR Code. Se os dois lados estiverem no mesmo celular, use a função de importar a imagem do cliente e, após a importação, exclua a captura de tela que contém a chave.
4. Após importar, obtenha a lista de modelos, selecione o modelo de chat, envie uma mensagem curta e confirme no registro de chamadas deste site.
5. Ao concluir, oculte o QR Code. Se enviá-lo por engano a outra pessoa, revogue essa chave e crie outra.
## Alternativa manual
| Campo | Valor |
| --- | --- |
| Tipo | OpenAI |
| Base URL | `https://1zheai.com/v1` |
| Caminho de Chat Completions | `/chat/completions` |
| Chave da API | chave atual |
A importação não pré-configura capacidades de modelos nem tamanho de contexto, e não ativa a opção de Responses. Quando precisar de Responses, verifique primeiro o modelo selecionado e a versão do cliente e valide separadamente.
## Resolução de problemas
Se a leitura por QR Code falhar, verifique primeiro se o QR Code está completo, a tela está nítida e a versão do cliente; se ainda falhar, use os campos manuais. Se a lista de modelos falhar, confira a chave e o endereço; permissões insuficientes não podem ser resolvidas lendo o QR Code novamente.
Oficial: [Início rápido](https://github.com/rikkahub/docs/blob/main/quickstart.mdx), [Implementação do formato de compartilhamento](https://github.com/rikkahub/rikkahub/blob/master/app/src/main/java/me/rerere/rikkahub/ui/components/ui/ShareSheet.kt).
verificado com o protocolo e materiais oficiais em 2026-10-19. Este site já implementou a geração de configuração e testes de regressão no frontend; não concluiu a verificação de inferência real em todos os clientes, sistemas e modelos. Após atualizar o cliente, verifique novamente. A integração personalizada não representa parceria oficial nem recomendação embutida.
Mais: [Chave da API](/pt/docs/api-keys/), [Lista de modelos](/pt/docs/models/), [Registro de chamadas](/pt/docs/usage-logs/), [Explicação do endereço](/pt/docs/base-url/).
---
# ChatWise Fornecedor Personalizado
Source: https://1zheai.com/pt/docs/quickstart-chatwise/
Markdown: https://1zheai.com/pt/docs/quickstart-chatwise.md
---
title: "ChatWise Fornecedor Personalizado"
description: "Adicione um fornecedor compatível com OpenAI nas configurações do ChatWise, preenchindo chave, endereço e modelos."
headingIds: {"Importação de capacidades e verificação":"section-1"}
---
Crie um fornecedor personalizado compatível com OpenAI em **Settings → Providers → +** no ChatWise. O console **API Key → Ferramentas → ChatWise** fornece campos copiáveis.
| Campo | Valor |
| --- | --- |
| API URL / Base URL | `https://1zheai.com/v1` |
| API Key | chave atual |
| Modelo | selecione após obter os modelos, ou preencha manualmente o ID do modelo |
A interface de listagem de modelos é `/v1/models`. Se a versão atual exigir o endereço completo da requisição em vez da Base URL, preencha `https://1zheai.com/v1/chat/completions`; siga a descrição do campo. Desative proxies de terceiros desnecessários antes de testar a conexão direta.
## Importação de capacidades e verificação
O `chatwise://chat` oficial e público é usado para abrir conversas, não para importar chaves de fornecedor. Este site não o disfarça de botão de importação de configuração. Capacidades de imagens, raciocínio e ferramentas devem ser configuradas conforme o suporte real de cada modelo; não habilite tudo por padrão.
Envie uma mensagem curta e verifique os logs deste site. 401: verifique a chave; 404: verifique se o campo de endereço espera um caminho completo; se não houver modelo, preencha manualmente um ID disponível atualmente.
Oficial: [Fornecedor personalizado](https://docs.chatwise.app/custom-provider)、[Abrir acordo do aplicativo](https://docs.chatwise.app/open-from-other-apps)。
Acordo e materiais oficiais verificados em 2026-10-19. Este site já implementou geração de configuração e testes de regressão de front-end; não concluiu a verificação de raciocínio real em todos os clientes, sistemas e modelos. Após atualizar o cliente, revalide. A integração personalizada não representa parceria oficial nem recomendação embutida.
Mais: [Chave da API](/pt/docs/api-keys/)、[Lista de modelos](/pt/docs/models/)、[Logs de chamadas](/pt/docs/usage-logs/)、[Explicação do endereço](/pt/docs/base-url/)。
---
# Endpoints personalizados do LibreChat
Source: https://1zheai.com/pt/docs/quickstart-librechat/
Markdown: https://1zheai.com/pt/docs/quickstart-librechat.md
---
title: "Endpoints personalizados do LibreChat"
description: "Administradores configuram endpoints personalizados do LibreChat; cada usuário preenche sua própria chave de API."
headingIds: {"Configuração do administrador":"section-1","Verificação e solução de problemas":"section-2"}
---
O LibreChat precisa ser implantado por um administrador que permita endpoints personalizados; usuários comuns não podem reescrever a configuração do servidor remoto usando os botões deste site. O console **Chave de API → Ferramentas → LibreChat** fornece o trecho de configuração.
## Configuração do administrador
Mesclar ao `librechat.yaml` existente o `endpoints.custom`, sem sobrescrever outros endpoints:
```yaml
endpoints:
custom:
- name: '1折AI'
apiKey: user_provided
baseURL: 'https://1zheai.com/v1'
models:
default: []
fetch: true
```
Aplicar a validação de configuração exigida pela versão atual e reiniciar o serviço; depois, peça ao usuário que preencha a própria chave nas configurações de chave de API do LibreChat. A configuração compartilhada não contém chaves reais. Se a obtenção de modelos falhar, o administrador pode definir `default` como um ID de modelo verificado e disponível, e verificar a saída de rede do servidor.
## Verificação e solução de problemas
Selecione o endpoint e o modelo recém-adicionados, faça uma requisição curta e confira os logs de chamadas deste site. Se o endpoint não aparecer, verifique primeiro o ponto de montagem da configuração e se o reinício teve efeito; em 401, confira a chave preenchida pelo usuário; em 404, confirme que a Base URL é `/v1` e não o caminho completo da requisição. Não use instâncias públicas do LibreChat de confiança desconhecida para armazenar chaves.
Oficial: [campos de endpoint personalizado](https://www.librechat.ai/docs/configuration/librechat_yaml/object_structure/custom_endpoint).
conferido com a documentação oficial em 2026-10-19. Este site já implementou a geração de configuração e testes de regressão no frontend; a verificação real de inferência em todos os clientes, sistemas e modelos não foi concluída. Após atualizar o cliente, verifique novamente. A integração personalizada não representa parceria oficial nem recomendação embutida.
Mais: [chave de API](/pt/docs/api-keys/), [lista de modelos](/pt/docs/models/), [logs de chamadas](/pt/docs/usage-logs/), [explicação de endereços](/pt/docs/base-url/).
---
# OpenClaw: integração com a API Claude
Source: https://1zheai.com/pt/docs/quickstart-openclaw/
Markdown: https://1zheai.com/pt/docs/quickstart-openclaw.md
---
title: "OpenClaw: integração com a API Claude"
description: "Tutorial de configuração do endereço, chave e modelos da API Claude via retransmissão 1折AI no OpenClaw, incluindo escolha de protocolo, exemplos de configuração, etapas de verificação e erros comuns."
headingIds: {"Verificação da integração e resolução de problemas":"section-1","Custos e outras formas de integração":"section-2"}
---
Use a funcionalidade de provedor personalizado do OpenClaw para conectar-se ao 1折AI. Primeiro, [crie uma chave de API](/pt/docs/api-keys/) e confirme os [modelos disponíveis atualmente](/pt/docs/models/); os IDs de modelo abaixo são exemplos — ajuste-os conforme as permissões da sua chave.
Data de verificação da configuração oficial: 2026-10-15. As configurações abaixo foram organizadas com base na documentação oficial; a verificação ponta a ponta neste site ainda não foi concluída — conclua primeiro uma breve pergunta-resposta e a verificação de chamada de ferramentas antes de usá-las em tarefas longas. Modelos OpenAI / GPT já estão disponíveis; a lista de modelos e preços está em [descrição dos modelos](/pt/docs/models/).
Com base em [provedor personalizado](https://docs.openclaw.ai/gateway/config-tools/custom-providers) e [exemplo de configuração](https://docs.openclaw.ai/gateway/configuration-examples), combine em `~/.openclaw/openclaw.json`:
```json
{
"agents": {
"defaults": {
"model": { "primary": "onezhe/claude-sonnet-4-6" },
"models": { "onezhe/claude-sonnet-4-6": { "alias": "1折AI Claude" } }
}
},
"models": {
"mode": "merge",
"providers": {
"onezhe": {
"baseUrl": "https://1zheai.com",
"apiKey": "${ONEZHE_API_KEY}",
"api": "anthropic-messages",
"models": [
{ "id": "claude-sonnet-4-6", "name": "Claude Sonnet 4.6" }
]
}
}
}
}
```
Certifique-se de que o processo que executa o Gateway possa ler `ONEZHE_API_KEY`; variáveis de ambiente no terminal nem sempre são repassadas a serviços em segundo plano já existentes. A [documentação oficial do Synthetic](https://docs.openclaw.ai/providers/synthetic) deixa claro que o cliente Anthropic anexa automaticamente `/v1`, portanto, aqui não inclua `/v1` e não preencha o `/v1/messages` completo.
Ao usar Chat Completions, substitua em pares por `baseUrl: "https://1zheai.com/v1"` e `api: "openai-completions"`. Embora o nome contenha "completions", este adaptador corresponde a `/v1/chat/completions`; não selecione `openai-responses` por engano. Se já existir uma lista de modelos permitidos, mantenha as demais entradas e adicione o novo modelo. O exemplo não inventa custos ou parâmetros de contexto; se a versão instalada atual exigir metadados adicionais na validação, verifique primeiro as capacidades reais do modelo antes de adicioná-los.
## Verificação da integração e resolução de problemas
1. Salve e recarregue a configuração; confirme que o provedor selecionado atualmente é `onezhe` ou o modelo personalizado que você adicionou.
2. Envie uma pergunta curta e confirme que ela retorna; em seguida, tente uma pequena tarefa reversível e verifique separadamente a chamada de ferramentas e o diálogo em múltiplas rodadas.
3. Abra o [log de chamadas](/pt/docs/usage-logs/) e confira horário da requisição, modelo, status e uso. Uma única resposta de texto bem-sucedida não significa que todas as capacidades dos Agentes sejam compatíveis.
4. Em caso de 404, confira se o endereço e o protocolo deste artigo são compatíveis; em caso de 401, confira a origem da chave e se o processo leu as variáveis de ambiente; em caso de 429, consulte as informações de limitação de taxa antes de tentar novamente. Mais cenários em [códigos de erro e resolução de problemas](/pt/docs/troubleshooting/).
Guarde a chave apenas no ambiente local ou no armazenamento de credenciais da ferramenta; não a envie para repositórios de código, capturas de tela ou logs públicos. Serviços em segundo plano podem não herdar as variáveis de ambiente do terminal; modelos auxiliares, busca e outras ferramentas também podem ter configurações de provedor independentes e precisam ser verificadas separadamente.
## Custos e outras formas de integração
Consulte [preços em tempo real da API Claude](https://1zheai.com/en/pricing/) e as [regras de cobrança](/pt/docs/pricing-explained/). Para outros clientes, retorne ao [diretório de integração de ferramentas](/pt/docs/integrations/); para escrever seu próprio programa, use o [SDK e guia de desenvolvimento](/pt/docs/guides/).
---
# Hermes Agent: integração com a API Claude
Source: https://1zheai.com/pt/docs/quickstart-hermes/
Markdown: https://1zheai.com/pt/docs/quickstart-hermes.md
---
title: "Hermes Agent: integração com a API Claude"
description: "Tutorial de configuração do Hermes Agent para o relay da API Claude da 1折AI, incluindo endereço, chave e modelo, com escolha de protocolo, exemplos de configuração, etapas de verificação e erros comuns."
headingIds: {"Verificação da integração e resolução de problemas":"section-1","Custos e outras formas de integração":"section-2"}
---
Use a funcionalidade de provedor personalizado do Hermes Agent para conectar-se à 1折AI. Primeiro, [crie uma chave de API](/pt/docs/api-keys/) e confirme os [modelos disponíveis atualmente](/pt/docs/models/); os IDs de modelo abaixo são exemplos — ajuste-os conforme as permissões da sua chave.
Data de verificação da configuração oficial: 2026-10-15. A configuração abaixo foi organizada com base na documentação oficial; a verificação ponta a ponta neste site ainda não foi concluída — conclua primeiro uma breve pergunta e a chamada de ferramenta de verificação antes de usá-la em tarefas longas. Modelos OpenAI / GPT já estão disponíveis; a lista de modelos e preços está em [descrição dos modelos](/pt/docs/models/).
Com base nos [Providers oficiais](https://hermes-agent.nousresearch.com/docs/integrations/providers): no terminal, execute `hermes model` → Custom endpoint, selecione explicitamente o modo de API `chat_completions`, preencha a Base URL com `https://1zheai.com/v1` e informe a chave e o modelo. Não selecione o login ChatGPT/Codex — é outra forma de integração.
Configuração de provider nomeada reutilizável, a ser mesclada em `~/.hermes/config.yaml`:
```yaml
providers:
onezhe:
api: https://1zheai.com/v1
key_env: ONEZHE_API_KEY
transport: chat_completions
default_model: claude-sonnet-4-6
model:
provider: custom:onezhe
default: claude-sonnet-4-6
```
Fornecida localmente em `~/.hermes/.env`:
```dotenv
ONEZHE_API_KEY=sk-替换为本站密钥
```
Após a configuração, é possível alternar `/model custom:onezhe:claude-sonnet-4-6` na conversa. `/model` não substitui a criação de um novo provider via `hermes model` no terminal. O suporte oficial inclui transporte `anthropic_messages`, mas este tutorial usa Chat Completions para evitar adivinhar o protocolo automaticamente pela URL. `OPENAI_BASE_URL` não é uma configuração universal para todos os provedores personalizados; use a configuração explícita acima.
## Verificação da integração e resolução de problemas
1. Salve e recarregue a configuração; confirme que o provedor selecionado atualmente é `onezhe` ou o modelo personalizado que você adicionou.
2. Envie uma pergunta curta e confirme que há resposta; em seguida, tente uma pequena tarefa reversível e verifique separadamente a chamada de ferramentas e o diálogo em múltiplas rodadas.
3. Abra o [log de chamadas](/pt/docs/usage-logs/) e confira hora da requisição, modelo, status e uso. Uma única resposta de texto bem-sucedida não significa que todas as capacidades do Agent são compatíveis.
4. Em caso de 404, confira se o endereço e o protocolo deste artigo são compatíveis; em caso de 401, confira a origem da chave e se o processo leu as variáveis de ambiente; em caso de 429, consulte as informações de limitação de taxa antes de tentar novamente. Mais cenários em [códigos de erro e resolução de problemas](/pt/docs/troubleshooting/).
A chave deve ser armazenada apenas no ambiente local ou no armazenamento de credenciais da ferramenta; não a envie para repositórios de código, capturas de tela ou logs públicos. Serviços em segundo plano podem não herdar as variáveis de ambiente do terminal; modelos auxiliares, busca e outras ferramentas também podem ter configurações de provedor independentes e precisam ser verificadas separadamente.
## Custos e outras formas de integração
Consulte os [preços em tempo real da API Claude](https://1zheai.com/en/pricing/) e as [regras de faturamento](/pt/docs/pricing-explained/). Para outros clientes, retorne ao [diretório de integrações de ferramentas](/pt/docs/integrations/); para escrever seu próprio programa, use o [SDK e guia de desenvolvimento](/pt/docs/guides/).
---
# Integrar com CC Switch
Source: https://1zheai.com/pt/docs/quickstart-cc-switch/
Markdown: https://1zheai.com/pt/docs/quickstart-cc-switch.md
---
title: "Integrar com CC Switch"
description: "Adicione 1折AI no CC Switch usando uma configuração personalizada para alternar provedores no Claude Code com um clique, sem editar settings.json manualmente."
headingIds: {"Instalação":"section-1","Adicionar 1折AI ao Claude Code":"section-2","Obter a lista de modelos":"section-3","Codex":"section-4","Perguntas frequentes":"section-5"}
---
[CC Switch](https://github.com/farion1231/cc-switch) é uma ferramenta de área de trabalho que ajuda a gerenciar as configurações de provedores de ferramentas de linha de comando como Claude Code e Codex. Depois de adicionar uma vez, alternar entre a conta oficial, 1折AI e outros provedores leva apenas um clique.
## Instalação
- macOS: `brew install --cask cc-switch`
- Windows / Linux: baixe o instalador em [GitHub Releases](https://github.com/farion1231/cc-switch/releases)
## Adicionar 1折AI ao Claude Code
Selecione **Claude Code** na barra lateral e clique em **Adicionar provedor** (símbolo +) no lado direito do cabeçalho da página.
O 1折AI ainda não está na lista predefinida do CC Switch; selecione **Configuração personalizada** no topo da lista.
Preencha o nome com `1折AI` e escreva no campo de edição da configuração `env`:
```json
{
"env": {
"ANTHROPIC_BASE_URL": "https://1zheai.com",
"ANTHROPIC_AUTH_TOKEN": "sk-你的Key"
}
}
```
Se quiser fixar o modelo ao mesmo tempo, adicione variáveis como `ANTHROPIC_MODEL`; a forma de escrita está na seção de mapeamento de modelos da [integração com Claude Code](/pt/docs/quickstart-claude-code/).
Clique em **Adicionar** no rodapé e, em seguida, habilite o 1折AI na lista de provedores. O CC Switch gravará a configuração no `~/.claude/settings.json` do Claude Code, e o Claude Code usará o novo provedor sem precisar reiniciar.
Execute `/status` no Claude Code; a base URL deve ser `https://1zheai.com`. Envie outra mensagem e confirme o registro nos [logs de chamada](/pt/docs/usage-logs/) do console.
O exemplo oficial do CC Switch usa `ANTHROPIC_API_KEY`; ambas as variáveis funcionam. Recomendamos `ANTHROPIC_AUTH_TOKEN`; o motivo está na [integração com Claude Code](/pt/docs/quickstart-claude-code/).
## Obter a lista de modelos
Ao editar um provedor, o botão **Obter lista de modelos** ao lado do campo de modelos usará sua chave de API (API key) para chamar `/v1/models`, listar os modelos disponíveis e permitir que você selecione um para preencher.
## Codex
O CC Switch também pode gerenciar os provedores do Codex. Para configurar a Base URL deste site, a chave de API e o modelo GPT, consulte a [integração com Codex CLI](/pt/docs/quickstart-codex/).
## Perguntas frequentes
Primeiro, confirme no CC Switch que o 1折AI está habilitado; depois, verifique se o terminal exportou `ANTHROPIC_BASE_URL` ou `ANTHROPIC_AUTH_TOKEN`. O Claude Code usa o settings.json como referência, mas variáveis antigas exportadas manualmente podem causar interpretações erradas; recomendamos limpá-las todas e deixar o gerenciamento unificado por meio do CC Switch.
A chave de API foi preenchida incorretamente ou foi excluída. Copie a chave de API novamente, tomando cuidado para não incluir espaços.
---
# Configuração do CC Provider
Source: https://1zheai.com/pt/docs/quickstart-cc-provider/
Markdown: https://1zheai.com/pt/docs/quickstart-cc-provider.md
---
title: "Configuração do CC Provider"
description: "Gerencie provedores Anthropic personalizados com a extensão CC Provider do VS Code."
headingIds: {"Etapas de configuração":"section-1","Escopo e solução de problemas":"section-2"}
---
Aqui refere-se à extensão do VS Code **onetooken/cc-provider**, não ao CC Switch. Ela suporta endpoints Anthropic compatíveis personalizados.
## Etapas de configuração
1. Instale a extensão a partir do link do repositório oficial e abra o painel de provedores.
2. Crie um novo provedor personalizado; no console, **Chave da API → Usar ferramenta → CC Provider** você pode copiar os campos correspondentes.
3. Preencha o nome com `1折AI`, a Base URL com `https://1zheai.com` e o API Token com sua própria chave.
4. Preencha o modelo principal e os slots de modelo necessários de acordo com os modelos atualmente disponíveis; não copie IDs de modelos ou sufixos de capacidade `[1m]` de outros provedores.
5. Faça backup da configuração existente do Claude Code antes de aplicar e verifique os campos que serão alterados. Reinicie as sessões que precisam ler a configuração e teste uma requisição curta.
## Escopo e solução de problemas
Este site fornece a cópia de campos, mas ainda não verificou o protocolo de importação rápida de provedores desta extensão. O comportamento deste cliente ao gravar a configuração do Claude Code difere da inclusão de provedores embutidos.
401: verifique o token; 404: verifique se o endereço raiz da Anthropic não recebeu por engano `/v1/messages`; quando o modelo não existir, use um modelo disponível com a chave atual. Confirme que a requisição aparece no log de chamadas deste site antes de usar em tarefas longas.
Oficial: [CC Provider](https://github.com/onetooken/cc-provider).
: o protocolo foi conferido com os materiais oficiais em 2026-10-19. Este site já implementou a geração de configuração e testes de regressão no frontend; não concluiu a verificação de inferência real em todos os clientes, sistemas e modelos. Após atualizações do cliente, verifique novamente. A integração personalizada não representa parceria oficial nem recomendação embutida.
Mais: [Chave da API](/pt/docs/api-keys/), [Lista de modelos](/pt/docs/models/), [Log de chamadas](/pt/docs/usage-logs/), [Explicação de endereços](/pt/docs/base-url/).
---
# Guia de Desenvolvimento
Source: https://1zheai.com/pt/docs/guides/
Markdown: https://1zheai.com/pt/docs/guides.md
---
title: "Guia de Desenvolvimento"
description: "Escolha entre SDK ou acesso via HTTP, desde a primeira requisição até a saída em streaming e o cache."
headingIds: {"Após a integração, continue refinando":"section-1","Do exemplo à aplicação":"section-2"}
---
Se você já tem código, comece pelo SDK correspondente; se ainda não escolheu a stack tecnológica, primeiro valide a chamada com curl e depois integre na aplicação.
usa o protocolo nativo do Claude, com exemplos em Python e TypeScript.chama GPT ou Claude usando o SDK do OpenAI, configurando o ID do modelo e o endereço da interface.mostra diretamente as requisições HTTP, eliminando diferenças de configuração do SDK.confirme o endpoint, o protocolo e o escopo de aplicação.
## Após a integração, continue refinando
- [Saída em streaming](/pt/docs/streaming/): trate respostas incrementais e interrupções de fluxo.
- [Prompt Caching](/pt/docs/prompt-caching/): entenda as condições de uso e como verificar os resultados.
- [Códigos de erro e resolução de problemas](/pt/docs/troubleshooting/): localize problemas de configuração ou do upstream com base no erro específico.
- [Logs de uso e conciliação](/pt/docs/usage-logs/): verifique os registros de requisições.
Ao usar software pronto, você pode ir direto para a [integração de ferramentas](/pt/docs/integrations/).
## Do exemplo à aplicação
Python / Node.js, desde a configuração das variáveis de ambiente até a execução do programa.diferencie erros de configuração, falhas temporárias e resultados incertos.verifique item a item endereço, chave, modelo e protocolo.use a interface Images e salve os resultados gerados.
---
# Integração com o SDK da Anthropic (Python / TypeScript)
Source: https://1zheai.com/pt/docs/quickstart-anthropic-sdk/
Markdown: https://1zheai.com/pt/docs/quickstart-anthropic-sdk.md
---
title: "Integração com o SDK da Anthropic (Python / TypeScript)"
description: "Use o SDK oficial da Anthropic para chamar a 1折AI: preencha base_url com https://1zheai.com; suporte nativo a cache, streaming, chamadas de ferramentas e thinking."
headingIds: {"Instalação":"section-1","Chamada":"section-2","Saída em streaming":"section-3","Chamada com cache":"section-4","Usar variáveis de ambiente":"section-5","Perguntas frequentes":"section-6","Estrutura de requisição e resposta":"section-7"}
---
O SDK oficial da Anthropic usa o caminho nativo `/v1/messages`, e todos os parâmetros do Claude podem ser usados diretamente. As únicas alterações são em `base_url` e `api_key`.
## Instalação
```bash title="Python"
pip install anthropic
```
```bash title="TypeScript / Node.js"
npm install @anthropic-ai/sdk
```
## Chamada
```python title="Python"
import os
import anthropic
client = anthropic.Anthropic(
base_url="https://1zheai.com",
api_key=os.environ["ONEZHE_API_KEY"],
)
message = client.messages.create(
model="claude-sonnet-5-5",
max_tokens=1024,
messages=[{"role": "user", "content": "用一句话介绍你自己"}],
)
print(message.model)
print(message.content[0].text)
print(message.usage)
```
```typescript title="TypeScript"
import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic({
baseURL: "https://1zheai.com",
apiKey: process.env.ONEZHE_API_KEY,
});
const message = await client.messages.create({
model: "claude-sonnet-5-5",
max_tokens: 1024,
messages: [{ role: "user", content: "用一句话介绍你自己" }],
});
console.log(message.model);
console.log(message.content);
console.log(message.usage);
```
Preencha `base_url` com a URL raiz; não adicione `/v1`.
## Saída em streaming
```python title="Python"
with client.messages.stream(
model="claude-sonnet-5-5",
max_tokens=1024,
messages=[{"role": "user", "content": "写一首四行的诗"}],
) as stream:
for text in stream.text_stream:
print(text, end="", flush=True)
```
```typescript title="TypeScript"
const stream = client.messages.stream({
model: "claude-sonnet-5-5",
max_tokens: 1024,
messages: [{ role: "user", content: "写一首四行的诗" }],
});
stream.on("text", (text) => process.stdout.write(text));
await stream.finalMessage();
```
## Chamada com cache
Coloque o conteúdo longo e fixo em `system` e adicione `cache_control`:
```python title="Python"
message = client.messages.create(
model="claude-sonnet-5-5",
max_tokens=1024,
system=[
{
"type": "text",
"text": LONG_PROJECT_CONTEXT, # 每次都一样的长文本
"cache_control": {"type": "ephemeral"},
}
],
messages=[{"role": "user", "content": "根据上面的说明回答：..."}],
)
print(message.usage.cache_creation_input_tokens, message.usage.cache_read_input_tokens)
```
Na segunda chamada, se `cache_read_input_tokens` for maior que 0, houve acerto (cache hit). Para detalhes, consulte [Prompt Caching](/pt/docs/prompt-caching/).
## Usar variáveis de ambiente
O SDK oficial lê `ANTHROPIC_BASE_URL` e `ANTHROPIC_API_KEY`; também é possível não passar parâmetros ao construir o cliente:
```bash
export ANTHROPIC_BASE_URL="https://1zheai.com"
export ANTHROPIC_API_KEY="sk-你的Key"
```
Em seguida, construa o cliente sem passar parâmetros:
```python
client = anthropic.Anthropic() # 自动读取上面两个变量
```
Se o Claude Code nesta máquina também ler essas duas variáveis, elas passarão juntas a apontar para a 1折AI — geralmente é exatamente o que você deseja.
## Perguntas frequentes
Você escreveu `/v1` a mais em `base_url`. O SDK da Anthropic monta `/v1/messages` automaticamente.
Verifique a chave da API (API key); além disso, se o ambiente também contiver `ANTHROPIC_AUTH_TOKEN` (por exemplo, um valor antigo configurado anteriormente para o Claude Code), o SDK também o lerá — remova o valor antigo e tente novamente.
## Estrutura de requisição e resposta
Quando precisar consultar system, blocos de conteúdo e motivos de parada, consulte [Detalhes da interface Messages](/pt/docs/api-messages/). Programas completos devem ler o texto de acordo com o tipo de bloco de conteúdo, sem assumir que o primeiro bloco é sempre text.
---
# Integração com o SDK da OpenAI (Python / Node)
Source: https://1zheai.com/pt/docs/quickstart-openai-sdk/
Markdown: https://1zheai.com/pt/docs/quickstart-openai-sdk.md
---
title: "Integração com o SDK da OpenAI (Python / Node)"
description: "Use o SDK oficial da OpenAI para chamar os modelos GPT e Claude da 1折AI: basta alterar base_url e api_key, com exemplos de streaming e uso de variáveis de ambiente."
headingIds: {"Instalação":"section-1","Chamada":"section-2","Saída em streaming":"section-3","Usar variáveis de ambiente sem alterar o código":"section-4","Quando trocar para o SDK da Anthropic":"section-5","Perguntas frequentes":"section-6","Responses e programa completo":"section-7"}
---
Se você já tem código escrito com o SDK da OpenAI, para trocar para a 1折AI basta alterar dois parâmetros: `base_url` e `api_key`. Preencha o nome do modelo com o ID de um modelo GPT ou Claude disponível no momento.
## Instalação
```bash title="Python"
pip install openai
```
```bash title="Node.js"
npm install openai
```
## Chamada
```python title="Python"
import os
from openai import OpenAI
client = OpenAI(
base_url="https://1zheai.com/v1",
api_key=os.environ["ONEZHE_API_KEY"],
)
resp = client.chat.completions.create(
model="gpt-5.6-sol",
messages=[{"role": "user", "content": "用一句话解释什么是 prompt caching"}],
)
print(resp.model)
print(resp.choices[0].message.content)
print(resp.usage)
```
```javascript title="Node.js"
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://1zheai.com/v1",
apiKey: process.env.ONEZHE_API_KEY,
});
const resp = await client.chat.completions.create({
model: "gpt-5.6-sol",
messages: [{ role: "user", content: "用一句话解释什么是 prompt caching" }],
});
console.log(resp.model);
console.log(resp.choices[0].message.content);
console.log(resp.usage);
```
`base_url` deve incluir `/v1`.
## Saída em streaming
```python title="Python"
stream = client.chat.completions.create(
model="gpt-5.6-sol",
messages=[{"role": "user", "content": "写一首四行的诗"}],
stream=True,
)
for chunk in stream:
if chunk.choices and chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="", flush=True)
```
```javascript title="Node.js"
const stream = await client.chat.completions.create({
model: "gpt-5.6-sol",
messages: [{ role: "user", content: "写一首四行的诗" }],
stream: true,
});
for await (const chunk of stream) {
process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}
```
## Usar variáveis de ambiente sem alterar o código
O SDK oficial da OpenAI (Python e Node) lê `OPENAI_BASE_URL` e `OPENAI_API_KEY`. Quando o código não passa parâmetros, definir essas duas variáveis permite a troca:
```bash
export OPENAI_BASE_URL="https://1zheai.com/v1"
export OPENAI_API_KEY="sk-你的Key"
```
Atenção: isso afeta todos os programas no mesmo ambiente que utilizam o SDK da OpenAI.
## Quando trocar para o SDK da Anthropic
A interface compatível com OpenAI é indicada para "código existente, apenas trocar de modelo". Se você precisa de `cache_control` do Prompt Caching, extended thinking ou do formato de chamada de ferramentas do Claude, use o [SDK da Anthropic](/pt/docs/quickstart-anthropic-sdk/) para a interface nativa.
## Perguntas frequentes
`base_url` está sem `/v1`. O SDK da OpenAI apenas anexa `/chat/completions` ao final.
Sim. Os modelos OpenAI / GPT já estão disponíveis; use o ID de um dos modelos que sua chave pode chamar em [modelos suportados](/pt/docs/models/).
## Responses e programa completo
Quando precisar do protocolo Responses, consulte a [interface Responses](/pt/docs/api-responses/). Na primeira vez usando Python ou Node.js, você pode executar diretamente o [exemplo completo](/pt/docs/code-examples/); antes de entrar em produção, configure [timeout e retries limitados](/pt/docs/retries/).
---
# Chamadas com curl
Source: https://1zheai.com/pt/docs/quickstart-curl/
Markdown: https://1zheai.com/pt/docs/quickstart-curl.md
---
title: "Chamadas com curl"
description: "Sem instalar nenhum SDK, use curl para chamar /v1/messages e /v1/chat/completions da 1折AI, consultar a lista de modelos, testar o cache e ver a saída em streaming."
headingIds: {"Nativo do Anthropic: /v1/messages":"section-1","Compatível com OpenAI: /v1/chat/completions":"section-2","Lista de modelos: /v1/models":"section-3","Saída em streaming":"section-4","Testar o cache":"section-5","Ao depurar, adicione -i":"section-6"}
---
curl é a maneira mais rápida de confirmar se "a chave de API (API key) e o endereço realmente funcionam". Cada exemplo abaixo pode ser copiado diretamente; primeiro coloque a chave de API em uma variável de ambiente:
```bash
export ONEZHE_API_KEY="sk-你的Key"
```
Usuários do Windows são recomendados a executar estes comandos no WSL ou no Git Bash; a sintaxe para PowerShell está em [Início rápido](/pt/docs/quickstart/).
## Nativo do Anthropic: /v1/messages
```bash
curl https://1zheai.com/v1/messages \
-H "x-api-key: $ONEZHE_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-sonnet-5-5",
"max_tokens": 128,
"messages": [{"role": "user", "content": "ping"}]
}'
```
## Compatível com OpenAI: /v1/chat/completions
```bash
curl https://1zheai.com/v1/chat/completions \
-H "Authorization: Bearer $ONEZHE_API_KEY" \
-H "content-type: application/json" \
-d '{
"model": "claude-sonnet-5-5",
"messages": [{"role": "user", "content": "ping"}]
}'
```
## Lista de modelos: /v1/models
```bash
curl https://1zheai.com/v1/models \
-H "Authorization: Bearer $ONEZHE_API_KEY"
```
## Saída em streaming
Adicione `"stream": true` e use `-N` para desativar o buffer do curl, a fim de ver as respostas segmentadas:
```bash
curl -N https://1zheai.com/v1/messages \
-H "x-api-key: $ONEZHE_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-sonnet-5-5",
"max_tokens": 128,
"stream": true,
"messages": [{"role": "user", "content": "从一数到五"}]
}'
```
O formato dos eventos está em [Saída em streaming](/pt/docs/streaming/).
## Testar o cache
Envie a mesma requisição duas vezes seguidas; se o `usage.cache_read_input_tokens` da segunda resposta for maior que 0, houve cache hit. O texto em `system` precisa atingir o comprimento mínimo cacheável do modelo; o script completo está em [Verificar modelos e uso](/pt/docs/verify-model/) e o princípio em [Prompt Caching](/pt/docs/prompt-caching/).
```bash
curl https://1zheai.com/v1/messages \
-H "x-api-key: $ONEZHE_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-sonnet-5-5",
"max_tokens": 32,
"system": [{
"type": "text",
"text": "把一段至少 512 token、每次都一样的长文本放在这里",
"cache_control": {"type": "ephemeral"}
}],
"messages": [{"role": "user", "content": "ping"}]
}'
```
## Ao depurar, adicione -i
```bash
curl -i https://1zheai.com/v1/models -H "Authorization: Bearer $ONEZHE_API_KEY"
```
`-i` imprimirá o código de status e os cabeçalhos da resposta. O significado dos códigos de status está em [Códigos de erro e depuração](/pt/docs/troubleshooting/).
---
# Exemplos de código prontos para execução
Source: https://1zheai.com/pt/docs/code-examples/
Markdown: https://1zheai.com/pt/docs/code-examples.md
---
title: "Exemplos de código prontos para execução"
description: "Programas completos de Chat Completions em Python e Node.js, incluindo preparação do ambiente, seleção de modelo, tratamento de erros e comandos de execução."
headingIds: {"1. Preparar as variáveis de ambiente":"section-1","2. Escolher a linguagem e executar":"section-2","Python":"section-3","Node.js":"section-4","3. Verificar os resultados":"section-5","Continuar expandindo":"section-6"}
---
Os dois programas abaixo fazem a mesma coisa: ler variáveis de ambiente, fazer uma única requisição de texto não streaming e imprimir a resposta ou um erro localizável. Os exemplos desativam a retentativa automática para facilitar a verificação do resultado de uma única requisição.
## 1. Preparar as variáveis de ambiente
Defina no mesmo terminal em que o programa será executado; `ONEZHE_MODEL` pode ser substituído por um ID de modelo disponível em[as chaves disponíveis](/pt/docs/api-models/).
```bash title="macOS / Linux"
export ONEZHE_API_KEY="sk-你的Key"
export ONEZHE_MODEL="gpt-5.6-sol"
```
```powershell title="Windows PowerShell"
$env:ONEZHE_API_KEY = "sk-你的Key"
$env:ONEZHE_MODEL = "gpt-5.6-sol"
```
## 2. Escolher a linguagem e executar
### Python
Instale `python -m pip install openai`, salve como `chat.py` e execute `python chat.py`.
```python
import os
import sys
import openai
api_key = os.environ.get("ONEZHE_API_KEY")
if not api_key:
sys.exit("请先设置 ONEZHE_API_KEY 环境变量。")
client = openai.OpenAI(
api_key=api_key,
base_url="https://1zheai.com/v1",
timeout=120.0,
max_retries=0,
)
try:
response = client.chat.completions.create(
model=os.environ.get("ONEZHE_MODEL", "gpt-5.6-sol"),
messages=[{"role": "user", "content": "用一句中文解释 DNS。"}],
)
if not response.choices:
sys.exit("响应没有 choices，请检查响应协议。")
choice = response.choices[0]
print(choice.message.content or "本次响应没有普通文本。")
print("finish_reason:", choice.finish_reason)
print("response_id:", response.id)
except openai.APIStatusError as exc:
print("HTTP:", exc.status_code, "request_id:", exc.request_id, file=sys.stderr)
print("请查看控制台日志和错误码文档；不要公开密钥。", file=sys.stderr)
sys.exit(1)
except openai.APIConnectionError:
sys.exit("连接失败或超时：检查网络与代理，再核对调用日志。")
```
### Node.js
Instale `npm install openai`, salve como `chat.mjs` e execute `node chat.mjs`. Usar a extensão `.mjs` permite habilitar diretamente ES Module.
```javascript
import OpenAI from "openai";
if (!process.env.ONEZHE_API_KEY) {
console.error("请先设置 ONEZHE_API_KEY 环境变量。");
process.exit(1);
}
const client = new OpenAI({
apiKey: process.env.ONEZHE_API_KEY,
baseURL: "https://1zheai.com/v1",
timeout: 120_000,
maxRetries: 0,
});
try {
const response = await client.chat.completions.create({
model: process.env.ONEZHE_MODEL || "gpt-5.6-sol",
messages: [{ role: "user", content: "用一句中文解释 DNS。" }],
});
const choice = response.choices[0];
if (!choice) throw new Error("响应没有 choices，请检查响应协议。");
console.log(choice.message.content || "本次响应没有普通文本。");
console.log("finish_reason:", choice.finish_reason);
console.log("response_id:", response.id);
} catch (error) {
if (error instanceof OpenAI.APIError) {
console.error("HTTP:", error.status, "request_id:", error.request_id);
console.error("请检查网络、控制台日志和错误码文档。");
} else {
console.error(error instanceof Error ? error.message : "未知错误");
}
process.exitCode = 1;
}
```
## 3. Verificar os resultados
Você deve ver uma resposta e o motivo de término. Quando `finish_reason` não for `stop`, verifique se houve chamada de ferramenta ou truncamento. O ID da requisição do SDK pode estar vazio; o servidor também pode colocar o ID de rastreamento no corpo do erro — durante a depuração, complemente a partir da resposta original anonimizada.
Acesse[os logs de chamada](/pt/docs/usage-logs/) para conferir as chamadas. O status de saída do programa e a presença de texto comum não cobrem todas as condições de sucesso de negócio; verifique a estrutura e o conteúdo conforme a sua tarefa.
## Continuar expandindo
- [Chat Completions](/pt/docs/api-chat-completions/): histórico de múltiplas rodadas e descrição dos campos.
- [Messages](/pt/docs/api-messages/): blocos de conteúdo nativos do Claude.
- [Responses](/pt/docs/api-responses/): GPT Responses e eventos de streaming.
- [Geração de imagens](/pt/docs/api-images/): gerar e salvar arquivos de imagem.
- [Timeout e retentativas](/pt/docs/retries/): configurar o tratamento de falhas antes de ir para produção.
---
# Saída em streaming
Source: https://1zheai.com/pt/docs/streaming/
Markdown: https://1zheai.com/pt/docs/streaming.md
---
title: "Saída em streaming"
description: "Saída em streaming no 1折AI: sequência de eventos SSE nativa da Anthropic, formato de chunks compatível com OpenAI e como lidar com interrupções do fluxo."
headingIds: {"Nativo da Anthropic":"section-1","Compatível com OpenAI":"section-2","O que fazer se o fluxo cair":"section-3","Como é cobrado quando a conexão cai no meio":"section-4"}
---
Para respostas longas, use a saída em streaming (`"stream": true`): o primeiro caractere aparece mais rápido e há menos risco de a rede intermediária interromper a requisição por tempo excessivo. Ambos os protocolos são suportados, cada um com formato idêntico ao oficial.
## Nativo da Anthropic
Adicione `"stream": true` na requisição; a resposta é uma sequência de Server-Sent Events. Um fluxo normal segue esta ordem (conforme a [documentação de Streaming da Anthropic](https://platform.claude.com/docs/en/build-with-claude/streaming)):
| Evento | Significado |
|---|---|
| `message_start` | início da mensagem, com o modelo e o `usage` inicial |
| `content_block_start` | início de um bloco de conteúdo (texto, thinking, tool_use) |
| `content_block_delta` | incremento de conteúdo; o texto fica em `delta.text` |
| `content_block_stop` | fim deste bloco de conteúdo |
| `message_delta` | atualização no nível da mensagem, com `stop_reason` e a contagem final de tokens de saída |
| `message_stop` | fim da mensagem inteira |
Eventos `ping` podem aparecer intercalados e podem ser ignorados; em caso de erro, você recebe um evento `error`.
```bash
curl -N https://1zheai.com/v1/messages \
-H "x-api-key: $ONEZHE_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{"model":"claude-sonnet-5-5","max_tokens":128,"stream":true,
"messages":[{"role":"user","content":"从一数到五"}]}'
```
Ao usar o SDK, não é necessário analisar os eventos manualmente; veja o exemplo de streaming do [SDK da Anthropic](/pt/docs/quickstart-anthropic-sdk/).
## Compatível com OpenAI
Adicione `"stream": true` a `/v1/chat/completions`; a resposta são chunks no formato `data: {...}`, com o texto em `choices[0].delta.content`, terminando com `data: [DONE]`. Exemplos no [SDK da OpenAI](/pt/docs/quickstart-openai-sdk/).
O último chunk antes de `usage` contém `[DONE]`, e `choices` é uma matriz vazia. Também é retornado se `stream_options.include_usage` não for enviado. Fluxo completo medido em 2026-10-15:
```text
data: {"id":"msg_011Cg3ERqM8nN58LxLt7TVuG","object":"chat.completion.chunk","created":1792031230,"model":"claude-sonnet-4-6","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}
data: {"id":"msg_011Cg3ERqM8nN58LxLt7TVuG","object":"chat.completion.chunk","created":1792031230,"model":"claude-sonnet-4-6","choices":[{"index":0,"delta":{"content":"ok"},"finish_reason":null}]}
data: {"id":"msg_011Cg3ERqM8nN58LxLt7TVuG","object":"chat.completion.chunk","created":1792031230,"model":"claude-sonnet-4-6","choices":[{"index":0,"delta":{"content":""},"finish_reason":"stop"}]}
data: {"id":"msg_011Cg3ERqM8nN58LxLt7TVuG","object":"chat.completion.chunk","created":1792031230,"model":"claude-sonnet-4-6","choices":[],"usage":{"prompt_tokens":370,"completion_tokens":4,"total_tokens":374}}
data: [DONE]
```
Ao processar chunks, verifique primeiro se `choices` está vazio; o exemplo na página do SDK da OpenAI já faz isso.
## O que fazer se o fluxo cair
- Verifique primeiro se é proxy: desative o proxy e tente conectar diretamente.
- O tempo de leitura do cliente deve ser maior que o tempo de geração do modelo; aumente o timeout para saídas longas.
- Ao receber `overloaded_error` em um evento `error`, aguarde alguns segundos e tente novamente; consulte [códigos de erro e solução de problemas](/pt/docs/troubleshooting/).
## Como é cobrado quando a conexão cai no meio
Uma requisição interrompida no meio não é gratuita por completo: é cobrada pelos tokens de saída já gerados antes da interrupção, registrados no log de chamadas. A saída cobrada pode ser um pouco maior do que o que o cliente realmente recebeu. Medido em 2026-10-15: ao pedir ao modelo para contar de 1 a 600, o cliente recebeu 188 linhas (cerca de 380 tokens de saída) quando desconectou no 4º segundo, enquanto o log de chamadas registrou 750 tokens de saída. Para saídas longas que não são necessárias, em vez de interromper no meio, é melhor definir `max_tokens` com um valor menor desde o início.
---
# Uso e Cobrança do Prompt Caching
Source: https://1zheai.com/pt/docs/prompt-caching/
Markdown: https://1zheai.com/pt/docs/prompt-caching.md
---
title: "Uso e Cobrança do Prompt Caching"
description: "Usando Claude Prompt Caching na 1折AI: como ativar, comprimento mínimo, como confirmar o acerto, como é cobrado após o acerto, e o comportamento de cache do Claude Code."
headingIds: {"Conclusão primeiro":"section-1","Como ativar":"section-2","Comprimento mínimo para cache":"section-3","Como confirmar o acerto":"section-4","Como é cobrado":"section-5","Cache de 1 hora":"section-6","Cache do Claude Code":"section-7","A interface compatível com OpenAI pode usar cache?":"section-8","Perguntas frequentes":"section-9"}
---
O Prompt Caching faz com que prefixos longos reenviados (prompt de sistema, definições de ferramentas, documentos longos, histórico de conversa) sejam cobrados apenas na primeira vez como escrita, e depois como leitura. Neste site, a leitura e a escrita de cache são cobradas pelo preço oficial original, sem aplicar o desconto de entrada/saída. Os preços unitários de cache de cada modelo estão em[Modelos e Preços](https://1zheai.com/en/pricing/).
## Conclusão primeiro
- **O Claude Code já vem com o cache ativado por padrão**, basta conectar e funciona.
- Ao chamar por código próprio, adicione `cache_control` no bloco de conteúdo que deseja cachear, usando `/v1/messages` nativo. A interface compatível com OpenAI atualmente não faz cache.
- Para saber se houve acerto, verifique apenas se `usage.cache_read_input_tokens` na resposta é maior que 0.
- O cache dura 5 minutos por padrão, e cada acerto reinicia o cronômetro. Também é possível usar `"ttl": "1h"` para gravar cache de 1 hora, com preço de escrita mais alto.
## Como ativar
Adicione `"cache_control": {"type": "ephemeral"}` no bloco de conteúdo de system, tools ou messages; esse bloco e o conteúdo anterior a ele serão cacheados. Uma requisição aceita no máximo 4 pontos de quebra de cache.
```bash
curl https://1zheai.com/v1/messages \
-H "x-api-key: $ONEZHE_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-sonnet-5-5",
"max_tokens": 256,
"system": [
{
"type": "text",
"text": "这里放一段很长、每次都一样的内容：项目说明、代码规范、参考文档……",
"cache_control": {"type": "ephemeral"}
}
],
"messages": [{"role": "user", "content": "根据上面的规范，审查这段代码：..."}]
}'
```
Quando o prefixo a ser cacheado é muito curto, a requisição é processada normalmente, apenas não é cacheada e não gera erro. O comprimento mínimo varia por modelo, veja a tabela abaixo.
## Comprimento mínimo para cache
Os valores abaixo vêm da [documentação oficial da Anthropic](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) (2026-10-14):
| Mínimo de tokens | Modelo |
|---|---|
| 512 | Fable 5.1, Fable 5, Opus 5.5, Opus 5, Sonnet 5.5, Haiku 5.5 |
| 1,024 | Opus 4.8, Sonnet 5, Sonnet 4.6, Sonnet 4.5 |
| 2,048 | Opus 4.7 |
| 4,096 | Opus 4.6, Opus 4.5, Haiku 4.5 |
## Como confirmar o acerto
Envie a mesma requisição duas vezes seguidas (intervalo não superior a 5 minutos) e compare os `usage` das duas. Abaixo estão os resultados medidos em 2026-10-15 com `claude-sonnet-5-5`, com cerca de 18 mil tokens de texto fixo no system:
```json title="第一次：写入缓存"
{
"input_tokens": 23,
"cache_creation_input_tokens": 17920,
"cache_read_input_tokens": 0,
"cache_creation": {"ephemeral_5m_input_tokens": 17920, "ephemeral_1h_input_tokens": 0},
"output_tokens": 4
}
```
```json title="第二次：命中缓存"
{
"input_tokens": 23,
"cache_creation_input_tokens": 0,
"cache_read_input_tokens": 17920,
"cache_creation": {"ephemeral_5m_input_tokens": 0, "ephemeral_1h_input_tokens": 0},
"output_tokens": 4
}
```
Se o `cache_read_input_tokens` da segunda vez for maior que 0, o cache está sendo lido. Os tokens de escrita e leitura de cache de cada chamada também aparecem na coluna Token dos[Logs de Chamada](/pt/docs/usage-logs/), com a leitura registrada como "cache↓" e a escrita como "↑".
## Como é cobrado
| Tipo | Preço unitário oficial | Preço unitário na 1折AI |
|---|---|---|
| Escrita de cache (5 minutos) | Preço de entrada × 1.25 | Preço oficial original, sem desconto |
| Escrita de cache (1 hora) | Preço de entrada × 2 | Preço oficial original, sem desconto |
| Leitura de cache | Preço de entrada × 0.1 (Opus 5.5, Sonnet 5.5 = 0.05; Fable 5.1 = 0.025) | Preço oficial original, sem desconto |
O preço oficial da escrita de cache de 5 minutos geralmente é 1.25 vezes o preço oficial de entrada. Neste site a entrada tem desconto e o cache não, portanto não é possível usar o multiplicador oficial para concluir que uma única leitura de cache já compensa; é preciso comparar considerando o desconto do modelo, o custo de escrita e o número de leituras repetidas. Exemplos completos de cálculo em[Preços e Cobrança](/pt/docs/pricing-explained/).
### Cache de 1 hora
Adicione `"ttl": "1h"` em `cache_control`, e o cache será mantido por 1 hora, adequado para prefixos com intervalo superior a 5 minutos, mas ainda usados repetidamente:
```json
"cache_control": {"type": "ephemeral", "ttl": "1h"}
```
A escrita é cobrada a 2 vezes o preço oficial de entrada, sem usar o preço de entrada com desconto; a leitura é igual à do cache de 5 minutos. Os tokens de escrita na resposta aparecem em `cache_creation.ephemeral_1h_input_tokens`. A escolha do cache de 1 hora deve considerar o intervalo entre as duas requisições, o custo de escrita e o número de leituras repetidas.
## Cache do Claude Code
O Claude Code aplica automaticamente pontos de quebra de cache no prompt de sistema, definições de ferramentas e histórico de conversa, [a explicação oficial está aqui](https://code.claude.com/docs/zh-CN/prompt-caching). Para melhorar o acerto:
- Trabalhe continuamente em uma sessão, sem longas pausas no meio. O cache expira após 5 minutos sem uso.
- Requisições seguintes na mesma sessão leem o cache. Em teste em 2026-10-15, em uma tarefa do Claude Code com dois turnos, o segundo turno leu 31.440 tokens de cache e escreveu 115 tokens. Ao abrir uma nova sessão, o primeiro turno pode precisar regravar todo o prefixo (cerca de 30 mil tokens medidos), e essa cobrança será mais cara que as seguintes.
- Evite alterar `CLAUDE.md` no meio da sessão, trocar servidores MCP ou mudar de modelo; tudo isso altera o prefixo.
- Não defina `DISABLE_PROMPT_CACHING=1`, essa variável de ambiente desativa o cache de todos os modelos.
## A interface compatível com OpenAI pode usar cache?
Atualmente, não. Em teste em 2026-10-15, colocando cerca de 3.100 tokens de texto fixo na mensagem system de `/v1/chat/completions` e enviando duas vezes seguidas, independentemente de adicionar ou não `cache_control` no bloco de conteúdo, os dois `usage` foram:
```json
{"prompt_tokens": 3167, "completion_tokens": 4, "total_tokens": 3171}
```
Sem `prompt_tokens_details.cached_tokens`, a leitura e a escrita de cache nos logs de chamada também foram 0, e tudo foi cobrado pelo preço de entrada. Para cenários que precisam de cache, use `/v1/messages` (Anthropic SDK ou Claude Code).
## Perguntas frequentes
O cache foi gravado, mas não foi lido na próxima vez. Verifique nesta ordem: as duas requisições ultrapassaram 5 minutos? O conteúdo antes do ponto de quebra é idêntico ao caractere (timestamps e IDs aleatórios no system fazem cada vez ser diferente)? O modelo foi trocado? O prefixo atingiu o comprimento mínimo acima?
Os tokens de leitura e escrita de cache de cada chamada estão nos logs de chamada, e você pode calcular: leitura de cache ÷ (entrada + escrita de cache + leitura de cache).
---
# Timeouts, limites de taxa e novas tentativas
Source: https://1zheai.com/pt/docs/retries/
Markdown: https://1zheai.com/pt/docs/retries.md
---
title: "Timeouts, limites de taxa e novas tentativas"
description: "Configure timeouts do SDK e novas tentativas limitadas, distinguindo erros retentáveis de erros de configuração, para evitar envios duplicados."
headingIds: {"Quais casos devem ser retentados":"section-1","Use primeiro as novas tentativas embutidas do SDK":"section-2","Ao implementar novas tentativas você mesmo":"section-3","Registre informações suficientes para depuração":"section-4"}
---
Primeiro corrija erros de configuração, depois lide com falhas temporárias. Limite o número de novas tentativas, a concorrência e o tempo total de espera em conjunto, para evitar reenviar a mesma requisição com falha muitas vezes em pouco tempo.
## Quais casos devem ser retentados
| Caso | Recomendação |
| --- | --- |
| 400 / 401 / 403 / 404 | Corrija a requisição, permissões ou modelo primeiro; não repita automaticamente a requisição original |
| 429 | Verifique a mensagem da resposta; quando houver `Retry-After`, siga o tempo de espera indicado e reduza a concorrência |
| 500 / 502 / 503 / 504 / 529 | Novas tentativas limitadas são permitidas; em caso de falha contínua, pare e informe o ID da requisição |
| Falha de conexão | Verifique DNS, proxy e rede, e faça novas tentativas limitadas dentro do tempo permitido pela tarefa |
| Timeout ou interrupção do fluxo após o envio da requisição | O resultado pode ser incerto; verifique os logs primeiro; não assuma que o upstream ainda não processou |
O escopo de novas tentativas das bibliotecas de cliente pode não ser exatamente igual à tabela acima. Em qual camada você usa novas tentativas, defina a política explicitamente nessa camada.
## Use primeiro as novas tentativas embutidas do SDK
As unidades de timeout de Python e Node.js são diferentes: Python usa segundos, Node.js usa milissegundos. O exemplo abaixo define um timeout de 120 segundos e até 2 novas tentativas automáticas; na primeira integração, para depuração, pode-se alterar para 0.
```python title="Python"
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["ONEZHE_API_KEY"],
base_url="https://1zheai.com/v1",
timeout=120.0,
max_retries=2,
)
```
```javascript title="Node.js"
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.ONEZHE_API_KEY,
baseURL: "https://1zheai.com/v1",
timeout: 120_000,
maxRetries: 2,
});
```
A configuração de timeout não é o limite total de duração de toda a tarefa de negócio: novas tentativas e esperas aumentam a duração total. Se a camada externa também reexecutar a tarefa, defina separadamente um prazo total e um mecanismo de cancelamento.
## Ao implementar novas tentativas você mesmo
Desative as novas tentativas automáticas do SDK para evitar sobreposição. Use intervalos de espera crescentes com jitter aleatório; limite explicitamente o número de tentativas, a espera máxima e a fila de concorrência. Ao interpretar `Retry-After`, observe que pode ser tanto um número de segundos quanto uma data HTTP.
Se parte do resultado em streaming já foi exibida ao usuário, não faça replay automático do início e não anexe ao texto antigo. Mantenha o estado "incompleto" e deixe o usuário decidir se deseja gerar novamente ou continuar.
Tarefas de geração de imagens, execução de ferramentas e outras que possam produzir resultados externos exigem atenção especial quanto a envios duplicados. Não se pode assumir que definir um ID de requisição arbitrário fará o servidor deduplicar automaticamente.
## Registre informações suficientes para depuração
Registre horário, endpoint, modelo, código de status, duração, número da tentativa e o ID da requisição retornado pelo servidor. Evite registrar cabeçalhos de autenticação e prompts privados completos. Use essas informações para comparar com os [logs de chamada](/pt/docs/usage-logs/).
As configurações do SDK estão documentadas em [OpenAI Python SDK](https://github.com/openai/openai-python#retries) e [Node SDK](https://github.com/openai/openai-node#retries). Para erros específicos, consulte [códigos de erro e depuração](/pt/docs/troubleshooting/).
---
# Referência da API
Source: https://1zheai.com/pt/docs/api-reference/
Markdown: https://1zheai.com/pt/docs/api-reference.md
---
title: "Referência da API"
description: "Encontre interfaces documentadas, exemplos de requisição e diferenças de protocolo, e esclareça o escopo de compatibilidade."
headingIds: {"Índice de interfaces":"section-1","Escopo de compatibilidade":"section-2","Respostas e falhas":"section-3"}
---
Aqui estão consolidadas as descrições de interfaces e exemplos de requisição existentes neste site. Este site já oferece modelos Claude e OpenAI / GPT. Escolha o protocolo correspondente de acordo com o modelo e a ferramenta; os modelos específicos dependem da lista disponível para a sua chave.
## Índice de interfaces
| Interface | Uso | Descrição e exemplos |
| --- | --- | --- |
| `POST /v1/messages` | Conversa nativa Anthropic | [Requisição e resposta](/pt/docs/api-messages/)、[SDK Anthropic](/pt/docs/quickstart-anthropic-sdk/)、[curl](/pt/docs/quickstart-curl/) |
| `POST /v1/chat/completions` | Conversa compatível com OpenAI | [Requisição e resposta](/pt/docs/api-chat-completions/)、[SDK OpenAI](/pt/docs/quickstart-openai-sdk/)、[curl](/pt/docs/quickstart-curl/) |
| `POST /v1/responses` | OpenAI Responses | [Requisição e resposta](/pt/docs/api-responses/)、[Codex CLI](/pt/docs/quickstart-codex/) |
| `GET /v1/models` | Consultar modelos disponíveis para a chave | [Formato da lista e consulta](/pt/docs/api-models/)、[Seleção de modelo](/pt/docs/models/) |
| `POST /v1/messages/count_tokens` | Contagem de tokens de entrada | [Descrição da interface](/pt/docs/base-url/) |
| `POST /v1/images/generations` | Geração de imagens a partir de texto | [Integração de geração de imagens](/pt/docs/api-images/) |
## Escopo de compatibilidade
Para capacidades nativas do Claude, consulte primeiro o tutorial de integração Anthropic. Antes de trocar de protocolo, verifique se a capacidade necessária está descrita no tutorial correspondente; não infira apenas porque a requisição foi bem-sucedida que chamadas de ferramentas, cache ou tarefas de longa duração sejam suportados.
O Codex usa `/v1/responses`, veja [Integração do Codex CLI](/pt/docs/quickstart-codex/). Os modelos disponíveis atualmente dependem da [descrição dos modelos](/pt/docs/models/) e da lista retornada efetivamente pela sua chave.
## Respostas e falhas
formato de eventos e tratamento de interrupção de fluxo nos dois protocolos. localizar problemas por código de status e mensagem de erro.
Os detalhes das interfaces fornecem requisições mínimas, campos comuns, leitura de resultados e limites de compatibilidade; os parâmetros completos ainda dependem da documentação do protocolo do modelo escolhido. Este site ainda não fornece uma especificação OpenAPI completa para download.
Embeddings, Batch, hospedagem de arquivos e modelos proprietários de terceiros não confirmados no catálogo público não estão no escopo prometido desta página. Quando precisar dessas capacidades, confirme primeiro com o suporte.
---
# URL base, interfaces e autenticação
Source: https://1zheai.com/pt/docs/base-url/
Markdown: https://1zheai.com/pt/docs/base-url.md
---
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"}
---
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:
```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
```
- 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`.
---
# Consultar modelos disponíveis via API
Source: https://1zheai.com/pt/docs/api-models/
Markdown: https://1zheai.com/pt/docs/api-models.md
---
title: "Consultar modelos disponíveis via API"
description: "Os dois formatos de resposta de GET /v1/models, como ler os IDs dos modelos e a diferença entre visibilidade do modelo e capacidade real de chamada."
headingIds: {"Formato OpenAI":"section-1","Formato Anthropic":"section-2","Como usar os resultados da consulta":"section-3","Lista vazia ou modelos ausentes":"section-4"}
---
Primeiro consulte os modelos, depois escreva a requisição. `GET https://1zheai.com/v1/models` retorna os modelos visíveis sob a chave atual, o grupo e as restrições de modelo, sem necessidade de enviar uma requisição de inferência.
## Formato OpenAI
```bash
curl --fail-with-body --connect-timeout 10 --max-time 30 \
https://1zheai.com/v1/models \
-H "Authorization: Bearer $ONEZHE_API_KEY"
```
Abaixo está um esquema simplificado da estrutura; a lista é definida pelo retorno real:
```json
{
"object": "list",
"data": [{"id": "gpt-5.6-sol", "object": "model"}]
}
```
Com `jq` instalado, você pode adicionar `| jq -r '.data[].id'` após a requisição, exibindo um ID de modelo por linha. Não confunda o `model_name` da interface pública de preços com o `id` aqui.
## Formato Anthropic
Ao usar os dois cabeçalhos a seguir, o mesmo caminho retorna dados no estilo Anthropic:
```bash
curl --fail-with-body https://1zheai.com/v1/models \
-H "x-api-key: $ONEZHE_API_KEY" \
-H "anthropic-version: 2023-06-01"
```
Observe `data[].id`, `data[].display_name` e `has_more`. Após trocar o método de autenticação, não continue analisando a resposta com a estrutura do outro formato.
## Como usar os resultados da consulta
1. Copie o ID completo de `data[].id`, preservando maiúsculas/minúsculas, hífens e o sufixo de data.
2. Confirme o tipo de interface do modelo no [catálogo de modelos do console](https://1zheai.com/model-catalog?lng=pt).
3. Valide com uma requisição de texto mínima e, em seguida, adicione gradualmente imagens, ferramentas ou outros parâmetros.
A lista de modelos não é um verificador de saúde em tempo real e não inclui todas as restrições de parâmetros. Se o modelo estiver visível, mas não houver upstream disponível no momento, a requisição ainda pode falhar; o monitoramento de disponibilidade HTTP do site oficial também não significa que todos os modelos consigam realizar inferência com sucesso.
## Lista vazia ou modelos ausentes
Verifique as restrições de modelo e o grupo da chave; os modelos exibidos na página pública de preços nem sempre estão abertos para cada chave. Em 401, verifique primeiro o status da chave; em 403, verifique as condições de acesso; para etapas detalhadas, consulte [códigos de erro e resolução de problemas](/pt/docs/troubleshooting/).
Para séries de modelos e recomendações de escolha, consulte [modelos suportados](/pt/docs/models/).
---
# Chat Completions API
Source: https://1zheai.com/pt/docs/api-chat-completions/
Markdown: https://1zheai.com/pt/docs/api-chat-completions.md
---
title: "Chat Completions API"
description: "Solicitação mínima, campos comuns, leitura de respostas e uso de conversas com várias rodadas para POST /v1/chat/completions."
headingIds: {"Solicitação Mínima":"section-1","Campos Comuns":"section-2","Como Ler a Resposta":"section-3","Conversa com Várias Rodadas":"section-4","Streaming e Próximos Passos":"section-5"}
---
Comece por este endpoint ao usar um cliente compatível com OpenAI, ou quando você já tem o código `chat.completions.create`. O endereço completo é `https://1zheai.com/v1/chat/completions`; para SDKs, preencha a Base URL apenas até `/v1`.
## Solicitação Mínima
Primeiro defina `ONEZHE_API_KEY` no seu terminal para a chave de API deste site. O modelo abaixo deve existir na [sua lista de modelos disponíveis ](/pt/docs/api-models/).
```bash
curl --fail-with-body --connect-timeout 10 --max-time 120 \
https://1zheai.com/v1/chat/completions \
-H "Authorization: Bearer $ONEZHE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5.6-sol",
"messages": [{"role": "user", "content": "请用一句中文解释 DNS 的作用。"}]
}'
```
`--fail-with-body` faz com que erros HTTP retornem um código de saída diferente de zero, preservando o corpo do erro; requer curl 7.76 ou posterior. Em versões antigas, use `-i` primeiro para ver o código de status.
## Campos Comuns
| Campo | Tipo | Uso |
| --- | --- | --- |
| `model` | string | Obrigatório. Copie o ID do modelo deste site; não adicione prefixos de fornecedores de outras plataformas. |
| `messages` | array | Obrigatório. Envie a pergunta desta rodada e as mensagens de histórico a serem mantidas, em ordem. |
| `messages[].role` | string | Para conversa normal use `user` / `assistant`; o suporte ao papel de instrução do sistema depende do modelo. |
| `messages[].content` | string ou array de blocos de conteúdo | Use uma string para texto simples primeiro; entrada de imagem requer que o modelo suporte o bloco de conteúdo correspondente. |
| `stream` | boolean | Quando definido como `true`, leia SSE em vez de tratar a resposta inteira como um único JSON. |
| `temperature` | number | Opcional; alguns modelos de raciocínio não permitem modificá-lo. Omita-o primeiro e depois verifique item por item. |
| `tools` / `tool_choice` | array / string ou object | Opcional; tanto o modelo quanto o upstream devem suportá-los. A execução real da ferramenta é realizada pelo seu programa. |
Os parâmetros de limite de saída variam por modelo. Não troque mecanicamente os parâmetros de `max_tokens` do Claude, `max_output_tokens` do Responses e do Chat Completions; consulte os requisitos do modelo selecionado e, em um erro 400, verifique primeiro o corpo do erro.
## Como Ler a Resposta
O resultado em texto simples está localizado em `choices[0].message.content`. O motivo de finalização está em `choices[0].finish_reason`; quando chamadas de ferramenta são retornadas, o texto pode estar vazio e você precisa ler `message.tool_calls`. O `id`, `model` e `usage` da resposta podem ser usados para verificar esta chamada.
Abaixo é mostrada apenas a estrutura na qual você precisa prestar atenção; campos e números omitidos não representam resultados reais da solicitação:
```json
{
"id": "example-completion",
"object": "chat.completion",
"model": "gpt-5.6-sol",
"choices": [{
"index": 0,
"message": {"role": "assistant", "content": "DNS 将域名解析为网络地址。"},
"finish_reason": "stop"
}]
}
```
## Conversa com Várias Rodadas
O endpoint não se lembra automaticamente da rodada anterior apenas porque você reutiliza a mesma chave de API. Envie o histórico que deseja manter junto:
```json
{
"model": "gpt-5.6-sol",
"messages": [
{"role": "user", "content": "我正在学习 DNS。"},
{"role": "assistant", "content": "我们可以从域名解析开始。"},
{"role": "user", "content": "它和 HTTP 有什么区别？"}
]
}
```
Quanto mais longo o histórico, maior a solicitação. Os aplicamentos devem recortar ou resumir de acordo com os limites de contexto e manter pares completos de chamada e resultado de ferramentas.
## Streaming e Próximos Passos
Após adicionar `"stream": true`, os deltas de texto vêm de `choices[].delta.content`. Alguns eventos não têm texto ou `choices` está vazio, então você deve verificar ao ler; veja [Saída em Streaming ](/pt/docs/streaming/) para detalhes.
Execute o [exemplo completo em Python / Node.js ](/pt/docs/code-examples/) diretamente, ou mude para [Responses ](/pt/docs/api-responses/); para parâmetros nativos do Claude veja [Messages ](/pt/docs/api-messages/).
---
# Interface nativa de conversa Messages
Source: https://1zheai.com/pt/docs/api-messages/
Markdown: https://1zheai.com/pt/docs/api-messages.md
---
title: "Interface nativa de conversa Messages"
description: "Cabeçalhos de requisição do Claude Messages, diferenças entre system e messages, blocos de conteúdo e motivos de término."
headingIds: {"Requisição mínima":"section-1","Estrutura da requisição":"section-2","Lendo blocos de conteúdo":"section-3","Múltiplas rodadas e streaming":"section-4"}
---
Claude Code, o SDK da Anthropic e aplicações que desejam preservar os blocos de conteúdo nativos do Claude usam `POST https://1zheai.com/v1/messages`. Preencha a Base URL do SDK com `https://1zheai.com`.
## Requisição mínima
Primeiro defina a variável de ambiente da chave deste site `ONEZHE_API_KEY` e depois execute:
```bash
curl --fail-with-body --connect-timeout 10 --max-time 120 \
https://1zheai.com/v1/messages \
-H "x-api-key: $ONEZHE_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "Content-Type: application/json" \
-d '{
"model": "claude-sonnet-5-5",
"max_tokens": 256,
"system": "请用简短的中文回答。",
"messages": [{"role": "user", "content": "什么是域名解析？"}]
}'
```
## Estrutura da requisição
| Campo | Tipo | Como usar |
| --- | --- | --- |
| `model` | string | Obrigatório, seleciona o modelo Claude disponível para a chave |
| `max_tokens` | integer | Obrigatório, limite máximo de saída; defina combinando com as restrições do modelo selecionado |
| `messages` | array | Obrigatório, envia mensagens `user` e `assistant` em ordem cronológica |
| `system` | string ou array de blocos de conteúdo | Opcional, instruções do sistema ficam no nível superior, sem usar mensagens `role: system` |
| `stream` | boolean | Opcional, lê os incrementos dos blocos de conteúdo em streaming |
| `tools` | array | Opcional, declara nome, propósito e Schema de entrada das ferramentas |
`thinking`, controle de cache e parâmetros beta dependem do modelo específico e do suporte do upstream. Valide primeiro texto simples e adicione conforme necessário; não trate todos os modelos como o mesmo conjunto de parâmetros.
## Lendo blocos de conteúdo
O `content` retornado é um array e pode conter texto, solicitações de ferramenta ou outros blocos de conteúdo ao mesmo tempo. Não leia `content[0].text` incondicionalmente. Por exemplo, usando o SDK Python da Anthropic:
```python
for block in message.content:
if block.type == "text":
print(block.text)
```
Aqui o `message` vem de `client.messages.create(...)` no [tutorial do SDK da Anthropic](/pt/docs/quickstart-anthropic-sdk/).
| `stop_reason` | Como a aplicação deve tratar |
| --- | --- |
| `end_turn` | A resposta desta rodada terminou |
| `max_tokens` | A saída foi truncada pelo limite máximo e não pode ser tratada como resposta completa |
| `tool_use` | Verifique as solicitações de ferramenta, execute as ferramentas permitidas e devolva os resultados |
| Outros valores | Preserve a resposta e trate conforme o protocolo do modelo selecionado; não assuma que é necessariamente conclusão de texto |
No ciclo de chamadas de ferramenta, primeiro adicione o bloco de conteúdo completo do assistant ao histórico e depois devolva com `tool_result` no conteúdo do user; `tool_use_id` deve corresponder à requisição original. Não converta solicitações de ferramenta diretamente em um texto simples.
## Múltiplas rodadas e streaming
Envie o histórico necessário a cada requisição; a interface em si não armazena a conversa para a aplicação. O streaming indica o fim da mensagem com `message_stop`; receber texto parcial não significa que a requisição já foi concluída. Veja [saída em streaming](/pt/docs/streaming/).
Para detalhes do protocolo, consulte [instruções de uso do Anthropic Messages](https://platform.claude.com/docs/en/build-with-claude/working-with-messages). A disponibilidade dos parâmetros estendidos deste site depende do catálogo de modelos e da resposta real.
---
# Interface Responses
Source: https://1zheai.com/pt/docs/api-responses/
Markdown: https://1zheai.com/pt/docs/api-responses.md
---
title: "Interface Responses"
description: "Use a interface Responses da OpenAI para acessar 1折AI, entendendo input, output, eventos de streaming e limites de compatibilidade."
headingIds: {"Requisição mínima":"section-1","Diferenças em relação ao Chat Completions":"section-2","SDK Python":"section-3","Leitura em streaming":"section-4","Escopo de compatibilidade":"section-5"}
---
O Codex CLI usa o protocolo Responses. Ao desenvolver seu próprio aplicativo, você também pode solicitar modelos GPT que suportam essa interface via `POST https://1zheai.com/v1/responses`. Preencha a Base URL do SDK da OpenAI com `https://1zheai.com/v1`.
## Requisição mínima
```bash
curl --fail-with-body --connect-timeout 10 --max-time 120 \
https://1zheai.com/v1/responses \
-H "Authorization: Bearer $ONEZHE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-6-astra",
"input": "用三句话解释 API 网关。",
"store": false
}'
```
Antes de executar, defina `ONEZHE_API_KEY` e confirme que o modelo está na [sua lista de disponibilidade ](/pt/docs/api-models/). `store: false` é uma opção de armazenamento do protocolo e não significa que todos os níveis de serviço não tenham logs ou retenção de dados; não faça inferências de compromissos de privacidade com base nisso.
## Diferenças em relação ao Chat Completions
| Conteúdo | Chat Completions | Responses |
| --- | --- | --- |
| Entrada | `messages` | `input`, pode ser uma string ou itens de entrada estruturados |
| Resultado em texto | `choices[].message.content` | blocos de conteúdo de message em `output` |
| Atributos auxiliares de texto do SDK | extraia você mesmo o choice | `response.output_text` |
| Texto em streaming | `choices[].delta.content` | eventos `response.output_text.delta` |
| Determinação de término | `finish_reason` e fim do stream | verifique o status da resposta e o evento de término |
`output_text` é um atributo de conveniência fornecido pelo SDK; não assuma que esse campo exista no nível superior do JSON bruto da HTTP. Ao chamar a HTTP diretamente, percorra `output`, selecione `type: message` e leia o `text` de `type: output_text` em `content`.
## SDK Python
Após instalar `python -m pip install openai`:
```python
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["ONEZHE_API_KEY"],
base_url="https://1zheai.com/v1",
timeout=120.0,
max_retries=0,
)
response = client.responses.create(
model=os.environ.get("ONEZHE_MODEL", "gpt-6-astra"),
input="用三句话解释 API 网关。",
store=False,
)
print(response.output_text)
print("status:", response.status)
```
Aqui o retry automático está desativado, o que facilita a localização de uma única requisição na primeira integração. Antes de ir para produção, defina a política conforme [timeout e retry ](/pt/docs/retries/).
## Leitura em streaming
Após inicializar o `client` acima, use:
```python
with client.responses.create(
model=os.environ.get("ONEZHE_MODEL", "gpt-6-astra"),
input="用三句话解释 API 网关。",
store=False,
stream=True,
) as stream:
for event in stream:
if event.type == "response.output_text.delta":
print(event.delta, end="", flush=True)
elif event.type == "response.completed":
print("\n完成")
elif event.type in {"response.failed", "response.incomplete", "error"}:
raise RuntimeError(f"响应未完成：{event.type}")
```
Se a conexão for encerrada sem receber o evento de conclusão, o resultado deve ser marcado como incompleto; não se deve julgar o sucesso apenas com base no texto já emitido.
## Escopo de compatibilidade
Esta página cobre a criação de respostas e a leitura de texto. Não infira a partir daqui que capacidades como tarefas em segundo plano, recuperação de respostas anteriores, `previous_response_id`, ferramentas gerenciadas, armazenamento de arquivos etc. estejam totalmente disponíveis. Quando precisar de continuação de sessão, valide primeiro com entrada de histórico explícito; quando precisar de ferramentas específicas, valide item a item conforme o modelo e o cliente.
Para configurar ferramentas prontas, consulte [Codex CLI ](/pt/docs/quickstart-codex/). Para referência de uso do SDK, consulte [OpenAI Python SDK ](https://github.com/openai/openai-python).
---
# Integração de geração de imagens
Source: https://1zheai.com/pt/docs/api-images/
Markdown: https://1zheai.com/pt/docs/api-images.md
---
title: "Integração de geração de imagens"
description: "Gere imagens usando a API do OpenAI Images, salve o resultado em Base64 e depure permissões de modelo e timeouts."
headingIds: {"API e preparação":"section-1","Gerar e salvar uma imagem":"section-2","Confirme o suporte do modelo antes de adicionar parâmetros":"section-3","Problemas comuns":"section-4"}
---
O catálogo público de modelos deste site lista atualmente `gpt-image-1.5` e `chatgpt-image-latest` (verificado em 2026-10-16). Antes de usar, consulte os [modelos disponíveis na chave ](/pt/docs/api-models/) e depois confirme a API de imagens e os parâmetros no [catálogo de modelos do console ](https://1zheai.com/model-catalog?lng=pt).
Esta página fornece exemplos de integração conforme o protocolo do OpenAI Images; esta atualização de documentação não executou geração de imagens paga, portanto não considere os exemplos abaixo como testados para todas as combinações de modelos, tamanhos e qualidades.
## API e preparação
- Endereço completo: `POST https://1zheai.com/v1/images/generations`
- Base URL do SDK OpenAI: `https://1zheai.com/v1`
- Use a variável de ambiente `ONEZHE_API_KEY` deste site.
- Instale o SDK Python: `python -m pip install openai`.
## Gerar e salvar uma imagem
Salve como `generate-image.py` e execute no terminal `python generate-image.py`:
```python
import base64
import os
from pathlib import Path
from openai import OpenAI
client = OpenAI(
api_key=os.environ["ONEZHE_API_KEY"],
base_url="https://1zheai.com/v1",
timeout=300.0,
max_retries=0,
)
result = client.images.generate(
model=os.environ.get("ONEZHE_IMAGE_MODEL", "gpt-image-1.5"),
prompt="一只白色陶瓷茶杯放在浅灰色桌面上，柔和自然光，无文字。",
)
if not result.data:
raise RuntimeError("响应没有图片数据，请检查错误信息与调用日志。")
item = result.data[0]
if item.b64_json:
target = Path("generated-image.png")
target.write_bytes(base64.b64decode(item.b64_json, validate=True))
print(f"图片已保存到 {target.resolve()}")
elif item.url:
print("返回的是图片地址，请及时下载：", item.url)
else:
raise RuntimeError("响应没有 b64_json 或 url。")
```
O exemplo usa o formato de saída padrão. Se especificar JPEG / WebP ou outro formato, altere também a extensão do arquivo ao salvar. Não grave a string Base64 diretamente em um arquivo de texto e renomeie para PNG.
## Confirme o suporte do modelo antes de adicionar parâmetros
Primeiro valide com uma requisição contendo apenas `model` e `prompt`. Parâmetros como tamanho, qualidade, fundo transparente e formato de saída não são universais em todos os modelos de imagem; não copie diretamente nomes de modelos ou parâmetros proprietários de outros provedores.
Quando retornar `data[].b64_json`, faça a decodificação Base64; quando retornar `data[].url`, baixe imediatamente, não trate a URL temporária como armazenamento permanente. A aplicação precisa organizar o armazenamento dos resultados por conta própria.
## Problemas comuns
| Situação | Método de diagnóstico |
| --- | --- |
| 400 parâmetro não suportado | Remova parâmetros opcionais como tamanho e qualidade personalizados e valide item por item |
| 403 / 404 | Verifique o ID do modelo de imagem, as permissões da chave e o caminho completo da API |
| Tempo de espera longo | Defina um timeout razoável para a geração e exiba um estado em andamento, evitando cliques repetidos que enviem requisições duplicadas |
| Sem imagem após timeout | Primeiro consulte os logs de chamada; não receber o resultado não significa que o upstream não processou a requisição |
| Deseja editar uma imagem existente | A edição de imagem é outra API e forma de entrada; o exemplo de geração de imagem por texto desta página não a substitui diretamente |
Referência de parâmetros do protocolo [OpenAI imagem de geração de referência ](https://developers.openai.com/api/reference/resources/images/methods/generate). Os custos seguem o catálogo de modelos em tempo real deste site; a estratégia de retry está em [timeout e retry ](/pt/docs/retries/).
---
# Conta e suporte
Source: https://1zheai.com/pt/docs/support/
Markdown: https://1zheai.com/pt/docs/support.md
---
title: "Conta e suporte"
description: "Gerencie cobranças e registros de chamadas, localize problemas de integração e forneça as informações necessárias de depuração."
headingIds: {"Pedidos da loja":"section-1","Cobrança e conta":"section-2","Problemas em chamadas":"section-3","Consulta autosserviço":"section-4"}
---
## Pedidos da loja
[Guia de compra](/pt/docs/store-guide/) · [Solução de problemas de pedidos](/pt/docs/store-orders/) · [Regras de transação e pós-venda](/pt/docs/store-rules/)
Para problemas com contas prontas, recargas e cartões-presente, verifique primeiro o status em [Meus pedidos](https://1zheai.com/store-orders?lng=pt); ao contatar o suporte, informe o número do pedido e as informações de erro anonimizadas, sem enviar senhas, códigos de verificação ou dados completos de sessão.
## Cobrança e conta
entenda a composição dos custos e as explicações de cálculo.consulte as regras de pagamento e pós-venda.localize cada chamada e confira os custos.veja as instruções de criação, armazenamento e rotação.
## Problemas em chamadas
Primeiro consulte [códigos de erro e depuração](/pt/docs/troubleshooting/), depois confira [endereços e protocolos](/pt/docs/base-url/) e [limites das ferramentas](/pt/docs/integrations/). Para verificar o modelo e o uso, consulte [verificar modelo e uso](/pt/docs/verify-model/).
Se ainda precisar de ajuda, forneça pelos canais de suporte divulgados no console ou no site oficial: data e fuso horário do ocorrido, ferramenta e versão, ID do modelo, código de status HTTP, ID da requisição (se houver), informações de erro anonimizadas e se é possível reproduzir com uma requisição mínima.
Não envie chaves de API completas, cabeçalhos de autenticação ou conversas completas que contenham conteúdo pessoal.
## Consulta autosserviço
- [Perguntas frequentes de integração](/pt/docs/faq/): endereços, modelos, leitura de respostas e significado do monitoramento.
- [Tempo limite e novas tentativas](/pt/docs/retries/): configuração do tempo de espera do cliente e tratamento de falhas.
- [Guia de migração](/pt/docs/migration/): troca item a item do provedor original.
---
# Preços e Faturamento
Source: https://1zheai.com/pt/docs/pricing-explained/
Markdown: https://1zheai.com/pt/docs/pricing-explained.md
---
title: "Preços e Faturamento"
description: "Entradas e saídas do Claude são cobradas com desconto por modelo, leituras e gravações de cache ao preço oficial cheio; confira os custos das chamadas através dos exemplos de faturamento por categoria."
headingIds: {"Quanto é cobrado por uma chamada":"section-1","Exemplo de cálculo":"section-2","Faturamento do prompt de sistema":"section-3","Saldo e moeda":"section-4","Como conferir descontos e custos":"section-5","Perguntas frequentes":"section-6"}
---
**Entradas e saídas do Claude são cobradas com o desconto do respectivo modelo; leitura e gravação de cache são cobradas ao preço oficial cheio, sem desconto.** O preço unitário e o desconto de cada modelo estão em [Modelos e preços](https://1zheai.com/en/pricing/). Para GPT, MiMo e modelos de geração de imagens, consulte suas respectivas unidades de faturamento e cotações; os exemplos de tokens desta página referem-se ao Claude.
## Quanto é cobrado por uma chamada
Cada chamada é cobrada separadamente por quatro categorias de tokens presentes no `usage` da resposta:
```text
费用 = ( 输入 token × 输入单价
+ 缓存写入 token × 缓存写单价
+ 缓存读取 token × 缓存读单价
+ 输出 token × 输出单价 ) ÷ 1,000,000
输入单价、输出单价 = 对应官方单价 × 该模型折扣
缓存读取单价、缓存写入单价 = 对应官方原价
```
As quatro categorias de tokens correspondem aos campos da resposta:
| Item de cobrança | Campo `usage` (nativo Anthropic) | Preço oficial relativo ao preço de entrada |
|---|---|---|
| Entrada | `input_tokens` | 1× |
| Gravação de cache | `cache_creation_input_tokens` | 1,25× (cache de 5 minutos), 2× (cache de 1 hora, `"ttl": "1h"`) |
| Leitura de cache | `cache_read_input_tokens` | 0,1× (Opus 5.5 e Sonnet 5.5: 0,05×; Fable 5.1: 0,025×) |
| Saída | `output_tokens` | Depende do modelo, veja a página de preços |
Os multiplicadores oficiais de cache provêm da documentação [Anthropic Prompt Caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching). Neste site, o cache é cobrado pelo preço oficial correspondente, sem aplicar o desconto de entrada/saída novamente.
Os tokens de gravação do cache de 1 hora são registrados separadamente em `cache_creation.ephemeral_1h_input_tokens` e cobrados a 2 vezes o preço oficial de entrada, sem aplicar o desconto de entrada/saída. O preço unitário de gravação de cache listado na página de preços refere-se ao cache de 5 minutos.
## Exemplo de cálculo
Os preços unitários abaixo são inteiros escolhidos aleatoriamente para demonstração e não correspondem a nenhum modelo específico; os preços unitários reais estão na página de preços.
Suponha que um modelo tenha os seguintes preços oficiais (por milhão de tokens): entrada $3, saída $15, gravação de cache $3,75, leitura de cache $0,30. O `usage` de uma requisição do Claude Code é:
```json
{
"input_tokens": 2000,
"cache_creation_input_tokens": 1500,
"cache_read_input_tokens": 30000,
"output_tokens": 800
}
```
Pelo preço oficial:
| Item | token | Preço unitário oficial | Custo oficial |
|---|---|---|---|
| Entrada | 2.000 | $3 | $0,006 |
| Gravação de cache | 1.500 | $3,75 | $0,005625 |
| Leitura de cache | 30.000 | $0,30 | $0,009 |
| Saída | 800 | $15 | $0,012 |
| Total | | | $0,032625 |
Suponha que, neste modelo de exemplo, entrada e saída tenham 20% do preço oficial (apenas para o exemplo, não representa o preço atual do modelo); então:
```text
输入费用 = $0.006 × 0.2 = $0.0012
输出费用 = $0.012 × 0.2 = $0.0024
缓存费用 = $0.005625 + $0.009 = $0.014625
合计 = $0.018225
```
Não é possível multiplicar o custo oficial total pelo desconto de entrada/saída, pois a parte de cache não tem desconto.
Se a mesma requisição não acertar o cache, esses 30.000 tokens serão cobrados pelo preço de entrada com desconto do modelo. Para saber se há economia, é preciso comparar considerando o desconto do modelo, o custo de gravação do cache e o número de leituras repetidas — não basta comparar apenas os preços oficiais. O método de configuração e verificação está em [Prompt Caching](/pt/docs/prompt-caching/).
## Faturamento do prompt de sistema
A API Claude provém de uma pool de contas de assinatura oficiais. Chamadas feitas pelo Claude Code não anexam conteúdo adicional. Outros clientes (SDK, curl e ferramentas de terceiros) anexam a cada requisição um prompt de sistema, cobrado como tokens de entrada: cerca de 350 tokens para Sonnet 4.6 e cerca de 500 tokens para a série 5.x. Essa parte é contabilizada junto com o conteúdo que você envia no `usage` da resposta, em `input_tokens`.
Teste real em 2026-10-15 enviando via curl a frase «Reply with just: ok»:
| Modelo | Contagem `count_tokens` | `input_tokens` real | Prompt de sistema anexado (aprox.) |
|---|---|---|---|
| Sonnet 4.6 | 19 | 370 | 350 tokens |
| Série 5.x | 18–19 | 510–530 | cerca de 500 tokens |
- `count_tokens` conta apenas o conteúdo que você envia, sem incluir esse prompt de sistema. Ao estimar custos com SDK, curl ou ferramentas de terceiros, some os valores da tabela acima; com o Claude Code não é necessário.
- Os tokens de entrada registrados nos logs de chamada já incluem essa parte; refaça o cálculo com a fórmula acima e o resultado deve coincidir com a cobrança nos logs.
- Quanto mais curta a requisição, maior a proporção dessa parte; em requisições com contexto longo, a proporção é muito pequena.
## Saldo e moeda
- As cobranças são calculadas pelo algoritmo em dólares acima e debitadas do saldo da sua conta. O saldo é contabilizado em dólares.
- O valor principal recarregado é creditado em dólares; a taxa de processamento de pagamento é cobrada separadamente e não é reembolsável; as formas de pagamento disponíveis e os limites de valor regem-se pela página de pedido da carteira.
## Como conferir descontos e custos
Primeiro verifique o desconto de entrada/saída do modelo e, em seguida, calcule separadamente entrada, saída, leitura de cache e gravação de cache. Cada cobrança pode ser recalculada no [log de chamadas](/pt/docs/usage-logs/) com o preço unitário correspondente.
## Perguntas frequentes
A causa mais comum é o cache não ter acertado: intervalo longo demais entre duas requisições (cache padrão de 5 minutos), alteração na primeira metade do contexto ou troca de modelo. Abra o log de chamadas e compare os tokens de leitura de cache das duas requisições para identificar.
Não. Leitura e gravação de cache são cobradas ao preço oficial cheio; entrada e saída são cobradas com o desconto de cada modelo.
Chamadas feitas pelo Claude Code não anexam conteúdo adicional. Outros clientes (SDK, curl e ferramentas de terceiros) anexam a cada requisição um prompt de sistema, cobrado como tokens de entrada: cerca de 350 tokens para Sonnet 4.6 e cerca de 500 tokens para a série 5.x. Os dados de teste estão em [Faturamento do prompt de sistema](#section-3).
Localize essa cobrança no log de chamadas, substitua os quatro tipos de tokens e os preços unitários da página de preços na fórmula acima; o resultado deve coincidir com a cobrança nos logs. Se não coincidir, envie-nos a hora e o modelo desse registro de log.
---
# Registros de Uso e Conciliação
Source: https://1zheai.com/pt/docs/usage-logs/
Markdown: https://1zheai.com/pt/docs/usage-logs.md
---
title: "Registros de Uso e Conciliação"
description: "Veja o modelo de cada chamada, os quatro tipos de token e os valores cobrados nos registros de chamadas do console da 1折AI, e recalcule uma fórmula de cobrança usando a fórmula."
headingIds: {"Onde Visualizar":"section-1","O Que Cada Registro de Log Contém":"section-2","Conciliar uma Fatura":"section-3","Usando os Logs para Ver a Eficiência do Cache":"section-4","Não Corresponde às Suas Próprias Estatísticas":"section-5"}
---
Cada chamada deixa um registro de detalhes nos registros de chamadas. Esta página explica como visualizá-los e como conciliar.
## Onde Visualizar
[Console](https://1zheai.com/console?lng=pt) menu esquerdo → "Registros de Chamadas" (URL `https://1zheai.com/usage-logs`), o título da página é "Registros Gerais".
No topo, você pode filtrar por intervalo de tempo; após clicar em "Expandir", também pode filtrar por nome do modelo, nome da chave API ("Nome do Token"), ID da requisição e tipo de registro. Após filtrar, clique em "Pesquisar"; "Exportar" baixa os resultados atualmente filtrados, facilitando a conciliação em uma planilha.
## O Que Cada Registro de Log Contém
| Coluna | Conteúdo |
|---|---|
| Hora | Quando a requisição ocorreu |
| Token | O nome da chave API usada nesta chamada |
| Modelo | O ID real do modelo chamado |
| Stream | "Stream" ou "Non-stream", mais a velocidade de saída (t/s) |
| Token | A primeira linha é "Input / Output" (entrada / saída) de tokens; quando há cache, aparece uma linha adicional abaixo: após "Cache↓" estão os tokens de leitura de cache, após "↑" estão os tokens de escrita de cache |
| Custo | O valor em USD cobrado por esta chamada |
| Duração | Duração total; requisições em streaming também mostram o tempo até o primeiro caractere |
| Detalhes | Preço unitário e outros detalhes desta chamada |
Requisições rejeitadas pelo gateway (chave API inválida, saldo insuficiente, nome de modelo incorreto, etc.) não são cobradas. Requisições em que o upstream retorna um erro têm custo 0. Uma requisição em streaming que se desconecta no meio não é totalmente gratuita, veja [Saída em Streaming](/pt/docs/streaming/).
## Conciliar uma Fatura
Encontre a entrada a verificar pela hora e pelo modelo, e anote os quatro números na coluna Token: entrada (input), saída (output), leitura de cache (Cache↓) e escrita de cache (↑).
Na [Página de Preços](https://1zheai.com/en/pricing/) encontre os preços unitários de entrada, saída, leitura de cache e escrita de cache daquele modelo (entrada e saída já estão calculados com o desconto do modelo; o cache está no preço original oficial).
```text
扣费 = ( 输入 × 输入单价
+ 缓存写入 × 缓存写单价
+ 缓存读取 × 缓存读单价
+ 输出 × 输出单价 ) ÷ 1,000,000
```
O resultado deve corresponder ao valor cobrado no registro. O arredondamento pode causar uma diferença no último dígito.
Se não corresponder, nos envie a hora, o modelo e uma captura de tela deste registro de log.
## Usando os Logs para Ver a Eficiência do Cache
Em ferramentas como o Claude Code, a maior parte da entrada deve cair na coluna "leitura de cache". Se várias entradas consecutivas mostrarem grandes quantidades de "escrita de cache" com muito pouco "leitura de cache", significa que o cache não está sendo reutilizado; para causas e correções, veja [Cache de Prompt](/pt/docs/prompt-caching/).
Uma taxa de acerto aproximada: leitura de cache ÷ (entrada + escrita de cache + leitura de cache).
## Não Corresponde às Suas Próprias Estatísticas
- O Claude Code usa modelos de nível Haiku para algumas tarefas em segundo plano, então modelos que você nunca selecionou ativamente aparecerão nos registros. Veja o mapeamento de modelos na [Integração com o Claude Code](/pt/docs/quickstart-claude-code/).
- Os tokens de entrada no registro são algumas centenas a mais do que o conteúdo que você enviou: ao chamar via SDK, curl ou ferramentas de terceiros, cada requisição inclui um prompt de sistema que é cobrado como entrada (o Claude Code não inclui um), veja [Cobrança do Prompt de Sistema](/pt/docs/pricing-explained/#section-3).
- Uma única "conversa" em uma ferramenta pode corresponder a muitas chamadas de API (uma rodada por chamada de ferramenta); os registros são gravados por chamada de API.
---
# Recarga, reembolso e faturas
Source: https://1zheai.com/pt/docs/billing/
Markdown: https://1zheai.com/pt/docs/billing.md
---
title: "Recarga, reembolso e faturas"
description: "Como recarregar na 1zheai, valor mínimo, formas de pagamento suportadas, regra de reembolso de saldo não utilizado em 7 dias, e quais faturas cada forma de pagamento pode emitir."
headingIds: {"Recarga":"section-1","Reembolso de saldo API":"section-2","Faturas":"section-3","Perguntas frequentes":"section-4"}
---
Esta página explica o saldo da conta API: primeiro recarregue, e as chamadas são debitadas conforme o uso. Produtos de conta de IA são comprados de acordo com as especificações do produto; o pós-venda consulte [a loja de contas ](https://1zheai.com/en/store/), que não se aplica às regras de reembolso de saldo API desta página.
As regras de reembolso de saldo deste artigo se aplicam à recarga da API de modelos. Para pedidos de contas prontas, recarga por terceiros e cartões-presente, consulte [regras de negociação e pós-venda da loja ](/pt/docs/store-rules/), que não aplicam diretamente a regra de 7 dias da API.
## Recarga
| Item | Descrição |
|---|---|
| Limite de valor | Conforme a página de pedido da carteira |
| Formas de pagamento | WeChat Pay, Alipay, Stripe (cartão de crédito/débito), USDT |
| Acesso | [Console ](https://1zheai.com/console?lng=pt) menu lateral "Carteira" → "Adicionar fundos" |
| Como é cobrado | Claude entrada/saída com desconto do modelo, cache pelo preço oficial; outros modelos conforme a tabela correspondente, veja [preços e cobrança ](/pt/docs/pricing-explained/) |
O principal da recarga é contabilizado em dólares; a taxa de processamento de pagamento é cobrada separadamente e não é reembolsável.
## Reembolso de saldo API
**Dentro de 7 dias após a recarga, é possível solicitar o reembolso do principal não utilizado pelo mesmo meio de pagamento. A parte já consumida e a taxa de processamento de pagamento não são reembolsáveis.**
Consulte nos logs de chamada o consumo após esta recarga; o valor de referência é o principal não utilizado reembolsável na carteira; a taxa de processamento de pagamento não é contabilizada no principal reembolsável.
Envie um e-mail para support@1zheai.com, indicando a conta, o horário da recarga e a forma de pagamento.
Na primeira vez, recarregue primeiro o valor permitido pela carteira, depois execute as verificações de [verificar modelos e uso ](/pt/docs/verify-model/), e use em suas tarefas reais por alguns dias. Dentro de 7 dias é possível solicitar o reembolso do principal não utilizado pelo mesmo meio de pagamento; a taxa de processamento de pagamento não é reembolsável.
## Faturas
| Forma de pagamento | O que pode ser emitido |
|---|---|
| WeChat Pay / Alipay | Fatura fiscal pode ser emitida, cobrando 6% do valor pago |
| Stripe (cartão de crédito/débito) | Fatura Stripe (em inglês) |
| USDT | Não fornece fatura |
Para emissão de fatura, compras corporativas e transferência bancária empresarial, envie e-mail para support@1zheai.com.
## Perguntas frequentes
O limite de valor segue a página de pedido da carteira. Antes de pagar, confirme o principal da recarga, a taxa de processamento de pagamento e o valor creditado.
Quando o saldo se esgota, a requisição retorna HTTP 403, e o corpo da resposta contém `Insufficient user quota` (`/v1/messages` em `error.type` é `billing_error`, em `/v1/chat/completions` é `insufficient_quota`). Requisições negadas não são cobradas; após a recarga ser creditada, é possível continuar usando.
Chamadas via Claude Code não anexam conteúdo adicional. Outros clientes (SDK, curl e ferramentas de terceiros) anexam a cada requisição um prompt de sistema, cobrado como tokens de entrada: Sonnet 4.6 cerca de 350 tokens, série 5.x cerca de 500 tokens. Explicação e dados medidos em [cobrança do prompt de sistema ](/pt/docs/pricing-explained/#section-3).
A regra de reemboldo de saldo API é: principal não utilizado dentro de 7 dias após a recarga; a parte já consumida e a taxa de processamento de pagamento não são reembolsáveis. Para situações além de 7 dias, entre em contato conosco separadamente para explicar.
---
# Verificar modelo e uso
Source: https://1zheai.com/pt/docs/verify-model/
Markdown: https://1zheai.com/pt/docs/verify-model.md
---
title: "Verificar modelo e uso"
description: "Use o log de chamadas e cinco verificações para conferir o modelo, o uso de tokens e o custo de cada chamada."
headingIds: {"Log de chamadas":"section-1","Cinco verificações":"section-2","Executar as quatro primeiras com um script":"section-3","Blocos thinking":"section-4","Ao encontrar inconsistências":"section-5","Perguntas frequentes":"section-6"}
---
## Log de chamadas
Cada chamada é registrada no [log de chamadas](/pt/docs/usage-logs/) do console, listando o modelo, o uso de tokens de entrada, saída, leitura de cache e escrita de cache, além do custo.
## Cinco verificações
As verificações abaixo comparam o formato público da API da Anthropic, para detectar diferenças nos campos e no formato retornados.
| Verificação | Resultado esperado | O que observar |
|---|---|---|
| 1. Campo `model` retornado | Coincide com o ID do modelo solicitado | Retorna outro nome de modelo, ou o campo está ausente |
| 2. Leitura de cache | A mesma requisição que atende às condições de cache é enviada duas vezes dentro da validade do cache; na segunda, `cache_read_input_tokens` é maior que 0 | Sempre 0, ou `usage` não contém campos de cache |
| 3. ID de chamada de ferramenta | O `id` do bloco `tool_use` começa com `toolu_` | Outro formato, ou o modelo não chama a ferramenta conforme solicitado |
| 4. Ordem dos eventos de streaming | Aparecem, nesta ordem, `message_start`, `content_block_start`, `content_block_delta`, `message_delta` e `message_stop` | Apenas blocos `data:` no formato OpenAI, ou eventos ausentes/desordenados |
| 5. Comparação com tarefa real | Use uma tarefa fixa e compare os resultados com a API oficial ou outra fonte confiável | Resultados claramente piores, recusas anormais ou cortes frequentes |
Essas verificações só detectam diferenças de campos e formato; não confirmam por si só o modelo realmente usado. O campo `model` pode ser reescrito e o formato pode ser imitado.
## Executar as quatro primeiras com um script
É necessário `bash`, `curl` e `jq`. O script faz cinco pequenas chamadas, uma das quais grava cerca de 18 mil tokens em cache, cobrada pelo preço normal.
```bash title="verify.sh"
#!/usr/bin/env bash
# 用法：ONEZHE_API_KEY=sk-你的API密钥 bash verify.sh [模型ID]
set -euo pipefail
BASE="https://1zheai.com"
MODEL="${1:-claude-sonnet-5-5}"
H=(-H "x-api-key: $ONEZHE_API_KEY" -H "anthropic-version: 2023-06-01" -H "content-type: application/json")
echo "== 1. model 字段"
curl -s "$BASE/v1/messages" "${H[@]}" \
-d "$(jq -n --arg m "$MODEL" '{model:$m,max_tokens:16,messages:[{role:"user",content:"ping"}]}')" \
| jq 'if .error then .error else {id, model, usage} end'
echo "== 2. 缓存：同一请求发两次，看第二次的 cache_read_input_tokens"
LONG=$(printf '这是一段用来测试缓存的固定文本，内容不重要，长度够就行。%.0s' {1..600})
BODY=$(jq -n --arg m "$MODEL" --arg t "$LONG" '{model:$m,max_tokens:16,
system:[{type:"text",text:$t,cache_control:{type:"ephemeral"}}],
messages:[{role:"user",content:"ping"}]}')
for i in 1 2; do
curl -s "$BASE/v1/messages" "${H[@]}" -d "$BODY" | jq -c 'if .error then .error else .usage end'
done
echo "== 3. 工具调用 ID"
curl -s "$BASE/v1/messages" "${H[@]}" \
-d "$(jq -n --arg m "$MODEL" '{model:$m,max_tokens:256,
tools:[{name:"get_weather",description:"查询城市天气",
input_schema:{type:"object",properties:{city:{type:"string"}},required:["city"]}}],
tool_choice:{type:"auto"},
messages:[{role:"user",content:"北京今天天气怎么样"}]}')" \
| jq -r 'if .error then .error.message else (.content[]? | select(.type=="tool_use") | .id) end'
echo "== 4. 流式事件序列"
curl -sN "$BASE/v1/messages" "${H[@]}" \
-d "$(jq -n --arg m "$MODEL" '{model:$m,max_tokens:32,stream:true,messages:[{role:"user",content:"数到三"}]}')" \
| grep '^event:' | uniq
```
O item 3 usa `tool_choice: auto`. Modelos 5.x, como Sonnet 5.5, não suportam forçar o uso de ferramentas (`{"type":"tool"}` ou `{"type":"any"}`) e retornam 400 `does not support forced tool_choice`.
A saída medida em 2026-10-15 com `claude-sonnet-5-5` é a abaixo (o item 1 manteve apenas os campos essenciais):
```text
== 1. model 字段
{
"id": "msg_011Cg3Esh8zeEdLeXAPVALKe",
"model": "claude-sonnet-5-5",
"usage": {
"input_tokens": 518,
"cache_creation_input_tokens": 0,
"cache_read_input_tokens": 0,
"output_tokens": 12,
...
}
}
== 2. 缓存：同一请求发两次，看第二次的 cache_read_input_tokens
{"input_tokens":23,"cache_creation_input_tokens":17920,"cache_read_input_tokens":0,"cache_creation":{"ephemeral_5m_input_tokens":17920,"ephemeral_1h_input_tokens":0},"output_tokens":4,"output_tokens_details":{"thinking_tokens":0},"service_tier":"standard","inference_geo":"global"}
{"input_tokens":23,"cache_creation_input_tokens":0,"cache_read_input_tokens":17920,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":0},"output_tokens":4,"output_tokens_details":{"thinking_tokens":0},"service_tier":"standard","inference_geo":"global"}
== 3. 工具调用 ID
toolu_01UPsdyKX8M9fJTTkDoSKHXA
== 4. 流式事件序列
event: message_start
event: content_block_start
event: ping
event: content_block_delta
event: content_block_stop
event: message_delta
event: message_stop
```
O evento `ping` pode ou não aparecer, e sua posição não é fixa; isso não afeta a avaliação.
## Blocos thinking
Com o thinking habilitado, o bloco `thinking` retornado traz o campo `signature`, o que também pode servir como verificação de formato. A escrita nos modelos 5.x difere da dos 4.x; medido em 2026-10-15:
| Modelo | Parâmetro `thinking` | Resultado |
|---|---|---|
| `claude-sonnet-4-6` | `{"type":"enabled","budget_tokens":1024}` | Retorna o bloco `thinking`, com texto de pensamento e `signature` |
| `claude-sonnet-5` | `{"type":"enabled","budget_tokens":1024}` ou `{"type":"adaptive"}` | Ambos funcionam |
| `claude-sonnet-5-5` | `{"type":"adaptive"}` | Funciona; enviar `enabled` retorna 400, informando que só é suportado adaptive |
Nos modelos 5.x, o bloco `thinking` contém por padrão apenas `signature`, com o texto de pensamento como string vazia. Para ver o resumo do pensamento, adicione `"display": "summarized"`:
```json
"thinking": {"type": "adaptive", "display": "summarized"}
```
Ao usar sites de detecção de terceiros, recomenda-se criar uma chave de API dedicada e excluí-la após o teste.
## Ao encontrar inconsistências
Envie um e-mail para support@1zheai.com com o horário da requisição, o ID do modelo, o conteúdo completo da resposta (sem a chave de API) e o item de verificação correspondente. O request id presente na resposta ou na mensagem de erro ajuda a localizar essa chamada.
## Perguntas frequentes
Não é confiável. A apresentação do modelo é influenciada pelo prompt de sistema e, em alguns prompts, ele responde errado a própria versão. Conferir os campos e o formato dos eventos retornados é mais útil.
O Claude Code usa o modelo Haiku para parte das tarefas em segundo plano, e registros correspondentes aparecem no log de chamadas. É possível especificar o modelo usado por essas tarefas com a variável de ambiente `ANTHROPIC_DEFAULT_HAIKU_MODEL`; veja [Integração com o Claude Code](/pt/docs/quickstart-claude-code/). Se isso ocorrer sem o uso do Claude Code, envie o horário da requisição para support@1zheai.com.
---
# Códigos de erro e solução de problemas
Source: https://1zheai.com/pt/docs/troubleshooting/
Markdown: https://1zheai.com/pt/docs/troubleshooting.md
---
title: "Códigos de erro e solução de problemas"
description: "Causas e soluções ao encontrar 401, 404, 429, 529, 5xx, timeouts e erros do Claude Code ao chamar a 1折AI."
headingIds: {"Ordem de verificação":"section-1","Tabela rápida de códigos de erro":"section-2","Respostas reais testadas":"section-3","Solução de problemas por sintoma":"section-4","401 / Invalid token":"section-5","404 / Invalid URL":"section-6","403 / error code: 1010":"section-7","429 Muitas requisições":"section-8","529 / overloaded_error":"section-9","Timeout, desconexão no meio do streaming":"section-10","Claude Code: entra direto na tela de login":"section-11","Claude Code: Extra inputs are not permitted / context_management retorna 400":"section-12","Saldo suficiente, mas as chamadas falham":"section-13","Retentativas limitadas e modelo de feedback":"section-14","Ainda não resolvido":"section-15"}
---
Percorra a lista abaixo na ordem indicada; a maioria dos problemas é encontrada nos três primeiros passos.
## Ordem de verificação
1. **Endereço**: ferramentas da série Anthropic devem usar `https://1zheai.com`, ferramentas da série OpenAI devem usar `https://1zheai.com/v1`. Veja [Base URL e autenticação](/pt/docs/base-url/).
2. **Chave de API (API key)**: está completa (sem espaços ou quebras de linha extras), foi excluída ou está preenchida no campo correto.
3. **Saldo**: o saldo no console é suficiente.
4. **ID do modelo**: está idêntico ao dos [modelos suportados](/pt/docs/models/).
5. **Rede**: desative o proxy e tente conectar diretamente novamente.
6. **Ainda sem solução**: gere uma reprodução mínima com curl (veja abaixo) e nos envie a resposta e o tempo.
```bash title="最小复现"
curl -i https://1zheai.com/v1/messages \
-H "x-api-key: sk-你的Key" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{"model":"claude-sonnet-5-5","max_tokens":16,"messages":[{"role":"user","content":"ping"}]}'
```
`-i` imprime o código de status junto com os cabeçalhos de resposta, o que é muito útil na solução de problemas.
## Tabela rápida de códigos de erro
| Código de status | Causas comuns | O que fazer |
|---|---|---|
| 400 | Problema no corpo da requisição: nome de parâmetro incorreto, tipo de campo incorreto, `max_tokens` acima do limite do modelo, campo beta não reconhecido pelo upstream | Verifique o campo indicado em `message`; para o caso do Claude Code, veja "Extra inputs are not permitted" abaixo |
| 401 | Chave de API inválida, excluída, desabilitada, expirada, cota própria esgotada, ou ausente/colocada no cabeçalho errado | Todas as respostas são `Invalid token`; verifique item por item; no uso nativo Anthropic, use `x-api-key` ou `Authorization: Bearer` |
| 403 | Saldo da conta insuficiente (`billing_error` / `insufficient_quota`); esta chave de API não tem acesso ao modelo; o IP da requisição não está na lista branca desta chave de API (ambos retornam `permission_error`) | Recarregue ou edite as restrições de modelo e a lista branca de IP desta chave de API na página "Chaves de API" |
| 404 | Caminho incorreto, ou modelo inexistente / indisponível no momento | `Invalid URL` verifique o endereço; `not_found_error` / `model_not_found` verifique o ID do modelo e a lista de disponibilidade |
| 413 | Corpo da requisição muito grande | Reduza o conteúdo enviado de uma vez; divida arquivos grandes em partes |
| 429 | Limitação temporária de taxa do upstream. Atualmente não aplicamos limites de taxa às chaves de API | Tente novamente mais tarde; em tarefas em lote, use backoff exponencial |
| 503 | O modelo existe, mas não há serviço upstream saudável disponível no momento, ou falha temporária do serviço | Tente novamente mais tarde; em falhas persistentes, entre em contato com o suporte informando o ID da requisição |
| 500 / 502 | Falha temporária do gateway ou do upstream | Tente novamente mais tarde; em falhas persistentes, envie e-mail para support@1zheai.com |
| 504 | Timeout da requisição | Use streaming para saídas longas; aumente o timeout do cliente |
| 529 | Sobrecarga do upstream Anthropic (`overloaded_error`) | Aguarde alguns segundos e tente novamente, ou troque temporariamente de modelo |
O significado completo dos tipos de erro oficiais da Anthropic (`invalid_request_error`, `authentication_error`, `rate_limit_error`, `overloaded_error`, etc.) está na [documentação oficial de Errors](https://platform.claude.com/docs/en/api/errors).
Erros retornados pelo upstream são repassados com o código de status e `message` inalterados, e `message` recebe o request id desta requisição no final. Ao usar `/v1/messages`, a estrutura externa é a `{"type":"error","error":{...}}` oficial, e `error.type` é preenchido com o tipo oficial conforme o código de status; ao usar `/v1/chat/completions`, é a estrutura `{"error":{...}}` da OpenAI.
## Respostas reais testadas
Abaixo estão respostas reais testadas em 2026-10-15 para `/v1/messages`. Ao usar `/v1/chat/completions`, o conteúdo é o mesmo, sem `"type":"error"` na camada externa, e `error` contém um campo adicional `code`.
```json title="401 API 密钥无效、禁用、过期或额度用完"
{"error":{"message":"Invalid token (request id: 202610150244355244812608268d9d6T1pY7T84)","type":"authentication_error"},"type":"error"}
```
```json title="403 账户余额不足"
{"error":{"type":"billing_error","message":"Insufficient user quota, remaining quota: ＄0.000000 (request id: 202610150244418753787808268d9d67YNhvwXd)"},"type":"error"}
```
```json title="403 API 密钥没开通该模型"
{"error":{"message":"This token has no access to model claude-sonnet-4-6 (request id: 202610150244377127013108268d9d6yCiFOxJA)","type":"permission_error"},"type":"error"}
```
```json title="403 IP 不在白名单"
{"error":{"message":"Your IP address is not on this token's allowlist (request id: 202610150244409011371208268d9d63tJvd5GD)","type":"permission_error"},"type":"error"}
```
```json title="400 上游参数错误"
{"error":{"type":"invalid_request_error","message":"messages: Unexpected role \"robot\". Allowed roles are \"user\", \"assistant\" or \"system\" (request id: 202610150245008404167198268d9d6sajV9TX3)"},"type":"error"}
```
```json title="404 路径不存在"
{"error":{"message":"Invalid URL (POST /v1/nonexistent)","type":"invalid_request_error","param":"","code":""}}
```
A explicação do 404 quando o modelo não existe ou está indisponível está em [modelos suportados](/pt/docs/models/). O request id na resposta corresponde a esta requisição; inclua-o ao reportar problemas.
## Solução de problemas por sintoma
### 401 / Invalid token
- A chave de API foi copiada com espaços ou quebras de linha extras; copie novamente.
- A chave de API foi excluída ou desabilitada no console, ou expirou, ou a cota própria foi esgotada. Em todos esses casos, a resposta é a mesma: `Invalid token`.
- No Claude Code, `ANTHROPIC_API_KEY` e `ANTHROPIC_AUTH_TOKEN` estão definidos ao mesmo tempo e um deles é um valor antigo: mantenha apenas um; recomenda-se `ANTHROPIC_AUTH_TOKEN`.
- O `env` do `settings.json` sobrescreve variáveis de mesmo nome exportadas no terminal; se alterar a variável do terminal não tiver efeito, verifique `~/.claude/settings.json`.
### 404 / Invalid URL
Verifique primeiro o tipo de erro: `not_found_error` ou `model_not_found` exige verificar [o ID do modelo e a lista de disponibilidade](/pt/docs/models/). Já `Invalid URL` exige verificar `/v1`: OpenAI SDK, Cursor e Cline (OpenAI Compatible) devem preencher até `https://1zheai.com/v1`; Claude Code e Anthropic SDK devem preencher apenas `https://1zheai.com`; preencher `/v1` resultará em `/v1/v1/messages`.
### 403 / error code: 1010
Se a resposta contiver apenas a linha `error code: 1010` e nenhum JSON, a requisição foi bloqueada antes de chegar ao gateway. É conhecido que enviar requisições diretamente com a biblioteca padrão do Python `urllib` causa isso (o User-Agent padrão dela é `Python-urllib/3.x`). Adicione um `User-Agent` próprio nos cabeçalhos da requisição, ou use o SDK oficial, `requests`, `httpx`.
### 429 Muitas requisições
Atualmente não aplicamos limites de taxa às chaves de API. Ao receber 429, normalmente é alta carga no upstream; tente novamente mais tarde. Para tarefas em lote, recomenda-se backoff exponencial: após uma falha, aguarde um período antes de tentar novamente, dobrando o tempo de espera a cada vez, e controle a concorrência com uma fila própria.
### 529 / overloaded_error
O upstream Anthropic está temporariamente sobrecarregado; não tem relação com sua chave de API ou saldo. Aguarde alguns segundos e tente novamente; se estiver com pressa, troque temporariamente para outro modelo da mesma série.
### Timeout, desconexão no meio do streaming
- Para respostas longas, use sempre streaming (`"stream": true`), que é menos propenso a ser cortado por dispositivos de rede intermediários.
- No Claude Code, use `API_TIMEOUT_MS` para aumentar o timeout; o padrão é 600000 (10 minutos).
- Se estiver usando proxy, desative-o e tente uma vez; muitas desconexões de stream vêm de nós de proxy.
### Claude Code: entra direto na tela de login
Isso significa que o Claude Code não encontrou sua chave de API. Execute `/status` no Claude Code e verifique as linhas de base URL e origem das credenciais; se estiverem vazias, volte para [integração com Claude Code](/pt/docs/quickstart-claude-code/) e verifique as variáveis de ambiente ou `settings.json`.
### Claude Code: Extra inputs are not permitted / context_management retorna 400
O Claude Code envia alguns campos beta experimentais nas requisições; um upstream estrito que não os reconhece retornará 400. Defina as variáveis de ambiente abaixo para desativá-las (da documentação oficial de LLM gateway do Claude Code):
```bash
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
```
### Saldo suficiente, mas as chamadas falham
- Se apenas um modelo falhar, pode ser que ele esteja temporariamente indisponível, o ID esteja escrito incorretamente, ou esta chave de API tenha restrição de modelo (403 `This token has no access to model …`).
- Se todos falharem com 401, verifique se esta chave de API tem limite de cota definido e já esgotado, ou se expirou. Isso pode ser visto nas colunas "Cota ($)" e "Expira em" da página "Chaves de API".
- Para outros casos, consulte a tabela de códigos de erro acima.
## Retentativas limitadas e modelo de feedback
Não use loops infinitos para mascarar erros de configuração. Para timeouts do SDK, número de retentativas automáticas e backoff, consulte [timeout e retentativas](/pt/docs/retries/).
Ao contatar o suporte, pode copiar o modelo abaixo, removendo chaves, cabeçalhos de autenticação e conteúdo pessoal antes de enviar:
```text
发生时间与时区：
客户端及版本：
请求方法与完整路径：
模型 ID：
HTTP 状态码：
request id（如有）：
脱敏后的错误正文：
最小请求能否复现：
是否使用代理 / 是否仅某个模型失败：
```
## Ainda não resolvido
Envie um e-mail para support@1zheai.com com o horário, o ID do modelo, a ferramenta e a versão usadas, e a saída completa de `curl -i` (remova a chave de API).
---
# IA e Automação
Source: https://1zheai.com/pt/docs/ai/
Markdown: https://1zheai.com/pt/docs/ai.md
---
title: "IA e Automação"
description: "Permita que assistentes de IA leiam a documentação sob demanda, entendendo os pontos de leitura para máquinas existentes e o status do MCP de documentação."
headingIds: {"Pontos de leitura para máquinas disponíveis":"section-1","Tarefas de integração para a IA":"section-2","Status do MCP de documentação":"section-3"}
---
Você pode pedir a um assistente de IA que leia primeiro a documentação deste site e depois ajude a configurar ferramentas ou escrever código de chamada. Leitura de documentação comum e chamadas à API do modelo são coisas diferentes: ler a documentação pública não exige fornecer uma chave de API.
## Pontos de leitura para máquinas disponíveis
| Ponto de acesso | Uso |
| --- | --- |
| [llms.txt](/pt/docs/llms.txt) | Descobrir a documentação por seção e escolher as páginas que precisam ser lidas |
| [Lista de documentos](/pt/docs/docs-manifest.json) | Obter títulos das páginas, seção de origem, endereços da web e do Markdown |
| [Texto completo da documentação](/pt/docs/llms-full.txt) | Ler todas as páginas de uma vez; o conteúdo é longo, prefira ler página a página |
| [Markdown da página inicial](/pt/docs/index.md) | Ler o conteúdo de origem do documento sem a navegação do site |
Cada artigo possui um endereço Markdown correspondente, por exemplo `/pt/docs/quickstart-claude-code/` corresponde a `/pt/docs/quickstart-claude-code.md`. Também é possível usar “Copiar esta página” no topo da página. O Markdown pode conter marcações de componentes de documentação, como cartões.
## Tarefas de integração para a IA
Copie as instruções da tarefa e peça ao assistente que verifique primeiro o escopo de suporte e depois configure e valide. Escolha o protocolo, o endereço e a configuração do modelo de acordo com a ferramenta.
## Status do MCP de documentação
Este site ainda não oferece um servidor MCP de documentação conectável. Use primeiro os endereços de documentação acima ou copie o conteúdo da página para o assistente; não trate a Base URL da API do modelo como um endereço MCP.
A finalidade do MCP de documentação é pesquisar e ler materiais públicos. Operações como consultas de conta e gerenciamento de chaves pertencem a outra categoria de capacidades e não podem ser obtidas pelos pontos de acesso da documentação pública.
---
# Deixe a IA ajudar você a integrar
Source: https://1zheai.com/pt/docs/agent-workflow/
Markdown: https://1zheai.com/pt/docs/agent-workflow.md
---
title: "Deixe a IA ajudar você a integrar"
description: "Instruções de tarefa copiáveis que ajudam a IA a ler a documentação primeiro, verificar as restrições e depois concluir a configuração e a validação."
headingIds: {"Copiar instruções da tarefa":"section-1","Verificar se a integração foi concluída":"section-2"}
---
## Copiar instruções da tarefa
Forneça as instruções abaixo a um assistente de IA capaz de ler páginas da web e inclua o nome da ferramenta e o sistema operacional. Se o assistente não tiver acesso à internet, primeiro obtenha o conteúdo do artigo correspondente pela [entrada de leitura automática](/pt/docs/ai/).
```text
请帮助我将现有工具或应用接入 1折AI。
目标工具与版本：[填写]
操作系统或编程语言：[填写]
先读取 https://1zheai.com/pt/docs/llms.txt，找到目标工具或 SDK 的文档。
再读取该页 Markdown，以及 API 参考和模型说明。
要求：
1. 先说明当前支持范围和工具配置要求。
2. 根据目标工具确定 Base URL，不要统一添加或删除 /v1。
3. 模型 ID 以当前文档和密钥可用模型列表为准，不要猜测。
4. 查看现有配置，只修改必要字段，保留其他供应商配置。
5. 使用环境变量或工具提供的凭据存储方式；不要把密钥写入源码、
对话、日志或提交记录。需要密钥时，让我在本地安全配置。
6. 执行会产生费用的测试前，说明测试内容并取得我的同意。
7. 用一次最小请求验证，再提示我在调用日志里核对记录。
8. 如果验证失败，保留脱敏的状态码与请求 ID，按排错文档处理；
不要用反复重试掩盖配置问题。
9. 最后说明修改位置、验证结果、剩余限制及恢复原配置的方法。
```
## Verificar se a integração foi concluída
Concluir a configuração não significa concluir a integração. É necessário confirmar simultaneamente que a ferramenta retorna normalmente, que o modelo efetivamente utilizado corresponde ao esperado e que é possível encontrar o registro correspondente nos [logs de chamada](/pt/docs/usage-logs/).
Esta página é uma instrução de tarefa copiável, não um Agent Skill ou serviço MCP já instalado. Qualquer assistente ainda precisa possuir as capacidades adequadas de ler documentação e manipular configurações locais.
---