如何通过 hiapi API 使用 Claude Opus 4.8

你将构建什么

一个可运行的集成，通过 hiapi 的 OpenAI 兼容 Chat Completions API 调用 Claude Opus 4.8 —— 这是 Anthropic 当前 Claude 4.8 系列中的顶级模型。一次请求即可返回真实补全，并附带你一旦 Demo 跑通后所需的生产模式（流式传输、工具调用、自适应思考）。

前提条件：一个 hiapi API 密钥。从控制台获取 —— 它就是一个 sk-... 字符串，且同一密钥适用于你账户下所有已启用的模型，不限于此模型。

下文所有内容在撰写时均针对线上 API 实际运行过。

最小可运行示例

Claude Opus 4.8 是标准 Chat Completions 端点上的文本模型 —— 而非 hiapi 用于图像/视频/音频模型的异步 /v1/tasks 流程。一次请求，一次响应，无需轮询。

curl https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-<your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-4-8",
    "messages": [
      {"role": "user", "content": "Review this function for edge cases and suggest a fix."}
    ],
    "max_tokens": 1024
  }'

响应（已精简）：

{
  "id": "msg_011CfFm8abLRcYtLVSky81As",
  "model": "claude-opus-4-8",
  "object": "chat.completion",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "..." },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 10, "completion_tokens": 4, "total_tokens": 14 }
}

Python 中同样的调用，仅使用 requests：

import requests

resp = requests.post(
    "https://api.hiapi.ai/v1/chat/completions",
    headers={"Authorization": "Bearer sk-<your-api-key>"},
    json={
        "model": "claude-opus-4-8",
        "messages": [
            {"role": "user", "content": "Review this function for edge cases and suggest a fix."}
        ],
        "max_tokens": 1024,
    },
    timeout=60,
)
resp.raise_for_status()
data = resp.json()
print(data["choices"][0]["message"]["content"])
print(data["usage"])  # prompt_tokens / completion_tokens / total_tokens

直接发送裸模型 ID claude-opus-4-8 —— 无需提供商前缀，无需路由后缀。hiapi 为该模型列出了两条后端路由（default 和 aws）以提供冗余，但它们共享同一个模型 ID；你无需在两者之间选择。

由于请求格式与 OpenAI 兼容，这同样无需修改即可用于官方 openai Python/JS SDK —— 只需将 base_url 指向 https://api.hiapi.ai/v1 并传入你的 hiapi 密钥。

生产模式

流式传输

设置 "stream": true 并读取 Server-Sent Events。每个分块包含一个 delta.content 片段；流在最后一个分块以 finish_reason: "stop" 结束，随后是一个 [DONE] 哨兵：

curl https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-<your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-4-8",
    "messages": [{"role": "user", "content": "Count 1 to 3"}],
    "stream": true,
    "max_tokens": 20
  }'

data: {"choices":[{"delta":{"content":"","role":"assistant"},"finish_reason":null,"index":0}]}

data: {"choices":[{"delta":{"content":"1"},"finish_reason":null,"index":0}]}

data: {"choices":[{"delta":{"content":", 2, 3"},"finish_reason":null,"index":0}]}

data: {"choices":[{"delta":{},"finish_reason":"stop","index":0}]}

data: [DONE]

跨分块累积 choices[0].delta.content 以重建完整文本。最终数据事件（在 finish_reason 之后）携带的是 usage 总计，而非 delta。

工具调用

按与 OpenAI 相同的方式声明函数，然后在下一轮重放助手的 tool_calls 消息及 tool 结果消息：

curl https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-<your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-4-8",
    "messages": [{"role": "user", "content": "What is the status of task demo-123?"}],
    "max_tokens": 200,
    "tools": [{
      "type": "function",
      "function": {
        "name": "get_task_status",
        "description": "Look up a task by ID.",
        "parameters": {
          "type": "object",
          "properties": {"task_id": {"type": "string"}},
          "required": ["task_id"],
          "additionalProperties": false
        }
      }
    }],
    "tool_choice": "auto"
  }'

响应返回时带有 finish_reason: "tool_calls"，并在 choices[0].message.tool_calls 中包含函数名及 JSON 编码的参数。在本地运行你的函数，然后在下一个请求中将结果作为携带匹配 tool_call_id 的 role: "tool" 消息发回 —— 模型将从那里继续。

