LLM API 接口文档

OpenAI 兼容接口 · 可直接使用官方 SDK 对接

Base URL：https://hw.hfcms.xyz/v1 Bearer 密钥认证 支持流式 SSE

1. 基本信息

Base URL
https://hw.hfcms.xyz/v1
认证方式
请求头 Authorization: Bearer <你的密钥>
模型 ID
ModelScope/MNN/Qwen3.5-2B-MNN
协议
HTTP/1.1、HTTP/2，OpenAI Chat Completions 兼容
内容类型
application/json（流式返回 text/event-stream）
字符编码
UTF-8
接口完全兼容 OpenAI 协议。如果你已经在用 openai 官方 SDK，只需把 base_url 和 api_key 换成本文档的值即可，其余代码不用改。

2. 快速开始

2.1 先验证密钥是否可用

curl https://hw.hfcms.xyz/v1/models \
  -H "Authorization: Bearer <你的密钥>"

返回模型列表即为正常。若返回 401，说明密钥无效或已过期。

2.2 发起一次对话（流式，推荐）

curl -N https://hw.hfcms.xyz/v1/chat/completions \
  -H "Authorization: Bearer <你的密钥>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ModelScope/MNN/Qwen3.5-2B-MNN",
    "messages": [{"role": "user", "content": "用一句话介绍你自己"}],
    "stream": true
  }'
流式请求请加 -N（curl）或关闭客户端缓冲，否则响应会攒到最后一次性输出。 服务端已关闭代理缓冲，数据是逐字下发的。

2.3 Python（openai 官方 SDK）

from openai import OpenAI

client = OpenAI(
    base_url="https://hw.hfcms.xyz/v1",
    api_key="<你的密钥>",
)

stream = client.chat.completions.create(
    model="ModelScope/MNN/Qwen3.5-2B-MNN",
    messages=[{"role": "user", "content": "用一句话介绍你自己"}],
    stream=True,
)
for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

2.4 Node.js（openai 官方 SDK）

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://hw.hfcms.xyz/v1",
  apiKey: "<你的密钥>",
});

const stream = await client.chat.completions.create({
  model: "ModelScope/MNN/Qwen3.5-2B-MNN",
  messages: [{ role: "user", content: "用一句话介绍你自己" }],
  stream: true,
});

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

2.5 Python（不用 SDK，原生 requests）

import json, requests

r = requests.post(
    "https://hw.hfcms.xyz/v1/chat/completions",
    headers={
        "Authorization": "Bearer <你的密钥>",
        "Content-Type": "application/json",
    },
    json={
        "model": "ModelScope/MNN/Qwen3.5-2B-MNN",
        "messages": [{"role": "user", "content": "你好"}],
        "stream": True,
    },
    stream=True,
    timeout=600,
)
for line in r.iter_lines():
    if not line:
        continue
    line = line.decode("utf-8")
    if not line.startswith("data:"):
        continue
    payload = line[5:].strip()
    if payload == "[DONE]":
        break
    delta = json.loads(payload)["choices"][0]["delta"].get("content")
    if delta:
        print(delta, end="", flush=True)

3. 接口清单

方法路径说明
GET /v1/models 列出可用模型，可用于验证密钥有效性
POST /v1/chat/completions 对话补全，支持流式与非流式、支持图片输入
POST /v1/messages Anthropic Messages 兼容格式（实验性）

4. 请求参数

字段类型必填说明
modelstring是填 ModelScope/MNN/Qwen3.5-2B-MNN
messagesarray是消息数组，元素含 role 与 content。role 可为 user / assistant / system
streamboolean否默认 false。true 时以 SSE 逐字返回
max_new_tokensinteger否限制生成的最大长度，建议 512 至 2048
temperaturenumber否采样温度，越大越发散

响应结构（非流式）

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "..." },
      "finish_reason": "stop"
    }
  ]
}

流式响应结构

每一行形如 data: {json}，增量内容在 choices[0].delta.content，最后以 data: [DONE] 结束。

data: {"choices":[{"delta":{"content":"你"}}]}
data: {"choices":[{"delta":{"content":"好"}}]}
data: [DONE]

5. 图片输入（多模态）

模型自带视觉编码器，可直接识图。content 传数组，图片用 base64 data URL：

import base64

b64 = base64.b64encode(open("photo.jpg", "rb").read()).decode()

body = {
    "model": "ModelScope/MNN/Qwen3.5-2B-MNN",
    "messages": [{
        "role": "user",
        "content": [
            {"type": "text", "text": "这张图里有什么？"},
            {"type": "image_url",
             "image_url": {"url": "data:image/jpeg;base64," + b64}}
        ]
    }],
    "max_new_tokens": 512,
}
图片请先压到最长边 1000 像素以内再传。原图直传会显著变慢，过大还可能失败。 另外本接口不支持 <img>URL</img> 这类内联标签写法，请务必使用上面的标准格式。

6. 错误码

状态码含义处理建议
200成功正常读取响应
401密钥无效或缺失检查请求头是否为 Authorization: Bearer <key>，注意不要漏掉 Bearer 和空格
404路径错误确认路径以 /v1/ 开头
429请求过于频繁降低发起频率，稍后重试
502 / 504后端模型暂不可用稍等后重试；若持续出现请反馈

错误响应体统一为 JSON：

{
  "error": {
    "message": "Invalid API key. Send header: Authorization: Bearer <your-key>",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

7. 使用限制与注意事项

8. 常见问题

返回 200 但响应体是空的？

通常是密钥问题。本服务在不带密钥时会返回 401，但如果你经过其他代理层转发，可能出现 200 空响应的情况。请先用第 2.1 节的方式单独验证密钥。

请求发出后很久没有输出？

模型正在生成。流式请求下首个字符通常需要 2 至 10 秒，复杂推理题可能更久。 若使用非流式请求，需等整段生成完毕才会返回，请务必把超时设长。

CORS 跨域调用？

服务端已开启跨域支持，允许任意来源、允许 Authorization 请求头， 浏览器端可直接调用。生产环境仍建议从服务端发起，以免密钥暴露。