第一次调用 API#

1. 到 HiKaRi 主站注册，完成站内要求的邮箱验证。
2. 登录后确认可用资金，在 API Key 页面创建密钥、选择实际需要的分组。
3. 在模型广场复制该 Key 有权使用的精确模型名。模型广场当前需要登录；教程提及的型号不代表你的分组已开放。
4. 阅读 地址与密钥怎么填，再用 Python 最小请求 验证一条短文本。
5. 最小请求成功后，再配置客户端、开启流式输出，最后接入长上下文、工具或媒体任务。

不要同时修改模型、线路和客户端配置。一次只改变一个变量，问题才容易定位。

已经接入，但遇到问题#

问题仍未解决时，到 联系与交流 查看需要提供的脱敏信息。不要发送完整 API Key。

正在选型或核算成本#

先读 渠道来源与服务边界，再看 Token 成本怎么算 和 模型评测怎么做。本博客不维护第二份实时价目表，价格、权限与实际计费以主站当前信息为准。

团队采购可以从 团队接入与开票 开始；合成数据和蒸馏项目请先看 数据质量与验收。

HiKaRi 提供什么#

HiKaRi 以不掺水、明示渠道来源、明确价格为服务定位，提供多模型 API 接入，并承接团队对接、开票及授权数据项目。具体协议、型号、并发与交付范围需要逐项核对，不在博客中作无限额或永久可用承诺。

• API 文档：实际请求格式和支持范围。
• 服务说明：渠道、费用、团队与开票入口。
• 生图站：需要图形界面时的图片生成入口。

文章中的计算例子会标明假设；示例代码不代表已对每个模型进行付费测试。你可以先用一条低成本请求核对，再按自己的任务逐步扩大。

先看状态，再看具体错误#

状态码只是入口，不同协议可能返回更具体的错误类型。正文是 HTML 时，检查是否访问了网页、被代理改写或经过了登录跳转，不能直接当 JSON 解析。

用最小请求做对照#

1. 先查询当前 Key 的模型目录。
2. 使用客户端相同的地址、Key 和模型，发一条无附件、无工具的短文本。
3. 目录请求失败，先解决认证和权限；短文本成功后，再逐步加回高级参数。
4. 终端成功、客户端失败，按 客户端清单 比较配置来源。

调用目录不是完整生成测试；短文本也不能证明长上下文、图片或工具能力全部可用。

超时后不要立刻重发#

连接在途中断开，客户端无法据此证明服务端没有受理。尤其图片、视频、工具执行可能存在成本或副作用。已有任务 ID 就续查，没有 ID 则保留原业务号、幂等键和时间，先核对记录。详见 重试与幂等。

提交问题时可以照这个模板#

1
时间与时区：
2
客户端及版本：
3
运行环境：Windows / WSL / Docker / 远端
4
请求路径：只写路径，不附凭据
5
模型与分组：
6
HTTP 状态与脱敏错误：
7
任务 ID 或请求记录编号：
8
已验证的最小请求结果：

通过 联系与交流 找运营方核对。不要提交完整 Key、Cookie、私有素材链接或客户原始数据。

依据：HiKaRi 常见错误。

按客户端的拼接规则填写地址#

“通常”需要结合客户端的说明确认。有的输入框要求完整 endpoint，有的只接受站点根地址。最终请求日志比输入框标签更有判断价值。

如果返回路径是 /v1/v1/chat/completions，说明版本前缀重复；如果请求发到了 /chat/completions，则可能缺少 /v1。站内“API Key → 使用”提供了已配置线路时，优先使用该入口给出的说明。

Key 是服务凭据，不是网页登录密码#

在 API Key 页面创建本站密钥，按应用分别管理。不要把上游官方平台 Key、网页登录密码或订阅账号 Cookie 填到本站 API Key 输入框。

分开 Key 有助于限额、轮换与排错，但创建更多 Key 不会凭空增加账号并发。Key 绑定分组、用户权限和可用资金仍会影响请求能否通过。

模型名以目录为准#

从当前 Key 的目录或模型广场复制模型 ID，不要按印象拼写。版本、大小写、前后缀和媒体分辨率后缀可能影响路由。

先查询目录的 Bash 示例：

