与黎 · 汇流新手 API 使用教程

更新日期：2026-10-29。本文只讲普通 API：登录本站、创建自己的 API Key、在软件里填地址、发出第一条请求，最后把 Codex 接到本站。第一次使用也按顺序做，不需要先懂代码。

网页版与飞书版教程使用同一份正文，两处内容同步更新。

先记住 4 件事

网站密码只用于登录控制台；API Key 才用于软件调用接口。两者不能互换。
普通 API 地址固定是：https://api.yulitongxing.com/v1。
本人网关 Token（页面也可能叫 API Key）只在创建完成时完整显示。格式以控制台实际显示为准；复制后马上保存，不要发到群里、截图里或公开代码中。
本教程不是团队 API 教程。不要把 yuli_private_ 团队 Key 或 https://console.yulitongxing.com/pool/api/private/v1 填到普通 API 的配置里。

第一步：登录本站

打开与黎 · 汇流控制台。
使用本站用户名和密码登录。这个密码不是上游 ChatGPT、Claude 或邮箱密码。
登录后先确认右上角显示的是自己的账号。余额和 API Key 都属于当前登录账号；切换账号后看到的数字会不同。
如果账号还没有余额，先按管理员给你的规则完成额度发放，再继续创建 Key。

第二步：创建自己的普通 API Key

在控制台找到“令牌”“API Key”或类似的密钥管理入口。
点击“创建”“添加令牌”或同义按钮。
名称填写容易辨认的用途，例如“我的电脑第一次测试”。名称只是备注，不是密钥。
第一次测试先保持默认有效期和模型范围；如果页面要求设置令牌额度，确认它大于 0，并且没有排除你准备测试的模型。
点击保存或创建。页面出现完整 Key 后，立即复制并保存到密码管理器或本机私密文件。
离开页面前确认已经保存完整 Key。之后列表通常只显示部分字符，不能靠列表找回完整 Key；忘记时创建一把新的，再撤销不用的旧 Key。

第三步：确认可用模型

打开模型目录，或在支持读取模型列表的软件里刷新模型。
复制目录中真实出现的完整模型 ID，例如 gpt-6.1-sol、gpt-6-astra 或其他目录中的 ID。
不要填写“GPT 最强”“GPT6.1”或中文显示名。模型名称必须逐字一致。
软件和模型还要使用匹配的协议：OpenAI 兼容软件通常使用 Chat Completions 或 Responses；支持 Claude 的软件要确认它支持 Messages。看到模型不代表所有软件和协议都能调用。

第四步：在软件里填写 3 个位置

在软件的“模型提供商”“自定义 API”“OpenAI 兼容接口”或类似设置里填写：

设置项	填写内容
API Base URL / API 地址	`https://api.yulitongxing.com/v1`
API Key / 密钥	第二步创建并保存的本人普通 Token
Model / 模型	第三步从本人目录复制的完整模型 ID

如果软件把输入框写成“服务根地址”，并且它会自动在后面加 /v1，这时填 https://api.yulitongxing.com，避免最终变成 /v1/v1。不确定时先看该软件对 Base URL 的说明。

第五步：用一条短问题测试

第一次只发一条短问题，例如：只回复：连接成功。不要一开始就跑长文档、批量任务或长时间 Agent。

用 Python 测试

先在终端安装一次 SDK：

python -m pip install openai

新建 test_api.py，不要把 Token 写进代码。运行脚本时从环境变量或隐藏输入读取它；模型 ID 从自己的目录复制：

import getpass
import os
from openai import OpenAI

TOKEN = os.getenv("YULI_API_TOKEN") or getpass.getpass("粘贴本人网关 Token：")
client = OpenAI(
    api_key=TOKEN,
    base_url="https://api.yulitongxing.com/v1",
)

result = client.chat.completions.create(
    model="目录中的完整模型 ID",
    messages=[{"role": "user", "content": "只回复：连接成功"}],
)
print(result.choices[0].message.content)

运行：

python test_api.py

看到模型返回文字后，再去查看控制台调用记录和余额变化。仅看到模型列表、保存配置或“Key 校验通过”都不等于真实请求成功。

用 curl 测试

Windows PowerShell、macOS 或 Linux 都可以用下面的结构；把两个占位符换成自己的值：

read -r -s -p "粘贴本人网关 Token：" YULI_API_TOKEN
printf "\n"
curl https://api.yulitongxing.com/v1/chat/completions \
  -H "Authorization: Bearer $YULI_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model":"目录中的完整模型 ID","messages":[{"role":"user","content":"只回复：连接成功"}],"stream":false}'
unset YULI_API_TOKEN

如果 PowerShell 对单引号或换行处理不同，优先使用软件的测试按钮或 Python 示例；不要把 Key 直接写进公开脚本仓库。

第六步：把 API 接到 Codex

Codex 的命令行和桌面端默认连 OpenAI 官方账号。让它走本站，只需要改一个本地配置文件：把请求地址和密钥指向本站。两边读的是同一份文件，改一次都生效。

1. 找到配置文件

系统	路径
Windows	`C:\Users\你的用户名\.codex\config.toml`
macOS / Linux	`~/.codex/config.toml`

