# 快速开始

从选择一个具体模型，到发出第一条请求。下面的例子采用本站网关支持的 OpenAI Chat 兼容格式。

> API 调用以服务端目录、密钥权限与可用额度为准，执行示例会发起真实计费请求。充值请登录个人工作台，或打开[充值页面](../recharge.html)办理；图片、音视频及其他协议是否可用取决于实际型号与渠道配置，不因文档中有示例就视为开通。

## 1. 选择具体模型

在[模型广场](../models.html)查看已发布型号、协议与分组售价，复制完整模型 ID。首次调用请选择 `openai-chat` 协议的文本型号，并核对目录中的 `maxOutputTokens`。

- 日常文本与代码任务：查看「文本」分类。
- 图片创作与编辑：查看「图片」分类及实际支持的协议。
- 视频任务：仅在目录和供应商通道均已配置后使用，不承诺当前可用。

## 2. 准备地址与密钥

登录[个人工作台](../dashboard.html#keys)，按服务端配置与账户权限创建真实应用 Key。密钥仅按页面提示展示，不提供演示 Key。核对本人余额与冻结额度，将应用密钥放在自己服务端的环境变量中。

网页地址随业务域切换；下载 .md 使用 123ali.com 示例，请以工作台的 Base URL 为准。未知或预览域不提供接入地址。

<!-- model-base-url:start -->

```bash
# Base URL 使用当前业务域对应的 api 子域，含 /v1
export AI_RELAY_BASE_URL="https://api.123ali.com/v1"
# 在私有服务端环境设置 AI_RELAY_API_KEY，不要写进公开代码
# 将 AI_RELAY_MODEL 设为目录中支持 openai-chat 的真实型号
# 将 AI_RELAY_MAX_TOKENS 设为不超过该型号 maxOutputTokens 的正整数
```

<!-- model-base-url:end -->

`AI_RELAY_BASE_URL` 已包含 `/v1`，后续请求只追加接口路径，例如 `/chat/completions`。[中转站](../relay.html#integration)可复制所选真实型号的代码示例，复制本身不会执行请求。

## 3. 发出第一条请求

```bash
: "${AI_RELAY_API_KEY:?请在私有环境设置应用密钥}"
: "${AI_RELAY_MODEL:?请设置目录中的真实模型 ID}"
: "${AI_RELAY_MAX_TOKENS:?请设置目录允许的最大输出 Token}"
python3 -c 'import json, os; print(json.dumps({"model": os.environ["AI_RELAY_MODEL"], "messages": [{"role": "user", "content": "用一句话介绍你能做什么。"}], "max_tokens": int(os.environ["AI_RELAY_MAX_TOKENS"])}))' \
  | curl --fail-with-body "$AI_RELAY_BASE_URL/chat/completions" \
    -H "Authorization: Bearer $AI_RELAY_API_KEY" \
    -H "Content-Type: application/json" \
    --data-binary @-
```

常规文本回答从 `choices[0].message.content` 读取。流式返回、图片和视频的响应结构不同，分别参考对应章节。请求中断或结果不确定时，先在[调用记录](../dashboard.html#logs)核对状态、用量与费用，再决定是否重试。

---

# 地址与认证

接入由 **Base URL、API Key、Model ID** 三项组成。三者对应正确后，再确认密钥权限与账户额度。

## 配置项

网页地址随业务域切换；下载 .md 使用 123ali.com 示例，请以[工作台](../dashboard.html#keys)的 Base URL 为准。未知或预览域不提供接入地址。

<!-- model-base-url:start -->

| 配置 | 作用 | 示例 |
| --- | --- | --- |
| Base URL | 当前业务域对应的 `api` 子域，含 `/v1` | `https://api.123ali.com/v1` |
| API Key | 用于请求认证的密钥 | `YOUR_API_KEY` |
| Model ID | 要调用的具体模型 | 从本站服务端目录复制完整 ID，不按示例名称猜测 |

<!-- model-base-url:end -->

OpenAI 兼容接口通过请求头发送密钥：

```http
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

## 选择正确的接口

| 接口 | 请求路径 | 用途 |
| --- | --- | --- |
| 文本对话 | `POST /v1/chat/completions` | 常规文本、流式对话和兼容的多模态输入 |
| Responses | `POST /v1/responses` | 采用 Responses 格式的模型调用 |
| 图片生成 | `POST /v1/images/generations` | 支持此协议的图片模型 |
| 图片编辑 | `POST /v1/images/edits` | 按模型说明提供图片与编辑指令 |
| 视频任务 | `POST /v1/videos` | 支持 OpenAI 兼容视频协议的通道 |

原生 Claude、Gemini 和部分视频通道可能需要不同路径或参数。模型能否通过某个接口调用，取决于部署版本、通道配置和模型支持；不要仅凭模型名称判断。

## 密钥与权限

- 把密钥放在服务端环境变量中，前端应用通过自己的服务端转发请求。
- 登录工作台通过真实密钥服务创建应用 Key；是否可创建及可选分组以服务端配置与账户权限为准。不生成演示密钥，创建后按一次性展示提示妥善保管。
- 排查错误时记录请求 ID 与错误信息，分享日志前移除密钥。

---

# 文本与多模态

OpenAI Chat 文本请求至少包含 `model`、`messages` 与正整数 `max_tokens`，输出上限不得超过目录中的 `maxOutputTokens`。对话历史按顺序追加到 `messages` 中，再发送下一次请求。型号必须来自本站服务端目录，协议、密钥权限与额度均满足才可调用。

## 常用参数

| 参数 | 用途 | 说明 |
| --- | --- | --- |
| `model` | 具体型号 | 使用完整模型 ID |
| `messages` | 对话内容 | 包含角色与消息内容 |
| `stream` | 流式输出 | `true` 时按流式协议读取 |
| `max_tokens` | 限制生成长度 | 本文的 OpenAI Chat 请求必填；为不超过目录 `maxOutputTokens` 的正整数，其他协议参数名不同 |
| `temperature` | 调整输出随机性 | 部分推理型号不接受此参数 |

## Python 示例

以下示例使用 Python 标准库，在服务端读取环境变量。

```python
import json
import os
from urllib.request import Request, urlopen

payload = {
    "model": os.environ["AI_RELAY_MODEL"],  # 目录中的真实 openai-chat 型号
    "messages": [{"role": "user", "content": "帮我整理一份项目计划。"}],
    "max_tokens": int(os.environ["AI_RELAY_MAX_TOKENS"]),  # 不超过目录 maxOutputTokens
}
request = Request(
    os.environ["AI_RELAY_BASE_URL"].rstrip("/") + "/chat/completions",
    data=json.dumps(payload).encode("utf-8"),
    headers={
        "Authorization": "Bearer " + os.environ["AI_RELAY_API_KEY"],
        "Content-Type": "application/json",
    },
    method="POST",
)
with urlopen(request, timeout=60) as response:
    result = json.load(response)
    print(result["choices"][0]["message"]["content"])
```

## JavaScript 示例

适用于支持 `fetch` 的 Node.js 服务端环境。代码读取环境变量，不在网页中填写真实密钥。

```javascript
const baseURL = process.env.AI_RELAY_BASE_URL;
const apiKey = process.env.AI_RELAY_API_KEY;
const model = process.env.AI_RELAY_MODEL;
const maxTokens = Number(process.env.AI_RELAY_MAX_TOKENS);
if (!baseURL || !apiKey || !model || !Number.isSafeInteger(maxTokens) || maxTokens < 1) {
  throw new Error("请配置接入地址、密钥、目录中的真实型号与允许的最大输出 Token");
}

const response = await fetch(baseURL.replace(/\/$/, "") + "/chat/completions", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + apiKey,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model,
    messages: [{ role: "user", content: "帮我整理一份项目计划。" }],
    max_tokens: maxTokens, // 不超过该型号目录 maxOutputTokens
  }),
  signal: AbortSignal.timeout(60000),
});
if (!response.ok) throw new Error("请求失败：" + response.status);
const result = await response.json();
console.log(result.choices[0].message.content);
```

## 流式与图像理解

设置 `stream: true` 后，响应通常为 SSE 事件流，应逐段读取并在结束信号到达时完成对话；不能按普通完整 JSON 处理。

支持图像理解的文本模型可接收图文内容，但这不代表它能生成图片。图片输入格式与大小限制以对应接口说明为准。先在[模型广场](../models.html)确认能力，再配置请求。

---

# 图片生成

图片生成和图片理解是两类任务。需要输出图片时，选择「图片」分类，并使用该模型支持的生成接口。

## 生成请求示例

下面展示 OpenAI 兼容图片接口的常见请求结构。替换 `YOUR_IMAGE_MODEL`，并按该型号支持范围调整 `size` 与 `n`。

```bash
curl --fail-with-body "$AI_RELAY_BASE_URL/images/generations" \
  -H "Authorization: Bearer $AI_RELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_IMAGE_MODEL",
    "prompt": "蓝色与橙色的极简产品海报，细线条，白色背景",
    "size": "1024x1024",
    "n": 1
  }'
