# 1折AI · Full documentation
# 1ZheAI Documentation
Source: https://1zheai.com/en/docs/
Markdown: https://1zheai.com/en/docs/index.md
---
title: "1ZheAI Documentation"
description: "Entry points for model API, ready-to-use accounts, and subscription top-up services, including purchase notes, order, and after-sales rules."
headingIds: {"Model API Integration":"section-1","What Do You Want to Do":"section-2","Reference and Support":"section-3","Most Common Questions Before Use":"section-4","Developer Quick Reference":"section-5"}
---
Start with what you need: connect a model API, buy an AI account, or activate a subscription on an existing account.
Confirm the platform, subscription tier, delivered content, and first-login notes.Check account conditions, required materials, and the activation process.Confirm region, validity period, redemption method, and applicable accounts.Understand cancellation, delivery issues, bans, and refund rules.
## Model API Integration
1折AI provides Claude and OpenAI / GPT APIs, supporting Anthropic Messages, OpenAI Responses, and Chat Completions. Common endpoints include Anthropic's native `/v1/messages` and OpenAI-compatible `/v1/chat/completions`. The code and tools you already have generally only need two changes: the Base URL and the API key.
```text
Anthropic Base URL https://1zheai.com
OpenAI Base URL https://1zheai.com/v1
API Key sk-...（在控制台创建）
```
Claude input and output are billed at each model's discounted rate; cache reads and cache writes are billed at the official original price with no discount. Prices and billing units for GPT, MiMo, and image generation models are listed in [Models and Pricing](https://1zheai.com/en/pricing/).
Claude, GPT, MiMo, and image generation models are live; the full list is in [Supported Models](/en/docs/models/).
## What Do You Want to Do
Claude Code, Codex CLI, Cursor, Cline, Cherry Studio, and CC Switch. Check the supported scope first, then configure step by step.Start with the Anthropic SDK, OpenAI SDK, or curl, then learn about streaming output.Machine-readable documentation, a page inventory, and copyable AI integration task instructions.Register, create an API key, and complete your first request.
## Reference and Support
Look up endpoints, protocols, examples, and compatibility scope.View costs, call records, and troubleshooting paths.
## Most Common Questions Before Use
Check returned fields and usage; these checks alone cannot prove the model's origin.
How to enable caching, how to see hit rates, and how much cheaper hits are.
What 401, 404, 429, and 5xx each mean.
Payment methods, 7-day refund, and invoice rules.
## Developer Quick Reference
| Your Task | View Directly |
| --- | --- |
| Writing code for the first time | [Complete runnable examples](/en/docs/code-examples/) |
| Switching from another platform | [Migration guide](/en/docs/migration/) |
| Looking up models and protocols | [Model lookup](/en/docs/api-models/) · [API reference](/en/docs/api-reference/) |
| Handling timeouts and rate limits | [Timeouts and retries](/en/docs/retries/) |
| Finding common questions | [Integration FAQ](/en/docs/faq/) |
---
# Quick Start
Source: https://1zheai.com/en/docs/quickstart/
Markdown: https://1zheai.com/en/docs/quickstart.md
---
title: "Quick Start"
description: "Create a 1zheai API key, make your first Claude / GPT call with curl or an SDK, then connect it to your favorite clients."
headingIds: {"You Can Also Start with GPT":"section-1","Next Steps":"section-2"}
---
Goal: get an API key within 5 minutes and complete your first Claude or GPT request.
Open [1zheai.com/register](https://1zheai.com/register?lng=en) to register. Calls deduct from your balance as you go, so you need to top up first. Balance is denominated in USD; WeChat Pay, Alipay, Stripe (bank card) and USDT are supported — the exact methods and amount limits are subject to the wallet order page. Within 7 days of topping up you can request a refund of unused principal to the original payment method; consumed amounts and payment processing service fees are non-refundable. See [Top-ups, Refunds and Invoices](/en/docs/billing/) for the rules.
Go to the [Console](https://1zheai.com/console?lng=en), click "API Keys" in the left sidebar, then click "Create API Key" in the top right, give it a name and save. API keys start with `sk-` — click the copy icon in the list to copy and store it. Details in [Getting and Managing API Keys](/en/docs/api-keys/).
Put the API key into an environment variable, then call the Anthropic native endpoint once with curl:
```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` is just an example variable name — any name works.
On success you get HTTP 200 with a structure identical to the official one. Focus on two things: whether `model` is the model you requested, and the token counts in `usage`. Below is an actual response measured on 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` is a few hundred more than the question itself — that's the system prompt attached by this kind of client (curl, SDK, third-party tools) on every request, billed as input; Claude Code does not attach one, see [Billing for System Prompts](/en/docs/pricing-explained/#section-3).
Then go to "Call Logs" on the left of the console to see this call: time, the API key used (the "Token" column), model, input / output tokens, cache read/write and cost.
## You Can Also Start with GPT
If you use the OpenAI SDK or plan to integrate Codex, you can choose the GPT protocol directly. Set the `ONEZHE_API_KEY` above in the same terminal first, then run:
```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。"}]}'
```
This is a macOS / Linux shell example; on Windows you can run the [cross-platform Python / Node.js example](/en/docs/code-examples/) directly. Text goes in `choices[0].message.content`; if the model is not in your list, first [query available models](/en/docs/api-models/). Codex requires Responses — follow the [Codex configuration tutorial](/en/docs/quickstart-codex/) to integrate.
## Next Steps
Connect it to your favorite tools:
Two environment variables are enough.
Use this if you don't want to hand-edit config files.
How to write a custom Base URL and its restrictions.
If you already have OpenAI code, just change base_url.
If a request fails, first check [Error Codes and Troubleshooting](/en/docs/troubleshooting/). To verify returned fields and usage, see [Verifying Models and Usage](/en/docs/verify-model/).
---
# Obtaining and Managing API Keys
Source: https://1zheai.com/en/docs/api-keys/
Markdown: https://1zheai.com/en/docs/api-keys.md
---
title: "Obtaining and Managing API Keys"
description: "Create sk- prefixed API keys in the 1zheAI console, and how to store, rotate, and limit damage when leaked."
headingIds: {"Creating an API Key":"section-1","One API Key Per Tool":"section-2","Where to Store It":"section-3","What to Do If It’s Leaked":"section-4","FAQ":"section-5"}
---
An API key corresponds to one set of call permissions, and charges are deducted from your account balance. This page explains how to create one, where to store it, and what to do if something goes wrong.
## Creating an API Key
Open [1zheai.com/console](https://1zheai.com/console?lng=en).
Click "API Keys" in the left sidebar menu, then click "Create API Key" in the top right. Fill in a name that shows its purpose, such as `claude-code-macbook`, `ci-staging`. Other fields can be left at their defaults and it will still work; click "Save Changes".
Configurable fields in the form:
| Form Field | Default | Description |
|---|---|---|
| Name | Empty | Used to distinguish API keys in call logs |
| Expiration | Never expires | Choose 1 hour, 1 day, 1 month, or specify an exact date and time |
| Quantity | 1 | Create multiple at once; names get a random suffix added automatically |
| "Unlimited Quota" toggle | On | When turned off, a "Quota (USD)" field appears; this API key can spend at most that many USD |
| Model Restrictions (under "Advanced Settings") | Empty, meaning all models allowed | Once models are selected, this API key can only call those models |
| IP Allowlist (under "Advanced Settings") | Empty, meaning no restriction | Only allows calls from the listed IPs or CIDR ranges |
API keys start with `sk-`. After copying, put it in a password manager or environment variable; do not paste it into chats, screenshots, or code repositories.
## One API Key Per Tool
It is recommended to create a separate API key for each tool and each machine. There are three benefits:
- Call logs are separated by API key, so you can see at a glance which tool spent how much.
- If one API key is leaked, you only delete that one; other tools are unaffected.
- In a team, each person is responsible for their own API key; delete the corresponding key when someone leaves or switches machines.
## Where to Store It
```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
```
Claude Code's project-level `.claude/settings.json` is usually committed to the repository, and Claude Code's official documentation explicitly recommends not writing credentials here. Put the API key in the user-level `~/.claude/settings.json`, or in a `.claude/settings.local.json` in the project that is not committed.
## What to Do If It’s Leaked
1. Find it in the "API Keys" list, click the "Disable" icon in the "Actions" column, or select "Delete" from the "⋯" menu. Once disabled it takes effect immediately; further calls with it return 401 `Invalid token`.
2. Create a new API key and replace it wherever the old one was used.
3. Open the call logs (console menu "Call Logs"), click "Expand", and filter by entering this API key's name in "Token Name" to check whether any recent calls were not initiated by you.
## FAQ
Yes, API keys are not bound to a tool. However, mixing them makes it unclear in the logs who spent the money, so it is still recommended to create them separately.
Mostly yes. Common causes: spaces or line breaks copied along with the key, the API key has been deleted, or it was entered into the wrong field in the tool. For step-by-step troubleshooting see [Error Codes and Troubleshooting](/en/docs/troubleshooting/).
By default they never expire. When creating or editing, you can set a time in "Expiration"; after expiration, calls return 401 `Invalid token`, the same response as when an API key is entered incorrectly. The "Expiration" column in the list shows each API key's expiration time.
---
# Supported Models
Source: https://1zheai.com/en/docs/models/
Markdown: https://1zheai.com/en/docs/models.md
---
title: "Supported Models"
description: "Check availability, model IDs, endpoints and pricing for Claude, GPT, MiMo and image generation models."
headingIds: {"Model List":"section-1","Both Endpoints Work":"section-2","OpenAI / GPT Models":"section-3","MiMo Models":"section-4","Query the Latest List via the API":"section-5","How to Choose":"section-6","FAQ":"section-7","Image Models and Endpoint Lookup":"section-8"}
---
Claude, GPT, MiMo and image generation models are now live. Below are the model IDs for Claude and GPT; the full availability is determined by the model catalog and what the API returns.
See [Public Models and Pricing](https://1zheai.com/en/pricing/) for quotes; logged-in users can go to [Console · Models](https://1zheai.com/model-catalog?lng=en) to look up models and view integration methods.
## Model List
The `model` in your request must match the IDs in the table exactly, including the date suffix.
| Model ID | Series | Notes |
|---|---|---|
| `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 | Pinned version ID with date |
| `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 | Pinned version ID with date |
| `claude-haiku-5-5` | Haiku 5.5 | |
| `claude-haiku-4-5-20251001` | Haiku 4.5 | Pinned version ID with date |
Unit prices for each model (input, output, cache read, cache write) are on the [Pricing Page](https://1zheai.com/en/pricing/). Model capabilities, context length and release notes are governed by the [Anthropic official model docs](https://platform.claude.com/docs/en/about-claude/models/overview).
## Both Endpoints Work
All models in the table above can be called via the Anthropic native `/v1/messages` and the OpenAI-compatible `/v1/chat/completions`, with the same model ID format. For Claude-specific parameters such as caching, thinking and tool calls, use the native endpoint; see [Base URL and Authentication](/en/docs/base-url/).
## OpenAI / GPT Models
- `gpt-5.6-luna`
- `gpt-5.6-sol`
- `gpt-5.6-terra`
- `gpt-6-astra`
GPT can be used with the [OpenAI SDK](/en/docs/quickstart-openai-sdk/) and [Codex CLI](/en/docs/quickstart-codex/). Endpoints and billing for different models are governed by the [Console model catalog](https://1zheai.com/model-catalog?lng=en).
## MiMo Models
IDs, supported endpoints and billing units for MiMo text and voice models are on [Models and Pricing](https://1zheai.com/en/pricing/). Text is billed per token and voice per the billing unit of the corresponding model; do not apply Claude's caching and discount rules.
## Query the Latest List via the API
Models are added or removed as official releases occur; the API response is authoritative:
```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'
```
## How to Choose
If you are unsure which to pick, you can start with:
| Scenario | Recommendation |
|---|---|
| Everyday coding, primary use in Claude Code | `claude-sonnet-5-5` |
| Complex refactoring, hard-to-debug issues | `claude-opus-5-5` |
| Subtasks, summarization, classification and other light work | `claude-haiku-5-5` |
For how to map the opus / sonnet / haiku tiers to specific models in Claude Code, see [Claude Code Integration](/en/docs/quickstart-claude-code/).
## FAQ
First verify the ID spelling and date suffix, then use the `/v1/models` above to confirm that your API key can see this model. Custom model names from other providers (e.g. with added prefixes or suffixes) cannot be used here.
When a model does not exist or is currently unavailable, the gateway returns HTTP 404. In the Anthropic native response, `error.type` is `not_found_error`; in the OpenAI-compatible response, `error.code` is `model_not_found`.
First verify the ID and the key's available model list; do not repeatedly retry the same wrong ID. A 503 is only returned when the model exists but there is temporarily no healthy upstream service; see [Error Codes and Troubleshooting](/en/docs/troubleshooting/).
Under normal conditions, the response's `model` is the ID you requested. If it does not match, send the request time and response to support@1zheai.com; you can also follow [Verify Model and Usage](/en/docs/verify-model/) to run the checks.
## Image Models and Endpoint Lookup
The public catalog listed `gpt-image-1.5` and `chatgpt-image-latest` as of 2026-10-16. See [Image Generation Integration](/en/docs/api-images/) for details; actual permissions and parameters are governed by your key and the model catalog.
For full API examples for models, both response formats and troubleshooting when the list is empty, see [Query Available Models API](/en/docs/api-models/).
---
# Migrating from Other Services to 1折AI
Source: https://1zheai.com/en/docs/migration/
Markdown: https://1zheai.com/en/docs/migration.md
---
title: "Migrating from Other Services to 1折AI"
description: "Migrate item by item across address, key, model, protocol, and features, while keeping the original configuration for rollback."
headingIds: {"Check Four Configuration Items Together":"section-1","Verify in Order":"section-2","Scope of Environment Variables":"section-3","Rollback When Switching Fails":"section-4"}
---
Save the original configuration before migrating. First verify in a separate terminal or development environment, and only change your commonly used tools or production services after confirming success.
## Check Four Configuration Items Together
| Configuration | How to write it in 1折AI | Common mistakes |
| --- | --- | --- |
| OpenAI Base URL | `https://1zheai.com/v1` | Writing an extra `/chat/completions`, or omitting `/v1` |
| Anthropic Base URL | `https://1zheai.com` | The SDK appends `/v1` once again |
| API key | A key created in this site's console | Reusing the key from the old provider |
| Model ID | The full ID returned by this site's `/v1/models` | Reusing names with a `vendor/` prefix or a custom suffix |
Raw HTTP requests require the full endpoint path; SDKs and desktop tools usually only require the Base URL. Refer to [the corresponding tool tutorial ](/en/docs/integrations/) for details.
## Verify in Order
Call once according to [the model query API ](/en/docs/api-models/). If it fails, first fix the address, credentials, or access conditions; do not adjust multiple business parameters at the same time.
Choose [Chat Completions ](/en/docs/api-chat-completions/), [Responses ](/en/docs/api-responses/), or [Messages ](/en/docs/api-messages/). Keep the protocol required by the original client, and remove optional parameters first.
Verify streaming, multi-turn history, tool calls, and other required capabilities in turn. Add only one item at a time, and keep comparable error responses. Success with plain text does not mean that all of an Agent's file, search, and auxiliary model features are compatible.
Confirm the request time and model in [the call log ](/en/docs/usage-logs/). Restart terminals, IDEs, or background services that need to reload configuration, to avoid them still using the old environment variables.
## Scope of Environment Variables
`export` in the terminal only affects the current shell and child processes started afterward. Desktop applications, containers, scheduled tasks, and system services may use a different set of environments; configure credentials where the program actually runs.
Fields with the same name in configuration files may also override environment variables. Tools such as Claude Code and Codex each refer to their own tutorials; do not pile all provider variables into the global shell configuration at once.
## Rollback When Switching Fails
Restore the previously saved provider, address, and model configuration, and restart the client. If you are migrating a production workload, first verify with a small number of requests before expanding the scope; keep the application-layer configuration switching method so the service can be restored easily.
If you are unsure whether a feature is available, check the model catalog or contact support. Do not assume this site offers the same services just because other platforms provide Embeddings, Batch, or a particular proprietary image model.
---
# API Integration FAQ
Source: https://1zheai.com/en/docs/faq/
Markdown: https://1zheai.com/en/docs/faq.md
---
title: "API Integration FAQ"
description: "Quickly find common questions about Base URL, models, streaming, clients, timeouts, and availability monitoring."
headingIds: {"Address, Keys, and Models":"section-1","Requests and Clients":"section-2","Service Status and Help":"section-3"}
---
## Address, Keys, and Models
For the OpenAI SDK, enter `https://1zheai.com/v1`; for the Anthropic SDK and Claude Code, enter `https://1zheai.com`. When using curl directly, fill in the full request path. Some desktop tools auto-complete the path — see the [address comparison table](/en/docs/base-url/).
Yes. This site's integration uses an API key created in this site's console; consumer-grade client subscriptions and this site's API credentials are different integration methods. The tool must also support custom providers or API addresses.
The list shows the models visible to the current key, not real-time inference success rates. You also need to verify the interface protocol, optional parameters, and upstream status — see the [model query API](/en/docs/api-models/).
Copy the complete ID from this site's model list. Different providers may use different prefixes, aliases, and date versions — do not guess or rename them. For migration steps, see the [migration guide](/en/docs/migration/).
## Requests and Clients
First confirm the response protocol. Chat Completions reads `choices[].message.content`, Messages iterates over `content` text blocks, and Responses iterates over `output` or uses the SDK's `output_text`. Tool-call responses may also contain no plain text.
Multi-turn conversations require the client to pass in history. Repeatedly using the same key does not automatically create a server-side session. Session-related extensions for Responses need to be confirmed separately — do not rely on them by default.
You also need to confirm the end event or final status. Mid-stream errors, broken streams, and output truncation can all occur after some text has already been received. See [streaming output](/en/docs/streaming/) for details.
Not recommended. A timeout may occur after the request has already been processed. First check the call logs, then retry with a limited number of attempts, backoff, and a total wait time — avoid both the SDK and the application each performing a round of retries. See [timeouts and retries](/en/docs/retries/).
Do not compile keys into browser scripts or public repositories. Keep credentials on your server and call the API from there; the browser should only connect to your own backend. Environment variables in demo code are for server-side or local terminal use.
## Service Status and Help
Monitoring checks the HTTP accessibility of the official website, console, and API entry points — it does not represent the inference success rate of each model. Monitoring is deployed on the same server as the application, so it will also pause during a full machine failure; historical data accumulates from the time monitoring is enabled.
Provide the occurrence time and time zone, client version, model ID, full request path, HTTP status code, request ID, and redacted error information. Remove keys, authentication headers, and private conversation content; you can organize the report using the [troubleshooting template](/en/docs/troubleshooting/).
---
# Store Purchase Guide
Source: https://1zheai.com/en/docs/store-guide/
Markdown: https://1zheai.com/en/docs/store-guide.md
---
title: "Store Purchase Guide"
description: "Understand the differences between ready-to-use accounts, subscription top-ups, and gift cards. Place orders according to product notices and track delivery."
headingIds: {"Check Before Ordering":"section-1","Ordering and Delivery":"section-2","Must Know Before Purchasing":"section-3","Invite Friends to Purchase":"section-4"}
---
Choose an AI account, subscription service or gift card in the store. Read the product details before placing your order.
| What you need | Service to choose | Where to check |
| --- | --- | --- |
| Call models in code or tools | Model API | [API Quick Start](/en/docs/quickstart/) |
| Buy an existing third-party account | Ready-made account | [Ready-made Account Purchase and Usage](/en/docs/account-guide/) |
| Activate membership for your own third-party account | Subscription top-up | [Top-up Conditions and Process](/en/docs/subscription-guide/) |
| Obtain a redemption code or redemption link | Gift card | [Redemption and Usage Notices](/en/docs/gift-card-guide/) |
API keys on this site cannot log in to ChatGPT, Claude, or Grok; purchasing a third-party platform membership does not equal topping up the API balance on this site.
## Check Before Ordering
Review the product name, specifications, region, subscription duration, current stock, delivery method, and purchase notices. Specifications not displayed in the catalog or not available for purchase have not yet been opened; do not pay according to demo pages or other merchants' processes.
Whether a product supports renewal, email changes, multi-user use, or specific clients must be based on the selected product description. If not explicitly stated, contact support first to confirm; these capabilities are not included by default.
## Ordering and Delivery
1. Select the product and specifications in the [Online Store](https://1zheai.com/en/store/).
2. After logging in, verify the checkout price, quantity, and purchase notices. Top-up products also require filling in the required information in the form.
3. Read the risk and after-sales rules, actively check the confirmation, and then place the order; orders are paid using the wallet balance on this site.
4. Check status, delivery content, or information that needs to be supplemented in [My Orders](https://1zheai.com/store-orders?lng=en). A successful balance top-up does not mean the product has been purchased or the top-up has been completed.
Automatically delivered products with stock, manually delivered products, and top-ups activated after ordering are handled differently. We do not uniformly promise instant delivery or a fixed completion time limit; the checkout page and order display are authoritative.
## Must Know Before Purchasing
After a ready-to-use account is normally delivered or a top-up succeeds, if the account is banned by a third-party platform, no refund will be issued due to the ban. We can assist with appeals, but do not promise unban results. Failure to deliver as agreed, unsuccessful top-ups, or situations where this site should bear responsibility according to law will be handled according to the corresponding after-sales rules.
[Transaction and After-sales Rules](/en/docs/store-rules/) · [Order Issue Troubleshooting](/en/docs/store-orders/)
## Invite Friends to Purchase
Store products can participate in commission rebates according to specifications. For participation scope, attribution, and settlement conditions, see [Invitation Rewards and Store Rebates](/en/docs/affiliate-guide/).
---
# Purchase and Use of Ready-to-Use Accounts
Source: https://1zheai.com/en/docs/account-guide/
Markdown: https://1zheai.com/en/docs/account-guide.md
---
title: "Purchase and Use of Ready-to-Use Accounts"
description: "Specifications, delivery contents, first login, and ban risks to confirm before purchasing ready-made ChatGPT, Claude, and Grok accounts."
headingIds: {"Confirm Before Purchase":"section-1","After Receiving the Account":"section-2","Daily Use and Renewal":"section-3","Bans and After-Sales Service":"section-4"}
---
A ready-to-use account delivers a third-party platform account as described in the selected product listing. Whether a subscription is included, the subscription tier, and the remaining duration are all determined by that product and the order; do not judge based on the platform name alone.
## Confirm Before Purchase
- Whether a subscription is included, and the specific tier (e.g. Pro, Max) and duration; specifications not displayed are not available for sale.
- Region, login method, and delivery contents; whether email access, verification code reception, or email change capability is provided.
- Whether it is a one-time delivery or has separate renewal arrangements; do not assume automatic renewal, email forwarding, or renewal reminders are included.
- Whether team, shared, or transferred use is allowed, as well as the third-party platform's own terms and regional restrictions.
## After Receiving the Account
1. In [My Orders ](https://1zheai.com/store-orders?lng=en) verify the product, specifications, and delivery information, and keep the order number safe.
2. Follow that product's login instructions to access the corresponding platform, and check whether the account can log in, its subscription tier, and its validity period.
3. Change the password, recover information, or enable security verification in the manner allowed by the product; for items that cannot be changed, contact support first to confirm.
4. If the delivered information is invalid, the specifications do not match, or login fails, keep redacted screenshots and error messages, and explain the situation through the official website's support channel. Do not publicly share account passwords, verification codes, or recovery codes.
## Daily Use and Renewal
Comply with the platform's terms of use. The account may be subject to regional, usage volume, identity verification, or risk-control restrictions; the purchase does not include any guarantee of circumventing restrictions, handling identity verification on your behalf, or never being banned. Identity verification must be completed by the actual user as required by the platform; do not send ID documents or verification codes to customer service unless there is another explicit and necessary legitimate process.
When renewal is needed, first confirm the method supported by the current product; do not apply top-ups intended for your own account directly to a ready-to-use account, and do not stack incompatible subscriptions on your own.
## Bans and After-Sales Service
After a ready-to-use account has been delivered normally or a top-up has succeeded, if the account is banned by the third-party platform, no refund is issued due to the ban. We can assist with an appeal, but do not promise an unbanning result. Failure to deliver as agreed, an unsuccessful top-up, or situations where this site should bear responsibility under law are handled according to the corresponding after-sales rules.
[Detailed Transaction Rules ](/en/docs/store-rules/) · [Order Issue Troubleshooting ](/en/docs/store-orders/)
---
# Subscription Top-Up Conditions and Process
Source: https://1zheai.com/en/docs/subscription-guide/
Markdown: https://1zheai.com/en/docs/subscription-guide.md
---
title: "Subscription Top-Up Conditions and Process"
description: "Check eligibility, required information, security notes, and order handling before topping up with your own account."
headingIds: {"Check Account Conditions First":"section-1","Order Process":"section-2","Information Security":"section-3","Processing, Failure, and Refunds":"section-4"}
---
Subscription top-up activates the selected membership for your existing third-party platform account; no new account is delivered. Whether a product is available for sale, and which platforms and tiers are supported, is subject to what the [store](https://1zheai.com/en/store/) currently displays. This document does not indicate that all platforms or specifications are open.
## Check Account Conditions First
Review the region, account type, current subscription status, outstanding balance, refund history, and renewal restrictions required by the selected product. Conditions may differ by channel; we do not uniformly require all accounts to be Free, nor do we uniformly guarantee that stacking, upgrading, or extending an existing subscription is possible.
If you have an existing subscription, outstanding balance, platform restrictions, or are unsure about account eligibility, contact support first. Do not repeatedly place orders to test, and do not substitute another merchant's operating instructions for the product notes on this site.
## Order Process
1. Select the specific specification and confirm the price, duration, applicable account, and activation method.
2. Fill in the information required by that specification in the checkout form on this site, such as the account identifier or Organization ID; fields vary by product.
3. Verify the target account and information, read the risk notice, and submit the order.
4. Check processing progress in [My Orders](https://1zheai.com/store-orders?lng=en). Update information only when the original order indicates it can be corrected; do not repurchase.
5. After the order shows completion, log in to the third-party platform to check the membership tier and validity period; if it still shows as not updated, refresh or log in again and re-check, and contact support if it remains inconsistent.
## Information Security
Some specifications may require login session information such as Session JSON. This type of information may allow access to your account and is as sensitive as a password. Submit it only through the dedicated form for the corresponding order on this site; do not send it to online chat, email, public screenshots, or third-party account lookup websites. Submit only after understanding the scope of authorization and accepting the product requirements; if you cannot accept them, do not purchase that specification.
Do not send passwords, verification codes, API keys, or complete login sessions in ordinary customer service messages. After processing is complete, check and manage login devices and sessions using the methods provided by the third-party platform.
## Processing, Failure, and Refunds
Processing begins after payment; once in the processing stage, it cannot be directly canceled. A timeout or failure notice does not mean a refund, nor does it necessarily mean activation did not occur. Keep the original order, wait for the status to update or contact support to verify, and avoid duplicate charges or duplicate activation. Refund results and destinations are subject to the order and wallet records on this site; we do not promise that refunds will always be returned via the original payment method.
After a finished account is normally delivered or a top-up succeeds, if the account is banned by the third-party platform, no refund is issued due to the ban. We can assist with appeals, but do not promise an unban result. Failure to deliver as agreed, unsuccessful top-up, or situations where this site should bear responsibility under law are handled according to the corresponding after-sales rules.
[Transaction and After-Sales Rules](/en/docs/store-rules/) · [Order Issue Troubleshooting](/en/docs/store-orders/)
---
# Gift Card Redemption Notice
Source: https://1zheai.com/en/docs/gift-card-guide/
Markdown: https://1zheai.com/en/docs/gift-card-guide.md
---
title: "Gift Card Redemption Notice"
description: "Check region, validity period, eligible accounts, and card delivery rules before purchase and redemption."
headingIds: {"Confirm Before Purchase":"section-1","How to Use After Receiving":"section-2","Cancellation and After-Sales":"section-3"}
---
Gift cards are delivered as a redemption code or redemption link; subscription top-ups may instead be activated directly through the order process. These are two different delivery methods — not all top-ups should be understood as receiving a card code and then redeeming it on an external site.
## Confirm Before Purchase
Check the platform, region, currency or face value, subscription tier, validity period, and eligible account conditions indicated on the product. Whether existing subscriptions, mobile subscriptions, stacked redemptions, or gifting are supported must be reviewed item by item in the product description; do not treat other merchants' validity periods or redemption conditions as commitments from this site.
When the store has no purchasable gift cards available, this means purchases are currently not open. When platform rules or supply status change, the actual product display shall prevail.
## How to Use After Receiving
1. Check the delivered content in [My Orders ](https://1zheai.com/store-orders?lng=en); do not publicly share the redemption code or screenshots containing it.
2. Confirm you are logged into the correct target account, then go to the designated redemption entry point according to the product description; beware of unfamiliar websites requesting additional transfers or passwords.
3. Re-check the region and account status before redeeming, and verify the actual credited benefits after redemption.
4. If you encounter an already-used code, an invalid code, a region mismatch, or benefits not credited, keep the order number, error content, and redacted screenshots and contact support; do not repurchase to troubleshoot.
## Cancellation and After-Sales
Orders that have not yet begun processing may be cancelled via the entry point provided with the order; direct refunds are not supported after a redemption code has been delivered. For issues, contact support for verification. Cases of non-delivery as agreed, invalid delivery, or situations where this site is legally responsible will be handled according to applicable after-sales rules. Gift card bans, redemption restrictions, and refund conditions are governed by the specific notice for that product; API balance refund rules do not apply.
[Transaction and After-Sales Rules ](/en/docs/store-rules/) · [Order Issue Troubleshooting ](/en/docs/store-orders/)
---
# Order Status and Troubleshooting
Source: https://1zheai.com/en/docs/store-orders/
Markdown: https://1zheai.com/en/docs/store-orders.md
---
title: "Order Status and Troubleshooting"
description: "Find delivery contents, processing progress, data corrections and refund records, and avoid duplicate orders."
headingIds: {"Status Explanations":"section-1","Common Issues":"section-2","Payment was deducted, but no account or membership was received":"section-3","Data was filled in incorrectly":"section-4","Order shows completed, but the platform has no membership yet":"section-5","Account was banned or identity verification is required":"section-6","Where is the refund":"section-7","What to provide when contacting support":"section-8"}
---
Select the corresponding order in [My Orders ](https://1zheai.com/store-orders?lng=en). Purchase records, delivery contents and processing progress are based on that order; balance top-up records are not product orders.
## Status Explanations
| Status | What it means | Next step |
| --- | --- | --- |
| Pending Delivery | The order has been created but delivery has not been completed | Check the delivery method and order notes; if a cancellation entry is provided, you can apply for cancellation |
| Processing | Manual processing is underway or activation is being opened through a partner channel | Keep the original order and do not repurchase; supplement or correct data as prompted |
| Delivered | The delivery contents or activation result have been provided | For finished accounts, verify login and specifications; for proxy top-ups, verify membership; for gift cards, redeem according to the instructions |
| Cancelled | The original order has been terminated | Check the cancellation reason and wallet transaction records; whether a refund is issued is subject to the actual records |
Detailed progress for proxy top-ups may indicate waiting for supply, waiting for activation, data needing correction, or refund in progress. These progress states differ from the final completion status; do not judge the activation or refund result based on a single error message.
## Common Issues
### Payment was deducted, but no account or membership was received
First open the order details to check the status and delivery contents. Manual delivery and proxy top-ups are not necessarily completed instantly; if the time limit stated in the product description is exceeded, the status has not been updated for a long time, or an abnormality is displayed, contact support and do not make a duplicate payment.
### Data was filled in incorrectly
Update only when the original order displays a correction entry, and submit after verifying the target account. If there is no entry or the order has already been delivered, contact support first; we do not promise that an activated subscription can be transferred.
### Order shows completed, but the platform has no membership yet
Confirm that you are logged into the target account submitted, refresh or log in again and check the subscription settings. If it is still inconsistent, keep a redacted screenshot and the order number and contact support; do not make another purchase on your own.
### Account was banned or identity verification is required
Appeal or verify through the official channels of the third-party platform. After normal delivery or successful proxy top-up, refunds are not issued due to account bans; we can assist with appeals but do not guarantee unbanning. Abnormalities such as failure to deliver as agreed are handled separately according to [After-sales Rules ](/en/docs/store-rules/).
### Where is the refund
Check the order cancellation reason and wallet transaction records. Returning to wallet balance differs from a refund to the original payment method; a refund showing as in progress has not yet been completed, so do not submit the same request again.
### What to provide when contacting support
Order number, product and specifications, occurrence time and time zone, order status, redacted error information. Do not send passwords, verification codes, complete Session JSON, redemption codes, or API keys.
---
# Store Transactions and After-Sales Rules
Source: https://1zheai.com/en/docs/store-rules/
Markdown: https://1zheai.com/en/docs/store-rules.md
---
title: "Store Transactions and After-Sales Rules"
description: "Cancellation, delivery anomalies, activation failures, and account bans are handled by order stage; Model API balance is processed separately under top-up rules."
headingIds: {"Information Before Placing an Order":"section-1","Cancellation and Refund Are Handled by Order Stage":"section-2","Ban Risk Must Be Understood Separately":"section-3","Difference from API Balance Refunds":"section-4","When After-Sales Service Is Needed":"section-5"}
---
## Information Before Placing an Order
Price, specifications, quantity, region, duration, delivery method, and risk notices are displayed on the product or checkout page. Please read them fully before confirming; if any condition is unclear, contact support first. The order retains the product and risk notices confirmed at the time of ordering; subsequent page updates do not rewrite the confirmation record of historical orders.
This site is your entry point for purchasing products and requesting after-sales service. When a supply partner is involved, this site handles verification based on the order; do not make separate payments to unfamiliar upstream parties, and there is no need to register a distribution account yourself.
## Cancellation and Refund Are Handled by Order Stage
| Situation | How to Handle |
| --- | --- |
| Pending delivery and the order provides a cancellation entry | You can request cancellation from the original order; after success, check the wallet refund transaction record |
| Processing in progress or activation result pending confirmation | Cannot be canceled directly; keep the original order and wait for verification, do not repurchase |
| Unable to log in, invalid delivery, or specifications do not match | Provide the order number and redacted proof; support will verify the delivery status |
| Top-up failed or information is incorrect | Correct as prompted on the original order or contact support; a failure notice does not mean a refund has been issued |
| A ready-to-use account was delivered normally or top-up succeeded, and was later banned by a third-party platform | No refund due to the ban; we can assist with an appeal, but do not guarantee unbanning |
| Gift card has been delivered | Direct refunds are not supported; anomalies such as invalid delivery can still be contacted for verification with support |
## Ban Risk Must Be Understood Separately
After a ready-to-use account is delivered normally or a top-up succeeds, if the account is banned by a third-party platform, no refund is issued due to the ban. We can assist with an appeal, but do not guarantee the unbanning result. Failure to deliver as agreed, unsuccessful top-up, or situations where this site should bear responsibility under law are handled according to the corresponding after-sales rules.
Third-party platforms may adjust terms, restrict access, or require identity verification; this site cannot guarantee that risk control will not occur, that bans will not happen, or that appeals will definitely pass. Do not confuse bans after normal delivery with failure to deliver as agreed or activation failure. The above explanation does not exclude responsibilities that should be borne by this site under legal provisions.
## Difference from API Balance Refunds
Refunds of unused principal for Model API are handled according to [Top-Up, Refund, and Invoice](/en/docs/billing/). Whether store products can be canceled and how refunds are issued follow the order stage and the corresponding product rules; the 7-day rule for API balance does not apply directly. Canceling an order to return funds to the wallet and refunding a wallet top-up to the original payment method are two different operations.
## When After-Sales Service Is Needed
From [My Orders](https://1zheai.com/store-orders?lng=en), keep the order number and provide the product specifications, occurrence time, order status, status displayed on the third-party platform, and redacted error screenshots. Contact us through the support channels published on the official website or console; do not provide passwords, verification codes, complete sessions, redemption codes, or original ID document images. For how to locate a specific issue, see [Order Issue Troubleshooting](/en/docs/store-orders/).
---
# Invitation Rewards and Mall Commission
Source: https://1zheai.com/en/docs/affiliate-guide/
Markdown: https://1zheai.com/en/docs/affiliate-guide.md
---
title: "Invitation Rewards and Mall Commission"
description: "Learn about the invitation attribution, participating products, settlement conditions, and commission status of mall commissions."
headingIds: {"How to Participate":"section-1","Which Orders Generate Commission":"section-2","When It Is Settled":"section-3","Where to View":"section-4"}
---
Eligible store orders can earn referral rewards. The administrator sets participation for each account, subscription activation and gift card product; commission does not apply to every product automatically.
## How to Participate
Copy your own registration link from the invitation entry in the console [wallet](https://1zheai.com/wallet?lng=en). After a friend completes registration through that link, the system-recorded invitation relationship is carried over. When the friend places an order, commission attribution is determined accordingly; it is not changed by later clicking someone else's link, and no inviter ID is submitted through the order form.
For friends who have already established an invitation relationship, purchases of commission-participating products after the feature is enabled are also handled under the new order rules. Historical orders placed before the feature was enabled will not receive retroactive mall commissions. Purchases by yourself do not count as your own invitation commission.
## Which Orders Generate Commission
The administrator configures a fixed commission for each product by product specification; entering 0 means it does not participate. Specifications whose actual commission has not yet been configured will not issue rewards. At the time of ordering, the inviter, product, quantity, and commission amount at that moment are recorded; subsequent adjustments to product price or commission do not rewrite records of orders already placed.
Mall commissions and registration rewards are two separate types of records. A friend topping up the wallet does not equate to purchasing a product, and will not automatically generate a mall commission on that basis. Whether registration rewards are issued follows the administrator's existing invitation reward settings.
## When It Is Settled
| Order Status | Commission Handling |
| --- | --- |
| Pending delivery, processing, or activation result pending confirmation | Only estimated commission is recorded; it cannot be transferred to balance |
| Finished account or gift card delivered successfully, top-up completed | Settled by the system and credited to the reward balance |
| Order cancelled and refunded | Estimated commission is voided; no reward is issued |
| Duplicate order submission or duplicate completion notification | The same order is settled only once |
An order error or timeout does not mean it has been delivered; whether commission has been generated cannot be judged based on a single processing result alone. Bans occurring after normal account delivery or successful top-up are handled according to the[mall after-sales rules ](/en/docs/store-rules/).
If the reward receiving account is disabled or has reached the system amount limit, the commission remains in a pending settlement state and will be retried once conditions are restored; this does not affect the buyer's order delivery. When system payment and reward features are suspended, settlement is also suspended.
## Where to View
The "Recent Mall Commissions" section in the wallet displays the product, specification, quantity, amount, and status of recent participating orders:
- **Pending Settlement**: Estimated amount, not yet credited to available rewards.
- **Credited**: Already credited to the reward balance; do not add it again when calculating available rewards.
- **Voided**: This commission will no longer be issued.
Available rewards use the existing transfer-to-balance entry and minimum transfer requirements, and can be used for model API consumption. Rewards are not a cash withdrawal quota, nor do they equal recharged mall available funds; the mall still validates according to its own fund eligibility rules.
Inviters can only view commission records attributed to themselves. Records do not display the buyer's identity, order number, account password, or redemption code. When commission verification is needed, provide the commission record number, product, and occurrence time through the support channels published on the official website; do not request the buyer's login credentials.
---
# Claude and GPT Tool Integration Guide
Source: https://1zheai.com/en/docs/integrations/
Markdown: https://1zheai.com/en/docs/integrations.md
---
title: "Claude and GPT Tool Integration Guide"
description: "API configuration guides and support scope for Claude Code, Codex CLI, OpenCode, OpenClaw, WorkBuddy, Hermes Agent, Cursor, Cline, Cherry Studio, and CC Switch."
headingIds: {"Programming Tools":"section-1","Desktop Assistants":"section-2","More Clients and Import Methods":"section-3","Agent Platforms":"section-4","Configuration Management":"section-5","Other Tools Supporting Custom APIs":"section-6","How to Confirm the Configuration Succeeded":"section-7"}
---
Enter the guide for the tool you are using. The statuses below are compiled from existing integration documentation and do not mean that all tool versions have been verified end-to-end. After a tool upgrade, please re-run the call verification on the page.
## Programming Tools
Native Anthropic integration. Environment variables, configuration files, and common issues. Calling OpenAI / GPT models via the Responses API. Distinguishing v1 and v2 configuration, custom OpenAI-compatible providers. OpenAI-compatible integration. First check the scope of custom keys and interface differences. Anthropic mode is preferred; an OpenAI Compatible configuration is also provided.
## Desktop Assistants
Adding a custom provider in a chat client. Adding a custom address via model settings; note the full URL and protocol toggle.
## More Clients and Import Methods
Importing via link or clipboard JSON, with manual fallback configuration supported. Android provider QR code; key content is hidden by default. Custom provider fields and model configuration. Admin YAML endpoint and per-user independent keys. Anthropic configuration for the VS Code extension.
One-click protocols are only for operations that the client has publicly supported. ChatWise's open-conversation protocol is not the same as importing a key; LibreChat requires admin configuration. Do not treat all tools as having the same import link.
## Agent Platforms
Configuring a custom Anthropic provider and default Agent model. Configuring Chat Completions via the model wizard or a named provider. The guides for OpenCode, OpenClaw, WorkBuddy, and Hermes Agent have been checked against official configuration, but end-to-end verification on this site is not yet complete. Please check the actual version against the guide and verify the call.
## Configuration Management
Managing provider configuration for Claude Code to reduce manual switching.
## Other Tools Supporting Custom APIs
First check whether the tool can set an API address, key, and model ID, then choose a configuration based on the protocol:
| Protocol supported by the tool | This site's endpoint | Next step |
| --- | --- | --- |
| Anthropic Messages | `/v1/messages` | Check whether the client automatically appends `/v1`; see [address notes ](/en/docs/base-url/) |
| OpenAI Chat Completions | `/v1/chat/completions` | Usually fill Base URL with `https://1zheai.com/v1`; except for full endpoint fields |
| OpenAI Responses | `/v1/responses` | Fill Base URL with `https://1zheai.com/v1`; see [Codex CLI ](/en/docs/quickstart-codex/) |
| Only supports official account login | Do not use this site's API key | Check whether the tool has a separate custom provider setting |
## How to Confirm the Configuration Succeeded
1. Select the protocol and Base URL according to the guide; whether each tool needs `/v1` is shown in the [address comparison table ](/en/docs/base-url/).
2. Select a currently available model from [supported models ](/en/docs/models/).
3. Send one short request and check that the tool returns normally.
4. Verify the corresponding call in [call logs ](/en/docs/usage-logs/); do not judge which provider the request went through based only on the reply content.
If you encounter a problem, first see [error codes and troubleshooting ](/en/docs/troubleshooting/). If you are writing your own program, go to the [developer guide ](/en/docs/guides/).
---
# Claude Code Integration
Source: https://1zheai.com/en/docs/quickstart-claude-code/
Markdown: https://1zheai.com/en/docs/quickstart-claude-code.md
---
title: "Claude Code Integration"
description: "Connect Claude Code to 1折AI: use ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN (environment variables or settings.json), with Windows syntax, model mapping, VS Code extension, and common errors."
headingIds: {"Shortest Path":"section-1","Full Steps":"section-2","Why Use ANTHROPIC_AUTH_TOKEN":"section-3","Model Mapping":"section-4","VS Code Extension":"section-5","Optional Settings":"section-6","FAQ":"section-7"}
---
Claude Code only needs two variables: `ANTHROPIC_BASE_URL` points to us, and `ANTHROPIC_AUTH_TOKEN` is filled with your API key (API key). No Anthropic account login is required.
## Shortest Path
If you already have Claude Code installed and an API key on hand, write the following two lines into `~/.claude/settings.json`, then run `claude`:
```json title="~/.claude/settings.json"
{
"env": {
"ANTHROPIC_BASE_URL": "https://1zheai.com",
"ANTHROPIC_AUTH_TOKEN": "sk-你的Key"
}
}
```
If the file already exists, merge these two items into the existing `env` without overwriting other configuration.
## Full Steps
If already installed, you can skip this. The following commands come from [Claude Code official installation docs ](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
```
When installing with npm, do not add `sudo`.
Create a new API key in the [console ](https://1zheai.com/console?lng=en); it is recommended to dedicate one specifically for Claude Code on this machine. See [Obtaining and Managing API Keys ](/en/docs/api-keys/).
Location of settings.json: on macOS / Linux it is `~/.claude/settings.json`, on Windows it is `%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"
```
Fill `ANTHROPIC_BASE_URL` with the root address; do not add `/v1`, Claude Code will append `/v1/messages` itself.
Run `claude` in the project directory, and after entering, type `/status`. Check two lines:
- The base URL line shows `https://1zheai.com`
- The credentials line shows the source is `ANTHROPIC_AUTH_TOKEN`
Then ask a question, and go to [call logs ](/en/docs/usage-logs/) to see if there is a new record. If there is, it is connected.
If you do not want to enter the interactive interface, you can also try once in non-interactive mode (tested on 2026-10-15, returned `ok`):
```bash
claude -p "say ok" --model claude-sonnet-4-6
```
## Why Use ANTHROPIC_AUTH_TOKEN
Claude Code has two variables that can hold the API key; the difference is as follows ([official explanation ](https://code.claude.com/docs/en/authentication)):
| Variable | How Sent | Behavior |
|---|---|---|
| `ANTHROPIC_AUTH_TOKEN` | `Authorization: Bearer <值>` | Takes effect immediately once set, no confirmation prompt |
| `ANTHROPIC_API_KEY` | `x-api-key: <值>` | In interactive mode, the first time it will pop up asking whether to use this API key |
We support both; `ANTHROPIC_AUTH_TOKEN` is recommended. **Set only one of the two**: if there is still an old official `ANTHROPIC_API_KEY` left in the system, delete it to avoid mixing and getting 401.
Two other rules that are easy to trip over:
- When `env` in `settings.json` and a terminal export set the same variable, **settings.json takes precedence**. If changing the terminal variable did not take effect, check settings.json first.
- Do not write the API key into the project's `.claude/settings.json`; this file is usually committed to the repository. To differentiate per project, use the non-committed `.claude/settings.local.json`.
## Model Mapping
`opus`, `sonnet`, `haiku`, and `fable` in Claude Code are aliases; you can use environment variables to specify the concrete models they map to. The Haiku tier is also used by Claude Code to run some small background tasks.
| Variable | Purpose | Example Value |
|---|---|---|
| `ANTHROPIC_MODEL` | Model used at startup | `claude-sonnet-5-5` |
| `ANTHROPIC_DEFAULT_OPUS_MODEL` | Model the `opus` alias points to | `claude-opus-5-5` |
| `ANTHROPIC_DEFAULT_SONNET_MODEL` | Model the `sonnet` alias points to | `claude-sonnet-5-5` |
| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | Model for the `haiku` alias and background tasks | `claude-haiku-5-5` |
| `ANTHROPIC_DEFAULT_FABLE_MODEL` | Model the `fable` alias points to | `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"
}
}
```
The model ID must be among the [supported models ](/en/docs/models/). While running, you can also use `/model claude-opus-5-5` to switch temporarily.
## VS Code Extension
The Claude Code VS Code extension checks credentials before startup; the official recommendation is to write the variables in VS Code's own user settings (Command Palette → 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" }
]
}
```
When only written in `~/.claude/settings.json`, the extension's own login check may not read them.
## Optional Settings
| Variable | Purpose |
|---|---|
| `API_TIMEOUT_MS` | Request timeout, default 600000 (10 minutes); long tasks that easily time out can be increased |
| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1` | Turns off non-essential traffic such as auto-update, telemetry, and error reporting. Note that setting it to `0` or `false` also counts as enabled; to turn it off you must delete this variable |
| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1` | Used when encountering 400 errors like "Extra inputs are not permitted" |
| `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1` | Lets the `/model` list fetch available models from `/v1/models` |
`CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1` has been tested and works (Claude Code 2.1.296, 2026-10-15): after startup, `[gatewayDiscovery] cached 14 models` appears in the debug log, and the 14 models match the [supported models ](/en/docs/models/).
Do not set `DISABLE_PROMPT_CACHING`; it will turn off caching and the bill will noticeably increase, see [Prompt Caching ](/en/docs/prompt-caching/).
## FAQ
Claude Code did not read the API key. Check the variable name spelling; if using environment variables, confirm you started in a newly opened terminal; if using settings.json, confirm the JSON format is correct (one extra comma will make the whole thing fail).
The API key was copied incompletely, or `ANTHROPIC_API_KEY` and `ANTHROPIC_AUTH_TOKEN` both exist and one of them is an old value. Keep only one of the two. See more in [error codes and troubleshooting ](/en/docs/troubleshooting/).
`ANTHROPIC_BASE_URL` has an extra `/v1` written. Change it to `https://1zheai.com`.
This is Claude Code running small background tasks with the Haiku tier. To switch to another model, set `ANTHROPIC_DEFAULT_HAIKU_MODEL`.
Delete (or comment out) the two variables above to return to official login. If you switch often, use [CC Switch ](/en/docs/quickstart-cc-switch/); one click to switch.
No association will be created. When connecting to 1折AI, Claude Code uses our API key and does not log in to your Anthropic account.
---
# Codex CLI Integration
Source: https://1zheai.com/en/docs/quickstart-codex/
Markdown: https://1zheai.com/en/docs/quickstart-codex.md
---
title: "Codex CLI Integration"
description: "Configuration method for integrating OpenAI Codex CLI with 1折AI (model_providers in ~/.codex/config.toml), calling GPT models via the Responses API."
headingIds: {"Configuration File":"section-1","Installing Codex":"section-2","FAQ":"section-3"}
---
OpenAI / GPT models are now live. Codex CLI uses the OpenAI Responses API (`/v1/responses`) and connects using the API key from this site. For available models and pricing, see the [model catalog](https://1zheai.com/model-catalog).
First, let's clarify how to configure a custom provider for Codex. The format comes from the [official Codex configuration documentation](https://developers.openai.com/codex/config-reference).
## Configuration File
Codex's configuration lives in `~/.codex/config.toml`. Custom providers can only be written in this user-level file; the `.codex/config.toml` setting `model_provider` in a project will be ignored.
```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"
```
The example uses `gpt-6-astra`, which can be replaced with any other GPT model ID supported by your key.
Meaning of each field:
| Field | Description |
|---|---|
| `model_provider` | Which provider to use, corresponding to the id under `[model_providers.]` below. `openai`, `ollama`, `lmstudio` are reserved names and cannot be used |
| `base_url` | Must include `/v1` |
| `env_key` | Codex reads the API key from this environment variable; the name must exactly match what you export |
| `wire_api` | The official documentation states that currently only `responses` is supported; it is also the default when omitted |
Then put the API key into an environment variable:
```bash title="macOS / Linux"
export ONEZHE_API_KEY="sk-你的Key"
```
```powershell title="Windows PowerShell"
[Environment]::SetEnvironmentVariable("ONEZHE_API_KEY", "sk-你的Key", "User")
```
## Installing Codex
The following commands come from the official Codex documentation:
```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"
```
## FAQ
The variable name in `env_key` does not match what you actually exported, or you opened the terminal before setting the environment variable. Double-check the names on both sides, then reopen the terminal and try again.
No. The official Codex configuration documentation states that `wire_api` only accepts `responses`. Services that only provide a Chat Completions API need an additional protocol conversion tool to connect to Codex.
Check the current models in the [model catalog](https://1zheai.com/model-catalog) and fill the model ID into `model`. After starting Codex, make a short request and verify the model and status in the [call log](/en/docs/usage-logs/).
---
# Connecting OpenCode to the Claude API
Source: https://1zheai.com/en/docs/quickstart-opencode/
Markdown: https://1zheai.com/en/docs/quickstart-opencode.md
---
title: "Connecting OpenCode to the Claude API"
description: "A tutorial on configuring OpenCode to use the 1折AI Claude API relay, covering the endpoint address, API key, and models — including protocol selection, configuration examples, verification steps, and common errors."
headingIds: {"OpenCode v1 Configuration":"section-1","OpenCode v2 Configuration":"section-2","Verifying the Connection and Troubleshooting":"section-3","Pricing and Other Integration Methods":"section-4"}
---
Use OpenCode's custom provider feature to connect to 1折AI. First, [create an API key](/en/docs/api-keys/), and confirm the [currently available models](/en/docs/models/); the model IDs below are examples — adjust them according to your key's permissions.
Official configuration verification date: 2026-10-15. The following configuration is compiled from the official documentation; end-to-end verification on this site has not yet been completed. Please first complete a brief Q&A and tool-call verification before using it for long-running tasks. OpenAI / GPT models are now live; see the [model notes](/en/docs/models/) for the model list and pricing.
## OpenCode v1 Configuration
Based on [official v1 Providers](https://opencode.ai/docs/providers/): run `/connect`, choose Other, enter `onezhe` as the provider ID, and fill in this site's API key. Merge into the project's `opencode.json`:
```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" }
}
}
}
}
```
Then use `/models` to select that provider's model. `/connect` only stores credentials and does not replace the provider configuration. Here we explicitly select the SDK for Chat Completions; it must not be mistakenly swapped for `@ai-sdk/openai`, which is used for Responses. The official docs also allow referencing environment variables via `options.apiKey: "{env:ONEZHE_API_KEY}"`.
## OpenCode v2 Configuration
Based on [official v2 Providers](https://opencode.ai/v2/docs/providers), use the native v2 fields — they must not be mixed with the v1 fields above. Merge into the project's `opencode.jsonc`:
```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" }
}
}
}
}
```
Provide `ONEZHE_API_KEY` in the environment of the process that launches OpenCode, then use `/models` to select `onezhe/claude-sonnet-4-6`. The main differences in v2 are `providers`, `package`, and `settings`, rather than v1's `provider`, `npm`, and `options`. Please first use `opencode --version` to confirm the major version in use.
To use native Anthropic, v1 officially allows overriding `provider.anthropic.options.baseURL`, with examples including `/v1`; v2 lists `@opencode/ai/providers/anthropic-compatible`. This tutorial follows an explicit OpenAI-compatible configuration; you must not switch protocols based on the model name alone, nor assume that caching and tool calls have already been verified.
## Verifying the Connection and Troubleshooting
1. Save and reload the configuration, and confirm that the currently selected provider is `onezhe` or the custom model you added.
2. Send a short question and confirm it returns a response; then try a small, reversible task to separately verify tool calls and multi-turn conversation.
3. Open the [call logs](/en/docs/usage-logs/) and check the request time, model, status, and usage. A single successful text reply does not mean all Agent capabilities are compatible.
4. If you encounter a 404, check whether the address and protocol in this article match; if you encounter a 401, check the key's origin and whether the process read the environment variable; if you encounter a 429, review the rate-limit information before retrying. See [error codes and troubleshooting](/en/docs/troubleshooting/) for more cases.
Keys should only be stored in your local environment or the tool's credential store — never commit them to a code repository, screenshots, or public logs. Background services may not inherit terminal environment variables; auxiliary models, search, and other tools may also have independent provider settings that need to be checked separately.
## Pricing and Other Integration Methods
Check [Claude API real-time pricing](https://1zheai.com/en/pricing/) and [billing rules](/en/docs/pricing-explained/). If you need other clients, return to the [tool integration directory](/en/docs/integrations/); if you are writing your own program, use the [SDK and development guide](/en/docs/guides/).
---
# Cursor Integration
Source: https://1zheai.com/en/docs/quickstart-cursor/
Markdown: https://1zheai.com/en/docs/quickstart-cursor.md
---
title: "Cursor Integration"
description: "Call 1折AI's Claude models in Cursor using a custom OpenAI API key and Base URL, and which features do not use the custom API key."
headingIds: {"Configuration":"section-1","Known Issues":"section-2","FAQ":"section-3"}
---
Cursor allows you to enter your own API key in settings, and chat models use this API key to send requests. Below is how to connect to 1折AI, along with several limitations you must know first.
Understand these three points before you start:
- According to Cursor's official documentation, **custom API keys only apply to chat models; Tab completion always uses Cursor's own models**.
- Requests pass through Cursor's servers first before being sent to the address you entered, so the Base URL must be publicly accessible (`https://1zheai.com/v1` works fine; a local `localhost` proxy does not).
- The "Override OpenAI Base URL" toggle is not in Cursor's official documentation. The interface description below comes from the Cursor forum and community tutorials, and may change after Cursor updates.
## Configuration
Cursor → **Cursor Settings** → **Models**, find the Keys section.
```text
OpenAI API Key sk-你的Key（1折AI 的 Key）
Override OpenAI Base URL https://1zheai.com/v1
```
The Base URL must include `/v1`.
Click **Add model** in the model list, enter the model ID, for example `claude-sonnet-5-5`, then turn on its toggle. For model IDs, see [supported models ](/en/docs/models/).
Select the newly added model in the Chat panel and send a message. After the reply comes back normally, go to the console [call logs ](/en/docs/usage-logs/) to confirm this call.
## Known Issues
There is feedback on the Cursor forum: after setting Override OpenAI Base URL, models whose names start with `claude-` may be treated by Cursor as Anthropic models, handled by the Anthropic API key, or cause an error directly. When selecting Claude, the model ID starts with `claude-`. If you encounter this issue, first clear any Anthropic API key you have entered in Cursor and try again.
Reference: [forum post 144899 ](https://forum.cursor.com/t/anthropic-models-break-when-override-openai-baseurl-is-set/144899), [forum post 146998 ](https://forum.cursor.com/t/override-anthropic-base-url-automatically-switches-on-when-using-anthropic-byok/146998).
## FAQ
No. According to Cursor's official documentation, Tab completion always uses Cursor's built-in models and does not go through your API key.
First confirm that the Base URL includes `/v1`. Community feedback indicates that the Verify button does not necessarily pass for non-OpenAI model names. You can send a message directly in Chat to test; the deciding factor is whether there is a record in the call logs.
Community tutorials generally report that only Chat uses the custom API key; features such as Agent, Apply, and Inline Edit may still go through Cursor's own backend. Rely on the records you actually see in the call logs.
If you mainly want to use Claude for writing code, [Claude Code ](/en/docs/quickstart-claude-code/) (command line or VS Code extension) and [Cline ](/en/docs/quickstart-cline/) have more complete support for custom addresses.
---
# Cline Integration
Source: https://1zheai.com/en/docs/quickstart-cline/
Markdown: https://1zheai.com/en/docs/quickstart-cline.md
---
title: "Cline Integration"
description: "Integrate 1折AI in the Cline extension for VS Code: either via Anthropic custom Base URL or OpenAI Compatible."
headingIds: {"Method 1: Anthropic (Recommended)":"section-1","Method 2: OpenAI Compatible":"section-2","FAQ":"section-3"}
---
Cline is a coding Agent extension for VS Code. Both methods can connect to 1折AI; the Anthropic method is recommended, as Claude's native capabilities (including caching) are more complete.
## Method 1: Anthropic (Recommended)
Open Cline settings and select **Anthropic** for **API Provider**.
- **Anthropic API Key** (enter your API key): `sk-你的Key`
- Check **Use custom base URL** and enter `https://1zheai.com` (do not add `/v1`)
Select a model supported by 1折AI from the model dropdown [supported models ](/en/docs/models/), for example `claude-sonnet-5-5`.
## Method 2: OpenAI Compatible
Select **OpenAI Compatible** for **API Provider**.
| Field | Value |
|---|---|
| Base URL | `https://1zheai.com/v1` |
| API Key | `sk-你的Key` |
| Model ID | `claude-sonnet-5-5` |
Click **Verify** to confirm the connection, then send a small task in Cline.
In Model Configuration you can fill in the context window and maximum output length; enter the values for the corresponding model according to the [Anthropic official model documentation ](https://platform.claude.com/docs/en/about-claude/models/overview).
## FAQ
The Anthropic method uses the native `/v1/messages`, so capabilities such as caching and thinking are the most complete; OpenAI Compatible uses `/v1/chat/completions` and is more universal. When using Claude models, prefer Anthropic.
The address for the Anthropic method must not include `/v1`; the address for the OpenAI Compatible method must include `/v1`. The two are exactly opposite.
---
# Cherry Studio Integration
Source: https://1zheai.com/en/docs/quickstart-cherry-studio/
Markdown: https://1zheai.com/en/docs/quickstart-cherry-studio.md
---
title: "Cherry Studio Integration"
description: "Add 1折AI as a custom provider in Cherry Studio by choosing the Anthropic or OpenAI endpoint and entering the base URL, API key, and models."
headingIds: {"One-Click Import":"section-1","Configuration":"section-2","Choosing the Anthropic or OpenAI Endpoint":"section-3","FAQ":"section-4"}
---
Cherry Studio is a desktop AI chat client where you can add 1折AI as a custom provider.
## One-Click Import
In the console, under **API Keys → Tools → Cherry Studio**, select the Anthropic or OpenAI protocol and click **Open Cherry Studio**. After confirming the import in the app, fetch the models, enable the provider, and test it. If a configuration with the same name already exists, check the overwrite prompt. The import link contains the full key — do not forward it.
The browser cannot confirm whether the app is installed. If it does not launch, install and start the client once first, or use the manual steps below. The protocol format has been checked against the official implementation, but actual inference still needs to be verified against your specific version and model.
## Configuration
Settings (gear icon) → **Model Services** → **+ Add Provider** at the bottom of the list.
| Field | What to enter |
|---|---|
| Provider Name | `1折AI` |
| API Key | `sk-你的Key` |
| Endpoint | Select **Anthropic** (recommended) or **OpenAI** |
| API Address | `https://1zheai.com` |
Enter only the base URL in the API Address field; Cherry Studio will automatically append `/v1/...` based on the selected protocol. Do not paste full paths like `/v1/messages` or `/v1/chat/completions`, and do not add `#` at the end (a trailing `#` means no path will be appended automatically).
Click **Get Model List** and add the models you want to use from the returned list; or click **+** to manually enter a model ID, such as `claude-sonnet-5-5`. Only models added to the list will appear in the model selector in the chat.
Turn on the enable toggle in the top-right corner of the provider page, return to the chat interface, and send a message using a model under 1折AI.
## Choosing the Anthropic or OpenAI Endpoint
| Endpoint | Best for |
|---|---|
| Anthropic | Using Claude-native capabilities such as extended thinking; refer to the current version for the Agent's protocol restrictions |
| OpenAI | Being used to the OpenAI format, or managing alongside other OpenAI-compatible services |
Both endpoints use the same API key and the same set of model IDs.
## FAQ
First check whether the API key has extra spaces; then confirm the API address is `https://1zheai.com` with no extra path written. If you cannot fetch the list, it does not affect usage — manually entering a model ID also works.
The API address was entered as a full path, or `#` was added at the end. Change it back to the base URL `https://1zheai.com`.
---
# Dify Integration
Source: https://1zheai.com/en/docs/quickstart-dify/
Markdown: https://1zheai.com/en/docs/quickstart-dify.md
---
title: "Dify Integration"
description: "Configure 1折AI using the official Dify OpenAI-API-compatible plugin, covering model setup, conversation testing, and troubleshooting the first call."
headingIds: {"Prerequisites":"section-1","Adding a Model":"section-2","Starting from the First Conversation":"section-3","Importing the Example Chatflow":"section-4","Troubleshooting":"section-5","Getting Integration Help":"section-6","Verification Scope":"section-7","English / Русский":"section-8"}
---
Dify users can configure 1折AI's OpenAI-compatible endpoint through the official **OpenAI-API-compatible** model plugin. First verify a text model, then use it in workflows; there is no need to install unverified third-party plugins.
## Prerequisites
- A Dify workspace where model plugins can be installed.
- Your own 1折AI API key, plus the model IDs that key is authorized to call. Check the [console](https://1zheai.com/console).
- Sufficient available balance in your account. The validation request when saving a model and application tests may incur normal API charges.
Do not send your full key to customer support, write it into workflow descriptions, screenshots, or public repositories. Store it only in Dify's API Key field; if you use a third-party hosted Dify, that instance holds your key and forwards requests.
## Adding a Model
1. In the Dify plugin marketplace, find **OpenAI-API-compatible** and confirm the publisher is **langgenius**.
2. Open the model providers in workspace settings, locate this plugin, and add an LLM model.
3. Fill in the fields below and save. The interface labels may vary by Dify version.
| Field | How to fill it in |
| --- | --- |
| Model Name | Copy the full model ID from the 1折AI console; do not substitute the display name |
| API Key | Your own 1折AI key |
| API Base URL | `https://1zheai.com/v1` |
| Completion mode | `Chat` |
| Model name in the API endpoint | Usually leave blank; if set, it must match the actual model ID |
| Model context size | Fill in according to the selected model's actual capability; do not copy another model's context length |
Here you need `/v1`. Do not enter the full `/v1/chat/completions`, and do not duplicate it as `/v1/v1`. Do not apply instructions from other clients that only require the root address.
## Starting from the First Conversation
Create a blank chat app, select the model you just saved, and enter "Please introduce what you can do in one sentence in Chinese." Once a complete text response is confirmed, verify streaming output next.
Check the corresponding request time, model, and result in the call logs of the 1折AI console. Do not rely solely on Dify's "Saved successfully" as proof that the app is connected. Only after the first success should you configure tool calls, vision input, or knowledge base retrieval; these capabilities depend on the specific model and interface, and a successful text conversation does not mean everything is available.
## Importing the Example Chatflow
[Download the keyless Chatflow template](/en/docs/downloads/1zheai-dify-chatflow.yml), then in Dify Studio choose **Create → Import DSL file** to upload it. The template is `User Input → LLM → Answer`, DSL version 0.7.0, using the official compatible plugin 0.0.68.
First add your own credentials following the steps above. After importing, open the LLM node and confirm your own provider and model are selected, not Dify's trial model. The example model ID is `claude-haiku-4-5-20251001`; if it is unavailable to your account, switch to a model you have access to and check the capability settings. The template contains no API key and does not provide free call credits.
## Troubleshooting
| Symptom | What to check first |
| --- | --- |
| 503 / No available accounts | The current upstream may be rate-limited or out of capacity. Check the service status and call logs first, retry with backoff later or contact support; do not retry at high frequency continuously, and do not repeatedly regenerate keys |
| 401 / Invalid key | Whether there are extra spaces, whether the key has been revoked, and whether a key from another platform was used by mistake |
| 404 | Whether the Base URL is exactly `https://1zheai.com/v1`; whether the model ID exists |
| Model not permitted or insufficient balance | The model restrictions of the current key, the account's available balance, and the selected model |
| Saved successfully, but the app cannot call | Whether the app selected the correct provider and model; whether the workspace server can reach the API |
| Normal responses work, streaming fails | Check the proxy's SSE support, the plugin version, and the streaming usage setting; keep a redacted error for troubleshooting |
| Tool calls or vision fail | First confirm the selected model actually supports that capability; avoid forcing it on by only toggling plugin switches |
Requests from self-hosted Dify are sent by its server; the fact that your browser can open the official site does not mean the Dify server can connect to the API.
## Getting Integration Help
Provide the Dify version, plugin version, model ID, error timestamp, request ID, and redacted error details through the official site's online customer service. Do not send the full key, customer data, or private prompts from your workflows.
## Verification Scope
On 2026-10-19, using the official plugin 0.0.68, Haiku text conversation and streaming calls were completed in Dify Cloud and matched against the gateway logs. The exported keyless DSL was imported into the same workspace as a new app. After import, a retest encountered a 503 caused by upstream rate limiting, so this round is not recorded as a post-import run passing.
This is an internal test with a defined time window, not a continuous availability guarantee. Fresh workspaces, older Dify versions, tool calls, vision, and knowledge base retrieval have not been verified; please complete your first test with your own rate-limited key.
[Official plugin source](https://github.com/langgenius/dify-official-plugins/tree/main/models/openai_api_compatible) · [Dify plugin marketplace](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. Новое рабочее пространство и расширенные функции ещё не проверены. Не отправляйте ключ службе поддержки. Доступность из конкретной сети и способы оплаты проверяются отдельно.
---
# Connecting WorkBuddy to the Claude API
Source: https://1zheai.com/en/docs/quickstart-workbuddy/
Markdown: https://1zheai.com/en/docs/quickstart-workbuddy.md
---
title: "Connecting WorkBuddy to the Claude API"
description: "A tutorial on configuring the address, key, and model for the 1折AI Claude API relay in WorkBuddy, including protocol selection, configuration examples, verification steps, and common errors."
headingIds: {"Verifying the Connection and Troubleshooting":"section-1","Costs and Other Connection Methods":"section-2"}
---
Use WorkBuddy's custom provider feature to connect to 1折AI. First, [create an API key](/en/docs/api-keys/), and confirm the [currently available models](/en/docs/models/); the model IDs below are examples, so adjust them according to your key's permissions.
Official configuration verification date: 2026-10-15. The following configuration is compiled based on official documentation; end-to-end verification on this site has not yet been completed. Please first complete a brief Q&A and tool-call verification before using it for long tasks. OpenAI / GPT models are now live; see [the model description](/en/docs/models/) for the model list and pricing.
Based on [the official model configuration](https://www.workbuddy.cn/docs/workbuddy/From-Beginner-to-Expert-Guide/Function-Description/Model): Settings → Models → Add Model → Custom. Fill in this site's key and the model `claude-sonnet-4-6`.
Use the full request URL configuration: enable "Custom Protocol" in Advanced Configuration, enter `https://1zheai.com/v1/chat/completions` as the URL, and after saving, select that model in the conversation model selector. The official documentation states that enabling this switch will use the entered URL directly, without path validation or automatic completion; when disabled, it will complete according to the standard `/chat/completions`. Therefore, the full URL and the switch must be described together.
Here, "Custom Protocol" does not mean that OpenAI requests can be automatically converted into Anthropic requests. You cannot enter `/v1/messages` and then claim that the native Claude protocol is connected. Prefer the UI; do not provide unverified manual formats like `models.json`. The official page simultaneously shows the current local configuration path and old `~/.codebuddy/models.json` migration notes; avoid writing the old path as a universal current path based on this. The tool capability markers on the interface also cannot replace end-to-end verification on this site.
## Verifying the Connection and Troubleshooting
1. Save and reload the configuration, and confirm that the currently selected item is the `onezhe` provider or the custom model you added.
2. Send a short question to confirm that a response can be returned; then try a small, reversible task to separately verify tool calls and multi-turn conversation.
3. Open the [call log](/en/docs/usage-logs/) and check the request time, model, status, and usage. A single successful text response does not mean that all Agent capabilities are compatible.
4. If you encounter a 404, check whether the address and protocol in this article match; if you encounter a 401, check the key source and whether the process read the environment variables; if you encounter a 429, check the rate-limiting information before retrying. See [error codes and troubleshooting](/en/docs/troubleshooting/) for more situations.
Keys should only be stored in the local environment or the tool's credential store; do not commit them to code repositories, screenshots, or public logs. Background services may not inherit terminal environment variables; auxiliary models, search, and other tools may also have independent provider settings that need to be checked separately.
## Costs and Other Connection Methods
Check [Claude API real-time pricing](https://1zheai.com/en/pricing/) and [billing rules](/en/docs/pricing-explained/). If you need other clients, return to the [tool connection directory](/en/docs/integrations/); if you are writing your own program, use the [SDK and development guide](/en/docs/guides/).
---
# Chatbox One-Click Import and Configuration
Source: https://1zheai.com/en/docs/quickstart-chatbox/
Markdown: https://1zheai.com/en/docs/quickstart-chatbox.md
---
title: "Chatbox One-Click Import and Configuration"
description: "Import Chatbox from the API Key page and verify API Host, path, model, and key."
headingIds: {"One-Click Import":"section-1","Clipboard and Manual Configuration":"section-2","Troubleshooting":"section-3"}
---
Chatbox 1.15.1 and later supports provider JSON and `chatbox://provider/import`. The desktop version must be installed and launched once first. For the web version or systems without a registered protocol, use clipboard import.
## One-Click Import
1. Open **API Keys** in the console, find the key you want to use, and go to **Use Tools → Chatbox**.
2. Select a chat model available for this key, then click **Open Chatbox** and allow the browser to open the app.
3. Confirm the import in Chatbox and check the provider address and model. If a configuration with the same name already exists, first verify the scope of the overwrite.
4. Send a short message and check the model and request time in the call logs on this site.
## Clipboard and Manual Configuration
If the app does not launch, copy **Chatbox JSON** from the same panel, then go to provider management in Chatbox settings and choose to import from the clipboard. You must delete `settings.apiKey` before sharing with others.
| Field | Value |
| --- | --- |
| Type | OpenAI API compatible |
| API Host | `https://1zheai.com` |
| API Path | `/v1/chat/completions` |
| API Key | Current key |
| Model ID | Chat model available for the current key |
Fill in Host and Path separately; do not add `/v1` to both fields at once. If there is no model, first fetch the model list or add one manually; capabilities such as images, embeddings, and tool calls must each be verified separately — do not treat an arbitrary model as a chat model.
## Troubleshooting
- App does not open: confirm the app is installed and has been launched, unblock this protocol in the browser, or use clipboard import.
- 401 after import: check whether the key is valid and contains no spaces.
- 404: confirm the final path is `/v1/chat/completions` and has not been concatenated twice.
- Model does not exist: use the exact ID from the model list; do not guess based on the display nickname.
Official: [Configuration import protocol ](https://docs.chatboxai.app/guides/providers/import-config), [Client source code ](https://github.com/chatboxai/chatbox/blob/main/src/renderer/utils/provider-config.ts).
protocol verified against official materials on 2026-10-19. This site has implemented configuration generation and frontend regression testing; real inference verification across all clients, systems, and models has not been completed. Please re-verify after client upgrades. Custom integration does not imply official partnership or built-in recommendation.
More: [API Keys ](/en/docs/api-keys/), [Model list ](/en/docs/models/), [Call logs ](/en/docs/usage-logs/), [Address notes ](/en/docs/base-url/).
---
# RikkaHub QR Code Import
Source: https://1zheai.com/en/docs/quickstart-rikkahub/
Markdown: https://1zheai.com/en/docs/quickstart-rikkahub.md
---
title: "RikkaHub QR Code Import"
description: "Import an OpenAI-compatible provider into Android RikkaHub via QR code, configure models, and troubleshoot."
headingIds: {"QR Code Configuration":"section-1","Manual Fallback":"section-2","Troubleshooting":"section-3"}
---
RikkaHub is an Android AI client. This site uses its `ai-provider:v1:` share format to generate a local QR code, without calling any third-party QR code website.
## QR Code Configuration
1. In the console, go to **API Keys → Tools → RikkaHub**.
2. In a private environment, tap **Show Import QR Code**. The QR code is equivalent to the full key; do not share screenshots of it.
3. In RikkaHub, go to **Settings → Provider Settings → Import** and choose QR code scanning. If both ends are on the same phone, use the client's import-from-image feature, and delete the screenshot containing the key after importing.
4. After importing, fetch the model list, select a chat model, send a short message, then confirm on this site's call log.
5. When done, hide the QR code. If it was accidentally sent to someone else, revoke that key and create a new one.
## Manual Fallback
| Field | Value |
| --- | --- |
| Type | OpenAI |
| Base URL | `https://1zheai.com/v1` |
| Chat Completions Path | `/chat/completions` |
| API Key | Current key |
Import does not pre-configure model capabilities or context length, nor does it enable the Responses toggle. If you need Responses, first verify the selected model and client version, then validate separately.
## Troubleshooting
If QR code scanning fails, first check that the QR code is complete, the screen is clear, and the client version is correct; if it still fails, use the manual fields. If the model list fails, check the key and address; insufficient permissions cannot be resolved by rescanning the QR code.
Official: [Quick Start ](https://github.com/rikkahub/docs/blob/main/quickstart.mdx), [Share Format Implementation ](https://github.com/rikkahub/rikkahub/blob/master/app/src/main/java/me/rerere/rikkahub/ui/components/ui/ShareSheet.kt).
protocol and official materials verified on 2026-10-19. This site has implemented configuration generation and frontend regression testing; real inference verification across all clients, systems, and models has not been completed. Please re-verify after client upgrades. Custom integration does not imply official partnership or built-in recommendation.
More: [API Keys ](/en/docs/api-keys/), [Model List ](/en/docs/models/), [Call Log ](/en/docs/usage-logs/), [Address Notes ](/en/docs/base-url/).
---
# ChatWise Custom Provider
Source: https://1zheai.com/en/docs/quickstart-chatwise/
Markdown: https://1zheai.com/en/docs/quickstart-chatwise.md
---
title: "ChatWise Custom Provider"
description: "Add an OpenAI-compatible provider in ChatWise settings by entering the key, address, and model."
headingIds: {"Import Capability and Verification":"section-1"}
---
Create a custom OpenAI-compatible provider in ChatWise under **Settings → Providers → +**. The console **API Keys → Tools → ChatWise** provides copyable fields.
| Field | Value |
| --- | --- |
| API URL / Base URL | `https://1zheai.com/v1` |
| API Key | Current key |
| Model | Select after fetching models, or manually enter a model ID |
The model list endpoint is `/v1/models`. If the current version requires a full request address rather than a Base URL, enter `https://1zheai.com/v1/chat/completions`; refer to the field description as the source of truth. Disable any unnecessary third-party proxies before testing a direct connection.
## Import Capability and Verification
The officially public `chatwise://chat` is used to open conversations, not to import provider keys. This site does not disguise it as a configuration import button. Image, reasoning, and tool capabilities must be configured according to what each model actually supports; do not enable everything by default.
Send a short message and check this site's logs. For 401, check the key; for 404, check whether the address field expects a full path; if no models appear, manually enter a currently available ID first.
Official: [Custom Provider ](https://docs.chatwise.app/custom-provider), [Open App Agreement ](https://docs.chatwise.app/open-from-other-apps).
agreement and official materials were verified on 2026-10-19. This site has implemented configuration generation and frontend regression testing; real inference verification across all clients, systems, and models has not been completed. Re-verify after client upgrades. Custom integration does not imply official partnership or built-in recommendation.
More: [API Keys ](/en/docs/api-keys/), [Model List ](/en/docs/models/), [Call Logs ](/en/docs/usage-logs/), [Address Notes ](/en/docs/base-url/).
---
# LibreChat Custom Endpoint
Source: https://1zheai.com/en/docs/quickstart-librechat/
Markdown: https://1zheai.com/en/docs/quickstart-librechat.md
---
title: "LibreChat Custom Endpoint"
description: "Administrators configure LibreChat custom endpoints; users enter their own API keys individually."
headingIds: {"Administrator Configuration":"section-1","Verification and Troubleshooting":"section-2"}
---
LibreChat requires a deployment administrator to allow custom endpoints; ordinary users cannot rewrite remote server configuration using this site's buttons. The console **API Keys → Use Tools → LibreChat** provides a configuration snippet.
## Administrator Configuration
Merge into the existing `librechat.yaml` the `endpoints.custom`; do not overwrite other endpoints:
```yaml
endpoints:
custom:
- name: '1折AI'
apiKey: user_provided
baseURL: 'https://1zheai.com/v1'
models:
default: []
fetch: true
```
Apply the configuration validation required by the current version and restart the service, then have users enter their own keys in LibreChat's API key settings. The shared configuration does not contain real keys. If model retrieval fails, the administrator can set `default` to a verified working model ID and check the server's outbound network access.
## Verification and Troubleshooting
Select the newly added endpoint and model, send a brief request, then check this site's call logs. If the endpoint does not appear, first check whether the configuration mount location and restart took effect; for 401, check the key entered by the user; for 404, check that the Base URL is `/v1` and not the full request path. Do not store keys on untrusted public LibreChat instances.
Official: [Custom endpoint fields](https://www.librechat.ai/docs/configuration/librechat_yaml/object_structure/custom_endpoint).
protocol and official materials verified on 2026-10-19. This site has implemented configuration generation and front-end regression testing; real inference verification across all clients, systems, and models has not been completed. Please re-verify after client upgrades. Custom integration does not imply official partnership or built-in recommendation.
More: [API Keys](/en/docs/api-keys/), [Model List](/en/docs/models/), [Call Logs](/en/docs/usage-logs/), [Address Notes](/en/docs/base-url/).
---
# Connecting OpenClaw to the Claude API
Source: https://1zheai.com/en/docs/quickstart-openclaw/
Markdown: https://1zheai.com/en/docs/quickstart-openclaw.md
---
title: "Connecting OpenClaw to the Claude API"
description: "A tutorial on configuring OpenClaw to use the 1折AI Claude API relay, covering the endpoint address, API key, and model selection, along with protocol choices, configuration examples, verification steps, and common errors."
headingIds: {"Verifying the Connection and Troubleshooting":"section-1","Costs and Other Integration Methods":"section-2"}
---
Use OpenClaw's custom provider feature to connect to 1折AI. First, [create an API key](/en/docs/api-keys/) and confirm the [currently available models](/en/docs/models/). The model IDs below are examples; adjust them according to your key's permissions.
Official configuration verification date: 2026-10-15. The following configuration is compiled based on official documentation; end-to-end verification on this site has not yet been completed. Please first complete a short Q&A and tool-call verification before using it for long tasks. OpenAI / GPT models are now live; see the [model description](/en/docs/models/) for the model list and pricing.
Based on [custom provider](https://docs.openclaw.ai/gateway/config-tools/custom-providers) and [configuration example](https://docs.openclaw.ai/gateway/configuration-examples), merge in `~/.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" }
]
}
}
}
}
```
Make sure the process actually running the Gateway can read `ONEZHE_API_KEY`; environment variables in your terminal are not necessarily passed to an existing background service. The [official Synthetic documentation](https://docs.openclaw.ai/providers/synthetic) explicitly states that the Anthropic client automatically appends `/v1`, so do not include `/v1` here, nor fill in the full `/v1/messages`.
When switching to Chat Completions, replace them as a pair with `baseUrl: "https://1zheai.com/v1"` and `api: "openai-completions"`. Despite the name containing "completions", this adapter corresponds to `/v1/chat/completions`; do not mistakenly select `openai-responses`. If you already have a model allowlist, keep the other entries and add the new model. The examples do not fabricate cost or context parameters; if your currently installed version's validation requires additional metadata, verify the actual model capabilities before adding them.
## Verifying the Connection and Troubleshooting
1. Save and reload the configuration, and confirm that the currently selected provider is `onezhe` or the custom model you added.
2. Send a short question to confirm a response is returned; then try a small, reversible task to separately verify tool calls and multi-turn conversation.
3. Open the [call log](/en/docs/usage-logs/) and check the request time, model, status, and usage. A single successful text response does not mean all Agent capabilities are compatible.
4. If you encounter a 404, check whether the address and protocol in this article match; if you encounter a 401, check the key's origin and whether the process read the environment variables; if you encounter a 429, review the rate-limiting information before retrying. For more cases, see [error codes and troubleshooting](/en/docs/troubleshooting/).
Store keys only in your local environment or the tool's credential store; do not commit them to code repositories, screenshots, or public logs. Background services may not inherit terminal environment variables; auxiliary models, search, and other tools may also have independent provider settings that need to be checked separately.
## Costs and Other Integration Methods
Check [Claude API real-time pricing](https://1zheai.com/en/pricing/) and [billing rules](/en/docs/pricing-explained/). If you need other clients, return to the [tool integration directory](/en/docs/integrations/); if you are writing your own program, use the [SDK and developer guide](/en/docs/guides/).
---
# Hermes Agent Integration with Claude API
Source: https://1zheai.com/en/docs/quickstart-hermes/
Markdown: https://1zheai.com/en/docs/quickstart-hermes.md
---
title: "Hermes Agent Integration with Claude API"
description: "Tutorial on configuring the 1折AI Claude API relay address, key, and model in Hermes Agent, including protocol selection, configuration examples, verification steps, and common errors."
headingIds: {"Verify the Connection and Troubleshoot":"section-1","Costs and Other Access Methods":"section-2"}
---
Use the custom provider feature of Hermes Agent to connect to 1折AI. First [create an API key ](/en/docs/api-keys/), and confirm the [currently available models ](/en/docs/models/); the model IDs below are examples — adjust them according to your key's permissions.
Official configuration verification date: 2026-10-15. The following configuration is compiled from official documentation; end-to-end verification on this site has not yet been completed; please first complete a short Q&A and tool-call verification before using it for long tasks. OpenAI / GPT models are now live; see the [model description ](/en/docs/models/) for the model list and pricing.
Based on [official Providers ](https://hermes-agent.nousresearch.com/docs/integrations/providers): run `hermes model` in the terminal → Custom endpoint, explicitly select `chat_completions` for API mode, fill in `https://1zheai.com/v1` for Base URL, and enter the key and model. Do not select ChatGPT/Codex login — it is a different access method.
Reusable named provider configuration, merge into `~/.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
```
Served locally at `~/.hermes/.env`:
```dotenv
ONEZHE_API_KEY=sk-替换为本站密钥
```
Once configured, you can switch `/model custom:onezhe:claude-sonnet-4-6` in the conversation. `/model` cannot replace terminal `hermes model` for creating a new provider. Officially `anthropic_messages` transport is supported, but this tutorial uses Chat Completions to avoid automatically guessing the protocol from the URL. `OPENAI_BASE_URL` is not a universal configuration for all custom providers; use the explicit configuration above.
## Verify the Connection and Troubleshoot
1. Save and reload the configuration, and confirm that the currently selected provider is `onezhe` or the custom model you added.
2. Send a short question and confirm it returns; then try a small, reversible task to separately verify tool calls and multi-turn conversation.
3. Open the [call log ](/en/docs/usage-logs/) and check the request time, model, status, and usage. A single successful text response does not mean all Agent capabilities are compatible.
4. If you encounter 404, check whether the address and protocol in this article match; if you encounter 401, check the key source and whether the process read the environment variables; if you encounter 429, review the rate-limit information before retrying. For more cases, see [error codes and troubleshooting ](/en/docs/troubleshooting/).
Keys should only be stored in the local environment or the tool's credential store — do not commit them to code repositories, screenshots, or public logs. Background services may not inherit terminal environment variables; auxiliary models, search, and other tools may also have independent provider settings that need to be checked separately.
## Costs and Other Access Methods
Check [Claude API real-time pricing ](https://1zheai.com/en/pricing/) and [billing rules ](/en/docs/pricing-explained/). For other clients, return to the [tool access directory ](/en/docs/integrations/); to write your own program, use the [SDK and developer guide ](/en/docs/guides/).
---
# Connect via CC Switch
Source: https://1zheai.com/en/docs/quickstart-cc-switch/
Markdown: https://1zheai.com/en/docs/quickstart-cc-switch.md
---
title: "Connect via CC Switch"
description: "Add 1折AI with a custom configuration in CC Switch to switch providers for Claude Code with one click, without manually editing settings.json."
headingIds: {"Installation":"section-1","Adding 1折AI to Claude Code":"section-2","Fetching the Model List":"section-3","Codex":"section-4","FAQ":"section-5"}
---
CC Switch](https://github.com/farion1231/cc-switch) is a desktop tool that helps you manage provider configurations for command-line tools like Claude Code and Codex. After adding it once, switching between your official account, 1折AI, and other providers takes just one click.
## Installation
- macOS: `brew install --cask cc-switch`
- Windows / Linux: download the installer from [GitHub Releases](https://github.com/farion1231/cc-switch/releases)
## Adding 1折AI to Claude Code
Select **Claude Code** in the sidebar, then click **Add Provider** (+) at the top right of the page header.
1折AI is not currently in CC Switch's preset list, so select **Custom Configuration** at the top of the list.
Enter `1折AI` as the name, and set `env` in the configuration editor to:
```json
{
"env": {
"ANTHROPIC_BASE_URL": "https://1zheai.com",
"ANTHROPIC_AUTH_TOKEN": "sk-你的Key"
}
}
```
To also pin a model, add variables such as `ANTHROPIC_MODEL`; see the model mapping section of [Claude Code Integration](/en/docs/quickstart-claude-code/) for the syntax.
Click **Add** in the footer, then enable 1折AI in the provider list. CC Switch writes the configuration into Claude Code's `~/.claude/settings.json`, and Claude Code will use the new provider without a restart.
Run `/status` in Claude Code; the base URL should be `https://1zheai.com`. Send another message and check the console [call logs](/en/docs/usage-logs/) to confirm there is a record.
CC Switch's official example uses `ANTHROPIC_API_KEY`; both variables work. We recommend `ANTHROPIC_AUTH_TOKEN`; see [Claude Code Integration](/en/docs/quickstart-claude-code/) for the reason.
## Fetching the Model List
When editing a provider, the **Fetch Model List** button next to the model input calls `/v1/models` with your API key (API key), lists the available models, and lets you select one to fill in.
## Codex
CC Switch can also manage Codex providers. For configuring this site's Base URL, API key, and GPT models, see [Codex CLI Integration](/en/docs/quickstart-codex/).
## FAQ
First confirm in CC Switch that 1折AI is enabled; then check whether the terminal has exported `ANTHROPIC_BASE_URL` or `ANTHROPIC_AUTH_TOKEN`. Claude Code follows settings.json, but manually exported old variables can easily cause misjudgment; it is recommended to clear them all and let CC Switch manage everything.
The API key was entered incorrectly or has been deleted. Copy the API key again, and be careful not to include spaces.
---
# CC Provider Configuration
Source: https://1zheai.com/en/docs/quickstart-cc-provider/
Markdown: https://1zheai.com/en/docs/quickstart-cc-provider.md
---
title: "CC Provider Configuration"
description: "Manage custom Anthropic providers with the CC Provider extension for VS Code."
headingIds: {"Configuration Steps":"section-1","Scope and Troubleshooting":"section-2"}
---
This refers to the VS Code extension **onetooken/cc-provider**, not CC Switch. It supports custom Anthropic-compatible endpoints.
## Configuration Steps
1. Install the extension from the official repository link and open its provider panel.
2. Create a new custom provider; the console **API Key → Tools → CC Provider** can copy the corresponding fields.
3. Fill Name with `1折AI`, Base URL with `https://1zheai.com`, and API Token with your own key.
4. Fill in the primary model and any needed model slots according to the currently available models; do not copy model IDs or `[1m]` capability suffixes from other providers.
5. Back up your existing Claude Code configuration before applying, and check the fields that will be changed. Restart sessions that need to read the configuration, then test a short request.
## Scope and Troubleshooting
This site provides field copying; the provider one-click import protocol of this extension has not been verified. The way this client writes to the Claude Code configuration differs from the built-in provider inclusion.
For 401, check the token; for 404, check that the Anthropic root address has not been mistakenly filled with `/v1/messages`; if the model does not exist, switch to a model available with the current key. Confirm that requests appear in this site's call log before using long tasks.
Official: [CC Provider](https://github.com/onetooken/cc-provider).
protocol and official materials were verified on 2026-10-19. This site has implemented configuration generation and frontend regression testing; real inference verification across all clients, systems, and models has not been completed. Please re-verify after client upgrades. Custom integration does not represent official partnership or built-in recommendation.
More: [API Key](/en/docs/api-keys/), [Model List](/en/docs/models/), [Call Log](/en/docs/usage-logs/), [Address Notes](/en/docs/base-url/).
---
# Development Guide
Source: https://1zheai.com/en/docs/guides/
Markdown: https://1zheai.com/en/docs/guides.md
---
title: "Development Guide"
description: "Choose an SDK or HTTP integration method, from your first request to streaming output and caching."
headingIds: {"Continue refining after integration":"section-1","From examples to application":"section-2"}
---
If you already have code, start with the corresponding SDK; if you haven't chosen a tech stack yet, first verify the call with curl, then integrate it into your application.
Use Claude's native protocol and view Python and TypeScript examples. Call GPT or Claude using the OpenAI SDK, configuring the model ID and endpoint address. View HTTP requests directly to rule out SDK configuration differences. Confirm the endpoint, protocol, and applicable scope.
## Continue refining after integration
- [Streaming output ](/en/docs/streaming/): Handle incremental responses and connection drops.
- [Prompt Caching ](/en/docs/prompt-caching/): Understand usage conditions and how to verify results.
- [Error codes and troubleshooting ](/en/docs/troubleshooting/): Locate configuration or upstream issues based on specific errors.
- [Usage logs and reconciliation ](/en/docs/usage-logs/): Verify request records.
When using ready-made software, you can go directly to [tool integration ](/en/docs/integrations/).
## From examples to application
Python / Node.js, from setting environment variables to running the program. Distinguish between configuration errors, temporary failures, and uncertain results. Verify item by item by address, key, model, and protocol. Use the Images API and save the generated results.
---
# Anthropic SDK Integration (Python / TypeScript)
Source: https://1zheai.com/en/docs/quickstart-anthropic-sdk/
Markdown: https://1zheai.com/en/docs/quickstart-anthropic-sdk.md
---
title: "Anthropic SDK Integration (Python / TypeScript)"
description: "Call 1zheAI using the official Anthropic SDK: set base_url to https://1zheai.com. Natively supports caching, streaming, tool calls, and thinking."
headingIds: {"Installation":"section-1","Calling":"section-2","Streaming Output":"section-3","Calls with Caching":"section-4","Using Environment Variables":"section-5","FAQ":"section-6","Request and Response Structure":"section-7"}
---
The official Anthropic SDK uses the native `/v1/messages`, so all Claude parameters can be used directly. The only things to change are `base_url` and `api_key`.
## Installation
```bash title="Python"
pip install anthropic
```
```bash title="TypeScript / Node.js"
npm install @anthropic-ai/sdk
```
## Calling
```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);
```
Fill in the root address in `base_url`; do not add `/v1`.
## Streaming Output
```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();
```
## Calls with Caching
Put long, fixed content into `system` and add `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)
```
On the second call, if `cache_read_input_tokens` is greater than 0, it was a cache hit. See [Prompt Caching](/en/docs/prompt-caching/) for details.
## Using Environment Variables
The official SDK reads `ANTHROPIC_BASE_URL` and `ANTHROPIC_API_KEY`, so you can skip passing parameters when constructing the client:
```bash
export ANTHROPIC_BASE_URL="https://1zheai.com"
export ANTHROPIC_API_KEY="sk-你的Key"
```
Then construct the client without passing parameters:
```python
client = anthropic.Anthropic() # 自动读取上面两个变量
```
If Claude Code on this machine also reads these two variables, they will both switch to 1zheAI, which is usually exactly what you want.
## FAQ
`base_url` has an extra `/v1`. The Anthropic SDK will assemble `/v1/messages` itself.
Check the API key (API key); additionally, if `ANTHROPIC_AUTH_TOKEN` exists in the environment at the same time (for example, an old value previously set for Claude Code), the SDK will also read it — delete the old value and try again.
## Request and Response Structure
To query system, content blocks, and stop reasons, see [Messages API Details](/en/docs/api-messages/). A complete program should read text by content block type and not assume the first block is always text.
---
# OpenAI SDK Integration (Python / Node)
Source: https://1zheai.com/en/docs/quickstart-openai-sdk/
Markdown: https://1zheai.com/en/docs/quickstart-openai-sdk.md
---
title: "OpenAI SDK Integration (Python / Node)"
description: "Call 1折AI's GPT and Claude models using the official OpenAI SDK: just change base_url and api_key, with streaming examples and environment variable usage included."
headingIds: {"Installation":"section-1","Calling":"section-2","Streaming Output":"section-3","Using Environment Variables Without Changing Code":"section-4","When to Switch to the Anthropic SDK":"section-5","FAQ":"section-6","Responses and Complete Programs":"section-7"}
---
If you already have code written with the OpenAI SDK, switching to 1折AI only requires changing two parameters: `base_url` and `api_key`. Fill in the model name with a currently available GPT or Claude model ID.
## Installation
```bash title="Python"
pip install openai
```
```bash title="Node.js"
npm install openai
```
## Calling
```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` must include `/v1`.
## Streaming Output
```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 ?? "");
}
```
## Using Environment Variables Without Changing Code
The official OpenAI SDK (Python and Node) reads `OPENAI_BASE_URL` and `OPENAI_API_KEY`. When no parameters are passed in the code, setting these two variables is enough to switch over:
```bash
export OPENAI_BASE_URL="https://1zheai.com/v1"
export OPENAI_API_KEY="sk-你的Key"
```
Note that this affects all programs using the OpenAI SDK in the same environment.
## When to Switch to the Anthropic SDK
The OpenAI-compatible interface is suitable for "existing code, just want to change models." If you need Prompt Caching's `cache_control`, extended thinking, or Claude's tool-calling format, using the [Anthropic SDK](/en/docs/quickstart-anthropic-sdk/) to go through the native interface is more appropriate.
## FAQ
`base_url` is missing `/v1`. The OpenAI SDK will only append `/chat/completions` at the end.
Yes. OpenAI / GPT models are already live. Please use the model ID from [supported models](/en/docs/models/) that your key can call.
## Responses and Complete Programs
When you need the Responses protocol, see the [Responses API](/en/docs/api-responses/). If you are using Python or Node.js for the first time, you can directly run the [complete example](/en/docs/code-examples/); before going live, configure [timeouts and limited retries](/en/docs/retries/).
---
# Calling with curl
Source: https://1zheai.com/en/docs/quickstart-curl/
Markdown: https://1zheai.com/en/docs/quickstart-curl.md
---
title: "Calling with curl"
description: "Without installing any SDK, use curl to call 1折AI's /v1/messages and /v1/chat/completions, list models, test caching, and view streaming output."
headingIds: {"Anthropic native: /v1/messages":"section-1","OpenAI compatible: /v1/chat/completions":"section-2","Model list: /v1/models":"section-3","Streaming output":"section-4","Testing caching":"section-5","Add -i when troubleshooting":"section-6"}
---
curl is the fastest way to confirm whether the API key and endpoint actually work. Every command below can be copied directly. First, put your API key into an environment variable:
```bash
export ONEZHE_API_KEY="sk-你的Key"
```
Windows users are advised to run these commands in WSL or Git Bash; for PowerShell syntax, see [Quick Start](/en/docs/quickstart/).
## Anthropic native: /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"}]
}'
```
## OpenAI compatible: /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"}]
}'
```
## Model list: /v1/models
```bash
curl https://1zheai.com/v1/models \
-H "Authorization: Bearer $ONEZHE_API_KEY"
```
## Streaming output
Add `"stream": true` and use `-N` to turn off curl's buffering so you can see the response arrive chunk by chunk:
```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": "从一数到五"}]
}'
```
For the event format, see [Streaming Output](/en/docs/streaming/).
## Testing caching
Send the same request twice in a row; if the `usage.cache_read_input_tokens` in the second response is greater than 0, it means the cache was hit. The text in `system` needs to reach the model's minimum cacheable length. For the full script, see [Verify Models and Usage](/en/docs/verify-model/), and for the underlying mechanism, see [Prompt Caching](/en/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"}]
}'
```
## Add -i when troubleshooting
```bash
curl -i https://1zheai.com/v1/models -H "Authorization: Bearer $ONEZHE_API_KEY"
```
`-i` will print the status code and response headers. For the meaning of status codes, see [Error Codes and Troubleshooting](/en/docs/troubleshooting/).
---
# Ready-to-Run Code Examples
Source: https://1zheai.com/en/docs/code-examples/
Markdown: https://1zheai.com/en/docs/code-examples.md
---
title: "Ready-to-Run Code Examples"
description: "Complete Chat Completions programs in Python and Node.js, covering environment setup, model selection, error handling, and execution commands."
headingIds: {"1. Prepare Environment Variables":"section-1","2. Choose a Language and Run":"section-2","Python":"section-3","Node.js":"section-4","3. Verify the Results":"section-5","Continue Extending":"section-6"}
---
The two programs below do the same thing: read environment variables, make a single non-streaming text request, and output the response or an identifiable error. The examples disable automatic retries so you can confirm the result of a single request.
## 1. Prepare Environment Variables
Set them in the same terminal where you run the program; `ONEZHE_MODEL` can be replaced with an ID from [models with available keys ](/en/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. Choose a Language and Run
### Python
Install `python -m pip install openai`, save as `chat.py`, and 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
Install `npm install openai`, save as `chat.mjs`, and execute `node chat.mjs`. Using the `.mjs` extension directly enables ES Modules.
```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. Verify the Results
You should see a response and a finish reason. When `finish_reason` is not `stop`, check whether it is a tool call or a truncation. The SDK's request ID may be empty; the server may also place the trace ID in the error body, so supplement it from the redacted raw response when debugging.
Go to [call logs ](/en/docs/usage-logs/) to verify calls. The program's exit status and whether there is plain text do not cover all business success conditions; check structure and content according to your task.
## Continue Extending
- [Chat Completions ](/en/docs/api-chat-completions/): multi-turn history and field descriptions.
- [Messages ](/en/docs/api-messages/): Claude-native content blocks.
- [Responses ](/en/docs/api-responses/): GPT Responses and streaming events.
- [Image Generation ](/en/docs/api-images/): generate and save image files.
- [Timeouts and Retries ](/en/docs/retries/): configure failure handling before going live.
---
# Streaming Output
Source: https://1zheai.com/en/docs/streaming/
Markdown: https://1zheai.com/en/docs/streaming.md
---
title: "Streaming Output"
description: "Using streaming output on 1折AI: Anthropic's native SSE event sequence, OpenAI-compatible chunk format, and how to handle stream interruptions."
headingIds: {"Anthropic Native":"section-1","OpenAI Compatible":"section-2","What to Do When the Stream Breaks":"section-3","Billing for Mid-Stream Disconnections":"section-4"}
---
For long responses, use streaming output (`"stream": true`) so the first character appears faster and the request is less likely to be cut off by intermediate networks due to a single request taking too long. Both protocols are supported, with formats matching the official ones respectively.
## Anthropic Native
Add `"stream": true` to the request; the response is Server-Sent Events. A normal stream follows this order (from [Anthropic Streaming documentation ](https://platform.claude.com/docs/en/build-with-claude/streaming)):
| Event | Meaning |
|---|---|
| `message_start` | Message starts, with model and initial `usage` |
| `content_block_start` | A content block starts (text, thinking, tool_use) |
| `content_block_delta` | Content delta, text is in `delta.text` |
| `content_block_stop` | This content block ends |
| `message_delta` | Message-level update, with `stop_reason` and final output token count |
| `message_stop` | The entire message ends |
`ping` events may be interspersed in between and can be ignored; on error you will receive a `error` event.
```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":"从一数到五"}]}'
```
When using an SDK you don't need to parse events yourself; see the streaming example in [Anthropic SDK ](/en/docs/quickstart-anthropic-sdk/).
## OpenAI Compatible
Add `"stream": true` to `/v1/chat/completions`; the response is chunks in the form of `data: {...}`, text is in `choices[0].delta.content`, and it ends with `data: [DONE]`. See [OpenAI SDK ](/en/docs/quickstart-openai-sdk/) for an SDK example.
The last chunk before `usage` contains `[DONE]`, and `choices` is an empty array. It is also returned if `stream_options.include_usage` is not passed. Full stream tested on 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]
```
When processing chunks, first check whether `choices` is empty; the example on the OpenAI SDK page above already does this.
## What to Do When the Stream Breaks
- First check if it's a proxy: turn off the proxy and connect directly, then try again.
- The client's read timeout should be longer than the model's generation time; increase the timeout setting for long outputs.
- On receiving `overloaded_error` in a `error` event, wait a few seconds and retry; see [Error Codes and Troubleshooting ](/en/docs/troubleshooting/).
## Billing for Mid-Stream Disconnections
A request disconnected mid-stream is not entirely free; it is billed based on the output tokens generated before the disconnection, recorded in the call log. The billed output may be slightly more than what the client actually received. Tested on 2026-10-15: having the model count from 1 to 600, when the client disconnected at the 4th second it had received 188 lines (about 380 output tokens), while the call log recorded 750 output tokens. For long output you don't need, rather than disconnecting mid-stream, it's better to set `max_tokens` small from the start.
---
# Prompt Caching Usage and Billing
Source: https://1zheai.com/en/docs/prompt-caching/
Markdown: https://1zheai.com/en/docs/prompt-caching.md
---
title: "Prompt Caching Usage and Billing"
description: "Using Claude Prompt Caching on 1折AI: how to enable it, minimum length, how to confirm a hit, how hits are billed, and Claude Code's caching behavior."
headingIds: {"Bottom line first":"section-1","How to enable it":"section-2","Minimum cacheable length":"section-3","Confirming a hit":"section-4","How it is billed":"section-5","1-hour cache":"section-6","Claude Code’s caching":"section-7","Can the OpenAI-compatible interface use caching?":"section-8","FAQ":"section-9"}
---
Prompt Caching lets the long prefix you send repeatedly (system prompt, tool definitions, long documents, conversation history) be billed as a write only the first time, and as a read thereafter. On this site, cache reads and cache writes are billed at official list prices, without the input/output discount applied. Per-model cache unit prices are listed in [Models and Pricing](https://1zheai.com/en/pricing/).
## Bottom line first
- **Claude Code has caching enabled by default**; it takes effect as soon as you connect.
- When calling from your own code, add `cache_control` to the content block you want cached, using the native `/v1/messages`. The OpenAI-compatible interface currently does not cache.
- To determine whether a hit occurred, check only whether the response's `usage.cache_read_input_tokens` is greater than 0.
- The cache lives for 5 minutes by default, and each hit resets the timer. You can also use `"ttl": "1h"` to write a 1-hour cache, at a higher write price.
## How to enable it
Add `"cache_control": {"type": "ephemeral"}` to a content block in system, tools, or messages; that block and everything before it will be cached. A single request can have at most 4 cache breakpoints.
```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": "根据上面的规范，审查这段代码：..."}]
}'
```
If the prefix to be cached is too short, the request is processed normally but simply not cached, and no error is raised. The minimum length varies by model; see the table below.
## Minimum cacheable length
The following comes from [Anthropic's official documentation](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) (2026-10-14):
| Minimum token count | Models |
|---|---|
| 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 |
## Confirming a hit
Send the same request twice (no more than 5 minutes apart) and compare the `usage` of both. Below are actual results measured on 2026-10-15 with `claude-sonnet-5-5`, with about 18,000 tokens of fixed text in the 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
}
```
If the second `cache_read_input_tokens` is greater than 0, the cache is being read. The cache write and read tokens for each call also appear in the Token column of the [call log](/en/docs/usage-logs/), with reads recorded as "cache↓" and writes as "↑".
## How it is billed
| Type | Official unit price | 1折AI unit price |
|---|---|---|
| Cache write (5 minutes) | Input price × 1.25 | Official list price, no discount |
| Cache write (1 hour) | Input price × 2 | Official list price, no discount |
| Cache read | Input price × 0.1 (0.05 for Opus 5.5 and Sonnet 5.5, 0.025 for Fable 5.1) | Official list price, no discount |
The official price for a 5-minute cache write is typically 1.25 times the official input price. On this site, input has a discount but caching does not, so you cannot use the official multiplier to conclude that a single cache read pays for itself; you need to compare the model discount, write cost, and number of repeated reads. Full worked examples are in [Pricing and Billing](/en/docs/pricing-explained/).
### 1-hour cache
Add `"ttl": "1h"` to `cache_control`, and the cache will be retained for 1 hour — suitable for prefixes with intervals over 5 minutes that are still used repeatedly:
```json
"cache_control": {"type": "ephemeral", "ttl": "1h"}
```
Writes are billed at 2 times the official input price, not the discounted input price; reads are the same as the 5-minute cache. The written tokens appear in `cache_creation.ephemeral_1h_input_tokens` of the response. Whether to choose the 1-hour cache should be judged based on the interval between the two requests, the write cost, and the number of repeated reads.
## Claude Code’s caching
Claude Code automatically places cache breakpoints on the system prompt, tool definitions, and conversation history; [the official explanation is here](https://code.claude.com/docs/zh-CN/prompt-caching). To make it hit better:
- Keep working continuously within one session; don't stop for long in the middle. The cache expires if unused for 5 minutes.
- Subsequent requests in the same session will read the cache. Measured on 2026-10-15, for a two-round Claude Code task, the second round read 31,440 cache tokens and wrote 115 tokens. When starting a new session, the first round may need to rewrite the entire prefix (measured at about 30,000 tokens), and that call will be more expensive than later ones.
- Avoid changing `CLAUDE.md`, switching MCP servers, or changing models mid-session; all of these change the prefix.
- Do not set `DISABLE_PROMPT_CACHING=1`; this environment variable turns off caching for all models.
## Can the OpenAI-compatible interface use caching?
Currently, no. Measured on 2026-10-15, with about 3,100 tokens of fixed text in the system message of `/v1/chat/completions`, sent twice in a row, whether or not `cache_control` was added to the content block, both responses' `usage` were:
```json
{"prompt_tokens": 3167, "completion_tokens": 4, "total_tokens": 3171}
```
There is no `prompt_tokens_details.cached_tokens`, and the cache reads and writes in the call log are both 0; the entire request is billed at the input price. For scenarios that need caching, please use `/v1/messages` (Anthropic SDK or Claude Code).
## FAQ
The cache was written, but the next request did not read it. Troubleshoot in order: were the two requests more than 5 minutes apart; is the content before the breakpoint byte-for-byte identical (timestamps and random IDs in the system make it different every time); was the model changed; did the prefix reach the minimum length above.
The cache read and cache write tokens for each call are in the call log, so you can calculate it yourself: cache reads ÷ (input + cache writes + cache reads).
---
# Timeouts, Rate Limits, and Retries
Source: https://1zheai.com/en/docs/retries/
Markdown: https://1zheai.com/en/docs/retries.md
---
title: "Timeouts, Rate Limits, and Retries"
description: "Configure SDK timeouts and limited retries, distinguish retryable errors from configuration errors, and avoid duplicate submissions."
headingIds: {"Which situations should be retried":"section-1","Use the SDK’s built-in retries first":"section-2","When implementing retries yourself":"section-3","Record sufficient debugging information":"section-4"}
---
Fix configuration errors first, then handle transient failures. Limit retry count, concurrency, and total wait time together to avoid sending the same failed request many times in a short period.
## Which situations should be retried
| Situation | Recommendation |
| --- | --- |
| 400 / 401 / 403 / 404 | Fix the request, permissions, or model first; do not automatically repeat the original request |
| 429 | Check the response message; when `Retry-After` is present, follow the wait time and reduce concurrency |
| 500 / 502 / 503 / 504 / 529 | Limited retries are allowed; if failures persist, stop and report the request ID |
| Connection failure | Check DNS, proxy, and network; retry within the time allowed by the task |
| Timeout or stream interruption after the request was sent | The result may be uncertain; check logs first; do not assume the upstream has not processed it |
The retry scope of client libraries may not exactly match the table above. Whichever layer you use for retries, explicitly set the policy at that layer.
## Use the SDK’s built-in retries first
Python and Node.js use different timeout units: Python uses seconds, Node.js uses milliseconds. The example below sets a 120-second timeout and up to 2 automatic retries; change it to 0 when debugging initial integration.
```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,
});
```
The timeout configuration is not an upper bound on the total duration of the entire business task: retries and waits will increase the total duration. If the outer layer will re-execute the task, set a total deadline and cancellation mechanism separately.
## When implementing retries yourself
Disable the SDK's automatic retries to avoid stacking. Use progressively increasing wait intervals with random jitter; explicitly limit attempt count, maximum wait, and concurrency queue. When parsing `Retry-After`, note that it may be either seconds or an HTTP date.
If partial streaming results have already been shown to the user, do not automatically replay from the beginning and append to the old text. Keep the "incomplete" state and let the user decide to regenerate or continue.
For image generation, tool execution, and other tasks that may produce external results, pay special attention to duplicate submissions. Do not assume that setting an arbitrary request ID will make the server automatically deduplicate.
## Record sufficient debugging information
Record time, endpoint, model, status code, duration, attempt number, and the request ID returned by the server. Avoid logging authentication headers and full private prompts. Use this information to cross-reference [call logs ](/en/docs/usage-logs/).
SDK settings are documented in [OpenAI Python SDK ](https://github.com/openai/openai-python#retries) and [Node SDK ](https://github.com/openai/openai-node#retries). For specific errors, see [error codes and troubleshooting ](/en/docs/troubleshooting/).
---
# API Reference
Source: https://1zheai.com/en/docs/api-reference/
Markdown: https://1zheai.com/en/docs/api-reference.md
---
title: "API Reference"
description: "Find documented endpoints, request examples, and protocol differences to clarify compatibility scope."
headingIds: {"Endpoint Index":"section-1","Compatibility Scope":"section-2","Responses & Troubleshooting":"section-3"}
---
This page collects the existing endpoint documentation and request examples on this site. This site provides both Claude and OpenAI / GPT models. Choose the corresponding protocol based on the model and tool; the specific models are subject to the list available to your key.
## Endpoint Index
| Endpoint | Purpose | Description & Examples |
| --- | --- | --- |
| `POST /v1/messages` | Anthropic native conversation | [Request & Response](/en/docs/api-messages/), [Anthropic SDK](/en/docs/quickstart-anthropic-sdk/), [curl](/en/docs/quickstart-curl/) |
| `POST /v1/chat/completions` | OpenAI-compatible conversation | [Request & Response](/en/docs/api-chat-completions/), [OpenAI SDK](/en/docs/quickstart-openai-sdk/), [curl](/en/docs/quickstart-curl/) |
| `POST /v1/responses` | OpenAI Responses | [Request & Response](/en/docs/api-responses/), [Codex CLI](/en/docs/quickstart-codex/) |
| `GET /v1/models` | Query models available to your key | [List format & query](/en/docs/api-models/), [Model selection](/en/docs/models/) |
| `POST /v1/messages/count_tokens` | Input token counting | [Endpoint description](/en/docs/base-url/) |
| `POST /v1/images/generations` | Text-to-image generation | [Image generation integration](/en/docs/api-images/) |
## Compatibility Scope
For Claude native capabilities, first refer to the Anthropic integration tutorial. Before switching protocols, verify that the required capabilities are described in the corresponding tutorial; do not infer that tool calls, caching, or long-running tasks are supported solely because a request succeeds.
Codex uses `/v1/responses`; see [Codex CLI integration](/en/docs/quickstart-codex/). The currently available models are subject to the [model description](/en/docs/models/) and the list actually returned by your key.
## Responses & Troubleshooting
event formats and stream disconnection handling for both protocols. locate issues by status code and error message.
Endpoint details provide minimal requests, common fields, result reading, and compatibility boundaries; full parameters still require combining the protocol documentation of the selected model. This site does not yet provide a downloadable complete OpenAPI specification.
Embeddings, Batch, file hosting, and third-party proprietary models not confirmed in the public directory are not within the scope of commitment on this page. Confirm with support first when you need these capabilities.
---
# Base URL, Endpoints, and Authentication
Source: https://1zheai.com/en/docs/base-url/
Markdown: https://1zheai.com/en/docs/base-url.md
---
title: "Base URL, Endpoints, and Authentication"
description: "Base URL, available endpoints, request header formats for 1折AI, and whether to add /v1 in different tools."
headingIds: {"Available Endpoints":"section-1","Whether to Add /v1":"section-2","Authentication Request Headers":"section-3","Check Whether the API Key Is Usable":"section-4","Rate Limits":"section-5","Network":"section-6"}
---
All requests are sent to the same domain, with two sets of paths based on the protocol.
```text
https://1zheai.com
```
## Available Endpoints
| Endpoint | Protocol | Purpose |
|---|---|---|
| `POST /v1/messages` | Anthropic native | Conversations. Used by Claude Code, Anthropic SDK, Cline (Anthropic mode) |
| `POST /v1/chat/completions` | OpenAI compatible | Conversations. Used by OpenAI SDK, Cursor, Cherry Studio (OpenAI mode) |
| `GET /v1/models` | OpenAI compatible | Lists the models your API key can use |
| `POST /v1/messages/count_tokens` | Anthropic native | Counts the tokens of a given input; does not generate a conversation and does not charge fees |
The request body of `count_tokens` is the same as `/v1/messages` (`model`, `messages`, and can include `system` and `tools`). The response contains only one field:
```json
{"input_tokens":19}
```
`count_tokens` only counts the content you send. When actually calling via SDK, curl, or third-party tools, each request also includes a system prompt, which is billed as input tokens (Claude Code does not include one). See [system prompt billing ](/en/docs/pricing-explained/#section-3).
Claude-specific capabilities such as Prompt Caching, extended thinking, and tool calls work most reliably with the native `/v1/messages`. The OpenAI-compatible endpoint is suitable for scenarios where you already have OpenAI code and just want to switch models.
## Whether to Add /v1
Different tools interpret the Base URL differently. This is the most common pitfall when integrating:
| Tool / SDK | What to Fill In | Reason |
|---|---|---|
| Claude Code (`ANTHROPIC_BASE_URL`) | `https://1zheai.com` | The tool itself appends `/v1/messages` |
| Anthropic SDK (`base_url`) | `https://1zheai.com` | Same as above |
| OpenAI SDK (`base_url`) | `https://1zheai.com/v1` | The SDK only appends `/chat/completions` |
| Cursor (Override OpenAI Base URL) | `https://1zheai.com/v1` | Same as OpenAI SDK |
| Cherry Studio | `https://1zheai.com` | Automatically appends `/v1/...` |
| Cline (OpenAI Compatible) | `https://1zheai.com/v1` | Same as OpenAI SDK |
Rule: Anthropic-family tools take the root address; OpenAI-family tools take it up to `/v1`. The typical symptom of filling it in wrong is a 404.
## Authentication Request Headers
The API key is placed in the request header. Both formats work:
```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
```
- When calling `/v1/messages`, include `anthropic-version` according to the official protocol; the current value is `2023-06-01`. In testing, it works without it, but official SDKs and tools all include it, so include it when writing requests yourself.
- Claude Code's `ANTHROPIC_AUTH_TOKEN` sends `Authorization: Bearer`, and `ANTHROPIC_API_KEY` sends `x-api-key`; we accept both.
- When beta features are needed, include the `anthropic-beta` header as per the official documentation. Including an unrecognized value does not cause an error, so whether a beta feature is in effect should be judged by the actual effect in the response.
## Check Whether the API Key Is Usable
```bash
curl https://1zheai.com/v1/models \
-H "Authorization: Bearer sk-你的Key"
```
Returning a model list means both the API key and the address are correct. Returning 401 means there is a problem with the API key. The response looks like this (tested on 2026-10-15):
```json
{"error":{"code":"","message":"Invalid token (request id: 202610150244361675490398268d9d6eKJPmcph)","type":"authentication_error"}}
```
When requesting `/v1/models` with the `x-api-key` and `anthropic-version` headers, the response is a model list in Anthropic format (`data[].id`, `display_name`, `has_more`). Claude Code's model auto-discovery reads this format.
For other cases, see [error codes and troubleshooting ](/en/docs/troubleshooting/).
## Rate Limits
Currently, no rate limits are set on API keys. Receiving a 429 usually means high upstream load; retry later, and add exponential backoff for batch jobs. See [error codes and troubleshooting ](/en/docs/troubleshooting/) for details.
## Network
When there is a connection timeout or TLS error, first confirm the network the terminal is using: if a global proxy is on, turn it off and connect directly, then try again; if the corporate network has an egress whitelist, `1zheai.com` needs to be allowed.
---
# Query Available Models API
Source: https://1zheai.com/en/docs/api-models/
Markdown: https://1zheai.com/en/docs/api-models.md
---
title: "Query Available Models API"
description: "Two response formats of GET /v1/models, reading model IDs, and the difference between model visibility and actual callability."
headingIds: {"OpenAI Format":"section-1","Anthropic Format":"section-2","How to Use Query Results":"section-3","Empty List or Missing Models":"section-4"}
---
Query models first, then write requests. `GET https://1zheai.com/v1/models` returns the models visible under the current key, group, and model limits, without needing to send an inference request.
## OpenAI Format
```bash
curl --fail-with-body --connect-timeout 10 --max-time 30 \
https://1zheai.com/v1/models \
-H "Authorization: Bearer $ONEZHE_API_KEY"
```
Below is a simplified structural illustration; the actual list is based on the real response:
```json
{
"object": "list",
"data": [{"id": "gpt-5.6-sol", "object": "model"}]
}
```
When `jq` is installed, you can append `| jq -r '.data[].id'` after the request, displaying one model ID per line. Do not confuse the `model_name` of the public pricing endpoint with the `id` here.
## Anthropic Format
When using the following two request headers, the same path returns Anthropic-style data:
```bash
curl --fail-with-body https://1zheai.com/v1/models \
-H "x-api-key: $ONEZHE_API_KEY" \
-H "anthropic-version: 2023-06-01"
```
Pay attention to `data[].id`, `data[].display_name`, and `has_more`. After switching authentication methods, do not continue parsing with the other response structure.
## How to Use Query Results
1. Copy the complete ID from `data[].id`, preserving case, hyphens, and date suffixes.
2. Verify the interface type of that model in the [console model catalog ](https://1zheai.com/model-catalog?lng=en).
3. Validate with a minimal text request, then gradually add images, tools, or other parameters.
The model list is not a real-time health check and does not include all parameter limits. Even if a model is visible, requests may still fail when no upstream is temporarily available; the official website's HTTP availability monitoring also does not mean every model can successfully infer.
## Empty List or Missing Models
Check the key's model limits and group; models shown on the public pricing page are not necessarily open to every key. For 401, first check the key status; for 403, check access conditions; see [error codes and troubleshooting ](/en/docs/troubleshooting/) for detailed steps.
For model series and selection recommendations, see [supported models ](/en/docs/models/).
---
# Chat Completions API
Source: https://1zheai.com/en/docs/api-chat-completions/
Markdown: https://1zheai.com/en/docs/api-chat-completions.md
---
title: "Chat Completions API"
description: "Minimal request, common fields, reading responses, and multi-turn conversation usage for POST /v1/chat/completions."
headingIds: {"Minimal Request":"section-1","Common Fields":"section-2","How to Read the Response":"section-3","Multi-Turn Conversation":"section-4","Streaming and Next Steps":"section-5"}
---
Start with this endpoint when using an OpenAI-compatible client, or when you already have `chat.completions.create` code. The full address is `https://1zheai.com/v1/chat/completions`; for SDKs, fill in the Base URL only up to `/v1`.
## Minimal Request
First set `ONEZHE_API_KEY` in your terminal to this site's API key. The model below must exist in [your available model list ](/en/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` makes HTTP errors return a non-zero exit code while preserving the error body; requires curl 7.76 or later. On older versions, use `-i` first to view the status code.
## Common Fields
| Field | Type | Usage |
| --- | --- | --- |
| `model` | string | Required. Copy this site's model ID; do not add vendor prefixes from other platforms. |
| `messages` | array | Required. Send this round's question and the history messages to retain, in order. |
| `messages[].role` | string | For normal conversation use `user` / `assistant`; support for the system instruction role depends on the model. |
| `messages[].content` | string or content block array | Use a string for plain text first; image input requires the model to support the corresponding content block. |
| `stream` | boolean | When set to `true`, read SSE instead of treating the entire response as a single JSON. |
| `temperature` | number | Optional; some reasoning models do not support modifying it. Omit it first, then verify item by item. |
| `tools` / `tool_choice` | array / string or object | Optional; both the model and upstream must support them. Actual tool execution is performed by your program. |
Output limit parameters vary by model. Do not mechanically swap Claude's `max_tokens`, Responses' `max_output_tokens`, and Chat Completions parameters; refer to the selected model's requirements, and on a 400 error check the error body first.
## How to Read the Response
The plain text result is located at `choices[0].message.content`. The finish reason is at `choices[0].finish_reason`; when tool calls are returned, the text may be empty and you need to read `message.tool_calls`. The response's `id`, `model`, and `usage` can be used to verify this call.
Below only shows the structure you need to pay attention to; omitted fields and numbers do not represent actual request results:
```json
{
"id": "example-completion",
"object": "chat.completion",
"model": "gpt-5.6-sol",
"choices": [{
"index": 0,
"message": {"role": "assistant", "content": "DNS 将域名解析为网络地址。"},
"finish_reason": "stop"
}]
}
```
## Multi-Turn Conversation
The endpoint does not automatically remember the previous round just because you reuse the same API key. Send the history you want to retain together:
```json
{
"model": "gpt-5.6-sol",
"messages": [
{"role": "user", "content": "我正在学习 DNS。"},
{"role": "assistant", "content": "我们可以从域名解析开始。"},
{"role": "user", "content": "它和 HTTP 有什么区别？"}
]
}
```
The longer the history, the larger the request. Applications should trim or summarize according to context limits, and keep complete tool call and result pairs.
## Streaming and Next Steps
After adding `"stream": true`, text deltas come from `choices[].delta.content`. Some events have no text or `choices` is empty, so you must check when reading; see [Streaming Output ](/en/docs/streaming/) for details.
Run the [Python / Node.js full example ](/en/docs/code-examples/) directly, or switch to [Responses ](/en/docs/api-responses/); for Claude native parameters see [Messages ](/en/docs/api-messages/).
---
# Messages Native Conversation Interface
Source: https://1zheai.com/en/docs/api-messages/
Markdown: https://1zheai.com/en/docs/api-messages.md
---
title: "Messages Native Conversation Interface"
description: "Claude Messages request headers, differences between system and messages, content blocks, and stop reasons."
headingIds: {"Minimal Request":"section-1","Request Structure":"section-2","Reading Content Blocks":"section-3","Multi-turn and Streaming":"section-4"}
---
Claude Code, the Anthropic SDK, and applications that want to preserve Claude's native content blocks use `POST https://1zheai.com/v1/messages`. Fill in the SDK Base URL with `https://1zheai.com`.
## Minimal Request
First set this site's key environment variable `ONEZHE_API_KEY`, then run:
```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": "什么是域名解析？"}]
}'
```
## Request Structure
| Field | Type | Usage |
| --- | --- | --- |
| `model` | string | Required, selects the Claude model available to the key |
| `max_tokens` | integer | Required, output upper limit; set in combination with the selected model's limits |
| `messages` | array | Required, sends `user` and `assistant` messages in chronological order |
| `system` | string or array of content blocks | Optional, system instructions are placed at the top level, not as a `role: system` message |
| `stream` | boolean | Optional, streams content block increments |
| `tools` | array | Optional, declares tool names, purposes, and input Schemas |
`thinking`, cache control, and beta parameters depend on the specific model and upstream support. Verify plain text first, then add as needed; do not treat all models as having the same set of parameters.
## Reading Content Blocks
The returned `content` is an array and may contain text, tool requests, or other content blocks at the same time. Do not unconditionally read `content[0].text`. For example, using the Anthropic Python SDK:
```python
for block in message.content:
if block.type == "text":
print(block.text)
```
Here `message` comes from `client.messages.create(...)` in the [Anthropic SDK Tutorial ](/en/docs/quickstart-anthropic-sdk/).
| `stop_reason` | How the application should handle it |
| --- | --- |
| `end_turn` | This turn's answer has ended |
| `max_tokens` | Output was truncated by the upper limit and cannot be treated as a complete answer |
| `tool_use` | Check tool requests, execute permitted tools, and send back results |
| Other values | Keep the response and handle it according to the selected model's protocol; do not assume it is necessarily a text completion |
In a tool call loop, first add the complete assistant content block to history, then send it back with `tool_result` in the user content; `tool_use_id` must correspond to the original request. Do not convert tool requests directly into a single plain text passage.
## Multi-turn and Streaming
Send the history that needs to be retained each time; the interface itself does not store conversations for the application. Streaming uses `message_stop` to indicate the end of a message; receiving partial text does not mean the request has completed. See [Streaming Output ](/en/docs/streaming/) for details.
For protocol details, refer to [Anthropic Messages Usage Notes ](https://platform.claude.com/docs/en/build-with-claude/working-with-messages). Whether this site's extended parameters are available is determined by the model catalog and actual responses.
---
# Responses API
Source: https://1zheai.com/en/docs/api-responses/
Markdown: https://1zheai.com/en/docs/api-responses.md
---
title: "Responses API"
description: "Access 1折AI via the OpenAI Responses API, covering input, output, streaming events, and compatibility boundaries."
headingIds: {"Minimal Request":"section-1","Differences from Chat Completions":"section-2","Python SDK":"section-3","Streaming Reads":"section-4","Compatibility Scope":"section-5"}
---
Codex CLI uses the Responses protocol. When writing your own applications, you can also request GPT models that support this API via `POST https://1zheai.com/v1/responses`. Set the OpenAI SDK Base URL to `https://1zheai.com/v1`.
## Minimal Request
```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
}'
```
Before running, set `ONEZHE_API_KEY` and confirm the model is in [your available list ](/en/docs/api-models/). `store: false` is a storage option in the protocol; it does not mean that all service tiers have no logging or data retention. Do not infer privacy commitments from this.
## Differences from Chat Completions
| Content | Chat Completions | Responses |
| --- | --- | --- |
| Input | `messages` | `input`, which can be a string or structured input items |
| Text result | `choices[].message.content` | message content blocks in `output` |
| SDK text helper attribute | Extract choices yourself | `response.output_text` |
| Streaming text | `choices[].delta.content` | `response.output_text.delta` events |
| Completion check | `finish_reason` and stream end | Check response status and termination events |
`output_text` is a convenience attribute provided by the SDK; do not assume this field exists at the top level of the raw HTTP JSON. When calling HTTP directly, iterate over `output`, select `type: message`, then read the `text` of `type: output_text` in its `content`.
## Python SDK
After installing `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)
```
Here automatic retries are disabled to make it easier to locate a single request during initial integration. Before going live, set the policy according to [timeouts and retries ](/en/docs/retries/).
## Streaming Reads
Use after initializing `client` above:
```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}")
```
If disconnected without receiving a completion event, the result should be marked as incomplete; do not judge success based only on the text already output.
## Compatibility Scope
This page covers creating responses and reading text. Do not infer from this that background tasks, historical response retrieval, `previous_response_id`, hosted tools, file storage, and other capabilities are all available. When session continuation is needed, first verify with explicit history input; when specific tools are needed, verify item by item per model and client.
For configuring ready-made tools, see [Codex CLI ](/en/docs/quickstart-codex/). For SDK usage, refer to [OpenAI Python SDK ](https://github.com/openai/openai-python).
---
# Image Generation Integration
Source: https://1zheai.com/en/docs/api-images/
Markdown: https://1zheai.com/en/docs/api-images.md
---
title: "Image Generation Integration"
description: "Generate images using the OpenAI Images API, save Base64 results, and troubleshoot model permissions and timeouts."
headingIds: {"API and Setup":"section-1","Generate and Save an Image":"section-2","Confirm Model Support Before Adding Parameters":"section-3","Troubleshooting":"section-4"}
---
The public model catalog on this site currently lists `gpt-image-1.5` and `chatgpt-image-latest` (verified on 2026-10-16). Before use, first query [available models for your key ](/en/docs/api-models/), then confirm the image API and parameters in the [console model catalog ](https://1zheai.com/model-catalog?lng=en).
This page provides integration examples following the OpenAI Images protocol; no paid image generation was performed during this documentation update, so the examples below should not be treated as having been tested across all model, size, and quality combinations.
## API and Setup
- Full endpoint: `POST https://1zheai.com/v1/images/generations`
- OpenAI SDK Base URL: `https://1zheai.com/v1`
- Use the `ONEZHE_API_KEY` environment variable on this site.
- Install the Python SDK: `python -m pip install openai`.
## Generate and Save an Image
Save as `generate-image.py`, then run `python generate-image.py` in the terminal:
```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。")
```
The example uses the default output format. If you specify JPEG / WebP or another format, change the file extension accordingly when saving. Do not write the Base64 string directly to a text file and rename it to PNG.
## Confirm Model Support Before Adding Parameters
First verify with a request containing only `model` and `prompt`. Parameters such as size, quality, transparent background, and output format are not universally supported across all image models; do not directly copy model names or proprietary parameters from other providers.
When `data[].b64_json` is returned, perform Base64 decoding; when `data[].url` is returned, download it promptly and do not treat the temporary URL as permanent storage. The application must arrange its own result storage.
## Troubleshooting
| Situation | Troubleshooting Method |
| --- | --- |
| 400 parameter not supported | Remove optional parameters such as custom size and quality, then verify one by one |
| 403 / 404 | Check the image model ID, key permissions, and the full API path |
| Long wait time | Set a reasonable timeout for generation and display an in-progress status to avoid repeated submissions from continuous clicking |
| No image after timeout | First check the call logs; not receiving a result does not mean the upstream did not process the request |
| Want to edit an existing image | Image editing is a different API and input method; the text-to-image example on this page cannot directly replace it |
For protocol parameter reference, see [OpenAI Image Generation Reference ](https://developers.openai.com/api/reference/resources/images/methods/generate). Fees are based on this site's real-time model catalog; for retry strategy, see [Timeouts and Retries ](/en/docs/retries/).
---
# Accounts and Support
Source: https://1zheai.com/en/docs/support/
Markdown: https://1zheai.com/en/docs/support.md
---
title: "Accounts and Support"
description: "Manage billing and call records, locate integration issues, and provide necessary troubleshooting information."
headingIds: {"Marketplace Orders":"section-1","Billing and Account":"section-2","Issues with Calls":"section-3","Self-Service Reference":"section-4"}
---
## Marketplace Orders
[Purchase Guide](/en/docs/store-guide/) · [Order Issue Troubleshooting](/en/docs/store-orders/) · [Transaction and After-Sales Rules](/en/docs/store-rules/)
For issues with ready-to-use accounts, top-ups, and gift cards, first check the status in [My Orders](https://1zheai.com/store-orders?lng=en); when contacting support, provide the order number and redacted error information, and do not send passwords, verification codes, or full session details.
## Billing and Account
Learn about billing composition and calculation details.Check payment and after-sales rules.Locate each call and verify charges.View instructions for creation, storage, and rotation.
## Issues with Calls
First check [Error Codes and Troubleshooting](/en/docs/troubleshooting/), then verify [Addresses and Protocols](/en/docs/base-url/) and [Tool Limits](/en/docs/integrations/). For how to check models and usage, see [Verify Models and Usage](/en/docs/verify-model/).
If you still need help, please provide the following through the console or support channels published on the official website: occurrence time and time zone, tool and version, model ID, HTTP status code, request ID (if any), redacted error information, and whether the issue can be reproduced with a minimal request.
Do not send full API keys, authentication headers, or full conversations containing private content.
## Self-Service Reference
- [Integration FAQ](/en/docs/faq/): addresses, models, response reading, and monitoring meanings.
- [Timeouts and Retries](/en/docs/retries/): setting client wait times and failure handling.
- [Migration Guide](/en/docs/migration/): switching item by item from your original provider.
---
# Pricing and Billing
Source: https://1zheai.com/en/docs/pricing-explained/
Markdown: https://1zheai.com/en/docs/pricing-explained.md
---
title: "Pricing and Billing"
description: "Claude input and output are billed at a discount per model, while cache reads and writes are billed at the official list price; verify call costs using the categorized billing examples."
headingIds: {"How Much Is Charged Per Call":"section-1","Example Calculation":"section-2","System Prompt Billing":"section-3","Balance and Currency":"section-4","How to Verify Discounts and Costs":"section-5","FAQ":"section-6"}
---
**Claude input and output are billed at the discount for that model; cache reads and cache writes are billed at the official list price with no discount.** Unit prices and discounts for each model are listed in [Models and Pricing ](https://1zheai.com/en/pricing/). For GPT, MiMo, and image generation models, check their respective billing units and pricing; the token examples on this page are for Claude.
## How Much Is Charged Per Call
Each call is billed separately for the four token categories in the response `usage`:
```text
费用 = ( 输入 token × 输入单价
+ 缓存写入 token × 缓存写单价
+ 缓存读取 token × 缓存读单价
+ 输出 token × 输出单价 ) ÷ 1,000,000
输入单价、输出单价 = 对应官方单价 × 该模型折扣
缓存读取单价、缓存写入单价 = 对应官方原价
```
The four token categories correspond to these fields in the response:
| Billing Item | `usage` Field (Anthropic Native) | Official Unit Price Relative to Input Price |
|---|---|---|
| Input | `input_tokens` | 1× |
| Cache Write | `cache_creation_input_tokens` | 1.25× (5-minute cache), 2× (1-hour cache, `"ttl": "1h"`) |
| Cache Read | `cache_read_input_tokens` | 0.1× (0.05× for Opus 5.5 and Sonnet 5.5, 0.025× for Fable 5.1) |
| Output | `output_tokens` | Varies by model; see the pricing page |
The official cache multipliers come from the [Anthropic Prompt Caching documentation ](https://platform.claude.com/docs/en/build-with-claude/prompt-caching). Cache usage on this site is billed at the corresponding official list price, without applying the input/output discount again.
1-hour cache write tokens are recorded separately in `cache_creation.ephemeral_1h_input_tokens` and billed at 2 times the official input price, without applying the input/output discount. The cache write unit prices listed on the pricing page are for the 5-minute cache.
## Example Calculation
The unit prices below are round numbers chosen for demonstration and do not correspond to any specific model; see the pricing page for actual unit prices.
Assume a model's official unit prices (per million tokens): input $3, output $15, cache write $3.75, cache read $0.30. The `usage` for one Claude Code request is:
```json
{
"input_tokens": 2000,
"cache_creation_input_tokens": 1500,
"cache_read_input_tokens": 30000,
"output_tokens": 800
}
```
At official prices:
| Item | Tokens | Official Unit Price | Official Cost |
|---|---|---|---|
| Input | 2,000 | $3 | $0.006 |
| Cache Write | 1,500 | $3.75 | $0.005625 |
| Cache Read | 30,000 | $0.30 | $0.009 |
| Output | 800 | $15 | $0.012 |
| Total | | | $0.032625 |
Assume this example model's input and output are billed at 20% of the official price (for demonstration only, not representing current model pricing), then:
```text
输入费用 = $0.006 × 0.2 = $0.0012
输出费用 = $0.012 × 0.2 = $0.0024
缓存费用 = $0.005625 + $0.009 = $0.014625
合计 = $0.018225
```
You cannot simply multiply the official total cost by the input/output discount, because the cache portion is not discounted.
If the cache misses on the same request, those 30,000 tokens are billed at the model's discounted input price. Whether this saves money depends on comparing the model discount, cache write cost, and the number of repeated reads — you cannot compare official prices alone. For configuration and verification methods, see [Prompt Caching ](/en/docs/prompt-caching/).
## System Prompt Billing
The Claude API comes from official subscription account pools. Calls made through Claude Code do not include any additional content. Other clients (SDK, curl, and third-party tools) attach a system prompt to every request, billed as input tokens: approximately 350 tokens for Sonnet 4.6 and approximately 500 tokens for the 5.x series. This portion is counted together with your own content in the response `usage`'s `input_tokens`.
Measured on 2026-10-15 by sending "Reply with just: ok" via curl:
| Model | `count_tokens` Count | Actual `input_tokens` | Attached System Prompt (Approx.) |
|---|---|---|---|
| Sonnet 4.6 | 19 | 370 | 350 tokens |
| 5.x series | 18–19 | 510–530 | ~500 tokens |
- `count_tokens` only counts what you send and does not include this system prompt. When estimating costs with the SDK, curl, or third-party tools, add the numbers from the table above; Claude Code does not need this.
- The input tokens recorded in the call log already include this portion; recalculating with the formula above will match the charges in the log.
- The shorter the request, the higher this portion's share; in long-context requests it is a very small fraction.
## Balance and Currency
- Charges are calculated using the USD formula above and deducted from your account balance. Balances are denominated in USD.
- Top-up principal is credited in USD; payment processing service fees are listed separately and are non-refundable. Available payment methods and amount limits are subject to the wallet order page.
## How to Verify Discounts and Costs
First check the model's input/output discount, then calculate input, output, cache read, and cache write separately. Each charge can be recalculated in the [call log ](/en/docs/usage-logs/) using the corresponding unit price.
## FAQ
The most common reason is a cache miss: too much time elapsed between the two requests (default cache is 5 minutes), the first part of the context changed, or the model was switched. Open the call log and compare the cache read tokens of the two entries to see.
No discount. Cache reads and cache writes are billed at the official list price; input and output are billed at each model's discount.
Calls made through Claude Code do not include any additional content. Other clients (SDK, curl, and third-party tools) attach a system prompt to every request, billed as input tokens: approximately 350 tokens for Sonnet 4.6 and approximately 500 tokens for the 5.x series. Measured data is in [System Prompt Billing ](#section-3).
Find the entry in the call log, plug the four token counts and the unit prices from the pricing page into the formula above; the result should match the charge in the log. If it does not match, send us the timestamp and model of that log entry.
---
# Usage Logs and Reconciliation
Source: https://1zheai.com/en/docs/usage-logs/
Markdown: https://1zheai.com/en/docs/usage-logs.md
---
title: "Usage Logs and Reconciliation"
description: "View each call's model, four token types, and charges in the 1折AI console's call logs, and recalculate a bill using the formula."
headingIds: {"Where to View":"section-1","What Each Log Entry Contains":"section-2","Reconcile a Bill":"section-3","Using Logs to See Cache Effectiveness":"section-4","Not Matching Your Own Statistics":"section-5"}
---
Every call leaves a detail record in the call logs. This page explains how to view them and how to reconcile.
## Where to View
[Console](https://1zheai.com/console?lng=en) left menu → "Call Logs" (URL `https://1zheai.com/usage-logs`), page title is "General Logs".
At the top you can filter by time range; after clicking "Expand" you can also filter by model name, API key name ("Token Name"), request ID, and log type. After filtering, click "Search"; "Export" downloads the current filtered results, making it convenient to reconcile in a spreadsheet.
## What Each Log Entry Contains
| Column | Content |
|---|---|
| Time | When the request occurred |
| Token | The API key name used for this call |
| Model | The actual model ID called |
| Stream | "Stream" or "Non-stream", plus output speed (t/s) |
| Token | The first line is "Input / Output" tokens; when caching is present, an additional line appears below: after "Cache↓" is the cache read tokens, after "↑" is the cache write tokens |
| Cost | The USD amount charged for this call |
| Duration | Total duration; streaming requests also show time to first character |
| Details | Unit price and other details for this call |
Requests rejected by the gateway (invalid API key, insufficient balance, incorrect model name, etc.) are not charged. Requests where the upstream returns an error have a cost of 0. A streaming request that disconnects mid-way is not entirely free of charge, see [Streaming Output](/en/docs/streaming/).
## Reconcile a Bill
Find the entry to verify by time and model, and note down the four numbers in the Token column: input, output, cache read (Cache↓), and cache write (↑).
On the [Pricing Page](https://1zheai.com/en/pricing/) find the input, output, cache read, and cache write unit prices for that model (input and output are already calculated with the model discount; cache is at the official original price).
```text
扣费 = ( 输入 × 输入单价
+ 缓存写入 × 缓存写单价
+ 缓存读取 × 缓存读单价
+ 输出 × 输出单价 ) ÷ 1,000,000
```
The result should match the charge in the log. Rounding may cause a difference in the last digit.
If it doesn't match, send us the time, model, and a screenshot of this log entry.
## Using Logs to See Cache Effectiveness
In tools like Claude Code, most input should fall into the "cache read" column. If several consecutive entries show large amounts of "cache write" with very little "cache read", it means the cache is not being reused; for causes and fixes see [Prompt Caching](/en/docs/prompt-caching/).
A rough hit rate: cache read ÷ (input + cache write + cache read).
## Not Matching Your Own Statistics
- Claude Code uses Haiku-level models for some background tasks, so models you never actively selected will appear in the logs. See the model mapping in [Claude Code Integration](/en/docs/quickstart-claude-code/).
- Input tokens in the log are a few hundred more than the content you sent: when calling via SDK, curl, or third-party tools, each request includes a system prompt that is billed as input (Claude Code does not include one), see [System Prompt Billing](/en/docs/pricing-explained/#section-3).
- A single "conversation" in a tool may correspond to many API calls (one round per tool call); logs are recorded per API call.
---
# Top-Ups, Refunds, and Invoices
Source: https://1zheai.com/en/docs/billing/
Markdown: https://1zheai.com/en/docs/billing.md
---
title: "Top-Ups, Refunds, and Invoices"
description: "How to top up on 1折AI, minimum amounts, supported payment methods, the 7-day unused balance refund policy, and what invoices are available for each payment method."
headingIds: {"Top-Up":"section-1","API Balance Refunds":"section-2","Invoices":"section-3","FAQ":"section-4"}
---
This page explains the API account balance: top up first, and charges are deducted based on usage when you make calls. AI account products are purchased according to their product specifications; for after-sales service, see [Account Store](https://1zheai.com/en/store/). The API balance refund rules on this page do not apply to them.
The balance refund rules in this article apply to model API top-ups. For ready-to-use accounts, subscription activation, and gift card orders, please refer to [Store Transaction and After-Sales Rules](/en/docs/store-rules/); the 7-day API rule does not directly apply.
## Top-Up
| Item | Description |
|---|---|
| Amount limits | Subject to the wallet order page |
| Payment methods | WeChat Pay, Alipay, Stripe (bank card), USDT |
| Entry point | [Console](https://1zheai.com/console) left sidebar menu "Wallet" → "Add Funds" |
| How charges are deducted | Claude input/output at model discount rates, caching at official list price; other models at their respective rates, see [Pricing and Billing](/en/docs/pricing-explained/) |
Top-up principal is credited in USD. Payment processing service fees are listed separately and are non-refundable.
## API Balance Refunds
**Within 7 days of top-up, you may apply to have unused principal refunded to the original payment method. Consumed portions and payment processing service fees are not refundable.**
Check the consumption after this top-up in the call logs; the refundable unused principal in the wallet is the basis. Payment processing service fees are not counted toward the refundable principal.
Send an email to support@1zheai.com, stating your account, top-up time, and payment method.
For first-time use, you can top up an amount allowed by the wallet, then run through the checks per [Verify Models and Usage](/en/docs/verify-model/), and use it on your real tasks for a few days. Within 7 days, you may apply to have unused principal refunded to the original payment method; payment processing service fees are non-refundable.
## Invoices
| Payment Method | What Can Be Issued |
|---|---|
| WeChat Pay / Alipay | Invoice available, additional 6% of the payment amount charged |
| Stripe (bank card) | Stripe invoice (English) |
| USDT | No invoice provided |
For invoicing, corporate procurement, and bank transfers, contact us by email at support@1zheai.com.
## FAQ
Amount limits are subject to the wallet order page. Before paying, verify the top-up principal, payment processing service fee, and credited amount.
When the balance is exhausted, requests return HTTP 403, and the response body contains `Insufficient user quota` (`/v1/messages` has `error.type` as `billing_error`, and `/v1/chat/completions` has `insufficient_quota`). Rejected requests are not charged; you can continue using the service after the top-up is credited.
Calls made through Claude Code do not include any additional content. Other clients (SDKs, curl, and third-party tools) attach a system prompt to each request, billed as input tokens: approximately 350 tokens for Sonnet 4.6 and approximately 500 tokens for the 5.x series. For explanations and measured data, see [Billing for System Prompts](/en/docs/pricing-explained/#section-3).
The API balance refund rule covers unused principal within 7 days of top-up; consumed portions and payment processing service fees are not refundable. For cases beyond 7 days, please contact us separately to explain.
---
# Verify Model and Usage
Source: https://1zheai.com/en/docs/verify-model/
Markdown: https://1zheai.com/en/docs/verify-model.md
---
title: "Verify Model and Usage"
description: "Use call logs and five checks to verify the model, token usage, and cost of each call."
headingIds: {"Call Log":"section-1","Five Checks":"section-2","Completing the First Four Checks with a Script":"section-3","thinking Blocks":"section-4","When Inconsistencies Are Found":"section-5","FAQ":"section-6"}
---
## Call Log
Every call is recorded in the console's [call log](/en/docs/usage-logs/), listing the model, input, output, cache read, and cache write token usage, as well as the cost.
## Five Checks
The following checks compare against the public format of the Anthropic API to detect differences in returned fields and format.
| Check | Expected Result | What to Watch For |
|---|---|---|
| 1. Returned `model` field | Matches the requested model ID | Returns a different model name, or the field is missing |
| 2. Cache read | The same request meeting cache conditions is sent twice within the cache validity period; the second `cache_read_input_tokens` is greater than 0 | Always 0, or no cache fields in `usage` |
| 3. Tool call ID | The `id` of the `tool_use` block starts with `toolu_` | Other formats, or the model does not call tools as required |
| 4. Streaming event order | `message_start`, `content_block_start`, `content_block_delta`, `message_delta`, and `message_stop` appear in sequence | Only OpenAI-format `data:` blocks, or events missing or out of order |
| 5. Real task comparison | Use a fixed task and compare results with the official API or other trusted sources | Results noticeably worse, abnormal refusals, or frequent truncation |
These checks can only detect differences in fields and format; they cannot alone confirm the model actually in use. `model` fields can be rewritten, and formats can be imitated.
## Completing the First Four Checks with a Script
Requires `bash`, `curl`, and `jq`. The script makes five small calls, one of which writes approximately 18,000 tokens to cache, billed at the normal price.
```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
```
Check 3 uses `tool_choice: auto`. 5.x models such as Sonnet 5.5 do not support forcing tool specification (`{"type":"tool"}` or `{"type":"any"}`) and will return a 400 `does not support forced tool_choice`.
The output from testing with `claude-sonnet-5-5` on 2026-10-15 is as follows (Check 1 only retains key fields):
```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
```
Whether the `ping` event appears and where it appears is not fixed and does not affect the judgment.
## thinking Blocks
When thinking is enabled, the returned `thinking` block includes a `signature` field, which can also serve as a format check. The syntax for 5.x models differs from 4.x; tested on 2026-10-15:
| Model | `thinking` Parameter | Result |
|---|---|---|
| `claude-sonnet-4-6` | `{"type":"enabled","budget_tokens":1024}` | Returns a `thinking` block with thinking text and `signature` |
| `claude-sonnet-5` | `{"type":"enabled","budget_tokens":1024}` or `{"type":"adaptive"}` | Both work |
| `claude-sonnet-5-5` | `{"type":"adaptive"}` | Works; passing `enabled` returns 400, indicating only adaptive is supported |
The `thinking` block of 5.x models contains only `signature` by default, with the thinking text as an empty string. To see the thinking summary, add `"display": "summarized"`:
```json
"thinking": {"type": "adaptive", "display": "summarized"}
```
When using third-party detection websites, it is recommended to create a dedicated API key and delete it after testing.
## When Inconsistencies Are Found
Send an email to support@1zheai.com with the request time, model ID, complete response content (with the API key removed), and the corresponding check item. The request id in the response content or error message can help locate this call.
## FAQ
Unreliable. The model's self-introduction is influenced by the system prompt, and under certain prompts it may answer its own version incorrectly. Checking the returned fields and event format is more informative.
Claude Code uses the Haiku model for some background tasks, and corresponding records will appear in the call log. You can use the `ANTHROPIC_DEFAULT_HAIKU_MODEL` environment variable to specify the model used for such tasks; see [Claude Code integration](/en/docs/quickstart-claude-code/). If this occurs when not using Claude Code, please send the request time to support@1zheai.com.
---
# Error Codes and Troubleshooting
Source: https://1zheai.com/en/docs/troubleshooting/
Markdown: https://1zheai.com/en/docs/troubleshooting.md
---
title: "Error Codes and Troubleshooting"
description: "Causes and solutions for 401, 404, 429, 529, 5xx, timeouts, and Claude Code errors when calling 1折AI."
headingIds: {"Troubleshooting Order":"section-1","Error Code Quick Reference":"section-2","Actual Response Samples":"section-3","Troubleshooting by Symptom":"section-4","401 / Invalid token":"section-5","404 / Invalid URL":"section-6","403 / error code: 1010":"section-7","429 Too Many Requests":"section-8","529 / overloaded_error":"section-9","Timeout, streaming disconnects mid-way":"section-10","Claude Code: Goes straight to the login screen":"section-11","Claude Code: Extra inputs are not permitted / context_management returns 400":"section-12","Balance is sufficient but calls fail":"section-13","Limited Retries and Feedback Template":"section-14","Still Not Resolved":"section-15"}
---
Go through the checklist below in order; most issues can be found within the first three steps.
## Troubleshooting Order
1. **Address**: For Anthropic-family tools, fill in `https://1zheai.com`; for OpenAI-family tools, fill in `https://1zheai.com/v1`. See [Base URL and Authentication](/en/docs/base-url/).
2. **API key**: Is it complete (no extra spaces or line breaks), has it been deleted, and is it filled into the correct field?
3. **Balance**: Is the balance in the console sufficient?
4. **Model ID**: Is it exactly the same as in [Supported Models](/en/docs/models/)?
5. **Network**: Turn off the proxy and try connecting directly again.
6. **Still not working**: Provide a minimal curl reproduction (see below), and send us the response and timing.
```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` will print the status code and response headers together, which is very useful for troubleshooting.
## Error Code Quick Reference
| Status Code | Common Cause | What to Do |
|---|---|---|
| 400 | Problem with the request body: wrong parameter name, wrong field type, `max_tokens` exceeds the model limit, or includes a beta field the upstream does not recognize | Check the field indicated in `message`; for Claude Code, see "Extra inputs are not permitted" below |
| 401 | API key is invalid, deleted, disabled, expired, its own quota is exhausted, or it is missing or placed in the wrong header | The response is always `Invalid token`; check each item; for Anthropic native, use `x-api-key` or `Authorization: Bearer` |
| 403 | Insufficient account balance (`billing_error` / `insufficient_quota`); this API key has not enabled that model; the request IP is not in this API key's whitelist (both are `permission_error`) | Top up, or edit this API key's model restrictions and IP whitelist on the "API Keys" page |
| 404 | Wrong path, or the model does not exist / is currently unavailable | `Invalid URL` verify the address; `not_found_error` / `model_not_found` verify the model ID and available list |
| 413 | Request body too large | Reduce the content sent at once; split large files into segments |
| 429 | Temporary upstream rate limiting. We currently do not set rate limits on API keys | Retry later; add exponential backoff for batch jobs |
| 503 | The model exists but there is temporarily no healthy upstream service, or a temporary service failure | Retry later; if it persists, provide the request ID and contact support |
| 500 / 502 | Temporary gateway or upstream failure | Retry later; if it persists, send an email to support@1zheai.com |
| 504 | Request timed out | Use streaming for long outputs; increase the client timeout |
| 529 | Upstream Anthropic overloaded (`overloaded_error`) | Wait a few seconds and retry, or temporarily switch to another model |
For the full meaning of Anthropic's official error types (`invalid_request_error`, `authentication_error`, `rate_limit_error`, `overloaded_error`, etc.), see the [official Errors documentation](https://platform.claude.com/docs/en/api/errors).
Errors returned by the upstream are passed through with the status code and `message` unchanged, and `message` appends this request's request id at the end. When going through `/v1/messages`, the outer layer is the official `{"type":"error","error":{...}}` structure, and `error.type` is filled with the official type based on the status code; when going through `/v1/chat/completions`, it is OpenAI's `{"error":{...}}` structure.
## Actual Response Samples
Below are the actual responses tested against `/v1/messages` on 2026-10-15. When going through `/v1/chat/completions`, the content is the same, the outer layer has no `"type":"error"`, and `error` has an additional `code` field.
```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":""}}
```
For an explanation of the 404 when the model does not exist or is unavailable, see [Supported Models](/en/docs/models/). The request id in the response corresponds to your specific request; include it when reporting an issue.
## Troubleshooting by Symptom
### 401 / Invalid token
- The API key had extra spaces or line breaks when copied; copy it again.
- The API key has been deleted or disabled in the console, or has expired, or its own quota is exhausted. In all these cases, the response is the same message `Invalid token`.
- In Claude Code, both `ANTHROPIC_API_KEY` and `ANTHROPIC_AUTH_TOKEN` are set, and one of them is an old value: keep only one, `ANTHROPIC_AUTH_TOKEN` is recommended.
- The `env` of `settings.json` overrides the same-named variable exported in the terminal; if changing the terminal variable has no effect, check `~/.claude/settings.json`.
### 404 / Invalid URL
First look at the error type: `not_found_error` or `model_not_found` requires checking the [Model ID and Available List](/en/docs/models/). For `Invalid URL`, check `/v1`: OpenAI SDK, Cursor, Cline (OpenAI Compatible) should be filled up to `https://1zheai.com/v1`; Claude Code and Anthropic SDK should only fill in `https://1zheai.com`; filling in `/v1` will result in `/v1/v1/messages`.
### 403 / error code: 1010
If the response contains only the line `error code: 1010` and no JSON, the request was blocked before reaching the gateway. It is currently known that sending requests directly with Python's standard library `urllib` will encounter this (its default User-Agent is `Python-urllib/3.x`). Add your own `User-Agent` in the request headers, or switch to the official SDK, `requests`, `httpx`.
### 429 Too Many Requests
We currently do not set rate limits on API keys. Receiving a 429 usually means high upstream load; just retry later. For batch jobs, it is recommended to add exponential backoff: wait a period after a failure before retrying, double the wait time each time, and control concurrency yourself with a queue.
### 529 / overloaded_error
Upstream Anthropic is temporarily overloaded; this is unrelated to your API key or balance. Wait a few seconds and retry; if you are in a hurry, temporarily switch to another model in the same series.
### Timeout, streaming disconnects mid-way
- For long responses, use streaming (`"stream": true`) as much as possible; it is less likely to be cut off by intermediate network devices.
- Claude Code can use `API_TIMEOUT_MS` to increase the timeout; the default is 600000 (10 minutes).
- If a proxy is on, turn it off and try once first; many disconnects come from proxy nodes.
### Claude Code: Goes straight to the login screen
This means Claude Code did not read your API key. Run `/status` in Claude Code and look at the base URL and credential source lines; if they are empty, go back to [Claude Code Integration](/en/docs/quickstart-claude-code/) to check environment variables or `settings.json`.
### Claude Code: Extra inputs are not permitted / context_management returns 400
Claude Code includes some experimental beta fields in requests; strict upstreams that do not recognize them will return 400. Set the following environment variables to turn them off (from Claude Code's official LLM gateway documentation):
```bash
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
```
### Balance is sufficient but calls fail
- If only a specific model fails, that model may be temporarily unavailable, the ID may be written incorrectly, or this API key has model restrictions set (403 `This token has no access to model …`).
- If all fail and it is 401, check whether this API key has a quota limit set and it has been exhausted, or it has expired. You can see this in the "Quota ($)" and "Expires" columns on the "API Keys" page.
- For other cases, see the error code table above.
## Limited Retries and Feedback Template
Do not use infinite loops to mask configuration errors. For SDK timeouts, automatic retry counts, and backoff handling, see [Timeouts and Retries](/en/docs/retries/).
When contacting support, you can copy the template below, delete the key, authentication headers, and private content before sending:
```text
发生时间与时区：
客户端及版本：
请求方法与完整路径：
模型 ID：
HTTP 状态码：
request id（如有）：
脱敏后的错误正文：
最小请求能否复现：
是否使用代理 / 是否仅某个模型失败：
```
## Still Not Resolved
Send an email to support@1zheai.com, including the time, model ID, the tool and version you used, and the complete output of `curl -i` (with the API key removed).
---
# AI and Automation
Source: https://1zheai.com/en/docs/ai/
Markdown: https://1zheai.com/en/docs/ai.md
---
title: "AI and Automation"
description: "Have an AI assistant read the documentation on demand, and understand the current status of machine-readable entry points and the documentation MCP."
headingIds: {"Available machine-readable entry points":"section-1","Handoff tasks for AI":"section-2","Documentation MCP status":"section-3"}
---
You can ask an AI assistant to read the documentation on this site first, then assist with configuring tools or writing calling code. Reading ordinary documentation and calling a model API are two different things: reading public documentation does not require an API key.
## Available machine-readable entry points
| Entry point | Purpose |
| --- | --- |
| [llms.txt](/en/docs/llms.txt) | Discover documentation by section, and choose the pages you need to read |
| [Documentation index](/en/docs/docs-manifest.json) | Get page titles, the section each belongs to, and the web and Markdown URLs |
| [Full documentation text](/en/docs/llms-full.txt) | Read all pages at once; the content is long, so prefer reading page by page |
| [Homepage Markdown](/en/docs/index.md) | Read the source documentation content without the site navigation |
Every article has a corresponding Markdown address; for example, `/en/docs/quickstart-claude-code/` corresponds to `/en/docs/quickstart-claude-code.md`. You can also use "Copy this page" at the top of a page. The Markdown may retain documentation component markup such as cards.
## Handoff tasks for AI
Copy the task instructions so the assistant first checks the scope of support, then configures and verifies it.Choose the protocol, address and model configuration according to the tool.
## Documentation MCP status
This site does not currently provide a connectable documentation MCP server. Please use the documentation addresses above first, or copy the page content to the assistant; do not treat a model API's Base URL as an MCP address.
The purpose of a documentation MCP is to search and read public materials. Operations such as account queries and key management are a different class of capability and cannot be obtained through the public documentation entry points.
---
# Let AI Help You Get Set Up
Source: https://1zheai.com/en/docs/agent-workflow/
Markdown: https://1zheai.com/en/docs/agent-workflow.md
---
title: "Let AI Help You Get Set Up"
description: "A copyable task brief that helps an AI read the documentation first, check the restrictions, and then complete the configuration and verification."
headingIds: {"Copy the Task Brief":"section-1","How to Judge Whether It Is Done":"section-2"}
---
## Copy the Task Brief
Give the instructions below to an AI assistant that can read web pages, and add the tool name and operating system. If the assistant cannot access the network, first obtain the relevant article content via [the machine-readable entry point](/en/docs/ai/).
```text
请帮助我将现有工具或应用接入 1折AI。
目标工具与版本：[填写]
操作系统或编程语言：[填写]
先读取 https://1zheai.com/en/docs/llms.txt，找到目标工具或 SDK 的文档。
再读取该页 Markdown，以及 API 参考和模型说明。
要求：
1. 先说明当前支持范围和工具配置要求。
2. 根据目标工具确定 Base URL，不要统一添加或删除 /v1。
3. 模型 ID 以当前文档和密钥可用模型列表为准，不要猜测。
4. 查看现有配置，只修改必要字段，保留其他供应商配置。
5. 使用环境变量或工具提供的凭据存储方式；不要把密钥写入源码、
对话、日志或提交记录。需要密钥时，让我在本地安全配置。
6. 执行会产生费用的测试前，说明测试内容并取得我的同意。
7. 用一次最小请求验证，再提示我在调用日志里核对记录。
8. 如果验证失败，保留脱敏的状态码与请求 ID，按排错文档处理；
不要用反复重试掩盖配置问题。
9. 最后说明修改位置、验证结果、剩余限制及恢复原配置的方法。
```
## How to Judge Whether It Is Done
Completing the configuration does not mean the setup is done. You should confirm at the same time that the tool returns results normally, that the model actually in use matches expectations, and that the corresponding record can be found in [the call log](/en/docs/usage-logs/).
This page is a copyable task brief, not an installed Agent Skill or MCP service. Any assistant still needs the corresponding ability to read documentation and operate local configuration.
---