API 文档

快速开始

一个 chat completions 调用 —— 选择您熟悉的客户端。

curl https://api.eastx.ai/v1/chat/completions \
  -H "Authorization: Bearer $EASTX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "messages": [
      {"role": "user", "content": "Hello!"}
    ]
  }'

鉴权

所有端点均要求在 Authorization 请求头中携带 API 密钥：

Authorization: Bearer sk-eastx-<your-key>

• • 密钥在 /keys 页面创建，且仅展示一次 —— 请妥善保存。
• • 创建密钥时可选配置单密钥消费上限、RPM 速率限制、可用模型名单与来源 IP 白名单。设置了 IP 白名单后，仅名单内的 IPv4/CIDR 来源可调用（否则返回 403）；留空则不限制来源 IP。
• • 若密钥泄漏，在同一页面立即吊销；吊销即时生效。

门户登录：获取滑块拼图

密码登录和邮箱验证码发信前，用户明确操作后获取 PNG 拼图。返回 challengeId、backgroundImage、pieceImage、width:320、height:160、pieceSize:44、pieceY；有效期120秒，不返回正确横坐标。白标门户应携带 tenantSlug。

请求体

{
  "email": "user@example.com",
  "tenantSlug": "acme"
}

示例

curl $PORTAL_ORIGIN/api/v1/auth/slider/challenge -H "Content-Type: application/json" -d '{"email":"user@example.com","tenantSlug":"acme"}'

门户登录：验证拼图位置

提交用户拖动后的横坐标 offset（原始320像素图片坐标）。成功返回 {captchaToken,expiresIn:300}，票据绑定邮箱、租户和来源IP，一次性使用。答错或过期后重新获取拼图。

请求体

{
  "email": "user@example.com",
  "tenantSlug": "acme",
  "challengeId": "<challengeId>",
  "offset": 180
}

示例

curl $PORTAL_ORIGIN/api/v1/auth/slider/verify -H "Content-Type: application/json" -d '{"email":"user@example.com","tenantSlug":"acme","challengeId":"<challengeId>","offset":180}'

• • 示例180仅展示数值类型；实际位移必须由用户根据当次图片拖动确定。

门户登录：邮箱密码

必须携带刚通过滑块获得的 captchaToken；缺失返回 captcha_required，伪造、过期或重复使用返回 invalid_captcha，不签发登录会话。每次尝试后重新验证，包括密码错误或网络失败。

请求体

{
  "email": "user@example.com",
  "password": "<password>",
  "captchaToken": "<captchaToken>",
  "tenantSlug": "acme"
}

示例

curl -c cookies.txt $PORTAL_ORIGIN/api/v1/auth/login -H "Content-Type: application/json" -d '{"email":"user@example.com","password":"<password>","captchaToken":"<captchaToken>","tenantSlug":"acme"}'