```

返回内容可能是图片 URL，也可能是 Base64 数据。按响应字段处理与保存结果；原生 Gemini 图片模型的请求与返回格式可能不同。

## 分辨率与计费

目录中的价格规格不等于接口一定接受同名的 `size` 参数。图片数量、质量和尺寸可能影响计费，实际请求必须符合该型号的协议和通道限制。

正式售价以服务端目录中所选分组、计费单位与规格为准；「—」表示未配置或未知，不代表免费。文档不列固定报价，也不承诺当前有可调用的图片型号，调用需实际渠道、密钥权限与可用额度。

---

# 视频任务

视频生成通常采用异步任务。提交请求后先取得任务 ID，再查询进度，最后获取生成结果。

## 提交与查询

以下路径适用于支持 OpenAI 兼容视频协议的通道；Veo、Kling 等型号可能使用不同协议，以实际模型与通道配置为准。

| 步骤 | 路径 | 需要保存的信息 |
| --- | --- | --- |
| 创建任务 | `POST /v1/videos` | 返回的任务 ID |
| 查询任务 | `GET /v1/videos/{video_id}` | 状态、进度与错误信息 |
| 获取结果 | `GET /v1/videos/{video_id}/content` | 生成的视频文件 |

## 处理任务状态

1. **已提交／排队中**：保存任务 ID，稍后查询。
2. **处理中**：继续等待，按服务建议的间隔查询。
3. **已完成**：读取结果或下载文件。
4. **失败**：查看错误信息，再决定是否重新提交。

相同任务尚未完成时，先查询状态再决定是否重新创建。时长、尺寸、参考图片和生成费用均与具体型号相关。

> 本文是视频协议与任务处理参考，不承诺当前有可调用的视频型号。请以服务端目录、密钥权限与可用额度为准；未配置通道时不能创建任务。模型状态页中的「暂无样本」表示没有监控样本，不代表任务失败。

---

# 计费与用量

文本与图片／视频的计费单位不同，先确认单位，再比较价格。

## 文本价格

| 字段 | 表示什么 | 单位 |
| --- | --- | --- |
| 输入价格 | 按该型号口径计费的输入 Token | ¥ / 1M Tokens |
| 输出价格 | 生成内容的 Token | ¥ / 1M Tokens |
| 缓存读取 | 命中缓存的输入部分 | ¥ / 1M Tokens |
| 缓存创建 | 写入缓存的部分 | ¥ / 1M Tokens |

缓存是否可用、保存时间和写入费率由具体模型与通道决定。不要将已包含缓存部分的输入总量再重复计费；实际扣费以账单与模型计费口径为准。

## 查看记录

- [调用日志](../dashboard.html#logs)：定位模型、请求、消耗与状态。
- [余额与账单](../dashboard.html#wallet)：登录查看本人余额、冻结额度与账本流水。
- [模型状态](../status.html)：查看服务端监控的成功率、延迟与历史趋势；暂无样本不等于成功或故障。

API 请求会按密钥所属分组与实际用量计费。默认组与官方组是价格分组名称，官方组不承诺官方直连。余额、用量、费用与请求状态以服务端记录为准；中断或状态不确定时先核对调用记录，不要直接重试。

充值：登录个人工作台，或直接打开[充值页面](../recharge.html)，选择金额与支付方式，支付确认后自动计入余额与额度账本。后台调账不是用户充值或支付，会员商品订单也不会自动转成 API 额度。

---

# 生成记录与费用明细

登录[个人工作台的调用记录](./dashboard.html#logs)，查看服务端返回的本人请求、用量、费用与执行状态。未登录、查询失败或缺失字段都不当作零，也不补入固定示例。记录中存在某种媒体类型不代表音视频能力已开通，实际调用仍取决于目录、协议、渠道、密钥权限与可用额度。

## 两种查看方式

- **调用明细**：列表展示服务端返回的模型、请求 ID、分组、计费方式、用量、耗时、费用和状态；没有返回的字段保持未知。
- **结果历史**：仅在记录包含实际归档结果时展示媒体入口，不使用本地样本填充。点击详情查询本人请求的正文与归档结果。

模型、生成类型、计费方式、状态、关键词和日期范围可以组合筛选。日期按北京时间统计。CSV 仅导出当前筛选的已加载记录，不包含尚未加载的服务端分页；可先点击「加载更多」取得后续记录再导出。导出字段为请求 ID、模型 ID、分组、状态、提交时间、输入与输出 Token、费用，未知费用保留为未知。

## 按 Token 计费

服务端用量可能包含输入、输出、缓存读取和缓存创建。按 Token 计费的单价单位为「元 / 1M Token」，输入总量包含缓存部分。以下是计费口径说明，不保证每条记录都返回全部用量或单价字段。

```text
普通输入 = 输入总量 - 缓存读取 - 缓存创建
单项费用 = 对应 Token 数量 ÷ 1,000,000 × 对应单价
本次费用 = 各单项费用之和
```

缓存 Token 不再重复计入普通输入。服务端以微元记录金额，显示可保留到 0.000001 元，避免小额费用被显示为零。结算费用以请求记录与账本为准，不能用当前目录价格倒推历史费用；未返回历史费率时保持未知。

## 按次计费

按次、按张或按秒计费的单位以目录及请求记录为准。仅在服务端返回相应规格、计费数量和单价时展示，不填入固定价格或假设成功扣费。

同一请求可以包含多个归档文件，文件数量不代表计费数量。类型与计费方式分别记录；图片也可能采用 Token 计费。

## 查看与保存生成结果

点击详情会通过登录认证的同源接口读取请求正文、响应正文和媒体状态；这只是读取归档，不会重新发起模型请求。正文与结果经服务端脱敏后返回。复制正文或请求 ID 前请核对内容，勿对外公开敏感信息。

仅在实际存在可用归档文件且当前账户有权读取时，才可预览或下载。图片可切换同一请求的多份结果，媒体默认不自动播放。关闭详情或切换页面后停止播放；登录过期或无权限时应重新登录或停止读取。

## 任务状态与结果有效期

- **成功**：显示已结算费用。结果可用时支持预览与下载。
- **生成中**：显示「待结算」，不计入已结算费用汇总。
- **失败**：显示服务端错误原因与实际结算字段，不一概承诺未扣费；请核对账本。
- **状态不确定**：响应中断或执行状态未确认时，不表示成功或失败，先核对请求记录与费用，勿直接重复调用。
- **正文或结果不可用**：分别显示缺失、读取失败、截断或过期等实际状态；不以「成功」替代未知。旧记录若标注过期则不能预览或下载，过期不代表费用自动退回。当前归档策略不会因页面上的示例期限而自动清理永久归档。

如果预览文件加载失败，页面会提示预览不可用，仍可查看服务端已返回的计费信息；没有正文或媒体也不等于请求未发生。

---

# 错误码与排查

先看 HTTP 状态码，再看错误正文和请求日志。下面是常见情况，具体错误类型以实际部署返回为准。

## 常见状态码

| 状态码 | 常见情况 | 排查方向 |
| --- | --- | --- |
| `400` | 请求参数不符合接口要求 | 检查 JSON、模型 ID 与支持的参数 |
| `401` | 认证信息缺失或无效 | 检查 Bearer 请求头与密钥 |
| `403` | 请求不被允许 | 根据错误信息检查模型、分组与账户权限 |
| `429` | 请求受到限制 | 检查限流信息，按建议等待后重试 |
| `500` / `502` / `503` / `504` | 服务或上游异常 | 保存请求 ID，查看日志与模型状态 |

## 分步排查

1. 确认 Base URL，只包含一次 `/v1`。
2. 使用模型广场中的完整 ID，检查模型和密钥是否属于可用分组。
3. 缩减为最小请求，暂时去掉可选参数。
4. 在调用日志中查看错误信息与请求 ID。
5. 对照模型状态页，判断是否存在异常或没有样本。

---

# 常见问题

## 为什么示例不能原样直接调用？

示例中的密钥与模型 ID 需要替换为自己的应用密钥和服务端目录中的实际型号。模型 Base URL 使用当前业务域对应的 `api` 子域并包含 `/v1`，请从工作台复制；未知或预览域不提供接入地址。一次调用还需模型协议、渠道、密钥权限与可用额度全部满足；运行示例会发起真实计费请求。先登录工作台核对配置，再在自己的服务端使用。

## 为什么有的价格显示「—」？

表示该计费字段尚未配置。它不代表免费，也不代表型号不可用。

## 为什么视频没有首 Token 延迟？

首 Token 延迟用于文本流式响应。图片和视频更适合查看生成完成耗时；两种指标的口径不同。

## 如何保存或维护这份文档？

点击页面上的「Markdown 原文」或「下载 .md」即可查看与保存。每篇文档由独立的 Markdown 文件渲染。可下载当前文档，也可从文档列表下载完整指南。

## 相关资料

- [New API 接入指南](https://docs.newapi.pro/en/docs/guide/feature-guide/user/api)
- [New API 日志与异步任务说明](https://docs.newapi.pro/en/docs/guide/feature-guide/user/log)
- [New API 视频接口参考](https://docs.newapi.pro/en/docs/api/ai-model/videos/sora/createvideo)

---

# 阿栗AI 设计规范

版本：v1.1 · 2026-10-15

此文档记录当前网站设计基线。互动示例见 design.html。

## 01 设计原则

用少量、明确的规则，让每一页都像同一个产品。

LINE

### 细线建立秩序

分隔、边界与图标优先用线表达。大面积阴影和厚重描边不承担结构。

WEIGHT

### 价格以字重表达

把注意力留给金额、模型名称和主操作。正文保持轻、清楚、有层次。

COLOUR

### 纯色划分区域

橙、蓝、黑、白构成主视觉。通过底色与留白分区，不引入渐变。

CONTENT

### 内容先于装饰

供应商、具体型号、订单与价格可被快速找到，装饰始终服从使用任务。

### 继续使用

- 细线条、平面色块、小面积圆形与轨道线。
- 一个区域只强调一个主操作。
- 需要比较的信息以列表、表格和对齐的数字呈现。

### 避免使用

- 渐变、玻璃拟态、霓虹、多套装饰色同时出现。
- 大面积品牌色堆叠，掩盖正文或打乱阅读顺序。
- 为了视觉统一改写既定商品文案或价格。

## 02 品牌与形象

采用已确认的圆润 ali 字形，i 顶部保留机器人双眼。保留字形、笔画比例与字母间距，只调整配色。

| 项目 | 使用规则 |
| --- | --- |
| 网站名称 | 完整写法为「阿栗AI」，页面标题采用「页面名 · 阿栗AI」。 |
| 页头组合 | ali 标识容器桌面 80 × 40px；手机 68 × 34px；保持原比例，以 contain 放入。 |
| 品牌文字 | 中文品牌名约 18px / 700，AI 采用较轻字重，与 ali 标识并排使用。 |
| 标准配色 | a、l 为墨黑 #19191b；机器人 i 的头部与竖笔为品牌蓝 #2a74db。 |
| 安全空间 | 标志周围至少预留 12px；不得拉伸、旋转或叠加滤镜改色。 |
| 深色适配 | 深色页头与黑色页尾采用纯品牌蓝版本，搭配浅色站名，不增加底板。 |
| 小尺寸入口 | 页签、联系入口与票据使用同系列机器人 i 简版，保留双眼与圆角特征。 |
| 插图与厂商品牌 | 小牛用于辅助插画；供应商 logo 保留原色，业务主色保持橙、蓝、黑、白。 |

首屏品牌形象受容器约束，不挤占文字与内容。

### UI 设计资源

设计规范页面的品牌章节提供 12 份透明 PNG，支持按品牌标识、平面阿栗、立体阿栗分类，切换深浅预览背景，查看原图、逐项下载或下载完整素材包。

| 阿栗动作 | 文件 | 推荐用途 |
| --- | --- | --- |
| 阿栗 · 欢迎 | ali-welcome.png | 首页欢迎、产品介绍 |
| 阿栗 · 会员 | ali-membership.png | 会员选购、商品介绍 |
| 阿栗 · 开发 | ali-developer.png | AI 中转站、开发者服务 |
| 阿栗 · 阅读 | ali-reading.png | 接入文档、学习引导 |
| 阿栗 · 帮助 | ali-support.png | 联系我们、服务帮助 |
| 阿栗 · 完成 | ali-success.png | 完成提示、成功状态 |

三类入口首屏采用左文右图：左侧放标题、说明与主要操作，右侧以完整阿栗形象为中心，四个小型业务标签通过细线与节点衬托。标签只保留名称与一行短说明，不展示大段正文或独立操作栏；桌面标题 13px、辅助信息 9px、标签宽度不超过 136px。悬停或键盘聚焦标签时，对应连线同步强调。连线两端使用实际 DOM 连接点，随窗口、容器、图片和字体变化重新测量 SVG 坐标，避免断点缩放导致错位。保留原有细折线、圆角转折和小端点，仅叠加短段蓝 / 橙流光，沿同一路径从标签流向形象，0.54 秒错峰循环（原速度的 10 倍）；暂停图标在悬停图内或键盘聚焦时出现，遵循减少动态效果偏好，页面隐藏或形象离屏时暂停。无 JavaScript 时隐藏尚未测量的连线，入口与图片照常可用。首页关联会员、中转站、模型与工作台，次主页使用各自相关的业务内容。手机上下排列，图内仍使用轻量标签与完整形象。图片保持原始 1:1 比例、自动高度与安全留白。首屏底色直接跟随站点 --paper：浅色为纯白 #FFFFFF，深色为 #121316。深色模式的形象承托面使用纯白，保留黑白轮廓。

## 03 色彩规范

主色少而明确，文本、边线和底色通过语义变量取值。

品牌橙`#F37021`版块点缀、选中胶囊与少量视觉重心点击复制色值 ⧉品牌蓝`#2A74DB`主要操作、链接与 API 服务入口点击复制色值 ⧉墨黑`#19191B`文字、反色区域与细线图形点击复制色值 ⧉纯白`#FFFFFF`留白、卡片和深色区域的文字点击复制色值 ⧉
- 橙色通常配墨黑文字；品牌蓝上的主操作配白字。
- 黑色页尾和联系悬浮按钮固定使用 #000000，不随主题反转为白色。
- 大片品牌色应有明确功能。形象区只保留容器内的有限色块，不向视口边缘溢出。
- 灰色用于层次，不增加绿色、紫色等新的业务主色。状态必须同时提供文字。

