> For the complete documentation index, see [llms.txt](https://nsclouds.gitbook.io/aillm.nscloud.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://nsclouds.gitbook.io/aillm.nscloud.ai/api-reference-cn/dui-hua-jie-kou/z.ai/responses.md).

# Responses

### 1. 概述

Z.AI 在当前环境中提供的 Responses 协议能力。

{% hint style="success" %}
本接口提供与 OpenAI Responses 兼容的请求路径。不同厂家和模型的实际参数支持范围可能不同。
{% endhint %}

**模型列表：**

* `glm-4.7`

### 2. 接口详情

## 创建 Responses 响应

> 提供与 OpenAI Responses 兼容的接口。具体支持的参数和行为因模型而异。

```json
{"openapi":"3.1.0","info":{"title":"NSCloud AI API 文档","version":"1.11.0"},"tags":[{"name":"responses_zai","description":"Z.AI 的 Responses 协议 API"}],"servers":[{"url":"https://aillm.nscloud.ai","description":"国际服务器"}],"security":[{"APIKeyHeader":[]}],"components":{"securitySchemes":{"APIKeyHeader":{"type":"http","scheme":"bearer","description":"使用 Bearer 令牌进行认证，格式：'Bearer YOUR_SECRET_TOKEN'"}},"schemas":{"CreateResponseRequest":{"type":"object","description":"Responses 协议请求体。","properties":{"model":{"type":"string","description":"要调用的模型 ID。"},"input":{"description":"输入内容，可以是纯文本，也可以是结构化输入数组。","oneOf":[{"type":"string","description":"纯文本输入。"},{"type":"array","description":"结构化输入数组。","items":{"$ref":"#/components/schemas/ResponseInputItem"}}]},"stream":{"type":"boolean","description":"是否以流式方式返回响应。","default":false}},"required":["model","input"],"additionalProperties":true},"ResponseInputItem":{"type":"object","description":"Responses 协议中的结构化输入项。","properties":{"type":{"type":"string","description":"输入项类型，例如 message。"},"role":{"type":"string","description":"输入项角色。"},"content":{"description":"输入内容，可以是纯文本，也可以是结构化内容片段数组。","oneOf":[{"type":"string","description":"纯文本输入。"},{"type":"array","description":"结构化内容片段数组。","items":{"$ref":"#/components/schemas/ResponseInputContentPart"}}]}},"additionalProperties":true},"ResponseInputContentPart":{"description":"Responses 协议输入内容片段。支持的输入类型包括 input_text、input_image 和 input_file。","oneOf":[{"$ref":"#/components/schemas/ResponseInputTextPart"},{"$ref":"#/components/schemas/ResponseInputImagePart"},{"$ref":"#/components/schemas/ResponseInputFilePart"}]},"ResponseInputTextPart":{"type":"object","description":"Responses 协议中的文本输入内容片段。","properties":{"type":{"type":"string","description":"输入片段类型。","enum":["input_text"]},"text":{"type":"string","description":"文本输入值。"}},"required":["type","text"],"additionalProperties":true},"ResponseInputImagePart":{"type":"object","description":"Responses 协议中的图片输入内容片段。支持 image_url 或 OpenAI 兼容的 file_id；当前推荐优先使用 image_url。可通过多个 input_image 片段传递多张图片。","properties":{"type":{"type":"string","description":"输入片段类型。","enum":["input_image"]},"image_url":{"type":"string","description":"可公开访问的图片 URL 或图片 data URL。支持常见图片格式，例如 data:image/png;base64,...。"},"file_id":{"type":"string","description":"OpenAI 兼容字段。预先上传的图片文件 ID，来源于 Files API；当前平台该能力建设中/适配中，实际可用性取决于文件托管和模型侧支持。"},"detail":{"type":"string","description":"支持时用于控制图片理解的细节等级。","default":"auto","enum":["auto","low","high"]}},"required":["type"],"anyOf":[{"required":["image_url"]},{"required":["file_id"]}],"additionalProperties":true},"ResponseInputFilePart":{"type":"object","description":"Responses 协议中的文件输入内容片段。支持 file_url、file_data 和 OpenAI 兼容的 file_id；当前推荐优先使用 file_url 或 file_data。支持常见文档和文本格式，PDF 仅为示例。","properties":{"type":{"type":"string","description":"输入片段类型。","enum":["input_file"]},"file_id":{"type":"string","description":"OpenAI 兼容字段。预先上传的文件 ID，来源于 Files API；当前平台该能力建设中/适配中，实际可用性取决于文件托管和模型侧支持。"},"file_url":{"type":"string","description":"用于文件输入的可公开访问文件 URL，当前推荐优先使用。支持常见文档和文本格式。"},"filename":{"type":"string","description":"以内联方式传递文件内容时使用的文件名。"},"file_data":{"type":"string","description":"以 data URL 形式传递的 base64 编码文件内容，当前推荐优先使用；例如 data:application/pdf;base64,... 或 data:text/plain;base64,..."}},"required":["type"],"anyOf":[{"required":["file_id"]},{"required":["file_url"]},{"required":["filename","file_data"]}],"additionalProperties":true},"ResponseObject":{"type":"object","description":"Responses 协议成功响应。","properties":{"id":{"type":"string","description":"响应唯一 ID。"},"object":{"type":"string","description":"对象类型，通常为 response。"},"model":{"type":"string","description":"实际使用的模型 ID。"},"status":{"type":"string","description":"响应处理状态，例如 completed、failed 或 incomplete。"},"created_at":{"type":"integer","description":"响应创建时间戳（Unix 秒）。"},"output_text":{"type":"string","description":"从 output 内容聚合出的便捷文本输出。"},"output":{"type":"array","description":"生成结果列表，可能包含消息、工具调用、reasoning 或其他结构化记录。","items":{"$ref":"#/components/schemas/ResponseOutputItem"}},"error":{"type":["object","null"],"description":"响应生成失败时的错误信息。","additionalProperties":true},"incomplete_details":{"type":["object","null"],"description":"响应未完成时的原因详情。","additionalProperties":true},"usage":{"$ref":"#/components/schemas/Usage"}},"additionalProperties":true},"ResponseOutputItem":{"type":"object","description":"Responses 输出数组中的单项。","properties":{"id":{"type":"string","description":"输出项唯一 ID。"},"type":{"type":"string","description":"输出项类型，例如 message、tool_call。"},"role":{"type":"string","description":"输出项关联角色。"},"status":{"type":"string","description":"输出项处理状态。"},"content":{"type":"array","description":"结构化输出内容片段。","items":{"$ref":"#/components/schemas/ResponseContentPart"}}},"additionalProperties":true},"ResponseContentPart":{"type":"object","description":"Responses 输出项中使用的宽松内容片段结构。","properties":{"type":{"type":"string","description":"输出片段类型，例如 output_text 或 tool_result。"},"text":{"type":"string","description":"内容片段中的文本值。"},"annotations":{"type":"array","description":"附加在内容片段上的可选标注信息。","items":{"type":"object","additionalProperties":true}}},"additionalProperties":true},"Usage":{"type":"object","description":"Token 使用量统计。","properties":{"prompt_tokens":{"type":"integer","description":"输入消耗的 token 数。"},"completion_tokens":{"type":"integer","description":"输出消耗的 token 数。"},"total_tokens":{"type":"integer","description":"总 token 数。"},"input_tokens":{"type":"integer","description":"输入消耗的 token 数，部分协议使用该字段。"},"output_tokens":{"type":"integer","description":"输出消耗的 token 数，部分协议使用该字段。"},"completion_tokens_details":{"type":"object","description":"输出 token 使用明细。","properties":{"reasoning_tokens":{"type":"integer","description":"推理类输出消耗的 token 数。"}},"additionalProperties":true},"input_tokens_details":{"type":"object","description":"输入 token 使用明细。","properties":{"text_tokens":{"type":"integer","description":"文本输入消耗的 token 数。"},"image_tokens":{"type":"integer","description":"图片输入消耗的 token 数。"}},"additionalProperties":true}}},"ErrorResponse":{"type":"object","description":"错误响应。","properties":{"error":{"$ref":"#/components/schemas/ErrorDetail"}}},"ErrorDetail":{"type":"object","description":"错误详情对象。","properties":{"message":{"type":"string","description":"错误说明。"},"type":{"type":"string","description":"错误类型。"},"param":{"description":"与错误相关的参数名。","type":["string","null"]},"code":{"description":"错误码。","type":["string","null"]}}}},"responses":{"ErrorResponse":{"description":"错误响应","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/v1/responses":{"post":{"tags":["responses_zai"],"summary":"创建 Responses 响应","description":"提供与 OpenAI Responses 兼容的接口。具体支持的参数和行为因模型而异。","operationId":"createResponse_zai","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateResponseRequest"}}}},"responses":{"200":{"description":"成功响应","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseObject"}},"text/event-stream":{"schema":{"type":"string","description":"Responses 流式返回使用 Server-Sent Events，并携带带类型的语义化事件。"}}}},"400":{"$ref":"#/components/responses/ErrorResponse"},"401":{"$ref":"#/components/responses/ErrorResponse"},"429":{"$ref":"#/components/responses/ErrorResponse"}}}}}}
```