newAPI

东东海2025-05-022025-06-25

中继接口 API 文档

本文档描述了 New API 的中继接口，用于调用各种 AI 模型和相关服务。

接口列表

聊天 (Chat)

OpenAI 格式 (Chat Completions)

官方文档: OpenAI Chat

📝 简介:

给定一组包含对话的消息列表,模型将返回一个响应。相关指南可参阅 OpenAI 官网:Chat Completions

💡 请求示例:

基础文本对话 ✅

curl https://你的newapi服务器地址/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $NEWAPI_API_KEY" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      { "role": "system", "content": "你是一个有帮助的助手。" },
      { "role": "user", "content": "你好!" }
    ]
  }'

响应示例:

{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "gpt-4o-mini",
  "system_fingerprint": "fp_44709d6fcb",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "你好!我很高兴能帮助你。请问有什么我可以协助你的吗?"
    },
    "logprobs": null,
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 9,
    "completion_tokens": 12,
    "total_tokens": 21
  }
}

图像分析对话 ✅

curl https://你的newapi服务器地址/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $NEWAPI_API_KEY" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {
        "role": "user",
        "content": [
          { "type": "text", "text": "这张图片里有什么?" },
          { "type": "image_url", "image_url": { "url": "https://example.com/image.jpg" } }
        ]
      }
    ],
    "max_tokens": 300
  }'

响应示例:

{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "gpt-4o-mini",
  "system_fingerprint": "fp_44709d6fcb",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "这张图片展示了一条木制栈道穿过茂密的绿色湿地。栈道似乎延伸到远处,两旁是郁郁葱葱的植被。"
    },
    "logprobs": null,
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 9,
    "completion_tokens": 12,
    "total_tokens": 21
  }
}

流式响应 ✅

curl https://你的newapi服务器地址/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $NEWAPI_API_KEY" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      { "role": "user", "content": "讲个故事" }
    ],
    "stream": true
  }'

流式响应示例:

{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-4o-mini","system_fingerprint":"fp_44709d6fcb","choices":[{"index":0,"delta":{"role":"assistant","content":""},"logprobs":null,"finish_reason":null}]}
{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-4o-mini","system_fingerprint":"fp_44709d6fcb","choices":[{"index":0,"delta":{"content":"从前"},"logprobs":null,"finish_reason":null}]}
{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-4o-mini","system_fingerprint":"fp_44709d6fcb","choices":[{"index":0,"delta":{"content":"有一只"},"logprobs":null,"finish_reason":null}]}
{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-4o-mini","system_fingerprint":"fp_44709d6fcb","choices":[{"index":0,"delta":{"content":"小兔子"},"logprobs":null,"finish_reason":null}]}
// ... 更多数据块 ...
{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-4o-mini","system_fingerprint":"fp_44709d6fcb","choices":[{"index":0,"delta":{},"logprobs":null,"finish_reason":"stop"}]}

函数调用 ✅

curl https://你的newapi服务器地址/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $NEWAPI_API_KEY" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      { "role": "user", "content": "北京今天的天气怎么样?" }
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_weather",
          "description": "获取指定位置的当前天气",
          "parameters": {
            "type": "object",
            "properties": {
              "location": { "type": "string", "description": "城市名称,如: 北京" },
              "unit": { "type": "string", "enum": ["celsius", "fahrenheit"] }
            },
            "required": ["location"]
          }
        }
      }
    ],
    "tool_choice": "auto"
  }'

响应示例:

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1699896916,
  "model": "gpt-4o-mini",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": null,
        "tool_calls": [
          {
            "id": "call_abc123",
            "type": "function",
            "function": {
              "name": "get_weather",
              "arguments": "{\"location\": \"北京\", \"unit\": \"celsius\"}"
            }
          }
        ]
      },
      "logprobs": null,
      "finish_reason": "tool_calls"
    }
  ],
  "usage": {
    "prompt_tokens": 82,
    "completion_tokens": 17,
    "total_tokens": 99
  }
}

JSON 模式输出 ✅

curl https://你的newapi服务器地址/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $NEWAPI_API_KEY" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      { "role": "system", "content": "你是一个JSON助手,请以JSON格式回复。" },
      { "role": "user", "content": "给我一个用户信息示例" }
    ],
    "response_format": { "type": "json_object" }
  }'

响应示例:

{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "gpt-4o-mini",
  "system_fingerprint": "fp_44709d6fcb",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "{\"user\":{\"id\":1,\"name\":\"张三\",\"age\":28,\"email\":\"[email protected]\",\"interests\":[\"读书\",\"旅游\",\"摄影\"]}}"
    },
    "logprobs": null,
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 15,
    "total_tokens": 25
  }
}

📮 请求:

端点:

1	POST /v1/chat/completions

创建给定聊天对话的模型响应。更多详情请参阅文本生成、视觉和音频指南。

鉴权方法:

在请求头中包含以下内容进行 API 密钥认证:

1	Authorization: Bearer $NEWAPI_API_KEY

其中 $NEWAPI_API_KEY 是您的 API 密钥。您可以在 OpenAI 平台的 API 密钥页面中找到或生成 API 密钥。

请求体参数:

messages
- 类型: 数组
- 必需: 是
- 到目前为止包含对话的消息列表。根据使用的模型,支持不同的消息类型(形式),如文本、图像和音频。
model
- 类型: 字符串
- 必需: 是
- 要使用的模型 ID。有关哪些模型适用于 Chat API 的详细信息,请参阅模型端点兼容性表。
store
- 类型: 布尔值或 null
- 必需: 否
- 默认值: false
- 是否存储此聊天补全请求的输出以用于我们的模型蒸馏或评估产品。
reasoning_effort
- 类型: 字符串或 null
- 必需: 否
- 默认值: medium
- 仅适用于 o1 和 o3-mini 模型
- 约束推理模型的推理工作。当前支持的值为 low、medium 和 high。减少推理工作可以加快响应速度并减少响应中用于推理的标记数。
metadata
- 类型: map
- 必需: 否
- 可以附加到对象的 16 个键值对集合。这对于以结构化格式存储对象的其他信息很有用,并可以通过 API 或仪表板查询对象。
- 键是最大长度为 64 个字符的字符串。值是最大长度为 512 个字符的字符串。
modalities
- 类型: 数组或 null
- 必需: 否
- 您希望模型为此请求生成的输出类型。大多数模型都能生成文本,这是默认设置: [“text”]
- 该模型还可以用于生成音频。要请求此模型同时生成文本和音频响应,您可以使用: [“text”, “audio”]
prediction
- 类型: 对象
- 必需: 否
- 预测输出的配置,当提前知道模型响应的大部分内容时,可以大大提高响应时间。这在您只对文件进行微小更改时最常见。
audio
- 类型: 对象或 null
- 必需: 否
- 音频输出的参数。当使用 modalities: [“audio”] 请求音频输出时需要。
temperature
- 类型: 数字或 null
- 必需: 否
- 默认值: 1
- 要使用的采样温度,介于 0 和 2 之间。较高的值(如 0.8)会使输出更加随机,而较低的值(如 0.2)会使其更加集中和确定性。我们通常建议更改此值或 top_p,但不要同时更改。
top_p
- 类型: 数字或 null
- 必需: 否
- 默认值: 1
- 一种替代采样温度的方法,称为核采样,其中模型考虑具有 top_p 概率质量的标记结果。因此,0.1 意味着只考虑包含前 10% 概率质量的标记。
- 我们通常建议更改此值或 temperature,但不要同时更改。
n
- 类型: 整数或 null
- 必需: 否
- 默认值: 1
- 为每个输入消息生成多少个聊天补全选择。请注意,您将根据所有选择生成的标记数量收费。保持 n 为 1 可最大限度地降低成本。
stop
- 类型: 字符串/数组/null
- 必需: 否
- 默认值: null
- API 将停止生成更多标记的最多 4 个序列。
max_tokens
- 类型: 整数或 null
- 必需: 否
- 聊天补全中可以生成的最大标记数。此值可用于控制通过 API 生成的文本成本。
- 该值现已弃用,取而代之的是 max_completion_tokens,并且与 o1 系列模型不兼容。
presence_penalty
- 类型: 数字或 null
- 必需: 否
- 默认值: 0
- 介于 -2.0 和 2.0 之间的数字。正值根据新标记到目前为止在文本中出现的情况来惩罚它们,从而增加模型讨论新主题的可能性。
frequency_penalty
- 类型: 数字或 null
- 必需: 否
- 默认值: 0
- 介于 -2.0 和 2.0 之间的数字。正值根据新标记到目前为止在文本中的现有频率来惩罚它们,从而降低模型逐字重复同一行的可能性。
logit_bias
- 类型: map
- 必需: 否
- 默认值: null
- 修改指定标记出现在补全中的可能性。
- 接受一个 JSON 对象,该对象将标记(由分词器中的标记 ID 指定)映射到从 -100 到 100 的关联偏差值。在数学上,偏差被添加到模型在采样之前生成的对数中。确切的效果会因模型而异,但介于 -1 和 1 之间的值应该会减少或增加选择的可能性;像 -100 或 100 这样的值应该导致相关标记被禁止或独占选择。
user
- 类型: 字符串
- 必需: 否
- 表示最终用户的唯一标识符,可以帮助 OpenAI 监控和检测滥用行为。了解更多。
service_tier
- 类型: 字符串或 null
- 必需: 否
- 默认值: auto
- 指定用于处理请求的延迟层级。此参数与订阅了 scale tier 服务的客户相关:
  - 如果设置为 ‘auto’,且项目启用了 Scale tier,系统将使用 scale tier 信用直到用完
  - 如果设置为 ‘auto’,且项目未启用 Scale tier,请求将使用默认服务层级处理,具有较低的正常运行时间 SLA 且无延迟保证
  - 如果设置为 ‘default’,请求将使用默认服务层级处理,具有较低的正常运行时间 SLA 且无延迟保证
  - 未设置时,默认行为为 ‘auto’
stream_options
- 类型: 对象或 null
- 必需: 否
- 默认值: null
- 流式响应的选项。仅在设置 stream: true 时使用。
response_format
- 类型: 对象
- 必需: 否
- 指定模型必须输出的格式。
- 设置为 { “type”: “json_schema”, “json_schema”: {…} } 启用结构化输出,确保模型将匹配您提供的 JSON schema。
- 设置为 { “type”: “json_object” } 启用 JSON 模式,确保模型生成的消息是有效的 JSON。
- 重要提示:使用 JSON 模式时,您还必须通过系统或用户消息自行指示模型生成 JSON。否则,模型可能会生成无尽的空白直到生成达到令牌限制。
seed
- 类型: 整数或 null
- 必需: 否
- Beta 功能。如果指定,我们的系统将尽最大努力进行确定性采样,使得具有相同 seed 和参数的重复请求应返回相同的结果。不保证确定性,您应参考响应参数以监控后端的变化。
tools
- 类型: 数组
- 必需: 否
- 模型可能调用的工具列表。目前仅支持函数作为工具。使用此参数提供模型可能生成 JSON 输入的函数列表。最多支持 128 个函数。
tool_choice
- 类型: 字符串或对象
- 必需: 否
- 控制模型调用哪个工具(如果有):
  - none: 模型不会调用任何工具,而是生成消息
  - auto: 模型可以在生成消息或调用一个或多个工具之间选择
  - required: 模型必须调用一个或多个工具
  - {“type”: “function”, “function”: {“name”: “my_function”}}: 强制模型调用特定工具
- 当没有工具时默认为 none,有工具时默认为 auto。
parallel_tool_calls
- 类型: 布尔值
- 必需: 否
- 默认值: true
- 是否在工具使用期间启用并行函数调用。

📥 响应:

成功响应:

返回一个聊天补全对象,如果请求被流式传输,则返回聊天补全块对象的流式序列。

id
- 类型: 字符串
- 说明: 响应的唯一标识符
object
- 类型: 字符串
- 说明: 对象类型,值为 “chat.completion”
created
- 类型: 整数
- 说明: 响应创建时间戳
model
- 类型: 字符串
- 说明: 使用的模型名称
system_fingerprint
- 类型: 字符串
- 说明: 系统指纹标识符
choices
- 类型: 数组
- 说明: 包含生成的回复选项
- 属性:
  - index: 选项索引
  - message: 包含角色和内容的消息对象
  - logprobs: 日志概率信息
  - finish_reason: 完成原因
usage
- 类型: 对象
- 说明: token 使用统计
- 属性:
  - prompt_tokens: 提示使用的 token 数
  - completion_tokens: 补全使用的 token 数
  - total_tokens: 总 token 数
  - completion_tokens_details: token 详细信息

Anthropic 格式 (Messages)

官方文档:

Anthropic Messages
Anthropic Streaming Messages

📝 简介:

给定一组包含文本和/或图像内容的结构化输入消息列表,模型将生成对话中的下一条消息。Messages API 可用于单次查询或无状态的多轮对话。

💡 请求示例:

基础文本对话 ✅

curl https://你的newapi服务器地址/v1/messages \
  --header "anthropic-version: 2023-06-01" \
  --header "content-type: application/json" \
  --header "x-api-key: $NEWAPI_API_KEY" \
  --data \
  '{
    "model": "claude-3-5-sonnet-20241022",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Hello, world"}
    ]
  }'

响应示例:

{
  "content": [
    {
      "text": "Hi! My name is Claude.",
      "type": "text"
    }
  ],
  "id": "msg_013Zva2CMHLNnXjNJKqJ2EF",
  "model": "claude-3-5-sonnet-20241022",
  "role": "assistant",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "type": "message",
  "usage": {
    "input_tokens": 2095,
    "output_tokens": 503
  }
}