主操作蓝 #2A74DB 配白字的对比度约 4.55:1；品牌橙 #F37021 配墨黑 #19191B 约 5.98:1。数值来自固定色值计算，不等于所有页面已完成视觉验收。

## 04 明暗主题与变量

主题切换改变语义底色和文字；品牌主操作、黑色页尾和黑色联系入口保持稳定。

LIGHT / 浅色
让层次来自边线。
白色画布、轻分隔、蓝色操作。
主要操作 →
DARK / 深色
让阅读保持清楚。
深色画布、浅色文字、稳定主色。
主要操作 →

| 语义变量 / 用途 | 浅色模式 | 深色模式 |
|  --- |  --- |  --- |
| `--paper`页面底色 | `#FFFFFF`⧉ | `#121316`⧉ |
| `--card`卡片底色 | `#FFFFFF`⧉ | `#1B1D22`⧉ |
| `--surface`功能页底色 | `#F8F8FA`⧉ | `#15171B`⧉ |
| `--subtle`次级底色 | `#FAFAFC`⧉ | `#22252B`⧉ |
| `--ink`主要文字 | `#19191B`⧉ | `#EEEEF2`⧉ |
| `--body-text`阅读正文 | `#50505B`⧉ | `#C4C7D0`⧉ |
| `--muted`辅助文字 | `#6F6F7B`⧉ | `#A8ACB7`⧉ |
| `--line`分隔线 | `#E1E1E7`⧉ | `#343840`⧉ |
| `--accent`主题链接 / 焦点 | `#2A74DB`⧉ | `#78ADFA`⧉ |
| `--accent-pale`浅蓝底色 | `#F4F7FC`⧉ | `#19283E`⧉ |
| `--accent-line`蓝色边线 | `#AAC6EE`⧉ | `#496B9D`⧉ |
| `--action-bg`主要操作底色 | `#2A74DB`⧉ | `#2A74DB`⧉ |
| `--on-accent`蓝底文字 | `#FFF`⧉ | `#FFF`⧉ |
| `--night`反色面板 | `#19191B`⧉ | `#19191B`⧉ |
| `--yellow`品牌橙（沿用变量名） | `#F37021`⧉ | `#F37021`⧉ |

