> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hingnet.com.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 文本与多模态对话（Chat / Responses）

> 通过 OpenAI 兼容接口使用豆包 Seed 1.6、DeepSeek、Kimi 等火山方舟模型进行对话与 Agent 调用。

本页面向 **普通 API 调用者（非管理员）**，说明如何在 HingNet AI 中，通过 Doubao / VolcArk 渠道使用文本与多模态对话能力。你只需要关心：

* 使用 **统一的 OpenAI 风格接口**：`/v1/chat/completions` 与 `/v1/responses`；
* 在 `model` 字段中填写 Doubao / DeepSeek / Kimi 等模型名；
* 使用自己的 HingNet AI API Key（`oh-xxxxxxxx`），**不需要管理火山方舟密钥、签名和路由**。

底层细节（如上游 Model ID、渠道配置、计费映射）均由平台和管理员负责维护。

***

## 一、前置准备

```bash theme={null}
export BASE_URL="https://models.hingnet.com.cn/v1"
export TOKEN="oh-xxxxxxxxxxxxxxxx"
```

统一请求头：

```http theme={null}
Authorization: Bearer <TOKEN>
Content-Type: application/json
```

在 Doubao 渠道下常用的文本 / 多模态模型包括：

* 豆包 Seed 系列：
  * `doubao-seed-1.8`
  * `doubao-seed-1.6`
  * `doubao-seed-1.6-lite`
  * `doubao-seed-1.6-flash`
  * `doubao-seed-1.6-thinking`（兼容别名）
  * `doubao-seed-1.6-vision`
* 辅助模型：
  * `doubao-seed-code`
  * `doubao-seed-translation`
* 经由 VolcArk 聚合的其它模型（视管理员配置而定）：
  * `deepseek-v3.2`、`deepseek-v3.1`、`deepseek-v3`、`deepseek-r1-ark`
  * `kimi-k2`
  * `glm-4.7`（需管理员在 VolcArk 渠道启用）

> 提示：
>
> * 模型名在平台内部会统一按小写处理，因此 `doubao-seed-1.8` / `Doubao-Seed-1.8` 均可被正确路由与计费；
> * 为了避免混淆，仍建议在客户端中使用文档中给出的 **小写 API 模型名**。

***

## 二、Chat Completions：标准对话接口

如果你已经习惯 OpenAI 的 `POST /v1/chat/completions`，那么 Doubao 渠道完全可以按相同方式使用，只需将 `model` 换成 Doubao / DeepSeek / Kimi 对应的模型名。

### 1. 基础对话示例

```bash theme={null}
curl -X POST "$BASE_URL/chat/completions" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seed-1.8",
    "messages": [
      {"role": "system", "content": "你是一个乐于助人的中文助手。"},
      {"role": "user", "content": "用三句话介绍一下 HingNet AI 是什么。"}
    ],
    "temperature": 0.7
  }'
```

说明：

* `model`：填 Doubao 模型名（如 `doubao-seed-1.8`），平台会自动映射到火山方舟所需的版本化 Model ID（如 `doubao-seed-1-8-251228`），你无需关心后缀；
* `messages`：完全兼容 OpenAI 的多轮对话格式；
* 计费与用量统计会自动归集到当前用户与对应模型，无需额外参数。

### 2. 流式输出（SSE）

```bash theme={null}
curl -N -X POST "$BASE_URL/chat/completions" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "model": "doubao-seed-1.6-flash",
    "messages": [
      {"role": "system", "content": "你是一位回答简洁的助手。"},
      {"role": "user", "content": "分点列出 5 条提高工作效率的小技巧。"}
    ],
    "stream": true
  }'
```

注意：

* `-N` 关闭 cURL 的输出缓冲，便于实时看到模型逐 token 输出；
* 响应格式为标准的 OpenAI SSE 事件（`data: {...}`），可以直接复用现有的 OpenAI 客户端或 SDK。

### 3. 工具调用 / JSON 输出

Doubao Seed 与经由 VolcArk 聚合的 DeepSeek / Kimi 模型，同样支持函数调用与 JSON 结构化输出。你可以沿用与 OpenAI 完全一致的写法：

* 使用 `tools` 与 `tool_choice` 描述函数；
* 设置 `response_format` 为 `{"type": "json_schema"}` 或 `{"type": "json_object"}` 约束输出；
* 平台会自动统计工具调用带来的额外用量并计入 `usage`。

具体字段含义与示例可参考通用文档《OpenAI / Chat Completions》。

***

## 三、多模态对话：图文理解（Vision）

当使用 `doubao-seed-1.6-vision` 等支持视觉的模型时，可以在 `messages` 中混合文本与图片内容，格式与 OpenAI Vision 模型兼容：

```bash theme={null}
curl -X POST "$BASE_URL/chat/completions" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seed-1.6-vision",
    "messages": [
      {
        "role": "user",
        "content": [
          {"type": "text", "text": "请描述这张图片的主要内容。"},
          {
            "type": "image_url",
            "image_url": {
              "url": "https://example.com/demo.png"
            }
          }
        ]
      }
    ]
  }'
```

要点：

* 图片可以是公网可访问 URL，也可以是 base64 数据 URL（视模型与上游限制而定）；
* 多模态输入仍然走统一的 `/v1/chat/completions` 路径，只是 `content` 从字符串变成了数组；
* 用量与计费会自动根据模型的多模态定价规则折算为 token，无需客户端参与。

***

## 四、Responses API：统一多模态响应接口

如果你更偏好使用 OpenAI 新一代的 `POST /v1/responses` 接口，也可以直接在 Doubao 渠道下使用 Doubao / DeepSeek / Kimi 模型。

### 1. 基础示例

```bash theme={null}
curl -X POST "$BASE_URL/responses" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seed-1.8",
    "input": [
      {
        "role": "user",
        "content": [
          {"type": "text", "text": "请把下面这段话整理成 3 个要点。"}
        ]
      }
    ],
    "response_format": {
      "type": "json_schema"
    }
  }'
```

说明：

* `input` 字段与 OpenAI 官方保持一致，可以在其中混合文本、图片、工具结果等内容；
* 响应中的 `output`、`usage` 字段与 OpenAI Responses 接口兼容，可复用现有解析逻辑；
* 对于 Web Search、Code Interpreter 等扩展工具，平台会在 `usage` 中附带额外计费信息（视具体模型与能力开放情况而定）。

### 2. 流式 Responses

```bash theme={null}
curl -N -X POST "$BASE_URL/responses" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "model": "doubao-seed-1.8",
    "input": "请逐步推理并回答：为什么天空是蓝色的？",
    "stream": true
  }'
```

当 `stream: true` 时：

* 服务端会以 SSE 事件的形式增量返回 `response.*` 事件；
* 若你希望在客户端侧兼容 Chat Completions 流格式，可参考通用文档《OpenAI / Responses》，HingNet AI 已提供基础的转换兼容逻辑。

***

## 五、与管理员配置的关系

作为普通调用者，你无需关心以下事项：

* 火山方舟控制台中具体开通了哪些 Model ID；
* 管理员如何在 HingNet AI 控制台中为 Doubao 渠道配置 Base URL、密钥和价格；
* 不同上游（官方 VolcArk 或 Sutui 等聚合商）之间的差异。

你只需要：

1. 从管理员处获取一个可用的 HingNet AI API Key（`oh-xxxxxxxx`）；
2. 在请求中选择文档中列出的 Doubao / DeepSeek / Kimi 模型名；
3. 通过 `/v1/chat/completions` 或 `/v1/responses` 发起调用即可。

其它诸如模型版本升级、计费映射与任务追踪，均由平台自动处理。