OpenAI-OpenAPI数据格式详解：JSON结构与字段说明

2026-02-05 04:04:14作者：翟江哲Frasier

你是否在使用OpenAI API时遇到过JSON数据解析错误？是否对API响应中的字段含义感到困惑？本文将详细解析OpenAI-OpenAPI的JSON数据格式，帮助你轻松理解和使用OpenAI API。读完本文后，你将能够：

掌握OpenAI API的基本JSON结构
理解常用字段的含义和用法
学会解析复杂的API响应数据
避免常见的数据格式错误

OpenAPI规范概述

OpenAI API基于OpenAPI 3.1.0规范构建，该规范定义了API的接口设计、数据格式和交互方式。OpenAPI规范使用YAML格式编写，位于项目根目录下的openapi.documented.yml文件中。

OpenAPI规范主要包含以下几个部分：

基本信息（info）：API的标题、描述、版本等
服务器配置（servers）：API的访问地址
安全机制（security）：API的认证方式
标签（tags）：API接口的分类
路径（paths）：API的具体接口定义
组件（components）：可复用的 schema 定义

基本JSON结构

OpenAI API的请求和响应数据都采用JSON格式。最基本的JSON结构包含以下几个部分：

请求JSON结构

{
  "model": "gpt-4o",
  "prompt": "Hello, world!",
  "max_tokens": 100,
  "temperature": 0.7
}

响应JSON结构

{
  "id": "cmpl-123456",
  "object": "text_completion",
  "created": 1627825464,
  "model": "gpt-4o",
  "choices": [
    {
      "text": "Hello! How can I assist you today?",
      "index": 0,
      "logprobs": null,
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 5,
    "completion_tokens": 9,
    "total_tokens": 14
  }
}

核心字段说明

通用字段

字段名	类型	描述
id	string	唯一标识符，用于追踪请求和响应
object	string	对象类型，如"text_completion"、"chat.completion"等
created	integer	创建时间戳，Unix时间格式
model	string	使用的模型名称

特定字段

Assistant对象

Assistant对象用于表示OpenAI的智能助手，包含以下主要字段：

{
  "id": "asst_abc123",
  "object": "assistant",
  "created_at": 1698982736,
  "name": "Coding Tutor",
  "description": null,
  "model": "gpt-4o",
  "instructions": "You are a helpful assistant designed to make me better at coding!",
  "tools": [],
  "tool_resources": {},
  "metadata": {},
  "top_p": 1.0,
  "temperature": 1.0,
  "response_format": "auto"
}

字段名	类型	描述
name	string	Assistant的名称
description	string	Assistant的描述信息
instructions	string	给Assistant的指令
tools	array	Assistant可以使用的工具列表
temperature	number	控制输出的随机性，0表示确定性，1表示最大随机性
top_p	number	控制输出的多样性，0表示只选择最可能的词，1表示考虑所有可能的词

列表响应对象

当API返回多个结果时，会使用列表响应对象：

{
  "object": "list",
  "data": [
    {
      "id": "asst_abc123",
      "object": "assistant",
      ...
    },
    ...
  ],
  "first_id": "asst_abc123",
  "last_id": "asst_abc789",
  "has_more": false
}

字段名	类型	描述
data	array	结果列表
first_id	string	第一个结果的ID
last_id	string	最后一个结果的ID
has_more	boolean	是否还有更多结果

常见接口数据格式

创建Assistant

请求：

{
  "instructions": "You are a personal math tutor. When asked a question, write and run Python code to answer the question.",
  "name": "Math Tutor",
  "tools": [{"type": "code_interpreter"}],
  "model": "gpt-4o"
}

响应：

{
  "id": "asst_abc123",
  "object": "assistant",
  "created_at": 1698984975,
  "name": "Math Tutor",
  "description": null,
  "model": "gpt-4o",
  "instructions": "You are a personal math tutor. When asked a question, write and run Python code to answer the question.",
  "tools": [
    {
      "type": "code_interpreter"
    }
  ],
  "metadata": {},
  "top_p": 1.0,
  "temperature": 1.0,
  "response_format": "auto"
}

列出Assistants

请求：

GET /v1/assistants?order=desc&limit=20

响应：

{
  "object": "list",
  "data": [
    {
      "id": "asst_abc123",
      "object": "assistant",
      "created_at": 1698982736,
      "name": "Coding Tutor",
      "description": null,
      "model": "gpt-4o",
      "instructions": "You are a helpful assistant designed to make me better at coding!",
      "tools": [],
      "tool_resources": {},
      "metadata": {},
      "top_p": 1.0,
      "temperature": 1.0,
      "response_format": "auto"
    },
    ...
  ],
  "first_id": "asst_abc123",
  "last_id": "asst_abc789",
  "has_more": false
}

数据交互流程

OpenAI API的典型数据交互流程如下：

sequenceDiagram
    participant 用户
    participant API
    participant 模型

    用户->>API: 发送请求(JSON格式)
    API->>模型: 处理请求
    模型->>API: 返回结果
    API->>用户: 返回响应(JSON格式)