企业开发者中心

充值余额后创建 API Key，调用华通云模型并按输入、输出 Token 分别计费。

¥0.00

可用余额

快速开始

先生成 API Key，充值到账后即可调用。

将 Base URL 设置为当前华通云网关地址，可直接使用 OpenAI SDK 调用。

Base URL: /v1 Model: hty-general Authorization: Bearer htk_live_...

API Key

名称	前缀	状态	RPM	TPM	最后使用	到期时间	操作

可用华通云模型

客户端只使用 hty-* 模型别名；上游厂商和真实模型不会对外展示。

调用用量

时间	API Key	华通云模型	状态	输入	缓存命中	输出	总 Token	金额	延迟

余额流水

时间	类型	金额	变动前	变动后	请求 ID	说明

10 分钟完成首次调用

从充值到获得第一条模型回复

这份文档面向首次接入华通云 API 的开发者。按照下面五步操作，无需了解底层模型厂商或路由配置。

1充值余额确认开发者中心显示可用余额。

2创建 API Key设置名称、限额和有效期。

3保存密钥明文只显示一次，请立即保存。

4调用接口获取模型列表并发送对话请求。

5核对用量核对 Token、金额和调用状态。

安全提醒：API Key 只能保存在服务器端。不要写入网页 JavaScript、手机 App、公开仓库、聊天记录或截图。

1. 地址与认证