1
export API_KEY='在本机填写本站密钥'
2
curl --fail-with-body 'https://hikariapi.xyz/v1/models' \
3
  -H "Authorization: Bearer $API_KEY"

Windows PowerShell 使用 curl.exe，或按 Python 教程 请求，避免旧版 PowerShell 中 curl 别名造成参数混淆。不要把终端里填过的密钥截图发给别人。

目录列出名称，不等于声明该模型支持所有参数。工具调用、图片输入、结构化输出和思考档位需要单独核对。

按这个顺序验收#

先查模型，再发短文本，然后开启流式，最后测试高级能力。若失败，保留请求路径和 HTTP 状态，按 报错清单 排查。

依据：HiKaRi 开始使用、文字 API。实时配置以主站文档为准。

先问清渠道来源#

不同渠道可能采用不同的采购和接入方式，能力与限制也会不同。查看主站标注的渠道信息，针对你的用途确认来源类型、支持协议、使用限制和可用资金方式。不要仅凭“官方”“直连”等名称推断拥有某种授权或服务等级。

团队采购如果需要更具体的来源材料，应在试点前沟通。博客不会用一个统一标签替代每条渠道的实际说明。

模型名称与能力需要分开核对#

模型自述“我是什么模型”、语气相似或一道题的答案，都不足以单独证明模型身份。更合理的验收是核对渠道披露、协议行为和有代表性的固定任务，同时保留可复现参数。

低价要放进任务成本里看#

假设渠道 A 的单次价格更低，但需要多次重试才能得到可用输出，最终成本可能更高。比较时把失败、返工、延迟和维护时间一起记录。相关方法见 模型评测 和 Token 费用。

本文不发布未经同条件测试的“全网最低”或“绝对优于某站”结论，也不把一次短请求成功写成长期稳定性证明。

如何查看 HiKaRi 当前信息#

到 服务与渠道说明 了解原则，登录 模型广场 核对当前模型、渠道与价格。大型任务先做小样本验收，再决定是否扩大。

先确认协议#

Chat Completions、Responses、Anthropic Messages、Gemini 风格接口的字段和事件不同。客户端只写着“自定义供应商”，不代表它支持所有协议。

完整请求路径应与 地址说明 对照。不要将三个接口的请求体互相混用。

配置要写在真正运行程序的位置#

Windows 桌面应用、WSL、Docker、远程 SSH 扩展可能读取不同的环境变量和配置文件。改了本机文件，但程序运行在远端，设置不会自动过去。

保存后检查客户端显示的供应商和模型。必要时按客户端文档重开进程，让它重新读取环境变量。不要把重装应用当成第一步。

再比较最小请求与完整会话#

先建一个不带历史、不带工具、不带图片的新会话。如果短文本成功，旧会话失败，逐项加入历史、工具和附件，找出触发差异的部分。上下文过长、附件格式不支持和函数参数不兼容，都可能只在完整会话出现。

流式出问题时，检查 SSE 与缓冲；工具失败时，保留脱敏的工具定义和响应片段，不能用“普通聊天能回复”证明工具协议完整兼容。

使用对应的站内教程#

• 聊天客户端与编辑器
• CC Switch
• Claude Code
• Codex

这些链接指向 HiKaRi 的接入说明。客户端版本和渠道能力会变化，应在实际使用的版本上验证；博客不承诺所有历史版本都兼容。

需要协助时，在 联系页 提交客户端版本、运行环境、实际路径、模型和错误码。请删除 Header 中的 Key、Cookie 与会话令牌。

先写出一页项目说明#

明确目标任务、最终使用场景、学生模型、输入来源、输出用途、数量与预算。逐项核对素材权利、隐私处理、上游条款及输出使用限制；无法确认的渠道不应默认用于训练项目。

有些任务用检索、提示词或规则就能满足要求，未必需要训练。先建立基线，确认蒸馏能解决的具体问题，避免把数据数量当成项目效果。

小样本先定标准#

先做少量人工可完整检查的样本，明确输入输出结构和合格条件。比如客服分类应检查类别定义和困难样本；代码任务应运行隔离测试；结构化抽取应验证 Schema、事实来源和缺失字段处理。

