# 方舟文本

> 使用火山方舟 Chat Completions 路径和 Ark SDK 调用文本模型，读取文本响应或流式增量。

Base URL：`https://platform.sgt.site/volcengine`

本页说明平台提供的方舟文本接入方式。HTTP 路径相对于上述 Base URL；Ark SDK 的 `base_url` 另需包含 `/api/v3`，具体配置见下文。

<a id="native-ark-text-h-019dc94f"></a>

## 接口与鉴权

| 方法 | 相对路径 | 用途与返回内容 |
| --- | --- | --- |
| POST | `/api/v3/chat/completions` | 提交 `messages` 对话；非流式返回 `choices`，流式返回 SSE 增量 |
| GET | `/api/v3/models` | 获取当前虚拟密钥可见的模型目录；返回 `object: "list"` 和 `data` 数组 |

使用平台签发给使用人或应用的虚拟密钥：

```http
Authorization: Bearer YOUR_VIRTUAL_KEY
Content-Type: application/json
```

将 `YOUR_VIRTUAL_KEY` 替换为完整虚拟密钥；`Content-Type` 用于 JSON 提交，GET 查询不需要请求体。不要填写火山账号 AK/SK 或上游渠道密钥。

模型目录的字段、可见范围和错误处理见[模型列表：通用模型目录与文本模型](models.md#models-text)。本页的目录入口与 `GET /v1/models` 返回相同的通用目录，也包含图片、视频和 3D 模型；提交文本对话时，只选 `native_endpoint_types` 不为 `null` 的模型 ID，筛选命令见[只列出文本模型](models.md#models-text-filter)。查询目录不发起生成，后续文本生成会消耗模型额度。

<a id="native-ark-text-h-17d044b5"></a>

## 完整请求示例

先准备 `request.json`，将 `MODEL_ID_FROM_CATALOG` 替换为当前目录返回的文本模型 ID：

```json
{
  "model": "MODEL_ID_FROM_CATALOG",
  "messages": [
    {"role": "user", "content": "用一句话介绍你自己"}
  ],
  "max_tokens": 1024,
  "stream": false
}
```

发送请求：

```bash
curl --request POST "https://platform.sgt.site/volcengine/api/v3/chat/completions" \
  --header "Authorization: Bearer YOUR_VIRTUAL_KEY" \
  --header "Content-Type: application/json" \
  --data-binary @request.json
```

| 字段 | 类型 | 用法 |
| --- | --- | --- |
| `model` | string | 当前密钥可调用的文本模型 ID，保留完整名称 |
| `messages` | object[] | 对话消息；最小请求可用一条 `role: "user"`、`content: "提示词"` |
| `max_tokens` | integer | 本次输出 token 上限，须符合目标模型限制 |
| `stream` | boolean | 省略或 `false` 时返回完整 JSON；`true` 时读取 SSE |

本页展示已支持的基础对话请求，不代表所有方舟 API 或型号特有参数都已开放。模型权限、额度和可用功能仍会在提交时检查。

<a id="native-ark-text-h-0db9af77"></a>

## 读取响应

非流式成功响应示例：

```json
{
  "id": "chatcmpl_example",
  "object": "chat.completion",
  "choices": [
    {
      "index": 0,
      "message": {"role": "assistant", "content": "我是一个帮助你完成任务的 AI 助手。"},
      "finish_reason": "stop"
    }
  ],
  "usage": {"prompt_tokens": 10, "completion_tokens": 20, "total_tokens": 30}
}
```

`choices[].message.content` 是生成文本；`finish_reason` 表示结束原因，输出达到限制时可能不是 `stop`。`usage` 是模型使用量，不是人民币金额。此文本接口直接返回生成结果，不创建可查询的媒体任务。

启用 `stream: true` 时，按 SSE 的 `data:` 事件读取 `choices[].delta` 并累积文本，不要把每个事件当成完整响应。连接断开时保留已收到内容和响应头 `X-Oneapi-Request-Id`，不要自动重复提交相同生成请求。

<a id="native-ark-text-h-2d982995"></a>

## Ark SDK 配置

| 配置项 | 值 | 说明 |
| --- | --- | --- |
| `base_url` | `https://platform.sgt.site/volcengine/api/v3` | SDK 自行追加 `/chat/completions`，不要再追加一次 `/api/v3` |
| `api_key` / `ARK_API_KEY` | 你的完整平台虚拟密钥 | 使用平台消费主体的调用凭证 |
| `max_retries` | `0` | 关闭客户端自动重试，由调用方处理失败与结果未知 |

现有接入验证使用官方 `volcengine-python-sdk 5.0.52` 的 `Ark` 客户端完成文本生成。客户端通过 `chat.completions.create` 传入 `model`、`messages` 等请求字段，读取返回的 `choices`；SDK 版本变化后仍需确认实际拼接路径。

<a id="native-ark-text-h-8184b44d"></a>

## 输出上限与失败处理

企业预算主体未指定 `max_tokens` 或 `max_completion_tokens` 时，平台会补入默认输出上限 `8192`，响应头 `X-Enterprise-Default-Output-Tokens` 给出实际值。需要不同上限时显式设置，并遵守目标模型的最大输出长度。

请求失败时同时检查 HTTP 状态和 `error` 正文：401 核对虚拟密钥，403 核对消费身份、模型授权和 IP 限制，400 核对字段与模型能力，429 按提示退避。生成超时或响应丢失不等于未产生用量，先保存请求标识供核对，不自动重复生成。