历史变量 --yellow 对应实际品牌橙 #F37021。新增主题色优先使用语义变量，不在业务组件里堆叠临时 HEX。

当前主题 CSS 变量 浅色复制当前主题 ⧉

- 首次按系统主题展示；用户主动选择后跨页面保存。
- 深色模式的链接蓝为 #78ADFA；主按钮底色仍为 #2A74DB，避免白字落在过浅的蓝色上。
- 首页浅蓝信息区为 #EDF3FC，深色为 #18283E；局部链接可用更清楚的对比色。
- 公告在浅色模式为 #19191B，在深色模式为 #272C35，并保留细边线，避免与页面混成一片。

## 05 字体与数字

层级来自字号、字重和对齐，不依赖额外装饰字体。

TYPE / HEADING / NUMBER
清楚，就是一种力量.

¥148价格以较高字重呈现
金额对齐，单位保持清楚

| 场景 | 现有规格 | 使用要求 |
|  --- |  --- |  --- |
| 首页主标题 | 62px / 600；中屏约 49px；手机约 43px | 标题可自然换行，不用 nowrap 强行撑开手机页面。 |
| 功能页主标题 | 模型 / 状态 / 文档约 38px；会员页 52 → 44 → 34px | 页面只保留一个 h1。 |
| 分区标题 | 24–30px / 550–600 | 先表达这一段能做什么。 |
| 模型名称 / 卡片标题 | 模型约 13–15px / 600；会员约 20–22px / 600 | 具体型号完整可读，避免只显示系列大类。 |
| 会员价格 | 常规 48px / 750；宽屏约 52px | 货币符号小于金额，数字启用等宽数值。 |
| 正文 / 表格 | 正文以 12–14px 为主，表格与辅助信息约 10–12px | 正文行高约 1.8–1.9；关键信息不用装饰性小字号。 |
| 英文序号 / 微型标签 | 约 7–10px，适量字距 | 只用于不承担关键含义的辅助标记。 |
| ID / 代码 / 计量 | 系统等宽字体 / tabular-nums | 模型 ID、请求 ID、金额和延迟保持稳定对齐。 |