不能仅凭模型自评“正确”入库。为常见错误建立标签，例如事实错误、格式错误、答非所问、信息不足却编造、敏感字段未处理。把失败原因反馈给任务设计，而不是只增加生成量。

数据集至少保留哪些字段#

1
sample_id、任务类型、输入来源标识、生成模型与渠道
2
提示词版本、参数、生成时间、用量与费用
3
校验结果、人工审核状态、淘汰原因、数据版本

上述是字段建议，不是声称本站提供现成标注平台。密钥不能进入样本；敏感原文和授权证据应独立受控管理，只给必要人员访问。

去重、切分与污染检查#

先按来源或业务实体划分训练、验证和测试，避免同一问题的轻微改写同时落入训练集和测试集。除了完全重复，还要检查近似重复和模板化回答；少量措辞变化不等于新知识。

测试集应在大规模生成前固定并控制访问。不要把测试答案再作为训练示例；涉及公开基准时，记录可能的数据重叠，谨慎解释成绩提升。

验收看学生模型的结果#

交付数量、格式通过率、人工抽样结果、重复率和成本只是数据验收的一部分。项目效果还需在固定测试集上比较学生模型训练前后表现，记录训练设置和随机性；不能承诺生成某个数量就必然提升多少。

分批生产，每批设置质量门槛、费用上限和异常停止条件。保留可追溯版本，方便回滚有问题的批次。可参考 成本计算 和 模型评测。

如何沟通项目#

通过 蒸馏服务说明 了解对接入口，再按 联系页面 提供任务、授权情况、输出结构、质量标准与预算。不要在首次公开咨询中上传整套私有数据；先确定保密、处理和交付边界，再提供最小必要样本。

图片：先确认输出形式#

选择模型后，逐项核对生成或编辑接口、支持尺寸、张数、输入格式和计费方式。不同模型可能有各自约束，尤其不能将一个模型的质量枚举直接复制到另一个模型。

返回结果可能是临时 URL 或编码内容，应依据真实响应解析。若要长期使用，及时将成品保存到自己的受控存储；不要假定返回链接永久有效。需要编辑原图时，只上传有权使用且适合交给相关服务处理的文件。

视频：把提交和完成拆开#

1. 阅读所选模型的专页，准备它接受的请求体。
2. 使用 POST /v1/videos 创建任务，按文档携带幂等键。
3. 保存返回的任务 ID，并用 GET /v1/videos/{id} 查询进度。
4. 生成完成后继续检查结算与成品状态。
5. 使用带 Bearer 鉴权的 GET /v1/videos/{id}/content 下载成品，保存到自有存储。

提交示例不在本文硬编码某个模型和参数，以免误导不同视频渠道的接入。创建接口的兼容别名及具体请求字段以当前文档为准。

三类状态分别看#

文档提及默认视频有效期，但业务应始终以响应中的 expires_at 为准，不能把固定 24 小时写成对所有任务的永久规则。已经完成的生成也可能因为文件过期而无法下载。

查询与下载的工程细节#

查询应有间隔、退避和总时限，避免每秒无上限轮询。将任务 ID 关联到实际用户订单，页面刷新后恢复查询，而不是重新提交生成。

/content 需要 Bearer 鉴权，直接放进不带请求头的普通浏览器链接可能失败。应用后端应在验证用户权限后下载或转存，不要为方便展示把 API Key 拼到 URL、前端源码或日志中。

下载时检查 HTTP 状态与内容类型，避免把错误 JSON 保存为视频文件。网络断开时，先判断任务状态，再决定重试下载或查询；不要重复创建。相关原则见 重试与幂等。

上线前用少量任务走完整条链路：成功、失败、超时恢复、过期、结算待复核。按 成本台账 同时记录任务规格与最终费用。

先确定不能妥协的条件#

列出协议、上下文、工具调用、结构化输出、媒体输入、响应时间和预算要求。精确到实际需要的能力，例如“输出能通过这份 JSON Schema”，比“支持 JSON”更容易验收。

查看 渠道说明，确认模型身份、来源标签、权限与计费。客户端有某个开关，不代表所有渠道都支持该参数。

用小样本覆盖真实困难#

初次可以整理 30～50 条有代表性的样本，覆盖高频任务、长输入、歧义、缺失信息和必须拒答的边界。这个数量用于发现明显问题，不足以证明极低故障率；关键业务需要扩大样本并持续观察。

