用代码而不是文档，探测聚合站这把 key 到底开了哪些端点

拿到一把 API key 后，最可靠的做法不是查阅文档，而是直接向服务端询问它能做什么。因为文档可能滞后，而聚合站的端点兼容性会因底层模型供应商而异。本文以常见的 OpenAI 兼容接口为例，教你用 curl 和简单脚本探测这把 key 实际可命中的端点，并将 /models 的返回作为唯一可信来源。\n\n## 为什么文档不足为凭\n\n聚合站通常聚合多个模型供应商，每个供应商对端点的支持程度不同。同一把 key 可能可以调用聊天补全，但不支持嵌入；有些模型支持流式输出，有些则只能一次性返回。文档往往只列出理想情况，而实际行为受路由策略、模型版本、甚至临时故障影响。因此，唯一可靠的依据是服务端实时返回的能力信息。\n\n## 第一步：获取模型列表\n\n几乎所有聚合站都提供 /v1/models 端点，返回当前 key 有权访问的模型 ID 列表。这是探测的起点。\n\n``bash\ncurl -s -H \"Authorization: Bearer $APIKEY\" \\\n https://your-aggregator.com/v1/models | jq .\n`\n\n注意：\n\n- 如果返回 401，说明 key 无效或缺少权限。\n- 如果返回 404，可能是端点路径不同，尝试去掉 /v1 或更换前缀。\n- 返回的 data 数组中的 id 字段就是后续测试要用的模型标识。\n\n记下这些 ID，它们是你探测其他端点的“种子”。\n\n## 第二步：基准聊天补全\n\n用列表中的任意一个模型测试 /v1/chat/completions。这是最基础的端点。\n\n`bash\ncurl -s -X POST https://your-aggregator.com/v1/chat/completions \\\n -H \"Authorization: Bearer $APIKEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"model\": \"MODELID\",\n \"messages\": [{\"role\": \"user\", \"content\": \"ping\"}],\n \"maxtokens\": 5\n }' | jq .\n`\n\n如果返回 choices 数组，说明该模型支持基础聊天。若返回错误，记录错误码和消息，这能帮你判断是模型不支持，还是端点整体不可用。\n\n## 第三步：探测流式变体\n\n在请求体中加入 \"stream\": true，观察响应是否为 text/event-stream 格式。\n\n`bash\ncurl -s -N -X POST https://your-aggregator.com/v1/chat/completions \\\n -H \"Authorization: Bearer $APIKEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"model\": \"MODELID\",\n \"messages\": [{\"role\": \"user\", \"content\": \"ping\"}],\n \"stream\": true,\n \"maxtokens\": 5\n }'\n`\n\n如果看到以 data: 开头的行，并且最后有 data: [DONE]，说明流式可用。注意有些聚合站可能对某些模型禁用流式，或者要求特殊参数。\n\n## 第四步：测试嵌入端点\n\n嵌入端点通常是 /v1/embeddings。用模型列表中的嵌入模型（ID 通常包含 embed 或 embedding）测试。\n\n`bash\ncurl -s -X POST https://your-aggregator.com/v1/embeddings \\\n -H \"Authorization: Bearer $APIKEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"model\": \"EMBEDMODELID\",\n \"input\": \"test\"\n }' | jq .\n`\n\n如果返回 data 数组且包含 embedding 向量，说明嵌入端点可用。若返回 404 或 400，可能是该模型不支持嵌入，或者聚合站未开放此端点。\n\n## 第五步：编写自动化探测脚本\n\n手动测试适合少量模型，但如果你想全面了解 key 的能力，可以写一个简单脚本遍历模型列表并测试各个端点。以下是一个 Bash 脚本示例：\n\n`bash\n#!/bin/bash\nAPIKEY=\"yourkey\"\nBASE=\"https://your-aggregator.com/v1\"\n\n# 获取模型列表\nMODELS=$(curl -s -H \"Authorization: Bearer $APIKEY\" $BASE/models | jq -r '.data[].id')\n\nfor MODEL in $MODELS; do\n echo \"Testing model: $MODEL\"\n\n # 测试聊天端点\n CHATRESULT=$(curl -s -o /dev/null -w \"%{httpcode}\" -X POST $BASE/chat/completions \\\n -H \"Authorization: Bearer $APIKEY\" \\\n -H \"Content-Type: application/json\" \\\n -d \"{\\\"model\\\": \\\"$MODEL\\\", \\\"messages\\\": [{\\\"role\\\": \\\"user\\\", \\\"content\\\": \\\"ping\\\"}], \\\"maxtokens\\\": 1}\")\n echo \" Chat: HTTP $CHATRESULT\"\n\n # 测试流式\n STREAMRESULT=$(curl -s -o /dev/null -w \"%{httpcode}\" -X POST $BASE/chat/completions \\\n -H \"Authorization: Bearer $APIKEY\" \\\n -H \"Content-Type: application/json\" \\\n -d \"{\\\"model\\\": \\\"$MODEL\\\", \\\"messages\\\": [{\\\"role\\\": \\\"user\\\", \\\"content\\\": \\\"ping\\\"}], \\\"stream\\\": true, \\\"maxtokens\\\": 1}\")\n echo \" Stream: HTTP $STREAM_RESULT\"\n\ndone\n`\n\n根据 HTTP 状态码（200 表示成功，4xx 表示客户端错误，5xx 表示服务端错误）快速筛选出可用端点。注意控制请求频率，避免触发速率限制。\n\n## 第六步：处理常见错误 \n\n探测过程中会遇到各种错误，理解它们能帮你更快定位问题：\n\n- 401 Unauthorized：key 无效、过期或缺少权限。\n- 403 Forbidden：key 有效但无权访问该端点或模型。\n- 404 Not Found：端点路径错误，或该模型不支持此端点。\n- 429 Too Many Requests：触发速率限制，需降低请求频率。\n- 400 Bad Request：请求体格式错误，或模型不支持某些参数（如流式）。\n\n如果遇到 400 且消息提到参数不支持，尝试移除该参数或换用其他模型。\n\n## 第七步：以 /models 为唯一可信来源\n\n整个探测过程中，/v1/models` 的返回是决策基础。它告诉你哪些模型可用，但不会告诉你每个模型支持哪些端点。因此你需要结合后续测试来建立映射关系。建议每次探测后记录：\n\n- 模型 ID\n- 支持的端点\n- 是否支持流式\n- 错误信息（如有）\n\n最终你会得到一份针对当前 key 的端点能力矩阵，比任何文档都准确。\n\n## 将探测集成到 CI 或监控\n\n如果 key 用于生产环境，建议定期运行探测脚本，以便在聚合站调整端点或模型时及时发现。将脚本放入 CI 流水线，每天跑一次，记录结果变化。这能帮助你避免因端点变动导致的服务中断。\n\n通过以上步骤，你可以用代码而非文档来理解 key 的真实能力，并据此设计更健壮的应用。