图像分析对话 ✅

curl https://你的newapi服务器地址/v1/messages \
  --header "anthropic-version: 2023-06-01" \
  --header "content-type: application/json" \
  --header "x-api-key: $NEWAPI_API_KEY" \
  --data \
  '{
    "model": "claude-3-5-sonnet-20241022",
    "messages": [
      {
        "role": "user",
        "content": [
          { "type": "image", "source": { "type": "base64", "media_type": "image/jpeg", "data": "/9j/4AAQSkZJRg..." } },
          { "type": "text", "text": "这张图片里有什么?" }
        ]
      }
    ]
  }'

响应示例:

{
  "content": [
    {
      "text": "这张图片显示了一只橙色的猫咪正在窗台上晒太阳。猫咪看起来很放松,眯着眼睛享受阳光。窗外可以看到一些绿色的植物。",
      "type": "text"
    }
  ],
  "id": "msg_013Zva2CMHLNnXjNJKqJ2EF",
  "model": "claude-3-5-sonnet-20241022",
  "role": "assistant",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "type": "message",
  "usage": {
    "input_tokens": 3050,
    "output_tokens": 892
  }
}

工具调用 ✅

curl https://你的newapi服务器地址/v1/messages \
  --header "anthropic-version: 2023-06-01" \
  --header "content-type: application/json" \
  --header "x-api-key: $NEWAPI_API_KEY" \
  --data \
  '{
    "model": "claude-3-5-sonnet-20241022",
    "messages": [
      { "role": "user", "content": "今天北京的天气怎么样?" }
    ],
    "tools": [
      {
        "name": "get_weather",
        "description": "获取指定位置的当前天气",
        "input_schema": {
          "type": "object",
          "properties": {
            "location": { "type": "string", "description": "城市名称,如:北京" }
          },
          "required": ["location"]
        }
      }
    ]
  }'

响应示例:

{
  "content": [
    {
      "type": "tool_use",
      "id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV",
      "name": "get_weather",
      "input": { "location": "北京" }
    }
  ],
  "id": "msg_013Zva2CMHLNnXjNJKqJ2EF",
  "model": "claude-3-5-sonnet-20241022",
  "role": "assistant",
  "stop_reason": "tool_use",
  "stop_sequence": null,
  "type": "message",
  "usage": {
    "input_tokens": 2156,
    "output_tokens": 468
  }
}

流式响应 ✅

curl https://你的newapi服务器地址/v1/messages \
  --header "anthropic-version: 2023-06-01" \
  --header "content-type: application/json" \
  --header "x-api-key: $NEWAPI_API_KEY" \
  --data \
  '{
    "model": "claude-3-5-sonnet-20241022",
    "messages": [
      { "role": "user", "content": "讲个故事" }
    ],
    "stream": true
  }'

响应示例:

{ "type": "message_start", "message": { "id": "msg_013Zva2CMHLNnXjNJKqJ2EF", "model": "claude-3-5-sonnet-20241022", "role": "assistant", "type": "message" } }
{ "type": "content_block_start", "index": 0, "content_block": { "type": "text" } }
{ "type": "content_block_delta", "index": 0, "delta": { "text": "从前" } }
{ "type": "content_block_delta", "index": 0, "delta": { "text": "有一只" } }
{ "type": "content_block_delta", "index": 0, "delta": { "text": "小兔子..." } }
{ "type": "content_block_stop", "index": 0 }
{ "type": "message_delta", "delta": { "stop_reason": "end_turn", "usage": { "input_tokens": 2045, "output_tokens": 628 } } }
{ "type": "message_stop" }

📮 请求:

端点:

1	POST /v1/messages

鉴权方法:

在请求头中包含以下内容进行 API 密钥认证:

1	x-api-key: $NEWAPI_API_KEY

其中 $NEWAPI_API_KEY 是您的 API 密钥。您可以通过控制台获取 API 密钥,每个密钥仅限于一个工作区使用。

请求头参数:

anthropic-beta
- 类型: 字符串
- 必需: 否
- 指定要使用的 beta 版本,支持用逗号分隔的列表如 beta1,beta2,或多次指定该请求头。
anthropic-version
- 类型: 字符串
- 必需: 是
- 指定要使用的 API 版本。

请求体参数:

max_tokens
- 类型: 整数
- 必需: 是
- 生成的最大 token 数量。不同模型有不同的限制,详见模型文档。范围 x > 1。

messages

类型: 对象数组
必需: 是
输入消息列表。模型被训练为在用户和助手之间交替进行对话。创建新消息时,您可以使用 messages 参数指定之前的对话轮次,模型将生成对话中的下一条消息。连续的用户或助手消息会被合并为单个轮次。
每个消息必须包含 role 和 content 字段。您可以指定单个用户角色消息,或包含多个用户和助手消息。如果最后一条消息使用助手角色,响应内容将直接从该消息的内容继续,这可以用来约束模型的响应。

单条用户消息示例:

1	[{"role": "user", "content": "Hello, Claude"}]

多轮对话示例:

[ {"role": "user", "content": "你好。"}, {"role": "assistant", "content": "你好!我是 Claude。有什么可以帮你的吗?"}, {"role": "user", "content": "请用简单的话解释什么是 LLM?"} ]

部分填充的响应示例:

1	[ {"role": "user", "content": "太阳的希腊语名字是什么? (A) Sol (B) Helios (C) Sun"}, {"role": "assistant", "content": "正确答案是 ("} ]

每个消息的 content 可以是字符串或内容块数组。使用字符串相当于一个 “text” 类型的内容块数组的简写。以下两种写法等效:
1
{"role": "user", "content": "Hello, Claude"}
1
{ "role": "user", "content": [{"type": "text", "text": "Hello, Claude"}] }

从 Claude 3 模型开始,您还可以发送图片内容块:

{ "role": "user", "content": [ { "type": "image", "source": { "type": "base64", "media_type": "image/jpeg", "data": "/9j/4AAQSkZJRg..." } }, { "type": "text", "text": "这张图片里有什么?" } ] }

目前支持的图片格式包括: base64, image/jpeg、image/png、image/gif 和 image/webp。
messages.role
- 类型: 枚举字符串
- 必需: 是
- 可选值: user, assistant
- 注意: Messages API 中没有 “system” 角色,如果需要系统提示,请使用顶层的 system 参数。

messages.content

类型: 字符串或对象数组
必需: 是
消息内容可以是以下几种类型之一:

文本内容 (Text)

{
  "type": "text", // 必需,枚举值: "text"
  "text": "Hello, Claude", // 必需,最小长度: 1
  "cache_control": {
    "type": "ephemeral" // 可选,枚举值: "ephemeral"
  }
}

图片内容 (Image)

{
  "type": "image", // 必需,枚举值: "image"
  "source": { // 必需
    "type": "base64", // 必需,枚举值: "base64"
    "media_type": "image/jpeg", // 必需,支持: image/jpeg, image/png, image/gif, image/webp
    "data": "/9j/4AAQSkZJRg..." // 必需,base64 编码的图片数据
  },
  "cache_control": {
    "type": "ephemeral" // 可选,枚举值: "ephemeral"
  }
}

工具使用 (Tool Use)

{
  "type": "tool_use", // 必需,枚举值: "tool_use",默认值
  "id": "toolu_xyz...", // 必需,工具使用的唯一标识符
  "name": "get_weather", // 必需,工具名称,最小长度: 1
  "input": { // 必需,工具的输入参数对象
    // 工具输入参数,具体格式由工具的 input_schema 定义
  },
  "cache_control": {
    "type": "ephemeral" // 可选,枚举值: "ephemeral"
  }
}

工具结果 (Tool Result)

{
  "type": "tool_result", // 必需,枚举值: "tool_result"
  "tool_use_id": "toolu_xyz...", // 必需
  "content": "结果内容", // 必需,可以是字符串或内容块数组
  "is_error": false, // 可选,布尔值
  "cache_control": {
    "type": "ephemeral" // 可选,枚举值: "ephemeral"
  }
}

当 content 为内容块数组时,每个内容块可以是文本或图片:

{
  "type": "tool_result",
  "tool_use_id": "toolu_xyz...",
  "content": [
    {
      "type": "text", // 必需,枚举值: "text"
      "text": "分析结果", // 必需,最小长度: 1
      "cache_control": {
        "type": "ephemeral" // 可选,枚举值: "ephemeral"
      }
    },
    {
      "type": "image", // 必需,枚举值: "image"
      "source": { // 必需
        "type": "base64", // 必需,枚举值: "base64"
        "media_type": "image/jpeg",
        "data": "..."
      },
      "cache_control": {
        "type": "ephemeral"
      }
    }
  ]
}

文档 (Document)

{
  "type": "document", // 必需,枚举值: "document"
  "source": { // 必需
    // 文档源数据
  },
  "cache_control": {
    "type": "ephemeral" // 可选,枚举值: "ephemeral"
  }
}

注意: 1. 每种类型都可以包含可选的 cache_control 字段,用于控制内容的缓存行为 2. 文本内容的最小长度为 1 3. 所有类型的 type 字段都是必需的枚举字符串 4. 工具结果的 content 字段支持字符串或包含文本/图片的内容块数组

model
- 类型: 字符串
- 必需: 是
- 要使用的模型名称,详见模型文档。范围 1 - 256 个字符。
metadata
- 类型: 对象
- 必需: 否
- 描述请求元数据的对象。包含以下可选字段:
- user_id: 与请求关联的用户的外部标识符。应该是 uuid、哈希值或其他不透明标识符。不要包含任何标识信息如姓名、邮箱或电话号码。最大长度:256。
stop_sequences
- 类型: 字符串数组
- 必需: 否
- 自定义的停止生成的文本序列。
stream
- 类型: 布尔值
- 必需: 否
- 是否使用服务器发送事件 (SSE) 来增量返回响应内容。
system
- 类型: 字符串
- 必需: 否
- 系统 prompt,为 Claude 提供背景和指令。这是一种为模型提供上下文和特定目标或角色的方式。注意这与消息中的 role 不同,Messages API 中没有 “system” 角色。
temperature
- 类型: 数字
- 必需: 否
- 默认值: 1.0
- 控制生成随机性,0.0 - 1.0。范围 0 < x < 1。建议对于分析性/选择题类任务使用接近 0.0 的值,对于创造性和生成性任务使用接近 1.0 的值。
- 注意:即使 temperature 设置为 0.0,结果也不会完全确定。
🆕 thinking
- 类型: 对象
- 必需: 否
- 配置 Claude 的扩展思考功能。启用时,响应将包含展示 Claude 在给出最终答案前的思考过程的内容块。需要至少 1,024 个 token 的预算,并计入您的 max_tokens 限制。
- 可以设置为以下两种模式之一:
- 1. 启用模式
  1
  2
  3
  4
  {
  "type": "enabled",
  "budget_tokens": 2048
  }
  - type: 必需,枚举值: “enabled”
  - budget_tokens: 必需,整数。决定 Claude 可以用于内部推理过程的 token 数量。更大的预算可以让模型对复杂问题进行更深入的分析,提高响应质量。必须 ≥1024 且小于 max_tokens。范围 x > 1024。
- 2. 禁用模式
  1
  2
  3
  {
  "type": "disabled"
  }
  - type: 必需,枚举值: “disabled”

tool_choice

类型: 对象
必需: 否
控制模型如何使用提供的工具。可以是以下三种类型之一:

1. Auto 模式 (自动选择)

{
  "type": "auto", // 必需,枚举值: "auto"
  "disable_parallel_tool_use": false // 可选,默认 false。如果为 true,模型最多只会使用一个工具
}

2. Any 模式 (任意工具)

{
  "type": "any", // 必需,枚举值: "any"
  "disable_parallel_tool_use": false // 可选,默认 false。如果为 true,模型将恰好使用一个工具
}

3. Tool 模式 (指定工具)

{
  "type": "tool", // 必需,枚举值: "tool"
  "name": "get_weather", // 必需,指定要使用的工具名称
  "disable_parallel_tool_use": false // 可选,默认 false。如果为 true,模型将恰好使用一个工具
}

注意: 1. Auto 模式:模型可以自行决定是否使用工具 2. Any 模式:模型必须使用工具,但可以选择任何可用的工具 3. Tool 模式:模型必须使用指定的工具

tools

类型: 对象数组
必需: 否
定义模型可能使用的工具。工具可以是自定义工具或内置工具类型:

1. 自定义工具(Tool)

每个自定义工具定义包含:

type: 可选,枚举值: “custom”
name: 工具名称,必需,1-64 个字符
description: 工具描述,建议尽可能详细
input_schema: 工具输入的 JSON Schema 定义,必需
cache_control: 缓存控制,可选,type 为 “ephemeral”

示例:

[
  {
    "type": "custom",
    "name": "get_weather",
    "description": "获取指定位置的当前天气",
    "input_schema": {
      "type": "object",
      "properties": {
        "location": { "type": "string", "description": "城市名称,如:北京" }
      },
      "required": ["location"]
    }
  }
]

2. 计算机工具 (ComputerUseTool)

{
  "type": "computer_20241022", // 必需
  "name": "computer", // 必需,枚举值: "computer"
  "display_width_px": 1024, // 必需,显示宽度(像素)
  "display_height_px": 768, // 必需,显示高度(像素)
  "display_number": 0, // 可选,X11 显示编号
  "cache_control": {
    "type": "ephemeral" // 可选
  }
}

3. Bash 工具 (BashTool)