样本应来自你有权使用的数据，去掉身份信息与密钥。将调试集和最终验收集分开，避免不断修改提示词后只在同一批题目上取得好成绩。

冻结变量并记录版本#

对同一轮测试，固定提示词、工具定义、输出约束与可共同支持的参数。记录模型 ID、渠道、日期、参数和客户端版本。不同协议无法完全对齐时，把差异写入结果，不要装作严格等价。

部分模型具有随机性，抽取一部分样本重复运行，观察一致性；不要只挑最好的一次。轮换测试顺序，减少特定时段网络负载造成的偏差。

一张可以直接使用的验收表#

能自动检查的先自动检查；主观质量去掉模型标签后交叉评分。若使用另一个模型评分，抽样人工复核，并记录评分模型的偏好与成本。

如何写出可信结论#

结论应写成“在这批任务、这组参数和这个时间段，A 的格式通过率更高”，并附样本数量。不要从 20 条样本推导“永不降智”或“99.99% 稳定”。输出风格、速度或某个冷知识的变化，也不能单独证明模型被替换。

上线时先用小流量，保留回退路径；扩容前再做受控并发测试，并与运营方确认并发和额度。团队沟通字段见 团队接入，成本口径见 费用计算。

先在本机设置环境变量#

Windows PowerShell：

1
$env:API_KEY = Read-Host '输入本站 API Key'
2
$env:MODEL_ID = Read-Host '输入模型广场中的精确模型 ID'
3
python first_call.py

macOS、Linux 或 Git Bash：

1
read -s -p 'API Key: ' API_KEY; echo
2
export API_KEY
3
read -p '精确模型 ID: ' MODEL_ID
4
export MODEL_ID
5
python3 first_call.py

示例中的交互输入用于本机验证。共享电脑或生产环境应使用自己的密钥管理方式；不要将 Key 写入 Git 仓库、前端代码或公开笔记。

保存为 first_call.py#

1
import json
2
import os
3
import urllib.error
4
import urllib.request
5

6
base = "https://hikariapi.xyz"
7
key = os.environ["API_KEY"].strip()
8
model = os.environ["MODEL_ID"].strip()
9

10
def request(path, payload=None):
11
    headers = {"Authorization": "Bearer " + key}
12
    data = None
13
    if payload is not None:
14
        headers["Content-Type"] = "application/json"
15
        data = json.dumps(payload).encode("utf-8")
16
    req = urllib.request.Request(base + path, data=data, headers=headers)
17
    with urllib.request.urlopen(req, timeout=120) as response:
18
        return json.load(response)
19

20
try:
21
    catalog = request("/v1/models")
22
    ids = [item["id"] for item in catalog["data"]]
23
    if model not in ids:
24
        raise SystemExit("模型不在此 Key 的目录中，请先核对分组与精确名称。")
25
    result = request("/v1/chat/completions", {
26
        "model": model,
27
        "messages": [{"role": "user", "content": "只回复 OK"}],
28
        "stream": False,
29
    })
30
    print(result["choices"][0]["message"]["content"])
31
    print("usage:", json.dumps(result.get("usage"), ensure_ascii=False))
32
except urllib.error.HTTPError as error:
33
    print("HTTP 状态：", error.code)
34
    print("响应内容请在本机查看，分享前移除凭据和私人数据：")
35
    print(error.read().decode("utf-8", errors="replace"))
36
    raise SystemExit(1)
37
except urllib.error.URLError as error:
38
    raise SystemExit("网络请求失败；检查本机 DNS、代理、网络，并核对用量后决定是否重发。") from error

如何判断成功#

先确认目录请求成功，再看生成结果和主站用量记录。输出未必严格等于 OK；自然语言遵循程度不是网络连通性的唯一判据。模型返回高级内容块或拒绝信息时，也要检查对应协议说明。

usage 是接口报告的用量，不应只用回答字数推测成本。完整账单还需核对实际分组、计费模型及倍率。

这段程序不自动重试生成请求：网络超时不证明服务端没有处理。排错见 HTTP 状态码，后续接入见 客户端检查清单。