自适应思考

Claude Opus 4.8 支持选择性加入的推理轮次。添加 "thinking": {"type": "adaptive"} 并通过 output_config.effort 选择努力级别（low、medium 或 high 均确认可用）：

{
  "model": "claude-opus-4-8",
  "messages": [{"role": "user", "content": "Compare two approaches and state the trade-offs."}],
  "thinking": {"type": "adaptive"},
  "output_config": {"effort": "high"}
}

围绕此功能构建之前，有两件事值得了解。第一，“自适应”意味着模型自行判断一个提示词是否值得思考 —— 在 low 甚至 medium 努力级别下，一个简单问题可能完全不会返回 reasoning_details 字段，因此不要假设每个请求都会产生该字段。第二，与 hiapi 上某些其他文本模型不同，Opus 4.8 不返回人类可读的推理轨迹：reasoning_details 数组中的 reasoning.text 条目返回为空，只有 signature 条目被填充。将 reasoning_details 视为不透明的延续状态 —— 如果你要将会话带入后续工具调用，请原样传递它 —— 而不要将其解析或展示给用户。

错误处理

认证失败返回 HTTP 401，并附带 hiapi_error 信封：

{
  "error": {
    "code": "permission_denied",
    "message": "This API key is invalid. Check that it is correct or use another API key and try again.",
    "type": "hiapi_error"
  }
}

在访问 response.json()["choices"] 之前检查 response.status_code，若需升级处理则记录 error.request_id —— 支持团队可据此追踪具体调用。

幂等性与重试

Chat Completions 调用不像 /v1/tasks 任务那样按请求 ID 幂等 —— 重试的请求是一次新的补全，也是一次新的计费。对于生产流量，请在你的代码中为 5xx/超时情况包装带退避的重试逻辑，并限制 max_tokens，以免重试风暴（或运行较久的自适应思考调用）导致无上限的开销。

相关阅读

• hiapi 上的 Claude Opus 4.8 —— 当前定价与模型卡片。
• 认证 —— hiapi API 密钥的工作原理及如何轮换。
• 如何通过 hiapi API 使用 Claude Sonnet 4.6 —— 针对 hiapi 平衡成本的 Claude 层级采用相同的集成模式，如果你的工作负载不需要 Opus 4.8 这么强的模型。
• hiapi 定价 —— Claude Opus 4.8 及所有其他已启用模型的实时每 token 费率。

常见问题

claude-opus-4-8 是我应该发送的精确模型 ID 吗？ 是的 —— 在 model 字段中发送裸字符串 claude-opus-4-8。无需提供商特定前缀，也无需路由后缀；hiapi 会在内部将其解析到正确的后端路由。

这是否使用与 hiapi 图像和视频模型相同的 /v1/tasks 流程？ 不是。像 Claude Opus 4.8 这样的文本模型使用同步的 POST /v1/chat/completions 端点 —— 一次请求，一次响应（或一个 SSE 流）。/v1/tasks 仅适用于媒体模型（图像、视频、音频），它们异步运行并返回一个用于轮询的 URL 或回调。

我可以使用 OpenAI SDK 而不是原始的 curl/requests 吗？ 可以。由于该端点与 OpenAI 兼容，将官方 openai SDK 的 base_url 指向 https://api.hiapi.ai/v1，并将你的 hiapi 密钥用作 api_key —— 基本聊天、流式传输或工具调用无需其他代码更改。

我应该使用 Opus 4.8 还是 Sonnet 4.6？ Opus 4.8 是能力更高、成本更高的层级 —— 在更难的推理、编码或智能体任务中，当准确性比延迟或每 token 成本更重要时，选择它。对于高流量或对延迟敏感的流量，Claude Sonnet 4.6 以更低的价格提供相同的 API 形态。

thinking 是否总是返回可见的推理轨迹？ 两方面都不是：自适应思考可能对判断为简单的请求完全跳过推理，而当它确实思考时，Opus 4.8 的 reasoning_details 目前返回的文本字段为空 —— 只有 signature 被填充。不要构建假定始终存在可读轨迹的 UI。

在运行大批量之前，我在哪里查看当前定价？ hiapi 的定价页面列出了 Claude Opus 4.8 的实时每 token 费率 —— 在做预算前查看它，因为本文没有硬编码可能过时的数字。