华通云提供 OpenAI Chat Completions 兼容接口。所有 /v1/* 请求都使用 API Key Bearer 认证。

网关地址

SDK Base URL：/v1

认证请求头

Authorization: Bearer htk_live_...
API Key 前缀应为 htk_live_。

macOS / Linux 环境变量

export HUATONG_API_KEY="htk_live_替换为你的完整密钥"
export HUATONG_BASE_URL="/v1"

API Key 明文只在创建时显示一次。若遗失，请吊销旧 Key 并创建新 Key，平台无法恢复原始密钥。

2. 选择华通云模型

正式调用前建议请求 GET /v1/models，只使用接口实际返回的模型 ID。客户无需配置底层路由。

模型	API 模型 ID	适用场景	当前价格

获取当前 Key 可访问的模型

curl -sS "/v1/models" \
  -H "Authorization: Bearer $HUATONG_API_KEY"

推荐：普通问答、文案和简单代码优先使用 hty-general；合同、标书、长文档和企业资料分析使用 hty-pro。

3. curl 完成首次对话

Idempotency-Key 用于避免网络重试造成重复扣费，每个业务请求应使用唯一值。

POST /v1/chat/completions

curl -sS "/v1/chat/completions" \
  -H "Authorization: Bearer $HUATONG_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: demo-20260728-0001" \
  -d '{
    "model": "hty-general",
    "messages": [
      {"role": "system", "content": "请用简洁中文回答。"},
      {"role": "user", "content": "用三句话介绍华通云 AI 网关。"}
    ],
    "stream": false,
    "temperature": 0.7,
    "max_tokens": 512
  }'

4. Python SDK

适用于 Python 3.9 及以上版本。先安装 SDK，再从环境变量读取密钥。

安装

pip install -U openai

完整非流式示例

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["HUATONG_API_KEY"],
    base_url="/v1",
    timeout=60.0,
    max_retries=2,
)

response = client.chat.completions.create(
    model="hty-general",
    messages=[
        {"role": "system", "content": "请用简洁中文回答。"},
        {"role": "user", "content": "为企业客户写一段产品欢迎语。"},
    ],
    temperature=0.7,
    max_tokens=512,
    extra_headers={"Idempotency-Key": "python-demo-0001"},
)

print(response.choices[0].message.content)
print("总 Token：", response.usage.total_tokens)

5. Node.js SDK

适用于 Node.js 18 及以上版本，示例使用 ES Module。

安装

npm install openai

完整非流式示例

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.HUATONG_API_KEY,
  baseURL: "/v1",
  timeout: 60_000,
  maxRetries: 2,
});

const response = await client.chat.completions.create(
  {
    model: "hty-general",
    messages: [
      { role: "system", content: "请用简洁中文回答。" },
      { role: "user", content: "生成一段客服欢迎话术。" },
    ],
    temperature: 0.7,
    max_tokens: 512,
  },
  { headers: { "Idempotency-Key": "node-demo-0001" } },
);

console.log(response.choices[0].message.content);
console.log("总 Token：", response.usage.total_tokens);

6. 流式输出

设置 stream: true 后，接口通过 Server-Sent Events 持续返回内容，并以 data: [DONE] 结束。

Python 流式读取

stream = client.chat.completions.create(
    model="hty-general",
    messages=[
        {"role": "user", "content": "写一段项目介绍"}
    ],
    stream=True,
    stream_options={"include_usage": True},
)

for chunk in stream:
    if chunk.choices:
        text = chunk.choices[0].delta.content or ""
        print(text, end="", flush=True)
    if chunk.usage:
        print("\n总 Token：", chunk.usage.total_tokens)

Node.js 流式读取

const stream = await client.chat.completions.create({
  model: "hty-general",
  messages: [
    { role: "user", content: "写一段项目介绍" },
  ],
  stream: true,
  stream_options: { include_usage: true },
});

for await (const chunk of stream) {
  process.stdout.write(
    chunk.choices[0]?.delta?.content ?? ""
  );
}

生产环境应设置读取超时，并正确处理客户端主动断开。不要将整段 SSE 缓存完后再展示，否则会失去流式响应体验。

7. 常用请求参数

参数	必填	类型与范围	说明
model	是	字符串	使用 /v1/models 返回的模型 ID。
messages	是	非空数组	角色支持 system、user、assistant，内容为纯文本。
stream	否	布尔值	默认 false。
temperature	否	0–2	值越高输出越发散；稳定业务建议 0.2–0.8。
top_p	否	0–1	通常只调整 temperature 或 top_p 其中一个。
max_tokens	否	正整数	限制最大输出 Token，实际值受平台上限约束。
stop	否	字符串或数组	命中指定文本时停止生成。
n	否	只能为 1	当前不支持一次生成多个候选答案。

当前客户 API 暂不支持工具调用、函数调用、多模态内容数组和 Responses API。请勿提交 tools 或 functions。

8. 响应结构

非流式接口返回模型内容和真实 Token 用量。建议保存响应头中的请求 ID，便于对账和排查。

成功响应示例

{
  "id": "chatcmpl-ht_xxx",
  "object": "chat.completion",
  "model": "hty-general",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "这里是模型回复。"
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 94,
    "completion_tokens": 46,
    "total_tokens": 140,
    "prompt_tokens_details": {"cached_tokens": 0}
  }
}

9. 计费、限流与幂等

Token 计费

输入和输出 Token 分别计价，最终扣费以真实 usage 和请求发生时的客户售价为准。

RPM / TPM

每个 API Key 都有每分钟请求数和 Token 数限制，可在创建 Key 时设置。

每日消费上限

可为每个 Key 设置每日消费上限，达到上限后返回 HTTP 429。

安全重试

为可重试请求传入唯一 Idempotency-Key，避免重复扣费。

响应头	用途
x-request-id	网关请求 ID；联系支持时必须提供。
x-huatong-billed-cny	本次请求实际扣费金额。
x-huatong-balance-cny	请求结算后的企业余额。
x-ratelimit-remaining-requests	当前窗口剩余请求次数。
x-ratelimit-remaining-tokens	当前窗口剩余 Token 额度。
x-huatong-idempotent-replay	为 true 时表示返回成功请求的幂等结果，不重复扣费。

10. 错误处理

error.message 用于展示，error.code 用于程序判断。

HTTP	常见错误码	处理建议
400	missing_model / missing_messages	检查请求 JSON、模型 ID 和消息数组。
401	missing_api_key / invalid_api_key	检查 Bearer 格式、Key 是否过期或已吊销。
403 / 404	MODEL_NOT_AVAILABLE / model_not_found	请求 /v1/models，只调用当前 Key 可见模型。
409	idempotency_key_mismatch / request_in_progress	不同请求不能复用同一个幂等键。
429	rate_limit_exceeded / tokens_per_minute_exceeded	读取限流响应头并采用指数退避。
429	insufficient_balance / daily_spend_limit_exceeded	充值余额或调整 Key 的每日消费上限。
503	model_unavailable / rate_limiter_unavailable	保留 x-request-id，有限次数重试。

错误响应结构

{
  "error": {
    "message": "企业账户余额不足，请先充值",
    "type": "insufficient_quota",
    "param": null,
    "code": "insufficient_balance"
  }
}

11. 生产上线检查

API Key 仅保存在服务端密钥管理或环境变量中。
开发、测试和生产环境分别使用不同 API Key。
为生产 Key 设置 RPM、TPM、每日消费上限和到期时间。
生成唯一 Idempotency-Key，并保存 x-request-id。
对 429、503 使用指数退避，限制最大重试次数。
为连接超时、读取超时和客户端断开设置处理逻辑。
分别验证 hty-general、hty-pro 和流式响应。
定期核对 Token、金额和异常请求。

接入完成标准：能够安全读取 API Key、获取模型列表、完成非流式与流式调用、记录请求 ID，并在开发者中心核对到相同的 Token 和扣费流水。

企业账户登录