字段与用途

字段路径位置类型必填填写规则与说明允许值 / 约束示例
id响应 JSONstring否响应字符串标识，用于日志关联；本目录不提供按该 ID 查询聊天任务的工作流。--
choices响应 JSONarray否候选数组。非流读取 message.content / tool_calls，finish_reason 表示 stop / length / tool_calls / content_filter 等原因。不要假定 content 始终为非空字符串。--
choices[]响应 JSONobject否数组元素。--
choices[].index响应 JSONinteger否---
choices[].message响应 JSONobject否---
choices[].message.role响应 JSONstring是消息角色可选：system / user / assistant / tool / developer-
choices[].message.content响应 JSONstringarray<object>是消息内容分支：string / array<object>
choices[].message.content（分支1）响应 JSONstring否按此分支填写。-
choices[].message.content（分支2）响应 JSONarray<object>否按此分支填写。-
choices[].message.content（分支2）[]响应 JSONobject否数组元素。--
choices[].message.content（分支2）[].type响应 JSONstring否-可选：text / image_url / input_audio / file / video_url-
choices[].message.content（分支2）[].text响应 JSONstring否---
choices[].message.content（分支2）[].image_url响应 JSONobject否---
choices[].message.content（分支2）[].image_url.url响应 JSONstring否图片 URL 或 base64--
choices[].message.content（分支2）[].image_url.detail响应 JSONstring否-可选：low / high / auto-
choices[].message.content（分支2）[].input_audio响应 JSONobject否---
choices[].message.content（分支2）[].input_audio.data响应 JSONstring否Base64 编码的音频数据--
choices[].message.content（分支2）[].input_audio.format响应 JSONstring否-可选：wav / mp3-
choices[].message.content（分支2）[].file响应 JSONobject否---
choices[].message.content（分支2）[].file.filename响应 JSONstring否---
choices[].message.content（分支2）[].file.file_data响应 JSONstring否---
choices[].message.content（分支2）[].file.file_id响应 JSONstring否---
choices[].message.content（分支2）[].video_url响应 JSONobject否---
choices[].message.content（分支2）[].video_url.url响应 JSONstring否---
choices[].message.name响应 JSONstring否发送者名称--
choices[].message.tool_calls响应 JSONarray<object>否---
choices[].message.tool_calls[]响应 JSONobject否数组元素。--
choices[].message.tool_calls[].id响应 JSONstring否---
choices[].message.tool_calls[].type响应 JSONstring否---
choices[].message.tool_calls[].function响应 JSONobject否---
choices[].message.tool_calls[].function.name响应 JSONstring否---
choices[].message.tool_calls[].function.arguments响应 JSONstring否---
choices[].message.tool_call_id响应 JSONstring否工具调用 ID（用于 tool 角色消息）--
choices[].message.reasoning_content响应 JSONstring否推理内容--
choices[].finish_reason响应 JSONstring否-可选：stop / length / tool_calls / content_filter-
usage响应 JSONobject否用量对象，可能因协议/流式缺失。prompt_tokens / completion_tokens / total_tokens；推理详情按模型返回。--
usage.prompt_tokens响应 JSONinteger否提示词 Token 数--
usage.completion_tokens响应 JSONinteger否补全 Token 数--
usage.total_tokens响应 JSONinteger否总 Token 数--
usage.prompt_tokens_details响应 JSONobject否---
usage.prompt_tokens_details.cached_tokens响应 JSONinteger否---
usage.prompt_tokens_details.text_tokens响应 JSONinteger否---
usage.prompt_tokens_details.audio_tokens响应 JSONinteger否---
usage.prompt_tokens_details.image_tokens响应 JSONinteger否---
usage.completion_tokens_details响应 JSONobject否---
usage.completion_tokens_details.text_tokens响应 JSONinteger否---
usage.completion_tokens_details.audio_tokens响应 JSONinteger否---
usage.completion_tokens_details.reasoning_tokens响应 JSONinteger否---

读取所有 choices，按 index 区分候选。finish_reason=length 表示截断，不能把残缺 JSON 或工具参数当作完整结果；拒绝内容和空 content 也应单独处理。

结构示意

{"id":"chatcmpl-example","object":"chat.completion","model":"gpt-6-astra","choices":[{"index":0,"message":{"role":"assistant","content":"这是结构示意。"},"finish_reason":"stop"}]}

此合成示意不保证所有可选字段存在。保存原始对象，业务层再提取需要的文字。

调用示例与参考

查看完整三语言调用。OpenAI 公共 API 规范。

常见错误

401：检查本站 API Key 和 Bearer 格式；403：确认此 Key 可用该模型；429：遵循 Retry-After 退避。超时或 5xx 时保留请求标识和脱敏错误，避免盲目重发；其他通用排查见聊天接入总览。