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

# OpenAI 多模态响应接口

> 统一的多模态响应接口，支持 JSON mode、工具序列与图文混合。

`POST /v1/responses` 是 OpenAI 新一代的统一接口，能在一次请求中混合文本、图像等类型的输入，并以结构化格式返回结果。

## 请求示例

```bash theme={null}
curl -X POST "https://api.gregapi.com/v1/responses" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4.1",
    "input": [
      {
        "role": "user",
        "content": [
          {"type": "text", "text": "请总结附件要点"}
        ]
      }
    ],
    "response_format": {"type": "json_schema"}
  }'
```

## 流式与兼容

* 流式输出：设置 `stream: true` 可获得服务端事件（SSE）增量；需要兼容 Chat Completions 流格式时，可在 SSE 客户端侧做转换（GregAPI 已内置向后兼容处理）。
* 工具事件：在流中会以 `response.output_item.added` 体现工具调用；结束时携带 `usage` 聚合令牌统计。

## 技巧与注意事项

* `input` 字段可以是字符串或复合数组，推荐使用数组以便在其中混合文本、图像、文件引用等内容。
* 对话历史可通过继续在 `input` 中添加多轮 `role`/`content` 分段。
* `response_format` 支持 `json_schema`、`text` 等选项；结合 GregAPI 的流控策略，可实现结构化自动化处理。
* 若需要工具调用，请在 `tools` 中声明可选函数，返回结果将出现在 `output` 的 `tool_calls` 字段里。
* 费用提示：当启用 Web Search Preview、Code Interpreter、File Search 等工具时，GregAPI 会在 `usage` 中附加额外计费元数据用于对账。


## OpenAPI

````yaml openapi/llm.yaml POST /v1/responses
openapi: 3.0.3
info:
  title: GregAPI 大语言模型
  version: 1.0.0
  description: GregAPI 统一网关下的大语言模型（LLM）接口，覆盖通用对话补全、多模态响应，以及各家原生消息与生成协议。
servers:
  - url: https://api.gregapi.com
security:
  - bearerAuth: []
paths:
  /v1/responses:
    post:
      summary: OpenAI 多模态响应接口
      description: 统一的多模态响应接口，可在一次请求中混合文本、图像等输入，并以结构化格式返回，支持 JSON mode 与工具序列。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - model
              properties:
                model:
                  type: string
                  description: 模型名称
                input:
                  type: array
                  description: 输入消息，可为字符串或复合数组
                response_format:
                  type: object
                  description: 输出格式
                stream:
                  type: boolean
                  description: 是否流式输出
                tools:
                  type: array
                  description: 可选工具声明
            example:
              model: gpt-4.1
              input:
                - role: user
                  content:
                    - type: text
                      text: 请总结附件要点
              response_format:
                type: json_schema
      responses:
        '200':
          description: 成功返回结构化响应结果
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.