LLM 调用总览

先判断能力，再选择端点

模型 ID 来自 HKGAI 的 /v1/models，目录可见只表示当前 Key 能看到它，不代表可以用 Chat 请求调用。请根据能力选择端点：

视频生成是异步任务，不能用同步 Chat 的超时规则判断可用性。

推荐接入顺序

1. 调用 GET /v1/models，让用户选择实际返回的模型 ID。
2. 使用最小请求验证目标端点。
3. 记录模型 ID、端点、HTTP 状态、耗时和错误，不记录 API Key。
4. 生产调用设置超时、重试上限和请求 ID 日志；视频任务还要保存任务 ID 并轮询状态。

Chat 最小请求

curl -sS "$HKGAI_BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $HKGAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "从 /v1/models 选择",
    "messages": [{"role": "user", "content": "只回复 OK"}],
    "max_tokens": 32,
    "chat_template_kwargs": {"enable_thinking": false}
  }'

Qwen3 类模型建议关闭隐藏推理；模型是否返回 usage.completion_tokens 由网关决定，不能自行用字符数代替 token。

本项目的服务端代理边界

浏览器只访问本项目的 /api/*，真实 Key 只在服务端 .env 中读取。接入其他项目时也应采用服务端代理或安全的后端环境变量，不要把 Key 写进前端代码、日志、截图或提交记录。

可用性与效果是两件事

探测成功只表示端点完成了一次真实调用。粤语翻译、粤语转写、TTS 音色和视频内容质量必须用业务样本单独验收，不能只看 HTTP 200。