最近更新：2026年4月24日 11:04

大模型 API 接入指南

本文说明如何把 NextAI Code 的文本、多模态、工具调用和流式输出接入到你的应用。

1. 选择端点

新项目优先使用 OpenAI Responses API。它是 OpenAI 当前统一的文本、图片、文件和工具调用接口。

POST https://www.nextai-code.com/v1/responses

如果你的 SDK、框架或第三方工具只支持 Chat Completions，继续使用 OpenAI Chat Completions 兼容协议。

POST https://www.nextai-code.com/v1/chat/completions

如果你的代码已经按 Anthropic Messages API 开发，使用 Anthropic Messages 官方协议。

POST https://www.nextai-code.com/v1/messages

所有协议都使用同一个 API Key。OpenAI 风格请求使用：

Authorization: Bearer YOUR_API_KEY

Anthropic 风格请求可以使用：

x-api-key: YOUR_API_KEY
anthropic-version: 2023-06-01

API Key 可在令牌管理页面创建。不要把真实 Key 写进前端代码、截图、日志或代码仓库。

2. 查询模型

模型会持续更新，请以模型列表接口返回为准。

curl "https://www.nextai-code.com/v1/models" \
  -H "Authorization: Bearer YOUR_API_KEY"

常见模型族：

OpenAI / OpenAI 兼容模型：gpt-*、o*
Claude 模型：claude-*
Gemini 模型：gemini-*
其他兼容模型：以模型列表接口返回为准

不是所有模型都支持图片、工具调用、推理参数或 Responses API。集成前先用目标模型做一次最小请求测试。

3. OpenAI Responses API

适合新项目。请求体使用 input 字段。

文本请求：

curl -X POST "https://www.nextai-code.com/v1/responses" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.2",
    "input": "用三句话介绍 NextAI Code"
  }'

图片输入请求：

curl -X POST "https://www.nextai-code.com/v1/responses" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.2",
    "input": [
      {
        "role": "user",
        "content": [
          {"type": "input_text", "text": "描述这张图片，并提取图片里的文字"},
          {"type": "input_image", "image_url": "https://example.com/image.png"}
        ]
      }
    ]
  }'

Base64 图片也可以用 Data URL：

{
  "type": "input_image",
  "image_url": "data:image/png;base64,BASE64_IMAGE_DATA"
}

流式输出：

curl -N -X POST "https://www.nextai-code.com/v1/responses" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.2",
    "input": "写一个 5 行的产品介绍",
    "stream": true
  }'

常用字段：

model：必填，模型名称。
input：必填，字符串或结构化输入。
instructions：系统级指令。
stream：是否流式输出。
max_output_tokens：最大输出 token。
reasoning.effort：推理强度，支持范围以具体模型为准。
tools：工具定义。需要内置工具时优先使用 Responses API。
previous_response_id：继续上一轮响应，适合有状态工作流。

4. OpenAI Chat Completions 兼容协议

适合已有 OpenAI Chat Completions 代码、老 SDK、第三方工具或只支持 /v1/chat/completions 的客户端。

文本请求：

curl -X POST "https://www.nextai-code.com/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {"role": "user", "content": "你好，介绍一下你自己"}
    ]
  }'

图片输入请求：

curl -X POST "https://www.nextai-code.com/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {
        "role": "user",
        "content": [
          {"type": "text", "text": "描述这张图片"},
          {
            "type": "image_url",
            "image_url": {
              "url": "https://example.com/image.png",
              "detail": "high"
            }
          }
        ]
      }
    ]
  }'

Base64 图片也使用 Data URL：

{
  "type": "image_url",
  "image_url": {
    "url": "data:image/jpeg;base64,BASE64_IMAGE_DATA",
    "detail": "high"
  }
}

工具调用请求：

{
  "model": "gpt-4o",
  "messages": [{"role": "user", "content": "北京天气如何？"}],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "获取天气信息",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {"type": "string", "description": "城市名"}
          },
          "required": ["location"]
        }
      }
    }
  ]
}

常用字段：

model：必填，模型名称。
messages：必填，对话消息数组。
stream：是否流式输出。
max_completion_tokens：最大输出 token。新模型优先使用它。
temperature / top_p：采样参数。推理模型可能不支持。
tools / tool_choice：工具定义和工具选择。
response_format：结构化输出。
reasoning_effort：部分推理模型支持。