字体栈：Inter、Helvetica Neue、Arial、PingFang SC、Microsoft YaHei、sans-serif。当前页面不额外加载商业字体；字体可用性决定实际回退。

## 06 布局、间距与边界

色块可以有层次，内容必须在可靠的容器里排版。

4`4px`
8`8px`
12`12px`
16`16px`
20`20px`
24`24px`
28`28px`
32`32px`
40`40px`
48`48px`
64`64px`

| 结构 | 现有规格 / 准则 |
|  --- |  --- |
| 页面容器 | 默认最大宽 1280px，宽屏 ≥1600px 时为 1400px；数值包含左右内边距。 |
| 左右留白 | 常规 40px；≤1100px 为 28px；≤580px 为 20px；≤360px 为 15px。 |
| 间距基准 | 以 4px 为基准，常用 8 / 12 / 16 / 20 / 24 / 28 / 32 / 40 / 48 / 64px。 |
| 栅格 | 弹性列使用 minmax(0, 1fr)，子项必要时设置 min-width: 0。 |
| 形象与装饰 | 绝对定位只在 position: relative 的专用画布内使用；画布设置 overflow: hidden。 |
| 通栏色块 | 外层 section 承担背景，内层容器承担内容；不使用负边距强行把形象图推出页面。 |
| 长内容 | 长模型 ID 可换行；数据表格和代码块使用独立横向滚动区域。 |