{
  "type": "bash_20241022", // 必需
  "name": "bash", // 必需,枚举值: "bash"
  "cache_control": {
    "type": "ephemeral" // 可选
  }
}

4. 文本编辑器工具 (TextEditor)

{
  "type": "text_editor_20241022", // 必需
  "name": "str_replace_editor", // 必需,枚举值: "str_replace_editor"
  "cache_control": {
    "type": "ephemeral" // 可选
  }
}

当模型使用工具时,会返回 tool_use 内容块:

[
  {
    "type": "tool_use",
    "id": "toolu_01D7FLrfh4GYq7yT1UL


#### Deepseek reasoning 格式（类Chat Completions）

**官方文档:** 推理模型 (deepseek-reasoner)

**📝 简介:**

Deepseek-reasoner 是 DeepSeek 推出的推理模型。在输出最终回答之前,模型会先输出一段思维链内容,以提升最终答案的准确性。API 向用户开放 deepseek-reasoner 思维链的内容,以供用户查看、展示、蒸馏使用。

**💡 请求示例:**

**基础文本对话 ✅**

curl https://api.deepseek.com/v1/chat/completions
-H “Content-Type: application/json”
-H “Authorization: Bearer $NEWAPI_API_KEY”
-d ‘{
“model”: “deepseek-reasoner”,
“messages”: [
{ “role”: “user”, “content”: “9.11 and 9.8, which is greater?” }
],
“max_tokens”: 4096
}’

1
2
3


响应示例:

{
“id”: “chatcmpl-123”,
“object”: “chat.completion”,
“created”: 1677652288,
“model”: “deepseek-reasoner”,
“choices”: [{
“index”: 0,
“message”: {
“role”: “assistant”,
“reasoning_content”: “让我一步步思考:\n1. 我们需要比较 9.11 和 9.8 的大小\n2. 两个数都是小数,我们可以直接比较\n3. 9.8 = 9.80\n4. 9.11 < 9.80\n5. 所以 9.8 更大”,
“content”: “9.8 is greater than 9.11.”
},
“finish_reason”: “stop”
}],
“usage”: {
“prompt_tokens”: 10,
“completion_tokens”: 15,
“total_tokens”: 25
}
}

1
2
3


**流式响应 ✅**

1
2
3


流式响应示例:

{“id”:”chatcmpl-123”,”object”:”chat.completion.chunk”,”created”:1694268190,”model”:”deepseek-reasoner”,”choices”:[{“index”:0,”delta”:{“role”:”assistant”,”reasoning_content”:”让我”},”finish_reason”:null}]}
{“id”:”chatcmpl-123”,”object”:”chat.completion.chunk”,”created”:1694268190,”model”:”deepseek-reasoner”,”choices”:[{“index”:0,”delta”:{“reasoning_content”:”一步步”},”finish_reason”:null}]}
{“id”:”chatcmpl-123”,”object”:”chat.completion.chunk”,”created”:1694268190,”model”:”deepseek-reasoner”,”choices”:[{“index”:0,”delta”:{“reasoning_content”:”思考:”},”finish_reason”:null}]}
// … 更多思维链内容 …
{“id”:”chatcmpl-123”,”object”:”chat.completion.chunk”,”created”:1694268190,”model”:”deepseek-reasoner”,”choices”:[{“index”:0,”delta”:{“content”:”9.8”},”finish_reason”:null}]}
{“id”:”chatcmpl-123”,”object”:”chat.completion.chunk”,”created”:1694268190,”model”:”deepseek-reasoner”,”choices”:[{“index”:0,”delta”:{“content”:” is greater”},”finish_reason”:null}]}
// … 更多最终答案内容 …
{“id”:”chatcmpl-123”,”object”:”chat.completion.chunk”,”created”:1694268190,”model”:”deepseek-reasoner”,”choices”:[{“index”:0,”delta”:{},”finish_reason”:”stop”}]}


**📮 请求:**

**端点:**

POST /v1/chat/completions


**鉴权方法:**

在请求头中包含以下内容进行 API 密钥认证:

Authorization: Bearer $NEWAPI_API_KEY


其中 $DEEPSEEK\_API\_KEY 是您的 API 密钥。

**请求体参数:**

*   **messages**
    *   类型: 数组
    *   必需: 是
    *   到目前为止包含对话的消息列表。请注意,如果您在输入的 messages 序列中传入了 reasoning\_content,API 会返回 400 错误。

*   **model**
    *   类型: 字符串
    *   必需: 是
    *   值: deepseek-reasoner
    *   要使用的模型 ID。目前仅支持 deepseek-reasoner。

*   **max\_tokens**
    *   类型: 整数
    *   必需: 否
    *   默认值: 4096
    *   最大值: 8192
    *   最终回答的最大长度(不含思维链输出)。请注意,思维链的输出最多可以达到 32K tokens。

*   **stream**
    *   类型: 布尔值
    *   必需: 否
    *   默认值: false
    *   是否使用流式响应。

**不支持的参数:**

以下参数当前不支持:

*   temperature
*   top\_p
*   presence\_penalty
*   frequency\_penalty
*   logprobs
*   top\_logprobs

注意: 为了兼容已有软件,设置 temperature、top\_p、presence\_penalty、frequency\_penalty 参数不会报错,但也不会生效。设置 logprobs、top\_logprobs 会报错。

**支持的功能:**

*   对话补全
*   对话前缀续写 (Beta)

**不支持的功能:**

*   Function Call
*   Json Output
*   FIM 补全 (Beta)

**📥 响应:**

**成功响应:**

返回一个聊天补全对象,如果请求被流式传输,则返回聊天补全块对象的流式序列。

*   **id**
    *   类型: 字符串
    *   说明: 响应的唯一标识符

*   **object**
    *   类型: 字符串
    *   说明: 对象类型,值为 "chat.completion"

*   **created**
    *   类型: 整数
    *   说明: 响应创建时间戳

*   **model**
    *   类型: 字符串
    *   说明: 使用的模型名称,值为 "deepseek-reasoner"

*   **choices**
    *   类型: 数组
    *   说明: 包含生成的回复选项
    *   属性:
        *   index: 选项索引
        *   message: 包含角色、思维链内容和最终回答的消息对象
            *   role: 角色,值为 "assistant"
            *   reasoning\_content: 思维链内容
            *   content: 最终回答内容
        *   finish\_reason: 完成原因

*   **usage**
    *   类型: 对象
    *   说明: token 使用统计
    *   属性:
        *   prompt\_tokens: 提示使用的 token 数
        *   completion\_tokens: 补全使用的 token 数
        *   total\_tokens: 总 token 数

**📝 上下文拼接说明:**

在每一轮对话过程中,模型会输出思维链内容(reasoning\_content)和最终回答(content)。在下一轮对话中,之前轮输出的思维链内容不会被拼接到上下文中,如下图所示:

注意

如果您在输入的 messages 序列中,传入了reasoning\_content,API 会返回 400 错误。因此,请删除 API 响应中的 reasoning\_content 字段,再发起 API 请求,方法如下方使用示例所示。

使用示例:

from openai import OpenAI

client = OpenAI(api_key=”“, base_url=”https://api.deepseek.com“)

第一轮对话

messages = [{“role”: “user”, “content”: “9.11 and 9.8, which is greater?”}]
response = client.chat.completions.create(
model=”deepseek-reasoner”,
messages=messages
)
reasoning_content = response.choices[0].message.reasoning_content
content = response.choices[0].message.content

第二轮对话 - 只拼接最终回答 content

messages.append({‘role’: ‘assistant’, ‘content’: content})
messages.append({‘role’: ‘user’, ‘content’: “How many Rs are there in the word ‘strawberry’?”})
response = client.chat.completions.create(
model=”deepseek-reasoner”,
messages=messages
)

1
2
3


流式响应示例:

第一轮对话

messages = [{“role”: “user”, “content”: “9.11 and 9.8, which is greater?”}]
response = client.chat.completions.create(
model=”deepseek-reasoner”,
messages=messages,
stream=True
)
reasoning_content = “”
content = “”
for chunk in response:
if chunk.choices[0].delta.reasoning_content:
reasoning_content += chunk.choices[0].delta.reasoning_content
else:
content += chunk.choices[0].delta.content

第二轮对话 - 只拼接最终回答 content

messages.append({“role”: “assistant”, “content”: content})
messages.append({‘role’: ‘user’, ‘content’: “How many Rs are there in the word ‘strawberry’?”})
response = client.chat.completions.create(
model=”deepseek-reasoner”,
messages=messages,
stream=True
)


### 嵌入 (Embeddings)

**官方文档:** OpenAI Embeddings

**📝 简介:**

获取给定输入文本的向量表示,这些向量可以被机器学习模型和算法轻松使用。相关指南请参阅 Embeddings Guide。

需要注意的是:

*   某些模型可能对输入的总 token 数有限制
*   您可以使用示例 Python 代码来计算 token 数量
*   例如:text-embedding-ada-002 模型的输出向量维度为 1536

**💡 请求示例:**

**创建文本嵌入 ✅**

curl https://你的 newapi 服务器地址/v1/embeddings
-H “Content-Type: application/json”
-H “Authorization: Bearer $NEWAPI_API_KEY”
-d ‘{
“input”: “The food was delicious and the waiter…”,
“model”: “text-embedding-ada-002”,
“encoding_format”: “float”
}’

1
2
3


响应示例:

{
“object”: “list”,
“data”: [
{
“object”: “embedding”,
“embedding”: [
0.0023064255,
-0.009327292,
// … (1536 个浮点数,用于 ada-002)
-0.0028842222
],
“index”: 0
}
],
“model”: “text-embedding-ada-002”,
“usage”: {
“prompt_tokens”: 8,
“total_tokens”: 8
}
}

1
2
3


**批量创建嵌入 ✅**

curl https://你的 newapi 服务器地址/v1/embeddings
-H “Content-Type: application/json”
-H “Authorization: Bearer $NEWAPI_API_KEY”
-d ‘{
“input”: [“The food was delicious”, “The waiter was friendly”],
“model”: “text-embedding-ada-002”,
“encoding_format”: “float”
}’

1
2
3


响应示例:

{
“object”: “list”,
“data”: [
{
“object”: “embedding”,
“embedding”: [
0.0023064255,
// … (1536 个浮点数)
],
“index”: 0
},
{
“object”: “embedding”,
“embedding”: [
-0.008815289,
// … (1536 个浮点数)
],
“index”: 1
}
],
“model”: “text-embedding-ada-002”,
“usage”: {
“prompt_tokens”: 12,
“total_tokens”: 12
}
}


**📮 请求:**

**端点:**

POST /v1/embeddings


创建表示输入文本的嵌入向量。

**鉴权方法:**

在请求头中包含以下内容进行 API 密钥认证:

Authorization: Bearer $NEWAPI_API_KEY


其中 $OPENAI\_API\_KEY 是您的 API 密钥。

**请求体参数:**

*   **input**
    *   类型: 字符串或数组
    *   必需: 是
    *   要嵌入的输入文本,编码为字符串或 token 数组。要在单个请求中嵌入多个输入,请传递字符串数组或 token 数组的数组。输入不得超过模型的最大输入 token 数(text-embedding-ada-002 为 8192 个 token),不能为空字符串,任何数组的维度必须小于等于 2048。

*   **model**
    *   类型: 字符串
    *   必需: 是
    *   要使用的模型 ID。您可以使用 List models API 查看所有可用模型,或查看模型概述了解它们的描述。

*   **encoding\_format**
    *   类型: 字符串
    *   必需: 否
    *   默认值: float
    *   返回嵌入的格式。可以是 float 或 base64。

*   **dimensions**
    *   类型: 整数
    *   必需: 否
    *   生成的输出嵌入应具有的维度数。仅在 text-embedding-3 及更高版本的模型中支持。

*   **user**
    *   类型: 字符串
    *   必需: 否
    *   代表您的最终用户的唯一标识符,可以帮助 OpenAI 监控和检测滥用行为。了解更多。

**📥 响应:**

**成功响应:**

返回嵌入对象列表。

*   **object**
    *   类型: 字符串
    *   说明: 对象类型,值为 "list"

*   **data**
    *   类型: 数组
    *   说明: 包含嵌入对象的数组
    *   属性:
        *   object: 对象类型,值为 "embedding"
        *   embedding: 嵌入向量,浮点数列表。向量长度取决于模型
        *   index: 嵌入在列表中的索引

*   **model**
    *   类型: 字符串
    *   说明: 使用的模型名称

*   **usage**
    *   类型: 对象
    *   说明: token 使用统计
    *   属性:
        *   prompt\_tokens: 提示使用的 token 数
        *   total\_tokens: 总 token 数

**嵌入对象:**

表示由嵌入端点返回的嵌入向量。

{
“object”: “embedding”,
“embedding”: [
0.0023064255,
-0.009327292,
// … (ada-002 总共 1536 个浮点数)
-0.0028842222
],
“index”: 0
}


*   **index**
    *   类型: 整数
    *   说明: 嵌入在列表中的索引

*   **embedding**
    *   类型: 数组
    *   说明: 嵌入向量,浮点数列表。向量长度取决于模型,具体请参阅嵌入指南

*   **object**
    *   类型: 字符串
    *   说明: 对象类型,始终为 "embedding"

**错误响应:**

当请求出现问题时,API 将返回一个错误响应对象,HTTP 状态码在 4XX-5XX 范围内。

**常见错误状态码:**

*   401 Unauthorized: API 密钥无效或未提供
*   400 Bad Request: 请求参数无效,例如输入为空或超出 token 限制
*   429 Too Many Requests: 超出 API 调用限制
*   500 Internal Server Error: 服务器内部错误

错误响应示例:

{
“error”: {
“message”: “The input exceeds the maximum length. Please reduce the length of your input.”,
“type”: “invalid_request_error”,
“param”: “input”,
“code”: “context_length_exceeded”
}
}


### 重排序 (Rerank)

**官方文档:** Jina AI Rerank

标准格式

在New API中,Jina AI的rerank格式被采用为标准格式。所有其他供应商(如Xinference、Cohere等)的rerank响应都会被格式化为Jina AI的格式,以提供统一的开发体验。

**📝 简介:**

Jina AI Rerank 是一个强大的文本重排序模型,可以根据查询对文档列表进行相关性排序。该模型支持多语言,可以处理不同语言的文本内容,并为每个文档分配相关性分数。

**💡 请求示例:**

**基础重排序请求 ✅**

curl https://你的 newapi 服务器地址/v1/rerank
-H “Content-Type: application/json”
-H “Authorization: Bearer $NEWAPI_API_KEY”
-d ‘{
“model”: “jina-reranker-v2-base-multilingual”,
“query”: “Organic skincare products for sensitive skin”,
“top_n”: 3,
“documents”: [
“Organic skincare for sensitive skin with aloe vera and chamomile…”,
“New makeup trends focus on bold colors and innovative techniques…”,
“Bio-Hautpflege für empfindliche Haut mit Aloe Vera und Kamille…”
]
}’

1
2
3


响应示例:

{
“results”: [
{
“document”: {
“text”: “Organic skincare for sensitive skin with aloe vera and chamomile…”
},
“index”: 0,
“relevance_score”: 0.8783142566680908
},
{
“document”: {
“text”: “Bio-Hautpflege für empfindliche Haut mit Aloe Vera und Kamille…”
},
“index”: 2,
“relevance_score”: 0.7624675869941711
}
],
“usage”: {
“prompt_tokens”: 815,
“completion_tokens”: 0,
“total_tokens”: 815
}
}


**📮 请求:**

**端点:**

POST /v1/rerank


**鉴权方法:**

在请求头中包含以下内容进行 API 密钥认证:

Authorization: Bearer $NEWAPI_API_KEY


其中 $NEWAPI\_API\_KEY 是您的 API 密钥。

**请求体参数:**

*   **model**
    *   类型: 字符串
    *   必需: 否
    *   默认值: jina-reranker-v2-base-multilingual
    *   说明: 要使用的重排序模型

*   **query**
    *   类型: 字符串
    *   必需: 是
    *   说明: 用于对文档进行相关性排序的查询文本

*   **top\_n**
    *   类型: 整数
    *   必需: 否
    *   默认值: 无限制
    *   说明: 返回排序后的前 N 个文档

*   **documents**
    *   类型: 字符串数组
    *   必需: 是
    *   说明: 要进行重排序的文档列表
    *   限制: 每个文档的长度不应超过模型的最大token限制

**📥 响应:**

**成功响应:**

*   **results**
    *   类型: 数组
    *   说明: 重排序后的文档列表
    *   属性:
        *   document: 包含文档文本的对象
        *   index: 文档在原始列表中的索引
        *   relevance\_score: 相关性分数(0-1之间)

*   **usage**
    *   类型: 对象
    *   说明: token 使用统计
    *   属性:
        *   prompt\_tokens: 提示使用的 token 数
        *   completion\_tokens: 补全使用的 token 数
        *   total\_tokens: 总 token 数
        *   prompt\_tokens\_details: 提示 token 详细信息
            *   cached\_tokens: 缓存的 token 数
            *   audio\_tokens: 音频 token 数
        *   completion\_tokens\_details: 补全 token 详细信息
            *   reasoning\_tokens: 推理 token 数
            *   audio\_tokens: 音频 token 数
            *   accepted\_prediction\_tokens: 接受的预测 token 数
            *   rejected\_prediction\_tokens: 拒绝的预测 token 数

**错误响应:**

当请求出现问题时,API 将返回错误响应:

*   400 Bad Request: 请求参数无效
*   401 Unauthorized: API 密钥无效或未提供
*   429 Too Many Requests: 请求频率超限
*   500 Internal Server Error: 服务器内部错误

**💡 最佳实践:**

### 查询优化建议¶

1.  使用清晰具体的查询文本
2.  避免过于宽泛或模糊的查询
3.  确保查询与文档使用相同的语言风格

### 文档处理建议¶

1.  保持文档长度适中,不要超过模型限制
2.  确保文档内容完整且有意义
3.  可以包含多语言文档,模型支持跨语言匹配

### 性能优化¶

1.  合理设置 top\_n 参数以减少不必要的计算
2.  对于大量文档,考虑分批处理
3.  可以缓存常用查询的结果

### 多语言支持¶

该模型支持多种语言的文档重排序,包括但不限于:

*   英语
*   中文
*   德语
*   西班牙语
*   日语
*   法语

无需指定语言参数,模型会自动识别和处理不同语言的内容。

### 实时对话 (Realtime)

OpenAI 格式 - New API Docs

跳转至

在 GitHub 上关注我们的最新动态或加入我们的 QQ 交流群

# OpenAI 实时对话接口¶

官方文档

* OpenAI Realtime WebRTC
* OpenAI Realtime WebSocket

## 📝 概述¶

### 简介¶

OpenAI Realtime API 提供两种连接方式:

1. WebRTC - 适用于浏览器和移动客户端的实时音视频交互
2. WebSocket - 适用于服务器到服务器的应用程序集成

### 使用场景¶

* 实时语音对话
* 音视频会议
* 实时翻译
* 语音转写
* 实时代码生成
* 服务器端实时集成

### 主要特性¶

* 双向音频流传输
* 文本和音频混合对话
* 函数调用支持
* 自动语音检测(VAD)
* 音频转写功能
* WebSocket 服务器端集成

## 🔐 认证与安全¶

### 认证方式¶

1. 标准 API 密钥 (仅服务器端使用)
2. 临时令牌 (客户端使用)

### 临时令牌¶

* 有效期: 1分钟
* 使用限制: 单个连接
* 获取方式: 通过服务器端 API 创建

POST https://你的 newapi 服务器地址/v1/realtime/sessions Content-Type: application/json Authorization: Bearer $NEW_API_KEY { “model”: “gpt-4o-realtime-preview-2024-12-17”, “voice”: “verse” }


### 安全建议¶

* 永远不要在客户端暴露标准 API 密钥
* 使用 HTTPS/WSS 进行通信
* 实现适当的访问控制
* 监控异常活动

## 🔌 连接建立¶

### WebRTC 连接¶

* URL: https://你的newapi服务器地址/v1/realtime
* 查询参数: model
* 请求头:
* Authorization: Bearer EPHEMERAL\_KEY
* Content-Type: application/sdp

### WebSocket 连接¶

* URL: wss://你的newapi服务器地址/v1/realtime
* 查询参数: model
* 请求头:
* Authorization: Bearer YOUR\_API\_KEY
* OpenAI-Beta: realtime=v1

### 连接流程¶

sequenceDiagram participant Client participant Server participant OpenAI alt WebRTC 连接 Client->>Server: 请求临时令牌 Server->>OpenAI: 创建会话 OpenAI–>>Server: 返回临时令牌 Server–>>Client: 返回临时令牌 Client->>OpenAI: 创建 WebRTC offer OpenAI–>>Client: 返回 answer Note over Client,OpenAI: 建立 WebRTC 连接 Client->>OpenAI: 创建数据通道 OpenAI–>>Client: 确认数据通道 else WebSocket 连接 Server->>OpenAI: 建立 WebSocket 连接 OpenAI–>>Server: 确认连接 Note over Server,OpenAI: 开始实时对话 end


### 数据通道¶

* 名称: oai-events
* 用途: 事件传输
* 格式: JSON

### 音频流¶

* 输入: addTrack()
* 输出: ontrack 事件

## 💬 对话交互¶

### 对话模式¶

1. 纯文本对话
2. 语音对话
3. 混合对话

### 会话管理¶

* 创建会话
* 更新会话
* 结束会话
* 会话配置

### 事件类型¶

* 文本事件
* 音频事件
* 函数调用
* 状态更新
* 错误事件

## ⚙️ 配置选项¶

### 音频配置¶

* 输入格式
* pcm16
* g711\_ulaw
* g711\_alaw
* 输出格式
* pcm16
* g711\_ulaw
* g711\_alaw
* 语音类型
* alloy
* echo
* shimmer

### 模型配置¶

* 温度
* 最大输出长度
* 系统提示词
* 工具配置

### VAD 配置¶

* 阈值
* 静音时长
* 前缀填充

## 💡 请求示例¶

### WebRTC 连接 ❌¶

#### 客户端实现 (浏览器)¶

async function init() { // 从服务器获取临时密钥 - 参见下方服务器代码 const tokenResponse = await fetch(“/session”); const data = await tokenResponse.json(); const EPHEMERAL_KEY = data.client_secret.value; // 创建对等连接 const pc = new RTCPeerConnection(); // 设置播放模型返回的远程音频 const audioEl = document.createElement(“audio”); audioEl.autoplay = true; pc.ontrack = e => audioEl.srcObject = e.streams[0]; // 添加浏览器麦克风输入的本地音频轨道 const ms = await navigator.mediaDevices.getUserMedia({ audio: true }); pc.addTrack(ms.getTracks()[0]); // 设置用于发送和接收事件的数据通道 const dc = pc.createDataChannel(“oai-events”); dc.addEventListener(“message”, (e) => { // 这里接收实时服务器事件! console.log(e); }); // 使用会话描述协议(SDP)启动会话 const offer = await pc.createOffer(); await pc.setLocalDescription(offer); const baseUrl = “https://你的 newapi 服务器地址/v1/realtime”; const model = “gpt-4o-realtime-preview-2024-12-17”; const sdpResponse = await fetch(${baseUrl}?model=${model}, { method: “POST”, body: offer.sdp, headers: { Authorization: Bearer ${EPHEMERAL_KEY}, “Content-Type”: “application/sdp” }, }); const answer = { type: “answer”, sdp: await sdpResponse.text(), }; await pc.setRemoteDescription(answer); } init();

1
2
3


#### 服务器端实现 (Node.js)¶

import express from “express”; const app = express(); // 创建一个端点用于生成临时令牌 // 该端点与上面的客户端代码配合使用 app.get(“/session”, async (req, res) => { const r = await fetch(“https://你的 newapi 服务器地址/v1/realtime/sessions”, { method: “POST”, headers: { “Authorization”: Bearer ${process.env.NEW_API_KEY}, “Content-Type”: “application/json”, }, body: JSON.stringify({ model: “gpt-4o-realtime-preview-2024-12-17”, voice: “verse”, }), }); const data = await r.json(); // 将从 OpenAI REST API 收到的 JSON 发送回客户端 res.send(data); }); app.listen(3000);

1
2
3


#### WebRTC 事件收发示例¶

// 从对等连接创建数据通道 const dc = pc.createDataChannel(“oai-events”); // 监听数据通道上的服务器事件 // 事件数据需要从 JSON 字符串解析 dc.addEventListener(“message”, (e) => { const realtimeEvent = JSON.parse(e.data); console.log(realtimeEvent); }); // 发送客户端事件:将有效的客户端事件序列化为 // JSON,并通过数据通道发送 const responseCreate = { type: “response.create”, response: { modalities: [“text”], instructions: “Write a haiku about code”, }, }; dc.send(JSON.stringify(responseCreate));


### WebSocket 连接 ✅¶

#### Node.js (ws模块)¶

import WebSocket from “ws”; const url = “wss://你的 newapi 服务器地址/v1/realtime?model=gpt-4o-realtime-preview-2024-12-17”; const ws = new WebSocket(url, { headers: { “Authorization”: “Bearer “ + process.env.NEW_API_KEY, “OpenAI-Beta”: “realtime=v1”, }, }); ws.on(“open”, function open() { console.log(“Connected to server.”); }); ws.on(“message”, function incoming(message) { console.log(JSON.parse(message.toString())); });

1
2
3


#### Python (websocket-client)¶

需要安装 websocket-client 库: # pip install websocket-client import os import json import websocket NEW_API_KEY = os.environ.get(“NEW_API_KEY”) url = “wss://你的 newapi 服务器地址/v1/realtime?model=gpt-4o-realtime-preview-2024-12-17” headers = [ “Authorization: Bearer “ + NEW_API_KEY, “OpenAI-Beta: realtime=v1” ] def on_open(ws): print(“Connected to server.”) def on_message(ws, message): data = json.loads(message) print(“Received event:”, json.dumps(data, indent=2)) ws = websocket.WebSocketApp( url, header=headers, on_open=on_open, on_message=on_message, ) ws.run_forever()

1
2
3


#### 浏览器 (标准WebSocket)¶

/_ 注意:在浏览器等客户端环境中,我们建议使用 WebRTC。但在 Deno 和 Cloudflare Workers 等类浏览器环境中, 也可以使用标准 WebSocket 接口。 _/ const ws = new WebSocket( “wss://你的 newapi 服务器地址/v1/realtime?model=gpt-4o-realtime-preview-2024-12-17”, [ “realtime”, // 认证 “openai-insecure-api-key.” + NEW_API_KEY, // 可选 “openai-organization.” + OPENAI_ORG_ID, “openai-project.” + OPENAI_PROJECT_ID, // Beta 协议,必需 “openai-beta.realtime-v1” ] ); ws.on(“open”, function open() { console.log(“Connected to server.”); }); ws.on(“message”, function incoming(message) { console.log(message.data); });


#### 消息收发示例¶

##### Node.js/浏览器¶

// 接收服务器事件 ws.on(“message”, function incoming(message) { // 需要从 JSON 解析消息数据 const serverEvent = JSON.parse(message.data) console.log(serverEvent); }); // 发送事件,创建符合客户端事件格式的 JSON 数据结构 const event = { type: “response.create”, response: { modalities: [“audio”, “text”], instructions: “Give me a haiku about code.”, } }; ws.send(JSON.stringify(event));

1
2
3


##### Python¶

发送客户端事件,将字典序列化为 JSON def on_open(ws): print(“Connected to server.”) event = { “type”: “response.create”, “response”: { “modalities”: [“text”], “instructions”: “Please assist the user.” } } ws.send(json.dumps(event)) # 接收消息需要从 JSON 解析消息负载 def on_message(ws, message): data = json.loads(message) print(“Received event:”, json.dumps(data, indent=2))


## ⚠️ 错误处理¶

### 常见错误¶

1. 连接错误
2. 网络问题
3. 认证失败
4. 配置错误
5. 音频错误
6. 设备权限
7. 格式不支持
8. 编解码问题
9. 会话错误
10. 令牌过期
11. 会话超时
12. 并发限制

### 错误恢复¶

1. 自动重连
2. 会话恢复
3. 错误重试
4. 降级处理

## 📝 事件参考¶

### 通用请求头¶

所有事件都需要包含以下请求头:

| 请求头 | 类型 | 说明 | 示例值 |
| --- | --- | --- | --- |
| Authorization | 字符串 | 认证令牌 | Bearer $NEW\_API\_KEY |
| OpenAI-Beta | 字符串 | API 版本 | realtime=v1 |

### 客户端事件¶

#### session.update¶

更新会话的默认配置。

| 参数 | 类型 | 必需 | 说明 | 示例值/可选值 |
| --- | --- | --- | --- | --- |
| event\_id | 字符串 | 否 | 客户端生成的事件标识符 | event\_123 |
| type | 字符串 | 否 | 事件类型 | session.update |
| modalities | 字符串数组 | 否 | 模型可以响应的模态类型 | ["text", "audio"] |
| instructions | 字符串 | 否 | 预置到模型调用前的系统指令 | "Your knowledge cutoff is 2023-10..." |
| voice | 字符串 | 否 | 模型使用的语音类型 | alloy、echo、shimmer |
| input\_audio\_format | 字符串 | 否 | 输入音频格式 | pcm16、g711\_ulaw、g711\_alaw |
| output\_audio\_format | 字符串 | 否 | 输出音频格式 | pcm16、g711\_ulaw、g711\_alaw |
| input\_audio\_transcription.model | 字符串 | 否 | 用于转写的模型 | whisper-1 |
| turn\_detection.type | 字符串 | 否 | 语音检测类型 | server\_vad |
| turn\_detection.threshold | 数字 | 否 | VAD 激活阈值(0.0-1.0) | 0.8 |
| turn\_detection.prefix\_padding\_ms | 整数 | 否 | 语音开始前包含的音频时长 | 500 |
| turn\_detection.silence\_duration\_ms | 整数 | 否 | 检测语音停止的静音持续时间 | 1000 |
| tools | 数组 | 否 | 模型可用的工具列表 | [] |
| tool\_choice | 字符串 | 否 | 模型选择工具的方式 | auto/none/required |
| temperature | 数字 | 否 | 模型采样温度 | 0.8 |
| max\_output\_tokens | 字符串/整数 | 否 | 单次响应最大token数 | "inf"/4096 |

#### input\_audio\_buffer.append¶

向输入音频缓冲区追加音频数据。

| 参数 | 类型 | 必需 | 说明 | 示例值 |
| --- | --- | --- | --- | --- |
| event\_id | 字符串 | 否 | 客户端生成的事件标识符 | event\_456 |
| type | 字符串 | 否 | 事件类型 | input\_audio\_buffer.append |
| audio | 字符串 | 否 | Base64编码的音频数据 | Base64EncodedAudioData |

#### input\_audio\_buffer.commit¶

将缓冲区中的音频数据提交为用户消息。

| 参数 | 类型 | 必需 | 说明 | 示例值 |
| --- | --- | --- | --- | --- |
| event\_id | 字符串 | 否 | 客户端生成的事件标识符 | event\_789 |
| type | 字符串 | 否 | 事件类型 | input\_audio\_buffer.commit |

#### input\_audio\_buffer.clear¶

清空输入音频缓冲区中的所有音频数据。

| 参数 | 类型 | 必需 | 说明 | 示例值 |
| --- | --- | --- | --- | --- |
| event\_id | 字符串 | 否 | 客户端生成的事件标识符 | event\_012 |
| type | 字符串 | 否 | 事件类型 | input\_audio\_buffer.clear |

#### conversation.item.create¶

向对话中添加新的对话项。

| 参数 | 类型 | 必需 | 说明 | 示例值 |
| --- | --- | --- | --- | --- |
| event\_id | 字符串 | 否 | 客户端生成的事件标识符 | event\_345 |
| type | 字符串 | 否 | 事件类型 | conversation.item.create |
| previous\_item\_id | 字符串 | 否 | 新对话项将插入在此ID之后 | null |
| item.id | 字符串 | 否 | 对话项的唯一标识符 | msg\_001 |
| item.type | 字符串 | 否 | 对话项类型 | message/function\_call/function\_call\_output |
| item.status | 字符串 | 否 | 对话项状态 | completed/in\_progress/incomplete |
| item.role | 字符串 | 否 | 消息发送者的角色 | user/assistant/system |
| item.content | 数组 | 否 | 消息内容 | [text/audio/transcript] |
| item.call\_id | 字符串 | 否 | 函数调用的ID | call\_001 |
| item.name | 字符串 | 否 | 被调用的函数名称 | function\_name |
| item.arguments | 字符串 | 否 | 函数调用的参数 | {"param": "value"} |
| item.output | 字符串 | 否 | 函数调用的输出结果 | {"result": "value"} |

#### conversation.item.truncate¶

截断助手消息中的音频内容。

| 参数 | 类型 | 必需 | 说明 | 示例值 |
| --- | --- | --- | --- | --- |
| event\_id | 字符串 | 否 | 客户端生成的事件标识符 | event\_678 |
| type | 字符串 | 否 | 事件类型 | conversation.item.truncate |
| item\_id | 字符串 | 否 | 要截断的助手消息项的ID | msg\_002 |
| content\_index | 整数 | 否 | 要截断的内容部分的索引 | 0 |
| audio\_end\_ms | 整数 | 否 | 音频截断的结束时间点 | 1500 |

#### conversation.item.delete¶

从对话历史中删除指定的对话项。

| 参数 | 类型 | 必需 | 说明 | 示例值 |
| --- | --- | --- | --- | --- |
| event\_id | 字符串 | 否 | 客户端生成的事件标识符 | event\_901 |
| type | 字符串 | 否 | 事件类型 | conversation.item.delete |
| item\_id | 字符串 | 否 | 要删除的对话项的ID | msg\_003 |

#### response.create¶

触发响应生成。

| 参数 | 类型 | 必需 | 说明 | 示例值 |
| --- | --- | --- | --- | --- |
| event\_id | 字符串 | 否 | 客户端生成的事件标识符 | event\_234 |
| type | 字符串 | 否 | 事件类型 | response.create |
| response.modalities | 字符串数组 | 否 | 响应的模态类型 | ["text", "audio"] |
| response.instructions | 字符串 | 否 | 给模型的指令 | "Please assist the user." |
| response.voice | 字符串 | 否 | 模型使用的语音类型 | alloy/echo/shimmer |
| response.output\_audio\_format | 字符串 | 否 | 输出音频格式 | pcm16 |
| response.tools | 数组 | 否 | 模型可用的工具列表 | ["type", "name", "description"] |
| response.tool\_choice | 字符串 | 否 | 模型选择工具的方式 | auto |
| response.temperature | 数字 | 否 | 采样温度 | 0.7 |
| response.max\_output\_tokens | 整数/字符串 | 否 | 最大输出token数 | 150/"inf" |

#### response.cancel¶

取消正在进行中的响应生成。

| 参数 | 类型 | 必需 | 说明 | 示例值 |
| --- | --- | --- | --- | --- |
| event\_id | 字符串 | 否 | 客户端生成的事件标识符 | event\_567 |
| type | 字符串 | 否 | 事件类型 | response.cancel |

### 服务端事件¶

#### error¶

当发生错误时返回的事件。

| 参数 | 类型 | 必需 | 说明 | 示例值 |
| --- | --- | --- | --- | --- |
| event\_id | 字符串数组 | 否 | 服务端事件的唯一标识符 | ["event\_890"] |
| type | 字符串 | 否 | 事件类型 | error |
| error.type | 字符串 | 否 | 错误类型 | invalid\_request\_error/server\_error |
| error.code | 字符串 | 否 | 错误代码 | invalid\_event |
| error.message | 字符串 | 否 | 人类可读的错误消息 | "The 'type' field is missing." |
| error.param | 字符串 | 否 | 与错误相关的参数 | null |
| error.event\_id | 字符串 | 否 | 相关事件的ID | event\_567 |

#### conversation.item.input\_audio\_transcription.completed¶

当启用输入音频转写功能并且转写成功时返回此事件。

| 参数 | 类型 | 必需 | 说明 | 示例值 |
| --- | --- | --- | --- | --- |
| event\_id | 字符串 | 否 | 服务端事件的唯一标识符 | event\_2122 |
| type | 字符串 | 否 | 事件类型 | conversation.item.input\_audio\_transcription.completed |
| item\_id | 字符串 | 否 | 用户消息项的ID | msg\_003 |
| content\_index | 整数 | 否 | 包含音频的内容部分的索引 | 0 |
| transcript | 字符串 | 否 | 转写的文本内容 | "Hello, how are you?" |

#### conversation.item.input\_audio\_transcription.failed¶

当配置了输入音频转写功能,但用户消息的转写请求失败时返回此事件。

| 参数 | 类型 | 必需 | 说明 | 示例值 |
| --- | --- | --- | --- | --- |
| event\_id | 字符串 | 否 | 服务端事件的唯一标识符 | event\_2324 |
| type | 字符串数组 | 否 | 事件类型 | ["conversation.item.input\_audio\_transcription.failed"] |
| item\_id | 字符串 | 否 | 用户消息项的ID | msg\_003 |
| content\_index | 整数 | 否 | 包含音频的内容部分的索引 | 0 |
| error.type | 字符串 | 否 | 错误类型 | transcription\_error |
| error.code | 字符串 | 否 | 错误代码 | audio\_unintelligible |
| error.message | 字符串 | 否 | 人类可读的错误消息 | "The audio could not be transcribed." |
| error.param | 字符串 | 否 | 与错误相关的参数 | null |

#### conversation.item.truncated¶

当客户端截断了之前的助手音频消息项时返回此事件。

| 参数 | 类型 | 必需 | 说明 | 示例值 |
| --- | --- | --- | --- | --- |
| event\_id | 字符串 | 否 | 服务端事件的唯一标识符 | event\_2526 |
| type | 字符串 | 否 | 事件类型 | conversation.item.truncated |
| item\_id | 字符串 | 否 | 被截断的助手消息项的ID | msg\_004 |
| content\_index | 整数 | 否 | 被截断的内容部分的索引 | 0 |
| audio\_end\_ms | 整数 | 否 | 音频被截断的时间点(毫秒) | 1500 |

#### conversation.item.deleted¶

当对话中的某个项目被删除时返回此事件。

| 参数 | 类型 | 必需 | 说明 | 示例值 |
| --- | --- | --- | --- | --- |
| event\_id | 字符串 | 否 | 服务端事件的唯一标识符 | event\_2728 |
| type | 字符串 | 否 | 事件类型 | conversation.item.deleted |
| item\_id | 字符串 | 否 | 被删除的对话项的ID | msg\_005 |

#### input\_audio\_buffer.committed¶

当音频缓冲区中的数据被提交时返回此事件。

| 参数 | 类型 | 必需 | 说明 | 示例值 |
| --- | --- | --- | --- | --- |
| event\_id | 字符串 | 否 | 服务端事件的唯一标识符 | event\_1121 |
| type | 字符串 | 否 | 事件类型 | input\_audio\_buffer.committed |
| previous\_item\_id | 字符串 | 否 | 新对话项将插入在此ID对应的对话项之后 | msg\_001 |
| item\_id | 字符串 | 否 | 将要创建的用户消息项的ID | msg\_002 |

#### input\_audio\_buffer.cleared¶

当客户端清空输入音频缓冲区时返回此事件。

| 参数 | 类型 | 必需 | 说明 | 示例值 |
| --- | --- | --- | --- | --- |
| event\_id | 字符串 | 否 | 服务端事件的唯一标识符 | event\_1314 |
| type | 字符串 | 否 | 事件类型 | input\_audio\_buffer.cleared |

#### input\_audio\_buffer.speech\_started¶

在服务器语音检测模式下,当检测到语音输入时返回此事件。

| 参数 | 类型 | 必需 | 说明 | 示例值 |
| --- | --- | --- | --- | --- |
| event\_id | 字符串 | 否 | 服务端事件的唯一标识符 | event\_1516 |
| type | 字符串 | 否 | 事件类型 | input\_audio\_buffer.speech\_started |
| audio\_start\_ms | 整数 | 否 | 从会话开始到检测到语音的毫秒数 | 1000 |
| item\_id | 字符串 | 否 | 语音停止时将创建的用户消息项的ID | msg\_003 |

#### input\_audio\_buffer.speech\_stopped¶

在服务器语音检测模式下,当检测到语音输入停止时返回此事件。

| 参数 | 类型 | 必需 | 说明 | 示例值 |
| --- | --- | --- | --- | --- |
| event\_id | 字符串 | 否 | 服务端事件的唯一标识符 | event\_1718 |
| type | 字符串 | 否 | 事件类型 | input\_audio\_buffer.speech\_stopped |
| audio\_start\_ms | 整数 | 否 | 从会话开始到检测到语音停止的毫秒数 | 2000 |
| item\_id | 字符串 | 否 | 将要创建的用户消息项的ID | msg\_003 |

#### response.created¶

当创建新的响应时返回此事件。

| 参数 | 类型 | 必需 | 说明 | 示例值 |
| --- | --- | --- | --- | --- |
| event\_id | 字符串 | 否 | 服务端事件的唯一标识符 | event\_2930 |
| type | 字符串 | 否 | 事件类型 | response.created |
| response.id | 字符串 | 否 | 响应的唯一标识符 | resp\_001 |
| response.object | 字符串 | 否 | 对象类型 | realtime.response |
| response.status | 字符串 | 否 | 响应的状态 | in\_progress |
| response.status\_details | 对象 | 否 | 状态的附加详细信息 | null |
| response.output | 字符串数组 | 否 | 响应生成的输出项列表 | ["[]"] |
| response.usage | 对象 | 否 | 响应的使用统计信息 | null |

#### response.done¶

当响应完成流式传输时返回此事件。

| 参数 | 类型 | 必需 | 说明 | 示例值 |
| --- | --- | --- | --- | --- |
| event\_id | 字符串 | 否 | 服务端事件的唯一标识符 | event\_3132 |
| type | 字符串 | 否 | 事件类型 | response.done |
| response.id | 字符串 | 否 | 响应的唯一标识符 | resp\_001 |
| response.object | 字符串 | 否 | 对象类型 | realtime.response |
| response.status | 字符串 | 否 | 响应的最终状态 | completed/cancelled/failed/incomplete |
| response.status\_details | 对象 | 否 | 状态的附加详细信息 | null |
| response.output | 字符串数组 | 否 | 响应生成的输出项列表 | ["[...]"] |
| response.usage.total\_tokens | 整数 | 否 | 总token数 | 50 |
| response.usage.input\_tokens | 整数 | 否 | 输入token数 | 20 |
| response.usage.output\_tokens | 整数 | 否 | 输出token数 | 30 |

#### response.output\_item.added¶

当响应生成过程中创建新的输出项时返回此事件。

| 参数 | 类型 | 必需 | 说明 | 示例值 |
| --- | --- | --- | --- | --- |
| event\_id | 字符串 | 否 | 服务端事件的唯一标识符 | event\_3334 |
| type | 字符串 | 否 | 事件类型 | response.output\_item.added |
| response\_id | 字符串 | 否 | 输出项所属的响应ID | resp\_001 |
| output\_index | 字符串 | 否 | 输出项在响应中的索引 | 0 |
| item.id | 字符串 | 否 | 输出项的唯一标识符 | msg\_007 |
| item.object | 字符串 | 否 | 对象类型 | realtime.item |
| item.type | 字符串 | 否 | 输出项类型 | message/function\_call/function\_call\_output |
| item.status | 字符串 | 否 | 输出项状态 | in\_progress/completed |
| item.role | 字符串 | 否 | 与输出项关联的角色 | assistant |
| item.content | 数组 | 否 | 输出项的内容 | ["type", "text", "audio", "transcript"] |

#### response.output\_item.done¶

当输出项完成流式传输时返回此事件。

| 参数 | 类型 | 必需 | 说明 | 示例值 |
| --- | --- | --- | --- | --- |
| event\_id | 字符串 | 否 | 服务端事件的唯一标识符 | event\_3536 |
| type | 字符串 | 否 | 事件类型 | response.output\_item.done |
| response\_id | 字符串 | 否 | 输出项所属的响应ID | resp\_001 |
| output\_index | 字符串 | 否 | 输出项在响应中的索引 | 0 |
| item.id | 字符串 | 否 | 输出项的唯一标识符 | msg\_007 |
| item.object | 字符串 | 否 | 对象类型 | realtime.item |
| item.type | 字符串 | 否 | 输出项类型 | message/function\_call/function\_call\_output |
| item.status | 否 | 输出项的最终状态 | completed/incomplete |
| item.role | 字符串 | 否 | 与输出项关联的角色 | assistant |
| item.content | 数组 | 否 | 输出项的内容 | ["type", "text", "audio", "transcript"] |

#### response.content\_part.added¶

当响应生成过程中向助手消息项添加新的内容部分时返回此事件。

| 参数 | 类型 | 必需 | 说明 | 示例值 |
| --- | --- | --- | --- | --- |
| event\_id | 字符串 | 否 | 服务端事件的唯一标识符 | event\_3738 |
| type | 字符串 | 否 | 事件类型 | response.content\_part.added |
| response\_id | 字符串 | 否 | 响应的ID | resp\_001 |
| item\_id | 字符串 | 否 | 添加内容部分的消息项ID | msg\_007 |
| output\_index | 整数 | 否 | 输出项在响应中的索引 | 0 |
| content\_index | 整数 | 否 | 内容部分在消息项内容数组中的索引 | 0 |
| part.type | 字符串 | 否 | 内容类型 | text/audio |
| part.text | 字符串 | 否 | 文本内容 | "Hello" |
| part.audio | 字符串 | 否 | Base64编码的音频数据 | "base64\_encoded\_audio\_data" |
| part.transcript | 字符串 | 否 | 音频的转写文本 | "Hello" |

#### response.content\_part.done¶

当助手消息项中的内容部分完成流式传输时返回此事件。

| 参数 | 类型 | 必需 | 说明 | 示例值 |
| --- | --- | --- | --- | --- |
| event\_id | 字符串 | 否 | 服务端事件的唯一标识符 | event\_3940 |
| type | 字符串 | 否 | 事件类型 | response.content\_part.done |
| response\_id | 字符串 | 否 | 响应的ID | resp\_001 |
| item\_id | 字符串 | 否 | 添加内容部分的消息项ID | msg\_007 |
| output\_index | 整数 | 否 | 输出项在响应中的索引 | 0 |
| content\_index | 整数 | 否 | 内容部分在消息项内容数组中的索引 | 0 |
| part.type | 字符串 | 否 | 内容类型 | text/audio |
| part.text | 字符串 | 否 | 文本内容 | "Hello" |
| part.audio | 字符串 | 否 | Base64编码的音频数据 | "base64\_encoded\_audio\_data" |
| part.transcript | 字符串 | 否 | 音频的转写文本 | "Hello" |

#### response.text.delta¶

当"text"类型内容部分的文本值更新时返回此事件。

| 参数 | 类型 | 必需 | 说明 | 示例值 |
| --- | --- | --- | --- | --- |
| event\_id | 字符串 | 否 | 服务端事件的唯一标识符 | event\_4142 |
| type | 字符串 | 否 | 事件类型 | response.text.delta |
| response\_id | 字符串 | 否 | 响应的ID | resp\_001 |
| item\_id | 字符串 | 否 | 消息项的ID | msg\_007 |
| output\_index | 整数 | 否 | 输出项在响应中的索引 | 0 |
| content\_index | 整数 | 否 | 内容部分在消息项内容数组中的索引 | 0 |
| delta | 字符串 | 否 | 文本增量更新内容 | "Sure, I can h" |

#### response.text.done¶

当"text"类型内容部分的文本流式传输完成时返回此事件。

| 参数 | 类型 | 必需 | 说明 | 示例值 |
| --- | --- | --- | --- | --- |
| event\_id | 字符串 | 否 | 服务端事件的唯一标识符 | event\_4344 |
| type | 字符串 | 否 | 事件类型 | response.text.done |
| response\_id | 字符串 | 否 | 响应的ID | resp\_001 |
| item\_id | 字符串 | 否 | 消息项的ID | msg\_007 |
| output\_index | 整数 | 否 | 输出项在响应中的索引 | 0 |
| content\_index | 整数 | 否 | 内容部分在消息项内容数组中的索引 | 0 |
| delta | 字符串 | 否 | 最终的完整文本内容 | "Sure, I can help with that." |

#### response.audio\_transcript.delta¶

当模型生成的音频输出转写内容更新时返回此事件。

| 参数 | 类型 | 必需 | 说明 | 示例值 |
| --- | --- | --- | --- | --- |
| event\_id | 字符串 | 否 | 服务端事件的唯一标识符 | event\_4546 |
| type | 字符串 | 否 | 事件类型 | response.audio\_transcript.delta |
| response\_id | 字符串 | 否 | 响应的ID | resp\_001 |
| item\_id | 字符串 | 否 | 消息项的ID | msg\_008 |
| output\_index | 整数 | 否 | 输出项在响应中的索引 | 0 |
| content\_index | 整数 | 否 | 内容部分在消息项内容数组中的索引 | 0 |
| delta | 字符串 | 否 | 转写文本的增量更新内容 | "Hello, how can I a" |

#### response.audio\_transcript.done¶

当模型生成的音频输出转写完成流式传输时返回此事件。

| 参数 | 类型 | 必需 | 说明 | 示例值 |
| --- | --- | --- | --- | --- |
| event\_id | 字符串 | 否 | 服务端事件的唯一标识符 | event\_4748 |
| type | 字符串 | 否 | 事件类型 | response.audio\_transcript.done |
| response\_id | 字符串 | 否 | 响应的ID | resp\_001 |
| item\_id | 字符串 | 否 | 消息项的ID | msg\_008 |
| output\_index | 整数 | 否 | 输出项在响应中的索引 | 0 |
| content\_index | 整数 | 否 | 内容部分在消息项内容数组中的索引 | 0 |
| transcript | 字符串 | 否 | 音频的最终完整转写文本 | "Hello, how can I assist you today?" |

#### response.audio.delta¶

当模型生成的音频内容更新时返回此事件。

| 参数 | 类型 | 必需 | 说明 | 示例值 |
| --- | --- | --- | --- | --- |
| event\_id | 字符串 | 否 | 服务端事件的唯一标识符 | event\_4950 |
| type | 字符串 | 否 | 事件类型 | response.audio.delta |
| response\_id | 字符串 | 否 | 响应的ID | resp\_001 |
| item\_id | 字符串 | 否 | 消息项的ID | msg\_008 |
| output\_index | 整数 | 否 | 输出项在响应中的索引 | 0 |
| content\_index | 整数 | 否 | 内容部分在消息项内容数组中的索引 | 0 |
| delta | 字符串 | 否 | Base64编码的音频数据增量 | "Base64EncodedAudioDelta" |

#### response.audio.done¶

当模型生成的音频完成时返回此事件。

| 参数 | 类型 | 必需 | 说明 | 示例值 |
| --- | --- | --- | --- | --- |
| event\_id | 字符串 | 否 | 服务端事件的唯一标识符 | event\_5152 |
| type | 字符串 | 否 | 事件类型 | response.audio.done |
| response\_id | 字符串 | 否 | 响应的ID | resp\_001 |
| item\_id | 字符串 | 否 | 消息项的ID | msg\_008 |
| output\_index | 整数 | 否 | 输出项在响应中的索引 | 0 |
| content\_index | 整数 | 否 | 内容部分在消息项内容数组中的索引 | 0 |

### 函数调用¶

#### response.function\_call\_arguments.delta¶

当模型生成的函数调用参数更新时返回此事件。

| 参数 | 类型 | 必需 | 说明 | 示例值 |
| --- | --- | --- | --- | --- |
| event\_id | 字符串 | 否 | 服务端事件的唯一标识符 | event\_5354 |
| type | 字符串 | 否 | 事件类型 | response.function\_call\_arguments.delta |
| response\_id | 字符串 | 否 | 响应的ID | resp\_002 |
| item\_id | 字符串 | 否 | 消息项的ID | fc\_001 |
| output\_index | 整数 | 否 | 输出项在响应中的索引 | 0 |
| call\_id | 字符串 | 否 | 函数调用的ID | call\_001 |
| delta | 字符串 | 否 | JSON格式的函数调用参数增量 | "{\"location\": \"San\"" |

#### response.function\_call\_arguments.done¶

当模型生成的函数调用参数完成流式传输时返回此事件。

| 参数 | 类型 | 必需 | 说明 | 示例值 |
| --- | --- | --- | --- | --- |
| event\_id | 字符串 | 否 | 服务端事件的唯一标识符 | event\_5556 |
| type | 字符串 | 否 | 事件类型 | response.function\_call\_arguments.done |
| response\_id | 字符串 | 否 | 响应的ID | resp\_002 |
| item\_id | 字符串 | 否 | 消息项的ID | fc\_001 |
| output\_index | 整数 | 否 | 输出项在响应中的索引 | 0 |
| call\_id | 字符串 | 否 | 函数调用的ID | call\_001 |
| arguments | 字符串 | 否 | 最终的完整函数调用参数(JSON格式) | "{\"location\": \"San Francisco\"}" |

### 其他状态更新¶

#### rate\_limits.updated¶

在每个 "response.done" 事件之后触发,用于指示更新后的速率限制。

| 参数 | 类型 | 必需 | 说明 | 示例值 |
| --- | --- | --- | --- | --- |
| event\_id | 字符串 | 否 | 服务端事件的唯一标识符 | event\_5758 |
| type | 字符串 | 否 | 事件类型 | rate\_limits.updated |
| rate\_limits | 对象数组 | 否 | 速率限制信息列表 | [{"name": "requests\_per\_min", "limit": 60, "remaining": 45, "reset\_seconds": 35}] |

#### conversation.created¶

当对话创建时返回此事件。

| 参数 | 类型 | 必需 | 说明 | 示例值 |
| --- | --- | --- | --- | --- |
| event\_id | 字符串 | 否 | 服务端事件的唯一标识符 | event\_9101 |
| type | 字符串 | 否 | 事件类型 | conversation.created |
| conversation | 对象 | 否 | 对话资源对象 | {"id": "conv\_001", "object": "realtime.conversation"} |

#### conversation.item.created¶

当对话项创建时返回此事件。

| 参数 | 类型 | 必需 | 说明 | 示例值 |
| --- | --- | --- | --- | --- |
| event\_id | 字符串 | 否 | 服务端事件的唯一标识符 | event\_1920 |
| type | 字符串 | 否 | 事件类型 | conversation.item.created |
| previous\_item\_id | 字符串 | 否 | 前一个对话项的ID | msg\_002 |
| item | 对象 | 否 | 对话项对象 | {"id": "msg\_003", "object": "realtime.item", "type": "message", "status": "completed", "role": "user", "content": [{"type": "text", "text": "Hello"}]} |

#### session.created¶

当会话创建时返回此事件。

| 参数 | 类型 | 必需 | 说明 | 示例值 |
| --- | --- | --- | --- | --- |
| event\_id | 字符串 | 否 | 服务端事件的唯一标识符 | event\_1234 |
| type | 字符串 | 否 | 事件类型 | session.created |
| session | 对象 | 否 | 会话对象 | {"id": "sess\_001", "object": "realtime.session", "model": "gpt-4", "modalities": ["text", "audio"]} |

#### session.updated¶

当会话更新时返回此事件。

| 参数 | 类型 | 必需 | 说明 | 示例值 |
| --- | --- | --- | --- | --- |
| event\_id | 字符串 | 否 | 服务端事件的唯一标识符 | event\_5678 |
| type | 字符串 | 否 | 事件类型 | session.updated |
| session | 对象 | 否 | 更新后的会话对象 | {"id": "sess\_001", "object": "realtime.session", "model": "gpt-4", "modalities": ["text", "audio"]} |

### 速率限制事件参数表¶

| 参数 | 类型 | 必需 | 说明 | 示例值 |
| --- | --- | --- | --- | --- |
| name | 字符串 | 是 | 限制名称 | requests\_per\_min |
| limit | 整数 | 是 | 限制值 | 60 |
| remaining | 整数 | 是 | 剩余可用量 | 45 |
| reset\_seconds | 整数 | 是 | 重置时间(秒) | 35 |

### 函数调用参数表¶

| 参数 | 类型 | 必需 | 说明 | 示例值 |
| --- | --- | --- | --- | --- |
| type | 字符串 | 是 | 函数类型 | function |
| name | 字符串 | 是 | 函数名称 | get\_weather |
| description | 字符串 | 否 | 函数描述 | Get the current weather |
| parameters | 对象 | 是 | 函数参数定义 | {"type": "object", "properties": {...}} |

### 音频格式参数表¶

| 参数 | 类型 | 说明 | 可选值 |
| --- | --- | --- | --- |
| sample\_rate | 整数 | 采样率 | 8000, 16000, 24000, 44100, 48000 |
| channels | 整数 | 声道数 | 1 (单声道), 2 (立体声) |
| bits\_per\_sample | 整数 | 采样位数 | 16 (pcm16), 8 (g711) |
| encoding | 字符串 | 编码方式 | pcm16, g711\_ulaw, g711\_alaw |

### 语音检测参数表¶

| 参数 | 类型 | 说明 | 默认值 | 范围 |
| --- | --- | --- | --- | --- |
| threshold | 浮点数 | VAD 激活阈值 | 0.5 | 0.0-1.0 |
| prefix\_padding\_ms | 整数 | 语音前缀填充(毫秒) | 500 | 0-5000 |
| silence\_duration\_ms | 整数 | 静音检测时长(毫秒) | 1000 | 100-10000 |

### 工具选择参数表¶

| 参数 | 类型 | 说明 | 可选值 |
| --- | --- | --- | --- |
| tool\_choice | 字符串 | 工具选择方式 | auto, none, required |
| tools | 数组 | 可用工具列表 | [{type, name, description, parameters}] |

### 模型配置参数表¶

| 参数 | 类型 | 说明 | 范围/可选值 | 默认值 |
| --- | --- | --- | --- | --- |
| temperature | 浮点数 | 采样温度 | 0.0-2.0 | 1.0 |
| max\_output\_tokens | 整数/字符串 | 最大输出长度 | 1-4096/"inf" | "inf" |
| modalities | 字符串数组 | 响应模态 | ["text", "audio"] | ["text"] |
| voice | 字符串 | 语音类型 | alloy, echo, shimmer | alloy |

### 事件通用参数表¶

| 参数 | 类型 | 必需 | 说明 | 示例值 |
| --- | --- | --- | --- | --- |
| event\_id | 字符串 | 是 | 事件的唯一标识符 | event\_123 |
| type | 字符串 | 是 | 事件类型 | session.update |
| timestamp | 整数 | 否 | 事件发生的时间戳(毫秒) | 1677649363000 |

### 会话状态参数表¶

| 参数 | 类型 | 说明 | 可选值 |
| --- | --- | --- | --- | --- |
| status | 字符串 | 会话状态 | active, ended, error |
| error | 对象 | 错误信息 | {"type": "error\_type", "message": "error message"} |
| metadata | 对象 | 会话元数据 | {"client\_id": "web", "session\_type": "chat"} |

### 对话项状态参数表¶

| 参数 | 类型 | 说明 | 可选值 |
| --- | --- | --- | --- | --- |
| status | 字符串 | 对话项状态 | completed, in\_progress, incomplete |
| role | 字符串 | 发送者角色 | user, assistant, system |
| type | 字符串 | 对话项类型 | message, function\_call, function\_call\_output |

### 内容类型参数表¶

| 参数 | 类型 | 说明 | 可选值 |
| --- | --- | --- | --- | --- |
| type | 字符串 | 内容类型 | text, audio, transcript |
| format | 字符串 | 内容格式 | plain, markdown, html |
| encoding | 字符串 | 编码方式 | utf-8, base64 |

### 响应状态参数表¶

| 参数 | 类型 | 说明 | 可选值 |
| --- | --- | --- | --- | --- |
| status | 字符串 | 响应状态 | completed, cancelled, failed, incomplete |
| status\_details | 对象 | 状态详情 | {"reason": "user\_cancelled"} |
| usage | 对象 | 使用统计 | {"total\_tokens": 50, "input\_tokens": 20, "output\_tokens": 30} |

### 音频转写参数表¶

| 参数 | 类型 | 说明 | 示例值 |
| --- | --- | --- | --- |
| enabled | 布尔值 | 是否启用转写 | true |
| model | 字符串 | 转写模型 | whisper-1 |
| language | 字符串 | 转写语言 | en, zh, auto |
| prompt | 字符串 | 转写提示词 | "Transcript of a conversation" |

### 音频流参数表¶

| 参数 | 类型 | 说明 | 可选值 |
| --- | --- | --- | --- |
| chunk\_size | 整数 | 音频块大小(字节) | 1024, 2048, 4096 |
| latency | 字符串 | 延迟模式 | low, balanced, high |
| compression | 字符串 | 压缩方式 | none, opus, mp3 |

### WebRTC 配置参数表¶

| 参数 | 类型 | 说明 | 默认值 |
| --- | --- | --- | --- |
| ice\_servers | 数组 | ICE 服务器列表 | [{"urls": "stun:stun.l.google.com:19302"}] |
| audio\_constraints | 对象 | 音频约束 | {"echoCancellation": true} |
| connection\_timeout | 整数 | 连接超时(毫秒) | 30000 |

## New API

🍥新一代大模型网关与AI资产管理系统

### 关于我们

* 关于项目
* 联系我们
* 功能特性

### 文档

* 快速开始
* 安装指南
* API 文档

### 相关项目

* One API
* Midjourney-Proxy
* chatnio
* neko-api-key-tool

### 基于New API的项目

* new-api-horizon
* VoAPI

Copyright © 2025 Quantum Nous. All Rights Reserved.

渝ICP备2025052930号

Made with ❤ by Quantum Nous

### 图像 (Image)

OpenAI 格式(Image) - New API Docs

跳转至

在 GitHub 上关注我们的最新动态或加入我们的 QQ 交流群

# OpenAI 图像格式(Image)¶

官方文档

OpenAI Images

## 📝 简介¶

给定文本提示和/或输入图片,模型将生成新的图片。OpenAI 提供多种强大的图像生成模型,可以根据自然语言描述创建、编辑和修改图像。目前支持的模型包括:

| 模型 | 描述 |
| --- | --- |
| DALL·E 系列 | 包括 DALL·E 2 和 DALL·E 3 两个版本,它们在图像质量、创意表现和精确度上都有显著差异 |
| GPT-Image-1 | OpenAI最新图片模型,支持多图片编辑功能,能够基于多个输入图像创建新的组合图像 |

## 💡 请求示例¶

### 创建图片 ✅¶

基础图片生成 curl https://你的 newapi 服务器地址/v1/images/generations \ -H “Content-Type: application/json” \ -H “Authorization: Bearer $NEWAPI_API_KEY” \ -d ‘{ “model”: “dall-e-3”, “prompt”: “一只可爱的小海獭”, “n”: 1, “size”: “1024x1024” }’ # 高质量图片生成 curl https://你的 newapi 服务器地址/v1/images/generations \ -H “Content-Type: application/json” \ -H “Authorization: Bearer $NEWAPI_API_KEY” \ -d ‘{ “model”: “dall-e-3”, “prompt”: “一只可爱的小海獭”, “quality”: “hd”, “style”: “vivid”, “size”: “1024x1024” }’ # 使用 base64 返回格式 curl https://你的 newapi 服务器地址/v1/images/generations \ -H “Content-Type: application/json” \ -H “Authorization: Bearer $NEWAPI_API_KEY” \ -d ‘{ “model”: “dall-e-3”, “prompt”: “一只可爱的小海獭”, “response_format”: “b64_json” }’

1
2
3


响应示例:

{ “created”: 1589478378, “data”: [ { “url”: “https://…”, “revised_prompt”: “一只可爱的小海獭在水中嬉戏,它有着圆圆的眼睛和毛茸茸的皮毛” } ] }

1
2
3


### 编辑图片 ✅¶

dall-e-2 图片编辑 curl https://你的 newapi 服务器地址/v1/images/edits \ -H “Authorization: Bearer $NEWAPI_API_KEY” \ -F image=”@otter.png” \ -F mask=”@mask.png” \ -F prompt=”一只戴着贝雷帽的可爱小海獭” \ -F n=2 \ -F size=”1024x1024” # gpt-image-1 多图片编辑示例 curl https://你的 newapi 服务器地址/v1/images/edits \ -H “Authorization: Bearer $NEWAPI_API_KEY” \ -F “model=gpt-image-1” \ -F “image[]=@body-lotion.png” \ -F “image[]=@bath-bomb.png” \ -F “image[]=@incense-kit.png” \ -F “image[]=@soap.png” \ -F “prompt=创建一个包含这四个物品的精美礼品篮” \ -F “quality=high”

1
2
3


响应示例 (dall-e-2):

{ “created”: 1589478378, “data”: [ { “url”: “https://…” }, { “url”: “https://…” } ] }

1
2
3


响应示例 (gpt-image-1):

{ “created”: 1713833628, “data”: [ { “b64_json”: “…” } ], “usage”: { “total_tokens”: 100, “input_tokens”: 50, “output_tokens”: 50, “input_tokens_details”: { “text_tokens”: 10, “image_tokens”: 40 } } }

1
2
3


### 生成图片变体 ✅¶

curl https://你的 newapi 服务器地址/v1/images/variations \ -H “Authorization: Bearer $NEWAPI_API_KEY” \ -F image=”@otter.png” \ -F n=2 \ -F size=”1024x1024”

1
2
3


响应示例:

{ “created”: 1589478378, “data”: [ { “url”: “https://…” }, { “url”: “https://…” } ] }


## 📮 请求¶

### 端点¶

#### 创建图片¶

POST /v1/images/generations


根据文本提示创建图片。

#### 编辑图片¶

POST /v1/images/edits


根据一个或多个原始图片和提示创建编辑或扩展的图片。此端点支持 dall-e-2 和 gpt-image-1 模型。

#### 生成变体¶

POST /v1/images/variations


创建给定图片的变体。

### 鉴权方法¶

在请求头中包含以下内容进行 API 密钥认证:

Authorization: Bearer $NEWAPI_API_KEY


其中 $OPENAI\_API\_KEY 是您的 API 密钥。

### 请求体参数¶

#### 创建图片¶

##### prompt¶

* 类型:字符串
* 必需:是
* 说明:期望生成图片的文本描述。
* dall-e-2 最大长度为 1000 字符
* dall-e-3 最大长度为 4000 字符
* 提示:
* 使用具体和详细的描述
* 包含关键的视觉元素
* 指定期望的艺术风格
* 描述构图和视角

##### model¶

* 类型:字符串
* 必需:否
* 默认值:dall-e-2
* 说明:用于图像生成的模型。

##### n¶

* 类型:整数或 null
* 必需:否
* 默认值:1
* 说明:要生成的图片数量。必须在 1-10 之间。dall-e-3 仅支持 n=1。

##### quality¶

* 类型:字符串
* 必需:否
* 默认值:standard
* 说明:生成图片的质量。hd 选项会生成更细致和一致的图片。仅 dall-e-3 支持此参数。

##### response\_format¶

* 类型:字符串或 null
* 必需:否
* 默认值:url
* 说明:返回生成图片的格式。必须是 url 或 b64\_json 之一。URL 在生成后 60 分钟内有效。

##### size¶

* 类型:字符串或 null
* 必需:否
* 默认值:1024x1024
* 说明:生成图片的尺寸。dall-e-2 必须是 256x256、512x512 或 1024x1024 之一。dall-e-3 必须是 1024x1024、1792x1024 或 1024x1792 之一。

##### style¶

* 类型:字符串或 null
* 必需:否
* 默认值:vivid
* 说明:生成图片的风格。必须是 vivid 或 natural 之一。vivid 倾向于生成超现实和戏剧性的图片,natural 倾向于生成更自然、不那么超现实的图片。仅 dall-e-3 支持此参数。

##### user¶

* 类型:字符串
* 必需:否
* 说明:代表最终用户的唯一标识符,可帮助 OpenAI 监控和检测滥用行为。

#### 编辑图片¶

##### image¶

* 类型:文件或文件数组
* 必需:是
* 说明:要编辑的图片。
* 对于 dall-e-2:必须是有效的 PNG 文件,小于 4MB,且为正方形。如果未提供 mask,图片必须具有透明度,这将用作蒙版。
* 对于 gpt-image-1:可以提供多个图片作为数组,每个图片应为 PNG、WEBP 或 JPG 文件,小于 25MB。

##### prompt¶

* 类型:字符串
* 必需:是
* 说明:期望生成图片的文本描述。
* dall-e-2 最大长度为 1000 字符
* gpt-image-1 最大长度为 32000 字符

##### mask¶

* 类型:文件
* 必需:否
* 说明:额外的图片,其完全透明区域(如 alpha 为零的区域)指示应该编辑的位置。如果提供了多个图片,mask 将应用于第一张图片。必须是有效的 PNG 文件,小于 4MB,且与 image 具有相同尺寸。

##### model¶

* 类型:字符串
* 必需:否
* 默认值:dall-e-2
* 说明:用于图像生成的模型。支持 dall-e-2 和 gpt-image-1。除非使用了 gpt-image-1 特有的参数,否则默认为 dall-e-2。

##### quality¶

* 类型:字符串或 null
* 必需:否
* 默认值:auto
* 说明:生成图片的质量。
* gpt-image-1 支持 high、medium 和 low
* dall-e-2 仅支持 standard
* 默认为 auto

##### size¶

* 类型:字符串或 null
* 必需:否
* 默认值:1024x1024
* 说明:生成图片的尺寸。
* gpt-image-1 必须是 1024x1024、1536x1024(横版)、1024x1536(竖版)或 auto(默认)之一
* dall-e-2 必须是 256x256、512x512 或 1024x1024 之一

其他参数与创建图片接口相同。

#### 生成变体¶

##### image¶

* 类型:文件
* 必需:是
* 说明:作为变体基础的图片。必须是有效的 PNG 文件,小于 4MB,且为正方形。

其他参数与创建图片接口相同。

## 📥 响应¶

### 成功响应¶

所有三个端点都返回包含图片对象列表的响应。

#### created¶

* 类型:整数
* 说明:响应创建的时间戳

#### data¶

* 类型:数组
* 说明:生成的图片对象列表

#### usage(仅适用于 gpt-image-1)¶

* 类型:对象
* 说明:API 调用的令牌使用情况
* total\_tokens:使用的总令牌数
* input\_tokens:输入使用的令牌数
* output\_tokens:输出使用的令牌数
* input\_tokens\_details:输入令牌的详细信息(文本令牌和图像令牌)

### 图片对象¶

#### b64\_json¶

* 类型:字符串
* 说明:如果 response\_format 为 b64\_json,则包含生成图片的 base64 编码 JSON

#### url¶

* 类型:字符串
* 说明:如果 response\_format 为 url(默认),则包含生成图片的 URL

#### revised\_prompt¶

* 类型:字符串
* 说明:如果提示有任何修改,则包含用于生成图片的修改后的提示

示例图片对象:

{ “url”: “https://…”, “revised_prompt”: “一只可爱的小海獭在水中嬉戏,它有着圆圆的眼睛和毛茸茸的皮毛” }


## 🌟 最佳实践¶

### Prompt 编写建议¶

1. 使用清晰具体的描述
2. 指定重要的视觉细节
3. 描述期望的艺术风格和氛围
4. 注意构图和视角的说明

### 参数选择建议¶

1. 模型选择
2. dall-e-3:适合需要高质量、精确细节的场景
3. dall-e-2:适合快速原型或简单图像生成
4. 尺寸选择
5. 1024x1024:通用场景的最佳选择
6. 1792x1024/1024x1536:适合横版/竖版场景
7. 较小尺寸:适合缩略图或快速预览
8. 质量和风格
9. quality=hd:用于需要精细细节的图像
10. style=vivid:适合创意和艺术效果
11. style=natural:适合真实场景再现

### 常见问题¶

1. 图片生成失败
2. 检查 prompt 是否符合内容政策
3. 确认文件格式和大小限制
4. 验证 API 密钥权限
5. 结果与预期不符
6. 优化 prompt 描述
7. 调整质量和风格参数
8. 考虑使用图片编辑或变体功能

## New API

🍥新一代大模型网关与AI资产管理系统

### 关于我们

* 关于项目
* 联系我们
* 功能特性

### 文档

* 快速开始
* 安装指南
* API 文档

### 相关项目

* One API
* Midjourney-Proxy
* chatnio
* neko-api-key-tool

### 基于New API的项目

* new-api-horizon
* VoAPI

Copyright © 2025 Quantum Nous. All Rights Reserved.

渝ICP备2025052930号

Made with ❤ by Quantum Nous

### 音频 (Audio)

OpenAI 格式 - New API Docs

跳转至

在 GitHub 上关注我们的最新动态或加入我们的 QQ 交流群

# OpenAI 音频格式¶

官方文档

OpenAI Audio

## 📝 简介¶

OpenAI 音频 API 提供了三个主要功能:

1. 文本转语音(TTS) - 将文本转换为自然的语音
2. 语音转文本(STT) - 将音频转录为文本
3. 音频翻译 - 将非英语音频翻译成英语文本

## 💡 请求示例¶

### 文本转语音 ✅¶

curl https://你的 newapi 服务器地址/v1/audio/speech \ -H “Authorization: Bearer $NEWAPI_API_KEY” \ -H “Content-Type: application/json” \ -d ‘{ “model”: “tts-1”, “input”: “你好,世界!”, “voice”: “alloy” }’ \ –output speech.mp3

1
2
3


### 语音转文本 ✅¶

curl https://你的 newapi 服务器地址/v1/audio/transcriptions \ -H “Authorization: Bearer $NEWAPI_API_KEY” \ -H “Content-Type: multipart/form-data” \ -F file=”@/path/to/file/audio.mp3” \ -F model=”whisper-1”

1
2
3


响应示例:

{ “text”: “你好,世界!” }

1
2
3


### 音频翻译 ✅¶

curl https://你的 newapi 服务器地址/v1/audio/translations \ -H “Authorization: Bearer $NEWAPI_API_KEY” \ -H “Content-Type: multipart/form-data” \ -F file=”@/path/to/file/chinese.mp3” \ -F model=”whisper-1”

1
2
3


响应示例:

{ “text”: “Hello, world!” }


## 📮 请求¶

### 端点¶

#### 文本转语音¶

POST /v1/audio/speech


将文本转换为语音。

#### 语音转文本¶

POST /v1/audio/transcriptions


将音频转录为输入语言的文本。

#### 音频翻译¶

POST /v1/audio/translations


将音频翻译为英语文本。

### 鉴权方法¶

在请求头中包含以下内容进行 API 密钥认证:

Authorization: Bearer $NEWAPI_API_KEY


其中 $NEWAPI\_API\_KEY 是您的 API 密钥。

### 请求体参数¶

#### 文本转语音¶

##### model¶

* 类型:字符串
* 必需:是
* 可选值:tts-1, tts-1-hd
* 说明:要使用的 TTS 模型

##### input¶

* 类型:字符串
* 必需:是
* 最大长度:4096 字符
* 说明:要转换为语音的文本

##### voice¶

* 类型:字符串
* 必需:是
* 可选值:alloy, echo, fable, onyx, nova, shimmer
* 说明:生成语音时使用的声音

##### response\_format¶

* 类型:字符串
* 必需:否
* 默认值:mp3
* 可选值:mp3, opus, aac, flac, wav, pcm
* 说明:音频输出格式

##### speed¶

* 类型:数字
* 必需:否
* 默认值:1.0
* 范围:0.25 - 4.0
* 说明:生成语音的速度

#### 语音转文本¶

##### file¶

* 类型:文件
* 必需:是
* 支持格式:flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, webm
* 说明:要转录的音频文件

##### model¶

* 类型:字符串
* 必需:是
* 当前仅支持:whisper-1
* 说明:要使用的模型 ID

##### language¶

* 类型:字符串
* 必需:否
* 格式:ISO-639-1 (如 "en")
* 说明:音频的语言,提供可提高准确性

##### prompt¶

* 类型:字符串
* 必需:否
* 说明:用于指导模型风格或继续前一段音频的文本

##### response\_format¶

* 类型:字符串
* 必需:否
* 默认值:json
* 可选值:json, text, srt, verbose\_json, vtt
* 说明:输出格式

##### temperature¶

* 类型:数字
* 必需:否
* 默认值:0
* 范围:0 - 1
* 说明:采样温度,较高的值使输出更随机

##### timestamp\_granularities¶

* 类型:数组
* 必需:否
* 默认值:segment
* 可选值:word, segment
* 说明:转录的时间戳粒度

#### 音频翻译¶

##### file¶

* 类型:文件
* 必需:是
* 支持格式:flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, webm
* 说明:要翻译的音频文件

##### model¶

* 类型:字符串
* 必需:是
* 当前仅支持:whisper-1
* 说明:要使用的模型 ID

##### prompt¶

* 类型:字符串
* 必需:否
* 说明:用于指导模型风格的英文文本

##### response\_format¶

* 类型:字符串
* 必需:否
* 默认值:json
* 可选值:json, text, srt, verbose\_json, vtt
* 说明:输出格式

##### temperature¶

* 类型:数字
* 必需:否
* 默认值:0
* 范围:0 - 1
* 说明:采样温度,较高的值使输出更随机

## 📥 响应¶

### 成功响应¶

#### 文本转语音¶

返回二进制音频文件内容。

#### 语音转文本¶

##### 基础 JSON 格式¶

{ “text”: “转录的文本内容” }

1
2
3


##### 详细 JSON 格式¶

{ “task”: “transcribe”, “language”: “english”, “duration”: 8.47, “text”: “完整的转录文本”, “segments”: [ { “id”: 0, “seek”: 0, “start”: 0.0, “end”: 3.32, “text”: “分段的转录文本”, “tokens”: [50364, 440, 7534], “temperature”: 0.0, “avg_logprob”: -0.286, “compression_ratio”: 1.236, “no_speech_prob”: 0.009 } ] }

1
2
3


#### 音频翻译¶

{ “text”: “翻译后的英文文本” }


### 错误响应¶

当请求出现问题时,API 将返回一个错误响应对象,HTTP 状态码在 4XX-5XX 范围内。

#### 常见错误状态码¶

* 400 Bad Request: 请求参数无效
* 401 Unauthorized: API 密钥无效或未提供
* 429 Too Many Requests: 超出 API 调用限制
* 500 Internal Server Error: 服务器内部错误

错误响应示例:

{ “error”: { “message”: “文件格式不支持”, “type”: “invalid_request_error”, “param”: “file”, “code”: “invalid_file_format” } }


## New API

🍥新一代大模型网关与AI资产管理系统

### 关于我们

* 关于项目
* 联系我们
* 功能特性

### 文档

* 快速开始
* 安装指南
* API 文档

### 相关项目

* One API
* Midjourney-Proxy
* chatnio
* neko-api-key-tool

### 基于New API的项目

* new-api-horizon
* VoAPI

Copyright © 2025 Quantum Nous. All Rights Reserved.

渝ICP备2025052930号

Made with ❤ by Quantum Nous

### 音乐 (Music)

## 功能支持标识说明

* ✅ 已支持: 该功能已经完全实现并可以使用
* ❌ 未支持: 该功能正在开发中或计划开发

中继接口 API 文档

接口列表

聊天 (Chat)

OpenAI 格式 (Chat Completions)

Anthropic 格式 (Messages)

messages.role

messages.content

文本内容 (Text)

图片内容 (Image)

工具使用 (Tool Use)

工具结果 (Tool Result)

文档 (Document)

1. 启用模式

2. 禁用模式

1. Auto 模式 (自动选择)

2. Any 模式 (任意工具)

3. Tool 模式 (指定工具)

1. 自定义工具(Tool)

2. 计算机工具 (ComputerUseTool)

3. Bash 工具 (BashTool)

4. 文本编辑器工具 (TextEditor)

第一轮对话

第二轮对话 - 只拼接最终回答 content

第一轮对话

第二轮对话 - 只拼接最终回答 content