参考：本站文字 API、Python urllib.request。代码依据协议编写；本文没有使用客户 Key 或发起付费模型调用。

按操作决定处理方法#

对允许重试的操作，可使用带随机抖动的指数退避，同时限制次数、单次超时和总体时间。若服务端提供有效的 Retry-After，按其指示等待。不要让 SDK、代理、队列消费者三层各自重试，导致次数相乘。

HiKaRi 视频创建的幂等规则#

依据 视频文档，创建视频使用 POST /v1/videos，也提供 /v1/videos/generations 兼容入口。对同一个业务动作，在第一次提交前生成并持久化 Idempotency-Key，它应是 1～128 个 ASCII 字符。

1
业务 ID → 幂等键 → 提交请求 → 保存任务 ID → 查询任务 → 保存成品

例如使用 Python 的 uuid.uuid4().hex 生成键。相同业务、相同请求体、相同 Key 凭据的安全重发使用同一幂等键；不要每次网络重试生成新键。修改模型、提示词等请求内容应视作新的业务版本，不能强行复用旧键。

请求头示意：

1
Authorization: Bearer <你的 API Key>
2
Content-Type: application/json
3
Idempotency-Key: <已持久化的本次业务幂等键>

这里描述的是视频文档明确提供的规则，不意味着文字、图片或所有第三方接口都自动支持相同幂等行为。幂等有效范围与冲突响应以实际文档和接口为准，不承诺永久去重。

任务队列怎么存状态#

在业务库中为一次用户动作建立唯一记录，保存请求摘要、幂等键、任务 ID、最近一次查询时间和最终状态。消费者重启后从这条记录恢复，先查后续进度。

若提交后未拿到任务 ID，保留“结果未知”，使用同一幂等规则核对，不直接宣告失败并自动另起任务。长时间无法确定时携带脱敏记录联系支持。

媒体生成完成、结算确认和成品存储是不同状态，详见 图片与视频流程。短期重试不能代替业务对账；最终应核对已创建任务与费用，排除重复执行。

先分清两个时间#

首个有效输出时间反映用户什么时候开始看到内容；总完成时间反映整次请求多久结束。有的模型先进行内部推理，开始输出较晚；这和代理把已生成内容攒住再发不是同一个问题。

不要只看平均总耗时。比较相同任务时，记录首次有效输出、完成时间、输出数量和失败比例，才有可比性。

检查协议与解析方式#

1. 请求体确认使用了目标接口支持的 stream: true。
2. 读取响应的 Content-Type 和实际事件；不要对整个 SSE 响应直接执行 response.json()。
3. 使用对应协议的事件解析器。Chat、Responses 和 Messages 的事件类型不能混用。
4. 网络数据块不等于事件边界，也不等于一个字或一个完整 Token。解析器需要缓冲未完成的行与事件。

用 curl 排查时可加 -N 关闭本地输出缓冲，并保持其他参数与原请求一致。Bash 例子：

1
curl -N --fail-with-body 'https://hikariapi.xyz/v1/chat/completions' \
2
  -H "Authorization: Bearer $API_KEY" \
3
  -H 'Content-Type: application/json' \
4
  -d "{\"model\":\"$MODEL_ID\",\"messages\":[{\"role\":\"user\",\"content\":\"用三句话说明什么是 API\"}],\"stream\":true}"

先在本机设置本站 Key 和支持该协议的精确模型 ID。该例子用于连通性检查，不保证所有模型产生相同分块节奏。

curl 正常而网页集中出现#

检查自建反代是否开启响应缓冲、应用是否先读完整个响应才返回，以及前端是否只在结束事件后更新状态。把流先转成完整字符串，再展示给页面，自然不会逐段显示。

如果只在某个网络环境发生，继续比较代理、VPN、网关和远程开发环境。不要直接调整主站配置，先定位自己能控制的那一层。

流中断怎么办#

记录最后收到的事件和错误，并核对主站用量。已经生成一部分内容的请求，不能把中断简单当作“完全没有执行”。涉及工具动作的应用还需要按业务 ID 防止重复执行。

参考：HiKaRi 文字 API 的流式说明。后续阅读：重试与幂等。

一次说明白的需求清单#

用量不确定时，先给范围并安排小样本试用。不要将“支持主流模型”解释成所有型号、全部参数和任意并发均已向每个 Key 开放。