CONTENT CONTAINER形象留在边界内。
装饰可以被容器裁切，正文和操作必须完整可见。

| 变化点 | 响应行为 |
|  --- |  --- |
| ≤1180px | 页头可分两行；主题按钮保持可见。 |
| ≤700px | 主导航允许横向滚动，不将每个入口压得过小。 |
| 会员卡片 | 常规 3 列；≤860px 为 2 列；≤580px 为 1 列。 |
| 模型目录 | 常规 4 列；≤1000px 为 3 列；≤720px 为 2 列。 |
| ≤760px / ≤520px | 首页首屏改为单列；窄屏产品与信息卡片依页面规则逐步收为单列。 |
| 验收视口 | 至少检查 320 / 375 / 768 / 1280px，以及长标题和长 ID 场景。 |

## 07 线条、圆角与图标

用细节形成一致性，避免每个模块拥有不同的装饰语言。

STROKE

边框 1px
图标约 1.2–1.5px
键盘焦点 2px

RADIUS

控件 2–4px
卡片 4–8px
胶囊与圆形按用途保留

ICON

圆头、圆角、线性图标
一般 16–24px
操作含义同时有文字或标签

- 普通输入控件约 3px，模型卡片约 4px，工作台卡片约 6px，会员卡片约 8px。
- 边线主要使用 --line；选中、悬停或聚焦时再使用蓝色。
- 阴影集中用于悬浮联系、模态浮层和轻微悬停，不把所有模块做成厚重浮卡。
- 动效通常为 150–200ms；折叠约 280ms；尊重减少动态效果偏好。

## 08 按钮、导航与筛选

主次清楚、选中可见，并让键盘用户知道焦点在哪里。

BUTTON / 实际可操作示例Tab 查看焦点
主要操作 次要操作 复制模型 ID ⧉暂不可用

| 组件 | 准则 |
|  --- |  --- |
| 主要按钮 | 一个任务区域一般一个；品牌蓝底白字，动词在前。 |
| 次要按钮 | 描边或文字形式；对取消、返回、查看使用较轻层级。 |
| 购买按钮 | 沿用会员卡片中的原始文案和价格，不为演示规范改写。 |
| 导航 | 当前页有文字强调与细选中线；手机横向滚动，不能依赖 hover 才能找到入口。 |
| 焦点 / 禁用 | 焦点为 2px 轮廓并留 3–5px 偏移；禁用使用真实 disabled，文字说明原因。 |
| 筛选 | 展示当前选择、结果数量与清空入口；分类与搜索共同生效。 |

FILTER / 模型类型清除筛选

全部文本图片视频搜索示例模型
OpenAI / 文本GPT-4.1Anthropic / 文本Claude Sonnet 4.5OpenAI / 图片GPT Image 2Google / 图片Gemini 3.1 Flash ImageGoogle / 视频Veo 3.1Google / 视频Veo 3.1 Fast
6 个模型示例

没有匹配结果，试试其他关键词或清除筛选。

## 09 表单与输入

先说明需要什么，再输入；错误紧贴字段，不让用户猜。

FORM / 只做页面内验证不会发送信息

联系邮箱 必填
用于演示标签、帮助文字与错误提示的位置。

请输入有效的邮箱地址。

使用场景个人使用应用开发团队协作消息提醒
验证表单
- 每个输入有持续可见的 label；placeholder 只给例子，不替代标签。
- 说明输入用途、格式和单位；必填以文字标明，不只依靠星号或颜色。
- 错误同时使用说明文字、字段状态与 aria-invalid，并关联 aria-describedby。
- 涉及 Session、密码和 API 密钥时，不把敏感信息放进无关咨询或前端展示中。
- 查询、筛选与验证反馈不伪装成实际提交；Demo 清楚说明是否保存、发送或扣款。

## 10 卡片、价格与数据

会员看方案和价格；模型先看供应商与具体名称，再看介绍与费用。

01 / CHATGPT热销


ChatGPT Plus
需提供账号 Session


¥148

付款后自动开通


- 订单页与邮件各存一份
- 不用注册，凭邮箱就能查订单
- 订单内可申请发票

          立即购买


### 原会员卡片

这是当前会员页中的原始卡片。标题、价格、交付说明和权益保持原样；本页按钮仅打开组件演示。

- 会员价格为主要视觉，字段与权益保持固定顺序。
- 模型以供应商分组，分类为文本 / 图片 / 视频，名称完整且容易扫读。
- 模型卡片保持紧凑，补充简短介绍；价格仍展示，复杂参数放入详情。
- 文本按 ¥ / 1M Tokens 展示输入、输出、缓存读取与缓存创建；图片按档位与次计费。
- 未知价格显示「—」，并说明为待配置；不当作 0 或免费。

| 计费项 | 排版示例 | 单位 |
|  --- |  --- |  --- |
| 输入价格 | ¥0.231 | / 1M Tokens |
| 输出价格 | ¥1.155 | / 1M Tokens |
| 缓存读取 | ¥0.023 | / 1M Tokens |
| 缓存创建 | ¥0.289 | / 1M Tokens |
| 图片 4K / 2K / 1K / 默认 | ¥0.18 / ¥0.15 / ¥0.12 / ¥0.12 | / 次 |

上述数字是用户提供的计费排版示例，不对应额外新增的正式报价。不能混用 Token 单价、图片次数与视频时长。

| 供应商 | 具体模型 | 能力 | 展示状态 |
|  --- |  --- |  --- |  --- |
| OpenAI | `gpt-4.1` | 文本 | 正常 |
| Google | `gemini-3.1-flash-image` | 图片 | 波动 |
| Google | `veo-3.1-generate-preview` | 视频 | 暂无样本 |

表格状态仅为组件样例。金额和时长右对齐，ID 可复制；成功率附样本与时间范围，文本首 Token 延迟和图片 / 视频完成耗时分开说明。