.codex 文件夹不存在就先新建；config.toml 不存在就新建一个纯文本文件，编码用 UTF-8。

2. 写入这段配置

model = "gpt-6.1-sol"
model_provider = "yuli"

[model_providers.yuli]
name = "与黎 · 汇流"
base_url = "https://api.yulitongxing.com/v1"
wire_api = "responses"
env_key = "OPENAI_API_KEY"

base_url 要写到 /v1 为止，Codex 不会自动补这一段。
wire_api 固定填 responses，这是 Codex 对自定义供应商唯一支持的协议。
env_key 是环境变量的名字，不是密钥本身。密钥放到环境变量里，不要写进这个文件。
model 填第三步从自己模型目录复制的完整 ID。目录里没有的 ID 换一个，不要凭印象写。

3. 把密钥放进环境变量

Windows（PowerShell 或 CMD，执行一次即可）：

setx OPENAI_API_KEY "你的本人网关 Token"

macOS / Linux（写进 ~/.zshrc 或 ~/.bashrc）：

export OPENAI_API_KEY="你的本人网关 Token"

设置完关掉终端重新打开，变量才会生效。

4. 确认 Codex 没有残留的 ChatGPT 登录

codex login status

如果显示已经用 ChatGPT 账号登录，先执行：

codex logout

否则 Codex 会继续走 ChatGPT 账号，上面写的配置等于没生效。

5. 验证

codex exec --skip-git-repo-check "只回复：连接成功"

看到返回“连接成功”就算接通。桌面端重启后，模型选择器里会读到配置文件里的 model。

6. 换模型或切回官方

换模型：改 config.toml 里的 model，或在会话里用 /model 切换。
切回官方：删掉 model_provider 这一行和 [model_providers.yuli] 整段，再执行 codex login 用 ChatGPT 账号登录。

Codex 相关故障

报 401 或 unauthorized：环境变量没生效或 Token 填错。先确认变量有值（Windows 用 echo $env:OPENAI_API_KEY，macOS / Linux 用 echo $OPENAI_API_KEY），再核对 Token 本身是否已撤销。

报 404 或 Not Found：base_url 写成了一层或两层 /v1。正确值只有一个：https://api.yulitongxing.com/v1。

一直转圈或超时：先按第五步用 curl 直接打网关。curl 能通说明网关正常，问题在 Codex 这一侧，重点检查是不是还在用 ChatGPT 账号登录。

提示模型不存在或没有权限：模型 ID 拼错，或这个 ID 不在自己账号的模型目录里。回第三步重新复制。

普通 API 与团队 API 的区别

项目	普通 API	团队 API
Token 形态	以控制台显示的本人普通 Token 为准	通常为 `yuli_private_` 开头
地址	`https://api.yulitongxing.com/v1`	`https://console.yulitongxing.com/pool/api/private/v1`
适用对象	本站个人账号与个人余额	已加入团队、由团队账号提供调用能力的成员
Key 从哪里创建	控制台“令牌 / API Key”	“成员与管理员”团队页
是否可以互换	不可以	不可以

只有管理员明确让你走团队流程时，才阅读团队使用教程。普通用户创建个人 Key 时，不要上传上游账号，也不要输入团队管理口令。

常见问题

提示 401、invalid token 或 Key 无效

确认填的是完整的本人普通网关 Token，不是网站密码、团队 Key 或上游账号密码；确认地址使用普通 API 地址；确认复制时没有少字符、换行或多余空格。若 Token 曾经撤销，创建一把新的。

提示 404 或找不到接口

检查软件是否自动追加 /v1。最终地址只能有一层 /v1。再检查软件选择的协议和接口是否匹配，OpenAI 兼容软件不要把团队地址填进去。

能看到模型，但发送失败

模型目录可见只说明该 Key 能看到模型，不保证当前协议、模型状态和上游额度都正常。先换目录中另一个已出现的模型，去掉未经确认的推理参数，再发一条短问题。

提示余额或令牌额度不足

分别检查本站账号余额和这把 Key 的令牌额度限制。账号余额有剩余，不代表令牌一定没有单独上限；令牌上限大于 0，也不代表账号余额充足。

团团里显示的数字和网页不同

先确认团团和网页登录的是同一个与黎站账号，再刷新并比较更新时间。团队上游额度、个人站内余额、API 请求 token 数是不同的数字，不能直接互相替代。

忘记了 Key

完整 Key 通常不会再次显示。创建新的普通 Key，确认新 Key 能完成短请求后，再撤销不再使用的旧 Key。

完成检查

我登录的是自己的与黎站账号。
我创建并保存了自己的普通网关 Token。
我填写的是 https://api.yulitongxing.com/v1，没有重复 /v1。
我从自己的模型目录复制了完整模型 ID。
我完成了一条真实短请求并收到回复。
我的 Codex 配置指向 https://api.yulitongxing.com/v1，并且在 Codex 里也完成了一条真实短请求。
我没有把网站密码、API Key、团队管理口令或上游密码发给别人。

相关入口：控制台 · 模型目录 · 团队使用教程