# 生成文本API文档

本文件介绍本平台 Chat Completions、Responses、流式文本、JSON 输出和结果保存，可交给 AI 编程助手完成接入。

## 接入前准备

- API 接入地址：`https://geekapi.net`，本文中的接口地址已按下载站点填写。
- 将 `sk-你的令牌` 替换为“接入密钥”页面显示的完整密钥。
- 从当前模型列表复制文本模型的 `name`。下面示例使用 `gpt-5.6-sol`，接口格式及可选能力仍须与所选模型一致。

```bash
curl 'https://geekapi.net/api/platform/model-catalog?scope=enabled' \
  -H 'Authorization: Bearer sk-你的令牌'
```

请让 AI 编程助手先阅读你的项目，复用现有配置、请求和消息列表实现。密钥由接入方配置，不要写入源码、日志或公开网页。

## Chat Completions

适合对话、单轮生成及兼容 OpenAI 的客户端：

```http
POST /v1/chat/completions
Authorization: Bearer sk-你的令牌
Content-Type: application/json
```

```bash
curl https://geekapi.net/v1/chat/completions \
  -H 'Authorization: Bearer sk-你的令牌' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gpt-5.6-sol",
    "messages": [
      { "role": "system", "content": "你是一个简洁、可靠的业务助手。" },
      { "role": "user", "content": "用一句话介绍本平台 API。" }
    ],
    "stream": false
  }'
```

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `model` | string | 必填，平台公开文本模型值。 |
| `messages` | array | 必填，对话消息列表。 |
| `role` | string | 消息角色，如 `system`、`user`、`assistant`、`tool`。 |
| `content` | string 或 array | 消息内容，多模态输入须符合模型能力。 |
| `stream` | boolean | 是否使用 SSE 流式输出。 |
| `temperature`、`top_p` | number | 可选采样参数，是否支持由模型决定。 |
| `max_tokens` | number | 可选输出长度限制，是否支持由模型决定。 |
| `tools`、`tool_choice` | array / string / object | 可选工具定义与选择策略，由模型支持情况决定。 |
| `response_format` | object | 可选 JSON 输出约束，由模型支持情况决定。 |

非流式成功结果通常为：

```json
{
  "id": "chatcmpl_xxx",
  "object": "chat.completion",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "这是一段生成的文本。" },
      "finish_reason": "stop"
    }
  ]
}
```

读取 `choices[0].message.content`；若返回工具调用，则执行接入方允许的工具，并按消息协议继续对话，不要把工具调用当作普通文本。多轮对话需要提交必要的历史消息。

## Responses

所选模型支持 Responses 时可使用：

```bash
curl https://geekapi.net/v1/responses \
  -H 'Authorization: Bearer sk-你的令牌' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gpt-5.6-sol",
    "instructions": "你是一个简洁、可靠的业务助手。",
    "input": "用一句话介绍本平台 API。",
    "stream": false
  }'
```

常用字段包括 `model`、`input`、`instructions`、`max_output_tokens`、`stream`、`tools`、`tool_choice` 和用于续接会话的 `previous_response_id`。支持范围以模型为准。

原始 HTTP JSON 响应从 `output[]` 中查找 `type=message` 的条目，再收集其 `content[]` 中 `type=output_text` 的 `text`；不要假设所有 HTTP 响应都提供 SDK 的 `output_text` 便捷属性。

## 流式文本

将请求中的 `stream` 设置为 `true`。curl 可加 `-N` 关闭输出缓冲：

```bash
curl -N https://geekapi.net/v1/chat/completions \
  -H 'Authorization: Bearer sk-你的令牌' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gpt-5.6-sol",
    "messages": [{ "role": "user", "content": "写一段简短的产品介绍。" }],
    "stream": true
  }'
```

响应为 `text/event-stream`。Chat Completions 按 SSE 事件解析 `data:`，逐段追加 `choices[].delta.content`，遇到 `[DONE]` 结束。Responses 使用自己的事件类型，例如 `response.output_text.delta` 和 `response.completed`，不能套用 Chat 的解析字段。

网络读取的单个数据块不等于完整 SSE 事件；客户端必须缓存尚未结束的事件，再解析 JSON。中途断线时显示已生成内容和中断状态，不要悄悄重复生成并覆盖结果。

## JSON 输出

支持 JSON 模式的 Chat 模型可在请求中加入：

```json
{
  "response_format": { "type": "json_object" }
}
```

同时在提示词说明所需字段，并在接入方业务中解析与校验 JSON。工具调用、JSON Schema 和多模态能力并非所有模型都支持。

## 保存文本与错误处理

非流式请求可用 `curl ... -o response.json` 保存完整响应；若需要下载 `.txt`，应提取最终文本后以 UTF-8 保存。流式请求应拼接文本增量后再保存，不要把 SSE 原始事件直接当作正文。

`400` 检查模型、消息结构和能力参数，`401` 检查完整密钥，`402` 检查余额，`429` 降低频率。请求超时或 `5xx` 时提示失败原因并由接入方决定是否重试，避免无限重发造成重复生成。

文本同步或 SSE 接口不使用视频任务 ID、状态轮询或视频回调字段。