## 11 反馈、公告与浮层

重要入口稳定可见，反馈简短，动态效果可被用户控制。

CONTACT / 固定黑色入口联系我们+
阿栗机器人图标、白色文字和橙色「＋」。浅色与深色页面均保持黑底。

DIALOG & TOAST / 非业务操作
打开对话框 显示反馈 ↗
可关闭、可取消、可键盘操作。确认不会创建订单或发送信息。

公告
浅色页面：近黑底，白色文字，品牌橙标记。

公告
深色页面：较亮炭灰底，细边线保留层次。

| 组件 / 状态 | 规则 |
|  --- |  --- |
| 顶部走马灯 | 高度克制；内容可暂停；悬停和键盘聚焦时暂停；减少动态效果时静态展示，重复副本不重复朗读。 |
| 联系悬浮按钮 | 桌面右下约 24px，手机约 16px，并考虑安全区域；对比栏和提示需避让。 |
| 模态对话框 | 原生 dialog；标题、说明、取消和确认完整；支持 Esc 和关闭按钮。 |
| 轻提示 | role=status / aria-live=polite；成功、失败都说明结果，不声称未发生的动作。 |
| 加载 / 空 / 错误 | 分别说明正在做什么、为什么没有内容、如何重试；错误不显示成空列表。 |
| 状态标记 | 正常用蓝，波动用橙，中断用墨色，未知用空心标记；都提供状态文字。 |
| 层级 | 轻提示 z-index 10，联系入口 20；模态使用原生 top layer，避免被普通页面覆盖。 |

FAQ 与折叠说明 +
问题是完整可读的按钮或 summary，展开状态可被识别。折叠适合次要说明，不隐藏价格、核心权限或主要操作。

## 12 页面模式与交付标准

### 入口页的首屏右侧

首页、会员与中转站共用 hero-visual.css 中的形象排版：桌面容器不超过 420 × 310px，手机不超过 300 × 240px。阿栗保持原比例，以 contain 放入，背景透明。

三页分别使用欢迎、会员和开发动作，保持同一个阿栗、同一种平面画风。首屏右侧只放形象，不增加展示框、网格、连线、背景块或装饰文字。手机下统一放在文案之后。



新增页面沿用现有组件，业务信息与视觉规则一起维护。

| 页面 | 信息组织 | 入口 |
|  --- |  --- |  --- |
| 官网首页 | 产品入口、模型发现、工作台与团队信息；用有限色块形成阅读节奏。 | 查看页面 ↗ |
| 会员选购 | 保留原商品卡片文案；首张可见商品的中点作为橙底起点。 | 查看页面 ↗ |
| AI 中转站 | 体验、接入示例与额度入口；配置和演示能力清楚标记。 | 查看页面 ↗ |
| 模型广场 | 按供应商呈现具体模型；搜索、分类、介绍、价格、详情与对比。 | 查看页面 ↗ |
| 模型状态 | 按具体型号展示成功率、延迟、样本口径与历史；无样本不视作失败。 | 查看页面 ↗ |
| 个人工作台 | 订单包含会员、卡密、额度与其他购买；再管理密钥、日志、账单和账号。 | 查看页面 ↗ |
| 文档中心 | 列表页与单篇阅读分开；内容来自 Markdown，含搜索、代码复制与源文件下载。 | 查看页面 ↗ |
| 联系我们 / 加入我们 | 咨询草稿与职位方向；未配置渠道或正式职位时如实说明。 | 查看页面 ↗ |

### 其他复用组件

| 组件 | 使用要求 |
| --- | --- |
| 搜索 / 排序 / 收藏 | 结果数量随条件更新；收藏给出选中状态；排序口径清楚，清空后回到可理解的默认状态。 |
| 模型对比栏 | 最多选择 3 个具体型号；可移除、清空与查看对比；固定栏避让右下联系入口。 |
| 分页 | 同时展示结果总数与当前页；首页禁用上一页，末页禁用下一页；筛选改变后校正页码。 |
| API 密钥 | 默认遮罩；查看、复制、停用按明确权限操作；说明密钥状态，不把无效 Demo Key 表达成真实可用。 |
| 代码与 Markdown | 保留换行、缩进和完整模型 ID；语言标签与复制结果一致；长行在代码区域横向滚动。 |
| 图表与历史状态 | 给出指标、单位、时间范围与样本口径；没有样本与失败分开；图例同时用文字和视觉标记。 |
| 额度与金额选项 | 预设金额是单选；自定义金额的整数与上下限在字段旁说明；确认前展示选中额度。 |
| 个人资料与偏好 | 保存、取消、开关状态各自清楚；Demo 只说明实际发生的本地变化，不声称已发送通知。 |
| 招聘与咨询 | 职位方向可筛选与展开；投递入口携带所选方向；未配置联系渠道时展示草稿状态。 |


### 每次改版，都检查这些

- 使用正确品牌名称和 logo；页尾与联系入口保持黑色。
- 明暗主题都检查文字、分隔、表单和选中状态。
- 320 / 375 / 768 / 1280px 下没有意外横向溢出，形象与装饰受容器约束。
- 确认商品文案与价格没有在视觉修改中变化。
- 测试筛选交集、空结果、复制失败、错误重试、关闭和返回入口。
- 验证键盘焦点、可见标签、动态效果偏好，以及表格和代码的横向滚动。
- 区分静态 / 代码校验与浏览器视觉验证；未完成的验证应如实说明。

此页是当前 Demo 的设计基线 v1.1，更新于 2026-10-15。后续修改色值、组件或规则时，同步维护规范与导出文件。

## 颜色变量速查