Key 与环境隔离#

开发、测试、生产使用独立密钥，按项目和责任人分配，禁止多人共享个人 Key。预算和权限能力以实际控制台为准，不能假设任何管理功能已默认开启。

密钥只放后端或受控的秘密管理服务；人员变更及时轮换。日志保留请求 ID、模型、状态和用量即可定位大部分问题，不应默认收集完整敏感输入。

先验收，再迁移#

先完成一条真实工作流，验证必需参数、格式、错误恢复与账单。然后做受控小流量迁移，再按双方确认的额度扩容。质量验收表可参照 模型评测，超时恢复参照 重试与幂等。

保留配置版本和回退路径。如果有特定响应时间、保障窗口或专属资源要求，应在采购前书面确认，不能从博客宣传推导出 SLA。

开票前核对哪些信息#

先通过 开票说明 和站内实际流程核对可开票订单及金额，再按要求提供抬头、税号、发票类型和接收信息。公司财务可能另有项目名称或合同要求，应提前沟通；不要把税号、个人地址或订单凭证发到公开群聊。

未核实前不要假设任何充值都能按同一种发票类型、时限和项目开具。退款、折扣、已开票订单等特殊情形以双方确认及实际规则为准。

现在可以从哪里开始#

阅读 团队对接说明，到 HiKaRi 主站 核对服务并发起沟通。通知与交流 QQ 群为 1107270061；进群先说明需求类别，涉及采购资料请与经核实的运营人员私下对接，不在群中公开敏感信息。

先确认计费口径#

文字调用通常需要分别核对输入、输出及缓存相关字段。不同渠道对缓存读取、缓存写入的展示与收费方式可能不同，不能把所有缓存 Token 都当成免费，也不能把已经包含在输入总量中的 Token 重复计算。

在 主站价格说明 和 计费文档 中确认：

1. 使用的是哪个分组、渠道、精确模型与计费模型。
2. 单位是元、账户余额单位还是其他单位，是否存在分组倍率。
3. 输入、输出、缓存分别如何计价，用量字段之间是否存在包含关系。
4. 图片按张还是按 Token，视频按任务还是按秒，哪些参数改变价格。

一次文字调用的假设例子#

以下数字只演示计算，不是 HiKaRi 报价。 假设输入单价为每百万 Token 2 元，输出为每百万 Token 8 元；本次没有缓存，输入 10,000 Token，输出 2,000 Token，没有额外倍率。

1
输入费用 = 10,000 ÷ 1,000,000 × 2 = 0.020 元
2
输出费用 =  2,000 ÷ 1,000,000 × 8 = 0.016 元
3
本次合计 = 0.036 元

若 1,000 次调用完全相同，理论合计为 36 元。实际任务长度不一，应从用量记录汇总，不能拿一条短提示词的费用直接代表整批数据。

有缓存时，先按渠道文档拆出可计费部分，再套入相应单价。长对话反复携带历史消息会增加输入；工具返回的内容也可能进入后续上下文。中文字数与 Token 数没有固定换算比例。

衡量“每个合格结果”的费用#

假设方案 A 每次 0.02 元，100 次中 70 次通过；方案 B 每次 0.03 元，100 次中 95 次通过。未计人工复核时：

A 在这组假设里仍便宜，但差距已经缩小。再加入人工改写时间，结论可能变化。评估方法见 模型与渠道评测。

图片与视频另建账目#

图片记录尺寸、质量、数量和编辑输入；视频记录时长、分辨率、是否带音频以及实际结算状态。不要仅看任务进入 completed 就认定所有计费和存储步骤都结束。

媒体任务的提交、查询与下载要分开记录。网络异常后重复创建任务，可能带来第二笔费用，参见 重试与幂等 和 媒体任务流程。

最低限度的成本台账#

每条业务记录保存时间、内部业务 ID、请求或任务 ID、模型、渠道、用量、结算金额、成功状态、人工验收结果。不要把完整提示词和用户隐私默认写入通用日志。

先跑小样本，估算平均值与高分位费用，给批任务设预算和停止条件。发现异常长输出、重复任务或渠道切换时及时复核；博客不维护另一份可能过期的实时价格表。