• • 此要求仅用于门户用户登录，不增加 API Key 调用 /v1/* 的滑块要求。

门户登录：发送邮箱验证码

purpose 为 login 或 signup 时，发信均要求新的一次性 captchaToken。收到邮件后调用 /api/v1/auth/email-code/confirm，携带同一 email、tenantSlug、purpose 和六位 code，无须再次滑块验证。原有邮箱/IP/全局发信限额继续生效。

请求体

{
  "email": "user@example.com",
  "purpose": "login",
  "captchaToken": "<captchaToken>",
  "tenantSlug": "acme"
}

示例

curl $PORTAL_ORIGIN/api/v1/auth/email-code/send -H "Content-Type: application/json" -d '{"email":"user@example.com","purpose":"login","captchaToken":"<captchaToken>","tenantSlug":"acme"}'

商户申请：图形验证码

公开接口，返回 {captchaId,imageSvg,expiresInSeconds:300}。以图片展示自托管 SVG，由申请人填写算式答案。支持手动刷新，不需要登录或 API Key。

示例

curl $PORTAL_ORIGIN/api/v1/merchant/apply/captcha

商户申请：发送邮箱验证码

申请人明确点击发送后调用；邮箱和子域名去除首尾空格并转小写。不会自动发送邮件。

请求体

{
  "email": "founder@acme.com",
  "slug": "acme",
  "captchaId": "<captchaId>",
  "captchaCode": "<math answer>"
}

示例

curl $PORTAL_ORIGIN/api/v1/merchant/apply/email-code/send -H "Content-Type: application/json" -d '{"email":"founder@acme.com","slug":"acme","captchaId":"<captchaId>","captchaCode":"<math answer>"}'

• • 成功返回 {cooldownSeconds:60}。倒计时结束后可重发；每次发送尝试后刷新一次性图形验证码。发送失败不显示成功。
• • 邮箱验证码为 6 位数字，仅用于当前邮箱及子域名；修改任一项后清空已输入验证码。服务端负责最终校验，前端校验不代表邮箱已验证。
• • 错误包括 captcha_invalid、email_domain_invalid、email_code_unavailable、rate_limit_exceeded、contact_email_reserved、slug_reserved、slug_taken 和 validation_failed。

商户申请：提交 / 补验历史申请

提交时必须携带收到的 6 位 emailCode。子域名须为 2–32 位小写字母、数字及连字符，不能以连字符开头或结尾。

请求体

{
  "slug": "acme",
  "contactEmail": "founder@acme.com",
  "emailCode": "123456",
  "name": "Acme AI",
  "contactName": "Jane",
  "applyMessage": "Our use case"
}

示例

curl $PORTAL_ORIGIN/api/v1/merchant/apply -H "Content-Type: application/json" -d '{"slug":"acme","contactEmail":"founder@acme.com","emailCode":"<six digits from email>"}'

• • 错误包括 email_code_invalid、email_code_unavailable、rate_limit_exceeded、contact_email_reserved、slug_reserved、slug_taken、application_changed 和 validation_failed。状态变化后请确认原邮箱和子域名并重新获取验证码。
• • 原有已开通或待审核工作区使用完全匹配的原 slug、原联系邮箱和有效验证码补验，成功返回 {reverificationOnly:true}。仅记录邮箱验证凭据，不覆盖原品牌名、联系人或申请说明，不改变原状态，也不表示审核通过或重新激活。子域名可用性提示仅供参考，不应阻止补验。

列出模型

返回当前账户可调用的模型目录。即将上线和已停用的模型会被过滤掉。

示例

curl https://api.eastx.ai/v1/models \
  -H "Authorization: Bearer $EASTX_API_KEY"

• • 每条记录都带有 OpenAI 风格的字段（id、object、created、owned_by），并额外包含 display_name、input_price_per_1m、output_price_per_1m。大多数 OpenAI SDK 会忽略未知字段。

获取单个模型

按 id 查询单个模型。部分 SDK 会在客户端初始化时调用此端点校验模型名是否有效。

示例

curl https://api.eastx.ai/v1/models/claude-sonnet-4-6 \
  -H "Authorization: Bearer $EASTX_API_KEY"

• • 若 id 未知或已停用，返回 404 model_not_found。

对话补全

兼容 OpenAI 的 chat completions 端点。支持流式（SSE）与非流式两种模式。token 用量在上游计费，您的余额会在每次请求结束时扣减。

请求体

{
  "model": "claude-sonnet-4-6",
  "messages": [
    {"role": "system", "content": "You are concise."},
    {"role": "user", "content": "Explain JWT in one sentence."}
  ],
  "max_tokens": 256,
  "temperature": 0.2,
  "stream": false
}

示例

curl https://api.eastx.ai/v1/chat/completions \
  -H "Authorization: Bearer $EASTX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "messages": [{"role":"user","content":"hi"}],
    "max_tokens": 32
  }'

• • 如需流式响应，请设置 "stream": true。每个 SSE 事件形如 "data: {...}"，承载一个 OpenAI 风格的 chunk，其中 "choices[0].delta.content" 为增量文本，最后一个非 DONE chunk 会带上 "choices[0].finish_reason"。请持续消费，直到读到 "data: [DONE]"。
• • Vision 与 tool / function calling 会透传到支持这些能力的上游模型（如 Claude、qwen-vl-*、GPT 系列）。详见下方示例。
• • 在调用前会按最坏情况（input + max_tokens × output 价格）预扣余额。余额不足返回 402。
• • 推理模型（如 gpt-5.5）会将思维链按 output_tokens 计费 —— 您看到的 usage.completion_tokens 可能超过可见消息的长度。思维链本身不会在响应中暴露，与 OpenAI o 系列保持一致。

{
  "model": "claude-sonnet-4-6",
  "messages": [
    {"role": "user", "content": "What's the weather in Paris?"}
  ],
  "tools": [{
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "Get the current weather for a city.",
      "parameters": {
        "type": "object",
        "properties": {"city": {"type": "string"}},
        "required": ["city"]
      }
    }
  }]
}

{
  "model": "claude-sonnet-4-6",
  "messages": [{
    "role": "user",
    "content": [
      {"type": "text", "text": "What is in this image?"},
      {"type": "image_url", "image_url": {"url": "https://example.com/cat.jpg"}}
    ]
  }]
}

Responses API（兼容）

兼容 OpenAI Responses 的文字和图片输入，支持文字流式输出。鉴权、模型白名单、额度和计费与 Chat Completions 相同。

请求体

{
  "model": "kimi-k3",
  "input": [{"role":"user","content":[{"type":"input_text","text":"Say hello"}]}],
  "max_output_tokens": 128,
  "stream": false
}

示例

curl https://api.eastx.ai/v1/responses \
  -H "Authorization: Bearer $EASTX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"kimi-k3","input":"Say hello","max_output_tokens":128}'

• • 请求使用 input 和 max_output_tokens，响应包含 output 和 usage；流式输出为 response.* 命名 SSE 事件。
• • 工具调用、previous_response_id、服务端保存的会话状态和不支持的字段会明确返回 400，不会静默忽略。
• • input_video 是实验性的上游扩展，会映射到 video_url；图片和视频能否成功取决于所选上游，协议兼容层不能代替上游支持媒体格式。

Anthropic Messages（兼容）

Anthropic Messages API 兼容端点。基于 Anthropic SDK 的工具（Claude Code、ZCode 等）把 base URL 指向这里即可直接使用 EastX。请求在内部翻译为 chat-completions 处理，鉴权、模型名单、限速、计费与 OpenAI 端点完全一致。

请求体

{
  "model": "claude-sonnet-4-6",
  "max_tokens": 1024,
  "system": "You are concise.",
  "messages": [
    {"role": "user", "content": "Explain JWT in one sentence."}
  ],
  "stream": false
}

示例

curl https://api.eastx.ai/v1/messages \
  -H "x-api-key: $EASTX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 256,
    "messages": [{"role":"user","content":"hi"}]
  }'

• • 鉴权同时接受 Anthropic 风格的 "x-api-key: <key>" 和 "Authorization: Bearer <key>" —— 用的都是同一把 sk-eastx-* 密钥。
• • 流式输出为标准 Anthropic SSE 事件（message_start、content_block_delta、message_delta、message_stop）。工具调用与图像输入双向翻译。
• • 请求中的 "thinking" 参数会被接受但不转发 —— 模型是否思考由上游自行决定。会输出推理过程的模型（如 DeepSeek）以标准 Anthropic "thinking" 内容块返回。
• • POST /v1/messages/count_tokens 返回本地估算值（约 4 字符/token），不打上游、不计费。

// %USERPROFILE%\.zcode\cli\config.json  (macOS/Linux: ~/.zcode/cli/config.json)
{
  "provider": {
    "eastx": {
      "kind": "openai-compatible",
      "name": "EastX",
      "options": {
        "baseURL": "https://api.eastx.ai/v1",
        "apiKey": "sk-eastx-...",
        "apiKeyRequired": true,
        "includeUsage": true
      },
      "models": {
        "claude-sonnet-4-6": { "name": "Claude Sonnet 4.6" },
        "deepseek-v4-pro":   { "name": "DeepSeek V4 Pro" }
      }
    }
  },
  "model": { "main": "eastx/claude-sonnet-4-6", "lite": "eastx/deepseek-v4-pro" }
}

向量

为一个或多个字符串生成向量。此端点仅接受 modality=embedding 的模型（对话模型会返回 400 wrong_endpoint）。

请求体

{
  "model": "text-embedding-v3",
  "input": "Hello, world."
}

示例

curl https://api.eastx.ai/v1/embeddings \
  -H "Authorization: Bearer $EASTX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-v3",
    "input": ["hello", "world"]
  }'

• • input 支持单个字符串或字符串数组。
• • 仅按 input token 计费（output_tokens = 0）。

图像生成

根据文本提示词生成图像。EastX 封装了阿里云的异步任务 API，因此客户端看到的是同步响应 —— 典型延迟 3-10 秒。按张计费，与分辨率无关。

请求体

{
  "model": "qwen-image-plus",
  "prompt": "a red apple on a wooden table",
  "n": 1,
  "size": "1024x1024"
}

示例

curl https://api.eastx.ai/v1/images/generations \
  -H "Authorization: Bearer $EASTX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-plus",
    "prompt": "a red apple on a wooden table",
    "n": 1,
    "size": "1024x1024"
  }'

• • 响应结构：{"created":<ts>,"data":[{"url":"<signed-oss-url>","revised_prompt":"..."}]}。
• • n 最多为 4。可选尺寸取决于具体模型；1024x1024 各模型均支持。
• • URL 是临时签名的 OSS 链接 —— 请在约 1 小时内下载并自行托管。
• • 内部轮询超时为 90 秒；过长的任务返回 504 upstream_timeout。

计费说明

按次计费，以美元结算，请求完成后从余额扣除。定价页给出的单价均为每 100 万 tokens 的价格。

• • 按实际用量结算：以上游返回的本次请求 token 数（输入 + 输出）计费，不按估算值。请求失败不计费。
• • 调用前的余额校验：转发前会按最坏情况估算本次花费（input + max_tokens，且按该请求可能落到的最贵档计价）来校验余额。余额不足时在调用上游之前就返回 402。
• • 阶梯计价：部分模型不是单一价，而是分档计价 —— 单价取决于输入有多长、模型是否进行了推理，少数模型还取决于调用时段。最便宜档与最贵档可能相差 10 倍，每次请求按其真实输入 token 数落到的那一档计费。所有分档模型都会在定价页标注「阶梯计价」徽章，展开即可看到每一档的单价。这类模型在目录里显示的价格是它最便宜的那一档。
• • 思考档如何判定：请求中声明了思考（enable_thinking、reasoning_effort 或 thinking.type），**或者**响应中实际包含推理内容，两者满足其一即按思考档计费。部分模型不需要显式声明就会默认思考，上游此时同样按思考档收费。
• • 缓存命中：当上游报告命中提示词缓存时，输入中命中的那部分按该模型的缓存命中价计费，其余部分按常规输入价计费。分档模型的缓存命中价同样分档，与该次请求落到的档位一致。
• • 核对某一笔扣费：每次调用命中的档位会显示在控制台首页的调用记录里。若仍有疑问，请把 request id 发给我们，我们会与上游账单逐笔核对。

错误码

所有错误均以以下 JSON 结构返回：{"error":{"code":"...","message":"...","type":"..."}}。HTTP 状态码与 error.code 的对应关系如下表。

type 字段按家族对错误码归类，便于您据此分支处理，而无需逐个匹配名称：auth_error（密钥问题）、invalid_request_error（请求输入）、rate_limit（RPM 上限）、billing_error（余额 / 上限）、upstream_error（上游服务商）、server_error（少见 —— EastX 自身问题）。

智能路由

在 API Key 设置中选择默认路由、智能自动、价格优先、速度优先或成功率优先。仅在同一对话模型有多个可用报价时生效，不改变模型权限与 IP 限制。

{
  "model": "gpt-6.1-sol",
  "routing_priority": "price",
  "messages": [
    {
      "role": "user",
      "content": "Hello"
    }
  ]
}

请求覆盖顺序：routing_priority → provider.sort → x-eastx-routing 请求头 → API Key 设置。有效值为 default、auto、price、speed、success_rate。支持 /v1/chat/completions 和 /v1/messages。

价格优先按请求预计费用排序；速度和成功率使用当前租户近 24 小时记录，无历史时采用保守估计，不能保证每次最快。默认路由保留原顺序并追加备用来源。目录显示各报价最高单价，实际按成功渠道的价格及档位结算；商户自定义零售价保持有效。余额预检覆盖可能故障切换的最高报价。