| 变量 | 浅色 | 深色 |
| --- | --- | --- |
| `--paper` | `#ffffff` | `#121316` |
| `--card` | `#ffffff` | `#1b1d22` |
| `--surface` | `#f8f8fa` | `#15171b` |
| `--subtle` | `#fafafc` | `#22252b` |
| `--ink` | `#19191b` | `#eeeef2` |
| `--body-text` | `#50505b` | `#c4c7d0` |
| `--muted` | `#6f6f7b` | `#a8acb7` |
| `--line` | `#e1e1e7` | `#343840` |
| `--accent` | `#2a74db` | `#78adfa` |
| `--accent-pale` | `#f4f7fc` | `#19283e` |
| `--accent-line` | `#aac6ee` | `#496b9d` |
| `--action-bg` | `#2a74db` | `#2a74db` |
| `--on-accent` | `#fff` | `#fff` |
| `--night` | `#19191b` | `#19191b` |
| `--yellow` | `#f37021` | `#f37021` |

## 阿栗AI 品牌素材

- 黑蓝标识：ali-logo-v3.png，墨黑 a、l 与蓝色机器人 i，用于浅色背景。
- 品牌蓝标识：ali-logo-blue-v3.png，纯品牌蓝 ali 字标，用于深色背景。
- 机器人图标：ali-icon-v3.png，用于页签和小尺寸入口。
- 牛头头像：ali-cow-logo.png。
- 扁平插画：ali-flat.png，保留使用笔记本电脑的角色姿态，蓝色领带。
- 立体形象：ali-mascot.png，保留绒毛材质，蓝色领带。

以上均为透明背景 PNG，可在设计规范页下载。

## 商品、支付与票据

列表按钮为「查看商品」，详情页按钮为「立即购买」。订单创建后进入独立支付页；支付宝、微信、USDT 共用布局和状态规范。付款成功后返回订单页，弹出账单与发货信息。

票据采用白色纸面、虚线分隔、等宽数字、加粗实付金额与锯齿底边。发货凭证与付款状态分别展示，支持复制、重开和打印。当前为本地演示，不会产生真实付款或邮件发送。

商品正文使用一个完整 Markdown 内容字段，自然段直接展开，不要求商家逐项配置场景、参数、准备资料和 FAQ。支付结果查询只读取状态，过期与关闭订单提供重新下单入口；付款与交付状态分别显示。票据支持仅打印收据或连同发货信息一起打印。

---

付款成功不等于马上能用，**先在「我的订单」里确认订单状态，再按提示领取卡密**。这篇把每一步说清楚。

> [!TIP]
> 下单和查单都不需要注册账号。用下单时填写的邮箱接收验证码，就能查到该邮箱的全部订单。

## 一、确认订单状态

第 1 步：打开「我的订单」，输入下单时填写的邮箱，获取验证码并登录查询。

第 2 步：在列表里找到这笔订单，确认状态。

- **待发货**：已付款，等待处理，稍后再来查看。
- **已发货**：卡密或充值结果已经可以领取。
- **已退款**：款项已退回，按原支付方式到账。

## 二、领取卡密

第 3 步：状态为「已发货」时，点开订单详情，复制卡密。

第 4 步：按卡密页面的说明完成兑换。不同商品的兑换方式不同，以商品详情页为准。

> [!WARN]
> 卡密只显示在订单详情里，请自行保存。卡密泄露等同于商品被他人使用，发卡后不支持退换。

## 三、申请发票

第 5 步：在订单详情页点击「申请发票」，填写抬头与邮箱。

第 6 步：发票开具后会发送到填写的邮箱。

## 常见问题

- **没收到邮件？** 先查垃圾邮件，再确认下单时填写的邮箱是否填对。
- **订单一直没发货？** 需要人工交付的商品要排队处理，可在订单页刷新查看最新状态。
- **想退款？** 未发货的订单可联系我们申请；已发放卡密的订单不支持退款。

> [!TIP]
> 遇到问题先看订单详情页的状态说明，大多数疑问在那里就能找到答案。

---

# 卡密兑换与结果核实

## 进入兑换页

从[我的订单](/orders/)打开兑换链接，也可在[卡密兑换](/redeem/)手工输入兑换凭证。凭证代表兑换权限，请勿转发或粘贴到工单。

旧的带凭证链接会自动校验，随后从页面地址中移除凭证。本页不把凭证或填写内容写入浏览器持久存储。刷新、离开或浏览器恢复页面后需要重新输入，或重新从订单进入。已经提交过的，请先核实订单，不要重复兑换。

## 四步真实流程

1. **验证卡密**：向本站服务端校验凭证，获取需要填写的字段。校验本身不消耗凭证；无效、过期或已使用的凭证不能继续。
2. **填写信息**：只填写服务端声明的项目。必填检查仅确认内容不为空，不代表服务端已核验目标账号身份或可用性。没有字段时可以继续。
3. **最终确认**：核对已填写项目数和静态提醒。为保护隐私，确认页不回显填写内容或凭证；可返回上一步修改。勾选确认后才发送真实提交。
4. **提交结果**：只有服务端明确确认后才显示「已提交」。这不代表会员已开通或商品已交付，后续以[我的订单](/orders/)里的真实结果为准。

## 网络异常或凭证已使用

提交发生网络中断、返回内容异常或服务不可用时，可能无法确认是否已经处理。本页不会自动重复提交。请先到「我的订单」核实结果；仍不明确时[联系支持](/contact/?topic=order)。不要把完整卡密、会话凭证或账号敏感信息放进工单。

「凭证已被使用」只说明当前凭证不可再次使用，不能证明本次提交成功，更不能证明已交付。

服务端明确指出填写内容有误时，可返回修改并自行确认提交；不要反复点击。订单归属、验证码、查看密码与服务端限流仍由原服务校验，兑换页不会绕过这些约束。

## 当前功能边界

当前兑换协议只提供字段校验读取和最终提交，不提供套餐详情、目标账号预验证、按凭证查询进度或历史记录的接口。本页因此不展示模拟进度、时间线或浏览器兑换记录，也不提供复制或打印兑换凭据。订单入口仍使用原有的登录或游客查询验证，不是公开的凭证进度接口。