Chat Completions 是兼容入口，不是新 OpenAI 集成的首选入口。新项目如果没有兼容性约束，建议使用 /v1/responses。

5. Anthropic Messages 官方协议

适合已有 Claude / Anthropic SDK 代码。请求体按 Anthropic Messages API 编写，Base URL 和 API Key 使用 NextAI Code。

文本请求：

curl -X POST "https://www.nextai-code.com/v1/messages" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "你好，介绍一下你自己"}
    ]
  }'

图片输入请求：

curl -X POST "https://www.nextai-code.com/v1/messages" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": [
          {"type": "text", "text": "描述这张图片"},
          {
            "type": "image",
            "source": {
              "type": "url",
              "url": "https://example.com/image.png"
            }
          }
        ]
      }
    ]
  }'

Base64 图片：

{
  "type": "image",
  "source": {
    "type": "base64",
    "media_type": "image/png",
    "data": "BASE64_IMAGE_DATA"
  }
}

Anthropic 格式和 OpenAI 格式的关键区别：

max_tokens 在 Anthropic Messages 中必填。
系统提示词使用独立的 system 字段。
图片使用 type: "image" 和 source。
工具 schema 字段叫 input_schema，不是 OpenAI 的 parameters。
停止原因字段是 stop_reason。

6. SDK 示例

OpenAI SDK 使用 Responses：

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://www.nextai-code.com/v1",
)

response = client.responses.create(
    model="gpt-5.2",
    input="用三句话介绍 NextAI Code",
)

print(response.output_text)

OpenAI SDK 使用 Chat Completions：

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://www.nextai-code.com/v1",
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "你好"}],
)

print(response.choices[0].message.content)

Anthropic SDK：

import anthropic

client = anthropic.Anthropic(
    api_key="YOUR_API_KEY",
    base_url="https://www.nextai-code.com",
)

message = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[{"role": "user", "content": "你好"}],
)

print(message.content[0].text)

7. 参数注意事项

图片输入不是图片生成。

本页的图片参数用于让模型“看图、理解图、提取图中信息”。如果你要生成图片或改图，请看图像生成与编辑 API。

不同协议的图片字段不同。

Responses：input[].content[] 中使用 type: "input_image"。
Chat Completions：messages[].content[] 中使用 type: "image_url"。
Anthropic Messages：messages[].content[] 中使用 type: "image" 和 source。

推理模型不要随便传采样参数。

部分推理模型不支持 temperature、top_p、presence_penalty、frequency_penalty、logprobs 等参数。遇到参数错误时，先删除采样参数，只保留 model、输入内容和 token 限制。

流式响应需要按 SSE 处理。

stream: true 返回的是 Server-Sent Events，不是一次性 JSON。客户端需要逐行读取 data: 事件。

8. 常见问题

新项目应该用 /v1/responses 还是 /v1/chat/completions？: 新项目优先使用 /v1/responses。如果你接入的是只支持 OpenAI Chat Completions 的 SDK、框架或第三方工具，再使用 /v1/chat/completions。

图片参数到底怎么传？: Responses 使用 input_image，Chat Completions 使用 image_url，Anthropic Messages 使用 image + source。图片 URL 可以是公网 URL，也可以是 data:image/png;base64,... 这种 Data URL。

为什么图片请求没有效果？: 先确认模型支持视觉输入，然后确认图片 URL 可公开访问，或改用 Data URL。不要把图片生成接口的参数传到 LLM 对话接口里。

为什么推理模型报参数不支持？: 推理模型通常对采样参数更严格。先删除 temperature、top_p、presence_penalty、frequency_penalty、logprobs 等参数，再逐个加回需要的字段。

为什么流式响应不能直接 JSON.parse？: 流式响应是 SSE 事件流，不是一个完整 JSON。客户端需要按行读取 data:，并处理结束事件。

大模型 API 接入指南

1. 选择端点

2. 查询模型

3. OpenAI Responses API

4. OpenAI Chat Completions 兼容协议

5. Anthropic Messages 官方协议

6. SDK 示例

7. 参数注意事项

8. 常见问题

官方参考