OpenAPI 参考

Modelink API · 聊天与批量推理

Modelink 聊天对话与异步批量推理 API，涵盖 OpenAI 兼容 Chat Completions、Anthropic Messages、Vertex/Gemini 原厂协议及批量任务生命周期管理。所有请求均需使用 API Key 进行身份认证；Anthropic Messages 和 Vertex/Gemini 接口优先使用对应原厂请求头，同时兼容 Bearer Token。

版本 1.0.0

bypass Anthropic协议

POST

/bypass/anthropic/v1/messages

通过 Anthropic 原生协议直接调用 Claude 系列模型，支持联网搜索。

鉴权方式： 优先使用 Anthropic 官方格式 X-Api-Key: $ANTHROPIC_API_KEY；也兼容 Authorization: Bearer $ANTHROPIC_API_KEY。

支持的模型： 支持所有 Claude 模型。

认证方式

AnthropicApiKeyAuthAPI 密钥

Anthropic Messages 接口推荐按 Anthropic 官方格式，在 X-Api-Key 请求头中直接传入 API Key。

header 参数：X-Api-Key

BearerAuthBEARER

在 Authorization 请求头中传入 API Key 或访问令牌，格式：Bearer {token}。

Bearer 格式：JWT

请求体

请求体属性

modelstring, 必填
将用于完成提示的模型名称
max_tokensinteger, 必填
生成停止前的最大 token 数。注意：模型可能会在此最大值之前自然停止生成。
messagesobject[], 必填
输入消息数组。模型被训练为在交替的 user 和 assistant 角色对话轮次上运行。
- roleenum, 必填
  消息角色。如果最后一条是 assistant，模型将继续补全该内容。
  - user
  - assistant
- contentstring | object[], 必填
  消息内容。可以是纯文本字符串，也可以是多媒体/工具内容块数组。
  - anyOf[0]string
    可选。
  - anyOf[1]object[]
    typeenum, 必填
    内容块的类型。
    text
    image
    document
    tool_use
    tool_result
    textstring
    [text] 文本内容。
    sourceobject
    [image/document] 文件/图片来源（Base64 或 URL）。
    typeenum
    资源来源类型。base64 表示内联编码数据，url 表示远程资源地址。
    base64
    url
    media_typestring
    媒体类型，例如 image/jpeg, application/pdf 等。
    datastring
    Base64 编码的数据。
    urlstring
    内容的远程 URL。
    idstring
    [tool_use] 工具调用的唯一 ID。
    namestring
    [tool_use] 要调用的工具名称。
    inputobject
    [tool_use] 传递给工具的 JSON 输入参数。
    tool_use_idstring
    [tool_result] 对应的工具调用 ID。
    contentstring | string[]
    [tool_result] 工具执行返回的结果，可以是字符串或内容块数组。
    anyOf[0]string
    可选。
    anyOf[1]string[]
    可选。
    is_errorboolean
    [tool_result] 标识工具执行是否发生错误。
    cache_controlobject
    用于 Prompt Caching 的缓存断点控制。
    typeenum
    缓存控制类型，固定为 ephemeral。
    ephemeral
systemstring | object[]
系统提示词。用于为 Claude 提供上下文和指令（例如指定特定目标或角色）。
- anyOf[0]string
  可选。
- anyOf[1]object[]
  - typeenum
    系统内容块类型，固定为 text。
    text
  - textstring
    系统提示词文本。
  - cache_controlobject
    在该系统内容块后创建 Prompt Caching 缓存断点。
    typeenum
    缓存控制类型，固定为 ephemeral。
    ephemeral
thinkingobject
扩展思考 (Extended Thinking) 配置。开启后，模型会在最终回答前输出思考过程。要求 max_tokens 至少大于 budget_tokens。
- typeenum
  是否启用思考模式。
  - enabled
  - disabled
  - adaptive
- budget_tokensinteger
  分配给思考过程的最大 token 预算（必须 >= 1024 且小于 max_tokens）。
- displayenum
  控制思考内容的显示方式。summarized 为正常返回，omitted 为脱敏隐藏。
  - summarized
  - omitted
toolsobject[]
模型可使用的工具定义列表。可为自定义工具（name + input_schema）或 Anthropic 内置服务端工具（type + name）。内置服务端工具目前仅支持网络搜索工具 web_search。
- typestring
  内置服务端工具的类型标识（如 web_search_20260209）。自定义工具可省略。
- namestring, 必填
  工具的名称，模型调用时将使用此名称。
- descriptionstring
  工具功能的详细描述，帮助模型理解何时及如何使用该工具。
- input_schemaobject
  工具输入参数的 JSON Schema 定义（自定义工具必填；内置服务端工具无需提供）。
  - typestring
    JSON Schema 根类型，固定为 object。
    default: object
  - propertiesobject
    工具参数的属性定义；键为参数名，值为对应的 JSON Schema。
    additionalProperties: true
  - requiredstring[]
    调用工具时必须提供的参数名列表。
tool_choiceobject
指定模型应如何使用提供的工具。
- typeenum
  自动决定(auto)、必须使用任意一个(any)、必须使用指定工具(tool)或不使用(none)。
  - auto
  - any
  - tool
  - none
- namestring
  当 type 为 'tool' 时，指定强制模型使用的工具名称。
- disable_parallel_tool_useboolean
  是否禁用并行工具调用。默认为 false。
output_configobject
模型输出配置（例如强制 JSON 结构化输出）。
- effortenum
  生成投入的计算代价级别。
  - low
  - medium
  - high
  - max
- formatobject
  输出格式限制。
  - typeenum
    输出格式类型，使用 JSON Schema 约束时固定为 json_schema。
    json_schema
  - schemaobject
    要约束模型输出的 JSON Schema。
temperaturenumber
注入响应的随机性大小。默认为 1.0。范围从 0.0 到 1.0。
top_pnumber
核采样（Nucleus sampling）。建议仅修改 temperature 或 top_p 其一。
top_kinteger
仅从后续标记的顶级 K 个选项中进行采样。
streamboolean
是否使用 Server-Sent Events (SSE) 逐步流式传输响应。
stop_sequencesstring[]
自定义文本序列数组，遇到这些序列时模型将停止生成。
cache_controlobject
顶层缓存控制设置（自动应用于最后一个可缓存的块）。
- typeenum
  缓存控制类型，固定为 ephemeral。
  - ephemeral
- ttlenum
  缓存生存时间，默认为 5m。
  - 5m
  - 1h
service_tierenum
服务层级。决定是使用优先容量（如果可用）还是标准容量。
- auto
- standard_only
metadataobject
关于请求的元数据。
- user_idstring
  与请求关联的用户的外部标识符（不应包含 PII 数据）。
containerstring
代码执行工具（Code Execution Tool）使用的容器标识符，用于在多次请求间复用会话状态。
inference_geostring
指定推理处理的地理区域（如果不指定，则使用工作区的 default_inference_geo）。

请求

POST/bypass/anthropic/v1/messages

curl https://api.qnaigc.com/bypass/anthropic/v1/messages \
  --request POST \
  --header 'X-Api-Key: YOUR_ANTHROPIC_API_KEY_AUTH' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "claude-sonnet-4-6",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "2026年5月最新手机GPU性能排行"
        }
      ]
    }
  ],
  "tools": [
    {
      "type": "web_search_20260209",
      "name": "web_search"
    }
  ],
  "max_tokens": 1024
}'

响应

object

响应.

响应体属性

idstring, 必填
消息的唯一对象标识符（ID 的格式和长度可能会随时间发生变化）。
typeenum, 必填
对象类型。对于 Messages 接口，始终为 'message'。
- message
roleenum, 必填
生成消息的对话角色。对于响应，这始终是 'assistant'。
- assistant
modelstring, 必填
实际用于完成提示的模型名称（例如 claude-3-7-sonnet-20250219）。
contentobject[], 必填
模型生成的内容。这是一个内容块数组，每个内容块都有一个决定其形状的 type。可能包含文本、思考过程或工具调用指令。
- typeenum, 必填
  响应内容块的类型。
  - text
  - thinking
  - redacted_thinking
  - tool_use
  - server_tool_use
  - container_upload
- textstring
  [text] 模型生成的普通文本回复。
- citationsobject[]
  [text] 支持文本块的引用信息（通常在开启文档或网页搜索引用时返回）。
  - typeenum
    char_location
    page_location
    content_block_location
    web_search_result_location
    search_result_location
  - cited_textstring
    引用的具体文本内容。
- thinkingstring
  [thinking] 模型在给出最终回答前的内部推理和思考过程（仅在请求中开启 thinking 时返回）。
- signaturestring
  [thinking] 思考块的签名，用于多轮对话中维持连贯性校验。
- datastring
  [redacted_thinking] 被脱敏/隐藏的思考内容数据（当 display 设置为 omitted 时返回）。
- idstring
  [tool_use/server_tool_use] 工具调用的唯一 ID。稍后返回工具结果时需带上此 ID。
- namestring
  [tool_use/server_tool_use] 模型决定调用的工具名称（自定义工具名，或内置服务端工具 web_search）。
- inputobject
  [tool_use/server_tool_use] 模型生成的，用于传递给工具的 JSON 格式输入参数。
- callerobject
  [tool_use/server_tool_use] 标识工具调用的发起者（直接来自模型，或由服务器端工具生成）。
  - typestring
    发起者类型：direct 表示模型直接发起，其余为服务端工具发起。
- file_idstring
  [container_upload] 上传到容器中的文件的标识符。
stop_reasonenum, 必填
模型停止生成的原因。end_turn(自然结束), max_tokens(达到长度限制), stop_sequence(触发停止词), tool_use(需要调用工具), pause_turn(长任务暂停), refusal(安全策略拒绝)。注：流式传输中间可能为 null。
- end_turn
- max_tokens
- stop_sequence
- tool_use
- pause_turn
- refusal
- null
stop_sequencestring
触发停止生成的具体自定义停止序列（如果 stop_reason 为 'stop_sequence'，则此字段非空）。
usageobject, 必填
计费与速率限制使用情况（Token 消耗详情）。字段映射与对账方法见 Usage 字段与计费对账。
- input_tokensinteger, 必填
  实际使用的未缓存输入 Token 数量。
- output_tokensinteger, 必填
  生成的输出 Token 数量（包括思考 token 和工具调用 token）。
- cache_creation_input_tokensinteger
  用于创建新缓存条目的输入 Token 数量（用于 Prompt Caching）。
- cache_read_input_tokensinteger
  从现有缓存中成功读取的输入 Token 数量。
- cache_creationobject
  按 TTL（生存时间）划分的缓存 Token 详细细分。
  - ephemeral_5m_input_tokensinteger
    可选。
  - ephemeral_1h_input_tokensinteger
    可选。
- inference_geostring
  处理此请求的推理节点的地理区域。
- service_tierenum
  该请求使用的服务层级。
  - standard
  - priority
  - batch
- server_tool_useobject
  服务器工具（Server Tools）的调用请求次数统计。
  - web_search_requestsinteger
    可选。
  - web_fetch_requestsinteger
    可选。
containerobject
关于本次请求中使用的代码执行容器的信息（仅在使用代码执行工具时返回）。
- idstring
  容器的标识符，可用于后续请求复用上下文。
- expires_atstring
  容器状态将过期的时间。

响应

{
  "id": "string",
  "type": "message",
  "role": "assistant",
  "model": "string",
  "content": [
    {
      "type": "text",
      "text": "string",
      "citations": [
        "string"
      ],
      "thinking": "string",
      "signature": "string",
      "data": "string",
      "id": "string",
      "name": "string"
    }
  ],
  "stop_reason": "end_turn",
  "stop_sequence": "string",
  "usage": {
    "input_tokens": 42,
    "output_tokens": 42,
    "cache_creation_input_tokens": 42,
    "cache_read_input_tokens": 42,
    "cache_creation": {
      "ephemeral_5m_input_tokens": 42,
      "ephemeral_1h_input_tokens": 42
    },
    "inference_geo": "string",
    "service_tier": "standard",
    "server_tool_use": {
      "web_search_requests": 42,
      "web_fetch_requests": 42
    }
  }
}

bypass Vertex/Gemini协议

POST

/bypass/vertex/v1/models/{model}:{invokeFuncName}

通过 Vertex / Gemini 原生协议格式调用 Gemini 模型。

鉴权方式： 优先使用 Google 官方格式 X-Goog-Api-Key: $GOOGLE_API_KEY；也兼容 Authorization: Bearer $GOOGLE_API_KEY。

调用方式：

非流式：gemini-3.1-pro-preview:generateContent
流式：gemini-3.1-pro-preview:streamGenerateContent?alt=sse

联网搜索：在请求体中加入 "tools": [{"googleSearch": {}}]。

支持的模型： 支持所有 Gemini 模型。

认证方式

GoogleApiKeyAuthAPI 密钥

Vertex/Gemini 接口推荐按 Google 官方格式，在 X-Goog-Api-Key 请求头中直接传入 API Key。

header 参数：X-Goog-Api-Key

BearerAuthBEARER

在 Authorization 请求头中传入 API Key 或访问令牌，格式：Bearer {token}。

Bearer 格式：JWT

路径参数

Name
model
Type
string, 必填
Description
模型名称
Name
invokeFuncName
Type
string, 必填
Description
调用方法名称

请求体

请求体属性

contentsobject[], 必填
包含对话上下文和当前提示内容的数组。对于单轮对话，通常只包含一个元素。
- roleenum
  内容提供者的角色。通常为 'user' (用户) 或 'model' (模型)。如果是第一轮对话，可以省略（默认为 user）。
  - user
  - model
  - function
- partsobject[], 必填
  构成此内容的各个部分（例如文本、图像、视频等）。一个 content 可以包含多个 part。
  - textstring
    文本提示内容。
  - inlineDataobject
    内联的媒体数据（如 Base64 编码的图片或音频）。
    mimeTypestring, 必填
    数据的 MIME 类型，例如 'image/jpeg', 'image/png', 'video/mp4' 等。
    datastring, 必填
    基于 Base64 编码的原始数据。
  - fileDataobject
    存储在 Google Cloud Storage (GCS) 中的媒体文件引用。
    mimeTypestring, 必填
    文件的 MIME 类型。
    fileUristring, 必填
    GCS URI，例如 'gs://bucket-name/path/to/image.jpg'。
  - functionCallobject
    模型请求调用的函数（通常出现在 role='model' 的返回中，或用于提供历史上下文）。
    namestring
    要调用的函数名称。
    argsobject
    传递给函数的参数。
  - functionResponseobject
    函数执行后的返回结果（通常出现在 role='function' 的内容中）。
    namestring
    被调用的函数名称。
    responseobject
    函数的返回结果（JSON 对象）。
systemInstructionobject
系统指令（System Prompt），用于在对话开始前设定模型的行为、角色或规则。
- partsobject[]
  系统指令的内容片段。
  - textstring
    系统指令文本。
generationConfigobject
控制模型文本生成的参数配置。
- temperaturenumber
  控制输出的随机性。值越高（如 0.8）输出越具创造性，值越低（如 0.2）输出越集中和确定。范围通常为 0.0 到 2.0。
  minimum: 0
- topPnumber
  Nucleus 采样参数。模型考虑累积概率达到 topP 质量的 token。范围 0.0 到 1.0。
- topKinteger
  Top-k 采样参数。模型从概率最高的 topK 个 token 中进行下一步选择。
- maxOutputTokensinteger
  模型单次响应生成的最大 Token 数量。
- candidateCountinteger
  要生成的响应候选数量。目前通常仅支持 1。
- stopSequencesstring[]
  停止序列。当模型生成这些字符串之一时，将停止继续生成内容。
- responseMimeTypestring
  指定模型输出的格式，例如 'application/json' 以强制模型输出 JSON 格式。
safetySettingsobject[]
内容安全过滤设置。
- categoryenum, 必填
  要拦截的安全类别。
  - HARM_CATEGORY_HARASSMENT
  - HARM_CATEGORY_HATE_SPEECH
  - HARM_CATEGORY_SEXUALLY_EXPLICIT
  - HARM_CATEGORY_DANGEROUS_CONTENT
- thresholdenum, 必填
  触发拦截的阈值级别。
  - HARM_BLOCK_THRESHOLD_UNSPECIFIED
  - BLOCK_LOW_AND_ABOVE
  - BLOCK_MEDIUM_AND_ABOVE
  - BLOCK_ONLY_HIGH
  - BLOCK_NONE
toolsobject[]
提供给模型使用的工具列表（如函数调用/Function Calling，或内置的 googleSearch 联网搜索工具）。
- functionDeclarationsobject[]
  模型可以调用的函数声明列表。
  - namestring, 必填
    函数名称（只能包含 a-z, A-Z, 0-9, 下划线和破折号）。
  - descriptionstring, 必填
    函数的详细描述，模型依赖此描述来决定何时以及如何调用该函数。
  - parametersobject
    函数的参数定义，采用 OpenAPI JSON Schema 格式。
- googleSearchobject
  启用 Gemini 内置的 Google 搜索联网工具，传入空对象即可开启。

请求

POST/bypass/vertex/v1/models/{model}:{invokeFuncName}

curl https://api.qnaigc.com/bypass/vertex/v1/models/{model}:{invokeFuncName} \
  --request POST \
  --header 'X-Goog-Api-Key: YOUR_GOOGLE_API_KEY_AUTH' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "Explain how AI works"
        }
      ]
    }
  ],
  "systemInstruction": {
    "parts": [
      {
        "text": "You are a helpful assistant."
      }
    ]
  },
  "generationConfig": {
    "temperature": 0.7,
    "topP": 0.9,
    "maxOutputTokens": 1024
  }
}'

响应

object

响应.

响应体属性

candidatesobject[]
模型生成的候选响应列表。通常情况下（candidateCount 默认为 1），这里只会有一个元素。
- contentobject, 必填
  模型实际生成的内容。
  - roleenum
    角色名称，对于模型的回复，这里固定为 'model'。
    model
  - partsobject[]
    模型生成的内容片段列表（可能包含文本或函数调用请求）。
    textstring
    模型生成的纯文本回复内容。
    functionCallobject
    如果模型决定调用外部函数，会返回此对象而不是文本。
    namestring
    模型要求调用的函数名称。
    argsobject
    模型解析出的，传递给该函数的 JSON 格式参数。
    inlineDataobject
    内联二进制数据（如图像生成模型返回的 base64 图像）。
    mimeTypestring
    可选。
    datastring
    base64 编码的数据。
    fileDataobject
    文件引用（如 GCS 文件 URI）。
    fileUristring
    可选。
    mimeTypestring
    可选。
- finishReasonenum
  模型停止生成内容的原因。
  - FINISH_REASON_UNSPECIFIED
  - STOP
  - MAX_TOKENS
  - SAFETY
  - RECITATION
  - OTHER
- safetyRatingsobject[]
  该生成内容的安全评级列表。针对不同的有害类别进行打分。
  - categoryenum
    安全评级类别（如仇恨言论、危险内容等）。
    HARM_CATEGORY_HARASSMENT
    HARM_CATEGORY_HATE_SPEECH
    HARM_CATEGORY_SEXUALLY_EXPLICIT
    HARM_CATEGORY_DANGEROUS_CONTENT
  - probabilityenum
    该类别违规的概率级别。
    HARM_PROBABILITY_UNSPECIFIED
    NEGLIGIBLE
    LOW
    MEDIUM
    HIGH
  - probabilityScorenumber
    该类别违规概率的具体分值 (0.0 - 1.0)。
  - severityenum
    该类别违规的严重程度级别。
    HARM_SEVERITY_UNSPECIFIED
    HARM_SEVERITY_NEGLIGIBLE
    HARM_SEVERITY_LOW
    HARM_SEVERITY_MEDIUM
    HARM_SEVERITY_HIGH
  - severityScorenumber
    严重程度的具体分值 (0.0 - 1.0)。
  - blockedboolean
    由于此项安全类别，内容是否被拦截。
- citationMetadataobject
  引用元数据。如果模型生成的文本直接引用了已有网页或来源，会在这里列出。
  - citationsobject[]
    具体的引用列表。
    startIndexinteger
    引用的文本在生成内容中的起始字符索引。
    endIndexinteger
    引用的文本在生成内容中的结束字符索引。
    uristring
    被引用源的 URI 链接。
    titlestring
    被引用源的标题。
    licensestring
    被引用源的许可证类型。
usageMetadataobject
当前请求的 Token 消耗统计信息，用于计费和配额评估。
- promptTokenCountinteger, 必填
  请求提示词（Input）消耗的 Token 数量。
- candidatesTokenCountinteger
  模型生成回复（Output）消耗的 Token 数量。
- totalTokenCountinteger, 必填
  总共消耗的 Token 数量 (Input + Output)。
promptFeedbackobject
对用户输入提示词的反馈（如果在输入阶段就被拦截，则此字段会说明原因）。
- blockReasonenum
  如果提示词被拦截，这里说明拦截原因。
  - BLOCK_REASON_UNSPECIFIED
  - SAFETY
  - OTHER
- safetyRatingsobject[]
  用户输入提示词的安全评级。
  - categoryenum
    安全评级类别（如仇恨言论、危险内容等）。
    HARM_CATEGORY_HARASSMENT
    HARM_CATEGORY_HATE_SPEECH
    HARM_CATEGORY_SEXUALLY_EXPLICIT
    HARM_CATEGORY_DANGEROUS_CONTENT
  - probabilityenum
    该类别违规的概率级别。
    HARM_PROBABILITY_UNSPECIFIED
    NEGLIGIBLE
    LOW
    MEDIUM
    HIGH
  - probabilityScorenumber
    该类别违规概率的具体分值 (0.0 - 1.0)。
  - severityenum
    该类别违规的严重程度级别。
    HARM_SEVERITY_UNSPECIFIED
    HARM_SEVERITY_NEGLIGIBLE
    HARM_SEVERITY_LOW
    HARM_SEVERITY_MEDIUM
    HARM_SEVERITY_HIGH
  - severityScorenumber
    严重程度的具体分值 (0.0 - 1.0)。
  - blockedboolean
    由于此项安全类别，内容是否被拦截。

响应

{
  "candidates": [
    {
      "content": {
        "role": "string",
        "parts": []
      },
      "finishReason": "FINISH_REASON_UNSPECIFIED",
      "safetyRatings": [
        "string"
      ],
      "citationMetadata": {
        "citations": []
      }
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 42,
    "candidatesTokenCount": 42,
    "totalTokenCount": 42
  },
  "promptFeedback": {
    "blockReason": "BLOCK_REASON_UNSPECIFIED",
    "safetyRatings": [
      {
        "category": "string",
        "probability": "string",
        "probabilityScore": 42,
        "severity": "string",
        "severityScore": 42,
        "blocked": true
      }
    ]
  }
}

bypass OpenAI Images 文生图

POST

/bypass/openai/v1/images/generations

使用 OpenAI Images 原厂协议创建图片，请求与响应保持原厂协议格式。支持 openai/gpt-image-2、openai/gpt-image-2.5-flare 和 openai/gpt-image-2.5-sunburst。GPT Image 2.5 支持 xhigh/max 质量档、background（含透明背景）和 output_compression；同步 Bypass 接口会原样透传这些字段。

除下方列出的常用字段外，也可以传递所选模型支持的其他 OpenAI Images 字段。

认证方式

BearerAuthBEARER

在 Authorization 请求头中传入 API Key 或访问令牌，格式：Bearer {token}。

Bearer 格式：JWT

请求体

请求体属性

modelstring, 必填
Modelink 模型名称。GPT Image 2 使用 openai/gpt-image-2；GPT Image 2.5 使用 openai/gpt-image-2.5-flare 或 openai/gpt-image-2.5-sunburst。
promptstring, 必填
图片生成提示词。GPT Image 系列最长 32000 个字符，其他模型以其自身限制为准。
backgroundstring
输出背景。GPT Image 2.5 可选 auto、transparent 或 opaque，其他模型以其自身支持范围为准。
ninteger
生成图片数量。
minimum: 1
output_formatstring
输出图片格式，例如 png、jpeg 或 webp；具体支持范围由模型决定。
output_compressioninteger
输出压缩率，范围 0～100。仅当 output_format 为 jpeg 或 webp 时可用。
minimum: 0; maximum: 100
qualitystring
输出质量。GPT Image 2 支持 auto、low、medium、high；GPT Image 2.5 额外支持 xhigh、max。
sizestring
输出尺寸，例如 1024x1024、1536x1024、1024x1536 或 auto；具体支持范围由模型决定。
streamboolean
是否以 Server-Sent Events 返回图片生成事件。
partial_imagesinteger
流式生成时返回的局部图片数量。
minimum: 0

请求

POST/bypass/openai/v1/images/generations

curl https://api.qnaigc.com/bypass/openai/v1/images/generations \
  --request POST \
  --header 'Authorization: Bearer YOUR_BEARER_AUTH' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "openai/gpt-image-2",
  "prompt": "一只橘猫坐在窗边，电影感光影",
  "size": "1024x1024",
  "quality": "high",
  "output_format": "png"
}'

响应

object

上游 OpenAI Images 响应；当 stream 为 true 时返回 SSE 事件流。

响应体属性

createdinteger
响应创建时间的 Unix 时间戳。
dataobject[]
- b64_jsonstring
  图片的 base64 数据。
- urlstring<uri>
  上游返回的图片地址。
usageobject
上游返回的原生用量字段。
additionalProperties: true

响应

{
  "created": 42,
  "data": [
    {
      "b64_json": "string",
      "url": "string"
    }
  ],
  "usage": {}
}

bypass OpenAI Images 图片编辑

POST

/bypass/openai/v1/images/edits

使用 OpenAI Images 原厂协议编辑图片。支持 OpenAI SDK 常用的 multipart/form-data，也支持 JSON 请求，请求与响应保持原厂协议格式。支持 openai/gpt-image-2、openai/gpt-image-2.5-flare 和 openai/gpt-image-2.5-sunburst。GPT Image 2.5 支持 xhigh/max 质量档、background（含透明背景）和 output_compression；同步 Bypass 接口会原样透传这些字段。

除下方列出的常用字段外，也可以传递所选模型支持的其他 OpenAI Images 字段。

认证方式

BearerAuthBEARER

在 Authorization 请求头中传入 API Key 或访问令牌，格式：Bearer {token}。

Bearer 格式：JWT

请求体

请求体属性

allOf[0]object
OpenAI Images 原厂文生图请求。GPT Image 2.5 支持 xhigh/max 质量档、background 和 output_compression；未列出的上游扩展字段也会透传。
additionalProperties: true
- modelstring, 必填
  Modelink 模型名称。GPT Image 2 使用 openai/gpt-image-2；GPT Image 2.5 使用 openai/gpt-image-2.5-flare 或 openai/gpt-image-2.5-sunburst。
- promptstring, 必填
  图片生成提示词。GPT Image 系列最长 32000 个字符，其他模型以其自身限制为准。
- backgroundstring
  输出背景。GPT Image 2.5 可选 auto、transparent 或 opaque，其他模型以其自身支持范围为准。
- ninteger
  生成图片数量。
  minimum: 1
- output_formatstring
  输出图片格式，例如 png、jpeg 或 webp；具体支持范围由模型决定。
- output_compressioninteger
  输出压缩率，范围 0～100。仅当 output_format 为 jpeg 或 webp 时可用。
  minimum: 0; maximum: 100
- qualitystring
  输出质量。GPT Image 2 支持 auto、low、medium、high；GPT Image 2.5 额外支持 xhigh、max。
- sizestring
  输出尺寸，例如 1024x1024、1536x1024、1024x1536 或 auto；具体支持范围由模型决定。
- streamboolean
  是否以 Server-Sent Events 返回图片生成事件。
- partial_imagesinteger
  流式生成时返回的局部图片数量。
  minimum: 0
allOf[1]
JSON 图片编辑请求，支持 image、images、mask 及所选模型提供的其他字段。GPT Image 2.5 最多支持 16 张参考图片，并支持 xhigh/max、透明背景和输出压缩。
additionalProperties: true
- image
  输入图片，格式由所选上游支持的 OpenAI Images 协议决定。
- images
  多图片输入或上游兼容字段。
- mask
  可选遮罩图片。
- anyOf[0]
  可选。
- anyOf[1]
  可选。

请求

POST/bypass/openai/v1/images/edits

curl https://api.qnaigc.com/bypass/openai/v1/images/edits \
  --request POST \
  --header 'Authorization: Bearer YOUR_BEARER_AUTH' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "openai/gpt-image-2",
  "prompt": "把背景改成日落海滩",
  "image": [
    {
      "image_url": "https://example.com/source.png"
    }
  ],
  "quality": "high"
}'

响应

object

上游 OpenAI Images 响应；当 stream 为 true 时返回 SSE 事件流。

响应体属性

createdinteger
响应创建时间的 Unix 时间戳。
dataobject[]
- b64_jsonstring
  图片的 base64 数据。
- urlstring<uri>
  上游返回的图片地址。
usageobject
上游返回的原生用量字段。
additionalProperties: true

响应

{
  "created": 42,
  "data": [
    {
      "b64_json": "string",
      "url": "string"
    }
  ],
  "usage": {}
}

bypass Responses协议

POST

/bypass/openai/v1/responses

通过 OpenAI Responses API 协议直接调用 GPT 系列模型，支持联网搜索。

支持的模型： 支持所有 GPT 模型。

认证方式

BearerAuthBEARER

在 Authorization 请求头中传入 API Key 或访问令牌，格式：Bearer {token}。

Bearer 格式：JWT

请求体

请求体属性

backgroundboolean
是否在后台运行模型响应。
context_managementobject[]
此请求的上下文管理配置。
- typestring, 必填
  上下文管理条目类型。目前仅支持 'compaction'（压缩）。
- compact_thresholdnumber
  触发此条目压缩的 Token 阈值。
conversationstring | object
该响应所属的对话。来自此对话的项目会附加到 input_items 前，响应完成后输入输出项目会自动加入此对话。
- anyOf[0]string
  对话的唯一 ID。
- anyOf[1]object
  - idstring, 必填
    对话的唯一 ID。
includeenum[]
指定要包含在模型响应中的附加输出数据。
- file_search_call.results
- web_search_call.results
- web_search_call.action.sources
- message.input_image.image_url
- computer_call_output.output.image_url
- code_interpreter_call.outputs
- reasoning.encrypted_content
- message.output_text.logprobs
inputstring | object[]
输入给模型的文本、图像或文件，用于生成响应。
- anyOf[0]string
  作为用户角色的纯文本输入。
- anyOf[1]object[]
  包含不同内容类型的一个或多个输入项列表。
  - roleenum
    消息输入的角色。
    user
    assistant
    system
    developer
  - contentstring | object[]
    用于生成响应的文本、图像或音频输入。
    anyOf[0]string
    可选。
    anyOf[1]object[]
    typestring
    内容类型，例如 'input_text', 'input_image', 'input_file' 等。
    textstring
    输入文本内容。
    image_urlstring
    输入图片 URL。
    file_idstring
    已上传文件的唯一 ID。
  - typestring
    输入类型，默认为 'message'。
    default: message
  - phaseenum
    将助手消息标记为中间评论或最终答案（针对后续重试）。
    commentary
    final_answer
  - statusenum
    项目状态。
    in_progress
    completed
    incomplete
instructionsstring
插入模型上下文的系统（或开发者）消息。当与 previous_response_id 一起使用时，可以轻松替换新响应的系统消息。
max_output_tokensnumber
响应可生成的 Token 数量上限（包括可见输出 Token 和推理 Token）。
max_tool_callsnumber
响应中可处理的内置工具调用的最大总数。
metadataobject
最多 16 个键值对的元数据，附加到对象上，键最大长度 64，值最大长度 512。
- *string
  可选。
modelstring
用于生成响应的模型 ID，如 gpt-4o, o3, gpt-5.1 等。
parallel_tool_callsboolean
是否允许模型并行执行工具调用。
previous_response_idstring
用于创建多轮对话的模型上一次响应的唯一 ID。不可与 conversation 同时使用。
promptobject
对提示模板及其变量的引用。
- idstring, 必填
  要使用的提示模板的唯一标识符。
- variablesobject
  可选的值映射，用于替换提示中的变量。值可以是字符串、图像或文件对象。
- versionstring
  提示模板的预期版本。
prompt_cache_keystring
用于缓存相似请求的响应，以优化缓存命中率。取代原本的 user 字段。
prompt_cache_retentionenum
提示缓存的保留策略。设置为 24h 可启用长达 24 小时的扩展缓存。
- in-memory
- 24h
reasoningobject
推理模型的配置选项（仅限 gpt-5 和 o 系列模型）。
- effortenum
  限制推理模型的推理努力程度。降低可加快响应速度并减少 Token 使用。
  - none
  - minimal
  - low
  - medium
  - high
  - xhigh
- summaryenum
  模型执行的推理摘要策略，可用于调试。包括 auto、concise 或 detailed。
  - auto
  - concise
  - detailed
safety_identifierstring
一个稳定的用户标识符，用于帮助检测可能违反 OpenAI 政策的用户应用程序（建议传入经过 Hash 的值，最长 64 个字符）。
service_tierenum
指定用于处理请求的服务层级。
- auto
- default
- flex
- scale
- priority
storeboolean
是否存储生成的模型响应，以便后续通过 API 检索。
streamboolean
如果设置为 true，模型响应数据将使用服务器发送事件 (SSE) 流式传输到客户端。
stream_optionsobject
仅当 stream: true 时设置的流选项。
- include_obfuscationboolean
  当为 true 时，启用流混淆以缓解旁路攻击。如果网络可信，可将其设置为 false 优化带宽。
temperaturenumber
采样温度，介于 0 和 2 之间。较高的值（如 0.8）输出更随机，较低的值（如 0.2）更集中和确定。建议更改此值或 top_p，不要同时更改。
textobject
模型文本响应的配置选项。
- formatobject
  指定模型必须输出的格式。
  - typeenum, 必填
    响应格式类型。推荐需要结构化数据时使用 json_schema。
    text
    json_schema
    json_object
  - namestring
    响应格式的名称（针对 json_schema）。
  - schemaobject
    JSON Schema 对象（针对 json_schema）。
  - descriptionstring
    格式的用途说明。
  - strictboolean
    是否启用严格的 Schema 校验遵守。
- verbosityenum
  限制模型响应的详细程度。较低的值产生更简明的响应。
  - low
  - medium
  - high
tool_choiceenum | object
模型在生成响应时应如何选择使用哪个（或哪些）工具。
- anyOf[0]enum
  none: 不调用工具; auto: 模型自行决定; required: 必须调用工具。
  - none
  - auto
  - required
- anyOf[1]object
  强制模型调用特定工具的配置。
  - typestring, 必填
    要使用的工具类型，如 'function', 'file_search', 'computer', 'mcp' 等。
  - namestring
    要调用的函数或自定义工具的名称。
  - server_labelstring
    要使用的 MCP 服务器标签。
toolsobject[]
模型在生成响应时可以调用的工具数组。包括内置工具、MCP 工具、函数调用（自定义工具）等。
- typeenum, 必填
  工具的类别。
  - function
  - file_search
  - computer
  - computer_use_preview
  - web_search
  - mcp
  - code_interpreter
  - image_generation
  - local_shell
  - shell
  - custom
  - namespace
  - tool_search
  - web_search_preview
  - apply_patch
- namestring
  工具/函数的名称（针对 function, custom 等）。
- descriptionstring
  向模型展示的工具描述。
- parametersobject
  描述函数参数的 JSON Schema 对象（针对 function 工具）。
- strictboolean
  是否对参数进行严格验证。
- defer_loadingboolean
  该工具是否通过工具搜索延迟加载。
- server_labelstring
  MCP 服务器的标签（针对 mcp 工具）。
- server_urlstring
  MCP 服务器的 URL。
- vector_store_idsstring[]
  要搜索的向量存储 ID 列表（针对 file_search 工具）。
top_logprobsnumber
一个介于 0 到 20 之间的整数，指定在每个位置返回的最可能 Token 的数量及其对数概率。
top_pnumber
核采样概率阈值（0.1 意味着仅考虑占前 10% 概率质量的 Token）。建议更改此值或 temperature，不要同时更改。
truncationenum
截断策略。'auto' 会在超过上下文窗口时从开头删除项目以适应窗口；'disabled' 则会报错（400）。
- auto
- disabled
userstring
最终用户的稳定标识符（即将被废弃，请使用 safety_identifier 和 prompt_cache_key）。

请求

POST/bypass/openai/v1/responses

curl https://api.qnaigc.com/bypass/openai/v1/responses \
  --request POST \
  --header 'Authorization: Bearer YOUR_BEARER_AUTH' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "openai/gpt-5.5",
  "input": "用一句话介绍你自己"
}'

响应

object

响应.

响应体属性

idstring, 必填
此响应的唯一标识符。
objectenum, 必填
此资源的对象类型，始终设置为 'response'。
- response
created_atnumber, 必填
创建此响应时的 Unix 时间戳（以秒为单位）。
completed_atnumber
完成此响应时的 Unix 时间戳（以秒为单位）。仅当状态为 'completed' 时存在。
statusenum
响应生成的状态。
- completed
- failed
- in_progress
- cancelled
- queued
- incomplete
errorobject
当模型无法生成响应时返回的错误对象。
- codestring
  响应的错误代码（如 server_error, rate_limit_exceeded, invalid_prompt 等）。
- messagestring
  人类可读的错误描述。
incomplete_detailsobject
有关响应为何不完整的详细信息。
- reasonenum
  响应不完整的原因。
  - max_output_tokens
  - content_filter
output_textstring
SDK 专用的便利属性，包含 output 数组中所有 output_text 项目的聚合文本输出（如果存在）。
outputobject[]
模型生成的内容项数组（顺序和长度取决于模型的响应）。
- idstring
  输出项目的唯一 ID。
- typestring
  输出项目类型（例如 'message', 'function_call', 'web_search_call', 'reasoning' 等）。
- statusstring
  该生成项的状态（例如 'in_progress', 'completed', 'incomplete'）。
- roleenum
  输出消息的角色，始终为 'assistant'（针对消息类型）。
  - assistant
- contentobject[]
  输出消息的内容（针对消息类型）。
  - typeenum
    output_text
    refusal
  - textstring
    模型输出的文本。
  - refusalstring
    模型的拒绝解释（如果是拒绝生成）。
- namestring
  运行的工具/函数名称（针对工具调用类型）。
- argumentsstring
  传递给工具的参数的 JSON 字符串（针对工具调用类型）。
- call_idstring
  工具调用的唯一 ID（针对工具调用类型）。
usageobject
表示 Token 使用情况的详细信息，包括输入、输出及总计。明细关系与对账方法见 Usage 字段与计费对账。
- input_tokensnumber
  输入 Token 数量。
- input_tokens_detailsobject
  - cached_tokensnumber
    从缓存中检索到的 Token 数量。
- output_tokensnumber
  输出 Token 数量。
- output_tokens_detailsobject
  - reasoning_tokensnumber
    推理 Token 数量。
- total_tokensnumber
  使用的 Token 总数。
conversationobject
此响应所属的对话上下文。
- idstring
  与此响应关联的对话唯一 ID。
previous_response_idstring
模型的上一个响应的唯一 ID。用于串联多轮对话。
modelstring
用于生成响应的实际模型 ID（例如 'gpt-4o', 'o3-mini' 等）。
instructionsstring
插入模型上下文的系统或开发者消息。
metadataobject
附加的键值对元数据。
- *string
  可选。
prompt_cache_keystring
用于优化缓存命中率的标识键。
prompt_cache_retentionstring
提示缓存的保留策略（如 'in-memory', '24h'）。
safety_identifierstring
用于检测违反政策用户的稳定标识符。
service_tierstring
实际用于处理请求的服务层级（如 'default', 'flex' 等）。该值可能与请求中设置的值不同。
parallel_tool_callsboolean
是否允许模型并行执行工具调用。
temperaturenumber
使用的采样温度。
top_pnumber
核采样概率。
top_logprobsnumber
指定在每个 Token 位置返回的最可能 Token 的数量。
max_output_tokensnumber
响应可生成的 Token 数量上限。
max_tool_callsnumber
响应中可处理的内置工具调用的最大总数。
truncationstring
截断策略 ('auto' 或 'disabled')。
userstring
最终用户的稳定标识符（即将被废弃）。
backgroundboolean
是否在后台运行模型响应。

响应

{
  "id": "string",
  "object": "response",
  "created_at": 42,
  "completed_at": 42,
  "status": "completed",
  "error": {
    "code": "string",
    "message": "string"
  },
  "incomplete_details": {
    "reason": "max_output_tokens"
  },
  "output_text": "string"
}

Chat Completions（对话补全）

POST

/v1/chat/completions

通用对话补全接口，兼容 OpenAI Chat Completions 协议，可通过请求体中的 model 字段切换底层模型（聊天、视觉、思考、文生图等）。支持流式输出、多模态输入（文本/图片/视频/文件/音频）、函数调用与结构化输出。

Gemini 生图：选择 Gemini 生图模型后，可通过同一接口完成文生图、图生图或纯对话。普通响应和 stream: true 的流式响应都在当前请求连接内返回结果；生成图片位于 message.images，推理过程位于 message.reasoning_content。使用 image_config 设置画幅比例和分辨率。

各模型的「思考 / 推理」开关方式不同，请按模型选择对应字段：

模型系列	控制字段	说明
Gemini 2.5 / 3.x	`reasoning_effort` 或 `thinking`	`reasoning_effort` 可选 `low`/`medium`/`high`；Gemini 3.1 Pro 仅支持这三档；Gemini 2.5 Pro 思考无法关闭
OpenAI GPT-5 / GPT-5.2	`reasoning_effort` 或 `reasoning`	`reasoning_effort` 可选 `low`/`medium`/`high`/`minimal`/`none`；GPT-5.2 推荐 `reasoning: {effort, summary}`，输出默认不展示思考内容
Claude 4.x	`thinking`	`{"type": "enabled", "budget_tokens": N}` 开启并设预算，`{"type": "disabled"}` 关闭
DeepSeek	`thinking`	`{"type": "enabled"}` 开启，`{"type": "disabled"}` 关闭
通义千问 Qwen3	`enable_thinking`	布尔值开关思考模式
豆包 Doubao	`thinking` / `enable_thinking`	通过 `thinking` 或 `chat_template_kwargs` 控制

多模态输入：在 messages[].content 中混合 text、image_url、file（视频/文档/音频）等类型；file_id 可填公网 URL、GCS URI、YouTube 链接或经文件接口上传得到的 qfile- 标识。

媒体理解分辨率：image_url.detail 对应 Gemini 的 media_resolution，支持 low/medium/high/ultra_high。

结构化输出：通过 response_format 指定 json_object 或带 json_schema 的结构化约束。

安全设置：Gemini 模型可通过 safety_settings 调整各危害类别的拦截阈值。

认证方式

BearerAuthBEARER

在 Authorization 请求头中传入 API Key 或访问令牌，格式：Bearer {token}。

Bearer 格式：JWT

请求体

请求体属性

modelstring, 必填
模型名称
messagesobject[], 必填
对话消息列表
- roleenum
  消息角色
  - system
  - user
  - assistant
  - function
  - tool
- contentstring | object[]
  消息内容，可以是字符串或内容对象数组
  - oneOf[0]string
    可选。
  - oneOf[1]object[]
    typeenum, 必填
    内容类型
    text
    image_url
    video_url
    file
    input_audio
    file_url
    video
    textstring | null
    文本内容
    image_urlobject
    图片URL对象
    urlstring
    图片URL地址
    detailenum
    图片细节级别
    auto
    low
    high
    video_urlobject
    视频URL对象
    urlstring
    视频URL地址
    fileobject
    文件对象
    file_datastring
    文件的 Base64 内联数据（与 file_id 二选一）。
    file_idstring
    文件标识：公网 URL、GCS URI、YouTube 链接，或文件接口返回的 qfile- 标识。
    formatstring
    文件的 MIME 类型，如 video/mp4、audio/mp3、application/pdf。
    detailstring | null
    处理详细程度，如 low、high、auto。
    video_metadataobject
    视频元数据，用于控制视频处理参数。
    fpsnumber | null
    视频帧率，有效范围 (0.0, 24.0]。
    start_offsetstring | null
    开始时间偏移，如 "30s"。
    end_offsetstring | null
    结束时间偏移，如 "60s"。
    input_audioobject
    音频输入对象
    datastring
    音频数据（base64编码）
    formatenum
    音频格式
    wav
    mp3
    ogg
    pcm
    videostring[]
    视频URL列表
    file_urlobject
    文件URL对象（支持docx/xlsx/pptx/pdf）
    urlstring
    文件URL地址
    detailstring | null
    文件详细级别
    thinkingstring
    思考内容
    signaturestring | null
    签名
    cache_controlobject
    缓存控制
    typestring
    缓存类型
    ttlstring
    缓存过期时间
- namestring | null
  函数名称或用户名称
- function_callobject
  函数调用信息（仅限role为function时填写）
  - namestring, 必填
    函数名称
  - argumentsstring, 必填
    函数参数（JSON字符串）
- tool_call_idstring | null
  工具调用ID（仅限role为tool时填写）
- tool_callsobject[]
  工具调用列表（仅限role为assistant时填写）
  - indexinteger | null
    调用索引
  - typeenum, 必填
    调用类型
    function
  - idstring, 必填
    调用ID
  - functionobject, 必填
    工具调用函数信息
    namestring
    函数名称
    argumentsstring
    函数参数（JSON字符串）
- reasoning_contentstring
  推理内容
- imagesobject[]
  图片列表
  - typestring
    图片类型
  - image_urlobject
    图片URL详情对象
    additionalProperties: true
    urlstring, 必填
    图片URL地址
  - indexinteger
    图片索引
- thinking_blocksobject[]
  思考块列表
  - typestring
    思考块类型
  - thinkingstring
    思考内容
  - signaturestring | null
    签名
streamboolean
是否使用流式响应
default: false
max_tokensinteger | null
生成的最大token数
presence_penaltynumber | null<float>
存在惩罚系数，范围 -2.0 到 2.0
minimum: -2; maximum: 2
frequency_penaltynumber | null<float>
频率惩罚系数，范围 -2.0 到 2.0
minimum: -2; maximum: 2
repetition_penaltynumber | null<float>
重复惩罚系数
temperaturenumber | null<float>
采样温度，范围 0.0 到 2.0
minimum: 0; maximum: 2
top_pnumber | null<float>
核采样参数，范围 0.0 到 1.0
minimum: 0; maximum: 1
top_kinteger | null
Top-K采样参数
toolsobject[]
函数工具列表
- typeenum, 必填
  工具类型
  - function
- functionobject, 必填
  工具函数定义
  - namestring, 必填
    函数名称
  - descriptionstring
    函数描述
  - urlstring | null
    函数URL
  - parametersobject, 必填
    工具参数定义
    typeenum
    参数类型
    object
    propertiesobject
    参数属性定义
    *object
    可选。
    propertyobject
    参数属性定义（备用字段）
    *object
    可选。
    requiredstring[]
    必填参数列表
tool_choiceobject
工具选择策略，可以是字符串或对象
typestring | null
请求类型
enable_thinkingboolean | null
是否启用思考模式
chat_template_kwargsobject
腾讯模型支持的聊天模板参数
- thinkingboolean
  腾讯DeepSeek思考参数
- enable_thinkingboolean
  是否启用思考模式
- thinking_budgetinteger
  思考token预算
thinkingobject
思考类型配置
- typeenum
  思考模式类型
  - disabled
  - enabled
  - auto
- budget_tokensinteger | null
  思考token预算
reasoningobject
推理配置
- effortenum
  推理强度
  - low
  - medium
  - high
- max_tokensinteger
  最大推理token数
- excludeboolean
  是否排除推理内容
- enabledboolean
  是否启用
reasoning_effortenum
推理强度
- low
- medium
- high
- minimal
- none
modalitiesstring[]
支持的模态类型列表
image_configobject
图像配置参数
- aspect_ratioenum
  图像宽高比，支持：1:1、1:4、1:8、3:2、2:3、3:4、4:1、4:3、4:5、5:4、8:1、9:16、16:9 和 21:9
  - 1:1
  - 1:4
  - 1:8
  - 2:3
  - 3:2
  - 3:4
  - 4:1
  - 4:3
  - 4:5
  - 5:4
  - 8:1
  - 9:16
  - 16:9
  - 21:9
- image_sizeenum
  图像分辨率，支持 512、1K、2K、4K
  - 512
  - 1K
  - 2K
  - 4K
response_formatobject
响应格式配置。type=json_schema 时通过 json_schema 指定结构化输出。
- typeenum
  响应格式类型。
  - text
  - json_object
  - json_schema
- json_schemaobject
  当 type=json_schema 时的结构定义。
  - namestring, 必填
    响应格式名称，供模型识别该结构。
  - descriptionstring
    结构化响应用途的说明，帮助模型理解输出目标。
  - schemaobject
    模型输出必须遵循的 JSON Schema。
    additionalProperties: true
  - strictboolean
    是否启用严格 Schema 遵循。启用后仅支持 JSON Schema 的受支持子集。
safety_settingsobject[]
Gemini安全设置列表
- categorystring, 必填
  危害类别
- thresholdenum, 必填
  阻止阈值
  - BLOCK_NONE
  - BLOCK_ONLY_HIGH
  - BLOCK_MEDIUM_AND_ABOVE
  - BLOCK_LOW_AND_ABOVE

请求

POST/v1/chat/completions

curl https://api.qnaigc.com/v1/chat/completions \
  --request POST \
  --header 'Authorization: Bearer YOUR_BEARER_AUTH' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "gemini-3.1-pro-preview",
  "messages": [
    {
      "content": [
        {
          "text": "什么是太阳",
          "type": "text"
        }
      ],
      "role": "user"
    }
  ]
}'

响应

object

请求成功

响应体属性

idstring
对话完成 ID
objectenum
对象类型
- chat.completion
createdinteger<int64>
响应创建时间戳（Unix 时间戳，秒）
modelstring
使用的模型名称
choicesobject[]
生成结果数组
- indexinteger
  结果索引
- messageobject
  - roleenum
    角色
    assistant
  - contentstring
    文本内容（如果只是聊天）
  - reasoning_contentstring
    模型的思考过程和推理内容
  - imagesobject[]
    生成的图像数组（如果有图像生成）
    typeenum
    图像类型
    image_url
    image_urlobject
    urlstring
    Base64 data URI 格式的图像数据
    indexinteger
    图像索引，从 0 开始
- finish_reasonstring
  完成原因，通常为 stop
usageobject
Token 使用统计信息。明细字段已包含在对应的顶层输入或输出总量中，不应重复相加；详见 Usage 字段与计费对账。
- prompt_tokensinteger
  输入 token 数
- completion_tokensinteger
  输出 token 数
- total_tokensinteger
  总 token 数
- prompt_tokens_detailsobject
  - text_tokensinteger
    文本 token 数
- completion_tokens_detailsobject
  - reasoning_tokensinteger
    推理 token 数
  - image_tokensinteger
    图像 token 数

响应

{
  "id": "chatcmpl-2f8236e9f2b34bd391289576d0e23e72",
  "object": "chat.completion",
  "created": 1764574464,
  "model": "gemini-3.1-flash-image-preview",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "",
        "reasoning_content": "**Analyzing the Icon Redesign**\n\nI'm focused on the icon's elements...",
        "images": [
          {
            "type": "image_url",
            "image_url": {
              "url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAABYAAAAMACAIAAAASU1SbA.........."
            },
            "index": 0
          }
        ]
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 19,
    "completion_tokens": 1322,
    "total_tokens": 1341,
    "prompt_tokens_details": {
      "text_tokens": 19
    },
    "completion_tokens_details": {
      "reasoning_tokens": 202,
      "image_tokens": 1120
    }
  }
}

Messages（Anthropic 消息协议）

POST

/v1/messages

兼容 Anthropic Messages 协议的对话接口，主要用于 Claude 系列模型。通过 thinking 字段控制扩展思考（{"type":"enabled","budget_tokens":N}），支持图片理解等多模态输入。

支持以下两种鉴权方式，任选其一；推荐使用 Anthropic 官方格式：

X-Api-Key: $ANTHROPIC_API_KEY（推荐）
Authorization: Bearer $ANTHROPIC_API_KEY

认证方式

AnthropicApiKeyAuthAPI 密钥

Anthropic Messages 接口推荐按 Anthropic 官方格式，在 X-Api-Key 请求头中直接传入 API Key。

header 参数：X-Api-Key

BearerAuthBEARER

在 Authorization 请求头中传入 API Key 或访问令牌，格式：Bearer {token}。

Bearer 格式：JWT

请求体

请求体属性

modelstring, 必填
用于生成回复的模型名称。
messagesobject[], 必填
输入消息数组。消息角色应在 user 与 assistant 之间交替；连续同角色消息会合并为一个对话轮次。
- roleenum
  消息角色。最后一条为 assistant 时，模型会从该内容后继续补全。
  - user
  - assistant
- contentstring | object[]
  消息内容：可为纯文本字符串，或内容块数组。
  - anyOf[0]string
    可选。
  - anyOf[1]object[]
    typeenum, 必填
    内容块类型。
    text
    image
    document
    tool_use
    tool_result
    textstring
    type=text 时的文本。
    sourceobject
    type=image/document 时的资源来源。
    typeenum
    资源来源类型。base64 表示内联编码数据，url 表示远程资源地址。
    base64
    url
    media_typestring
    Base64 资源的媒体类型，例如 image/jpeg 或 application/pdf。
    datastring
    base64 数据（type=base64 时）。
    urlstring
    资源 URL（type=url 时）。
max_tokensinteger, 必填
生成停止前的最大 token 数；模型可能在达到上限前自然停止。
minimum: 0
streamboolean
是否使用 Server-Sent Events 流式返回响应。
default: false
systemstring
系统提示词。
thinkingobject
扩展思考配置。
- typeenum
  思考模式。enabled 使用固定预算，disabled 关闭，adaptive 由模型动态决定。
  - enabled
  - disabled
  - adaptive
- budget_tokensinteger
  扩展思考的 token 预算。type=enabled 时使用，且应小于 max_tokens。
toolsobject[]
工具定义列表。
tool_choiceobject
工具选择策略。
temperaturenumber
采样温度，范围 0～1。通常只调整 temperature 或 top_p 其中一个。
minimum: 0; maximum: 1
top_pnumber
核采样累计概率阈值。通常只调整 temperature 或 top_p 其中一个。
minimum: 0; maximum: 1
top_kinteger
仅从概率最高的 K 个候选 token 中采样。
stop_sequencesstring[]
自定义停止序列；模型生成其中任一序列时停止。
metadataobject
请求元数据，例如用于滥用检测的外部 user_id；不应包含个人敏感信息。

请求

POST/v1/messages

curl https://api.qnaigc.com/v1/messages \
  --request POST \
  --header 'X-Api-Key: YOUR_ANTHROPIC_API_KEY_AUTH' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "claude-4.5-sonnet",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "你好"
        }
      ]
    }
  ],
  "max_tokens": 1024
}'

响应

object

响应.

响应体属性

idstring, 必填
必填。
typestring, 必填
必填。
rolestring, 必填
必填。
modelstring, 必填
必填。
contentobject[], 必填
响应内容块数组。
- typeenum, 必填
  内容块类型。
  - text
  - thinking
  - redacted_thinking
  - tool_use
  - server_tool_use
  - web_search_tool_result
- textstring
  type=text 时的文本。
- thinkingstring
  type=thinking 时的思考内容。
- signaturestring
  thinking 块的签名。
- datastring
  type=redacted_thinking 时的加密数据。
- idstring
  type=tool_use 时的工具调用 ID。
- namestring
  type=tool_use 时的工具名。
- inputobject
  type=tool_use 时的工具入参。
stop_reasonenum, 必填
停止原因。
- end_turn
- max_tokens
- stop_sequence
- tool_use
- pause_turn
- refusal
- null
usageobject, 必填
Anthropic Messages 格式的 Token 用量。字段映射与对账方法见 Usage 字段与计费对账。
- input_tokensinteger, 必填
  必填。
- output_tokensinteger, 必填
  必填。
- cache_read_input_tokensinteger
  可选。
- cache_creation_input_tokensinteger
  可选。

响应

{
  "id": "msg_f69c4d5d67c64d3bae8865537ee82ee8",
  "type": "message",
  "role": "assistant",
  "model": "claude-4.5-sonnet",
  "content": [
    {
      "type": "text",
      "text": "你好！很高兴见到你。有什么我可以帮助你的吗？"
    }
  ],
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 10,
    "output_tokens": 29,
    "cache_creation_input_tokens": 0
  }
}

创建批量推理任务

POSThttps://api.qnaigc.com

/v1/batchjob/inference

根据公开可访问的 JSONL 输入文件创建异步批量推理任务。接口在任务进入后台处理后立即返回任务 ID；后续可通过详情接口轮询任务状态。

国内模型的每行请求使用 body 包裹 OpenAI 风格消息结构，海外 Claude、Gemini 等模型使用 request 包裹对应厂商的原生请求结构。完整格式与限制请参阅批量任务推理指南。

认证方式

BearerAuthBEARER

在 Authorization 请求头中传入 API Key 或访问令牌，格式：Bearer {token}。

Bearer 格式：JWT

请求体

请求体属性

namestring, 必填
任务名称。
modelstring, 必填
控制台中支持 Batch 的模型 ID。国内与海外接入点支持的模型范围可能不同。
descriptionstring
任务描述。
default:
input_files_urlstring<uri>, 必填
服务端可公开访问的 JSONL 输入文件 URL，不能依赖 Cookie、登录态或内网访问。

请求

POST/v1/batchjob/inference

curl https://api.qnaigc.com/v1/batchjob/inference \
  --request POST \
  --header 'Authorization: Bearer YOUR_BEARER_AUTH' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "离线摘要任务",
  "model": "gemini-2.5-pro",
  "description": "2026-07 文档摘要",
  "input_files_url": "https://example.com/batch/input.jsonl"
}'

响应

object

任务创建成功并进入后台处理。

响应体属性

idstring, 必填
批量推理任务 ID，后续生命周期操作均需使用此 ID。
pattern: ^bat-.+$

响应

{
  "id": "bat-1753660800000000000-12345"
}

查询批量推理任务列表

GEThttps://api.qnaigc.com

/v1/batchjob/inferences

分页查询当前 API Key 所属用户创建且尚未删除的批量推理任务。

认证方式

BearerAuthBEARER

在 Authorization 请求头中传入 API Key 或访问令牌，格式：Bearer {token}。

Bearer 格式：JWT

查询参数

Name
page
Type
integer
Description
页码，从 1 开始。
Name
page_size
Type
integer
Description
每页任务数。

请求体

暂无请求体

请求

GET/v1/batchjob/inferences

curl 'https://api.qnaigc.com/v1/batchjob/inferences?page={page}&page_size={page_size}' \
  --header 'Authorization: Bearer YOUR_BEARER_AUTH' \
  --header 'Accept: application/json'

响应

object[]

成功返回任务列表。没有任务时返回空数组。

响应体属性

idstring, 必填
批量推理任务 ID。
namestring, 必填
任务名称。
modelstring, 必填
任务使用的模型 ID。
descriptionstring, 必填
任务描述。
input_files_urlstring<uri>, 必填
创建任务时提交的 JSONL 输入文件 URL。
output_files_urlstring, 必填
结果 JSONL 文件的临时下载地址。任务尚未完成时通常为空字符串。
statusenum, 必填
任务当前状态。文件同步阶段可能出现 SyncingInputFile 或 SyncingOutputFile 等中间状态。
- Initializing
- SyncingInputFile
- Uploading
- Queued
- Running
- SyncingOutputFile
- Completed
- Terminating
- Terminated
- Failed
- Unknown
status_messagestring, 必填
任务状态的补充说明。
request_progressobject
任务处理进度。任务尚未取得进度数据时不返回该字段。
- total_request_countsinteger<int64>
  输入文件中的请求总数。
  minimum: 0
- completed_request_countsinteger<int64>
  已处理完成的请求数。
  minimum: 0
- failed_request_countsinteger<int64>
  处理失败的请求数。部分供应商可能不提供该值。
  minimum: 0
created_atstring<date-time>, 必填
任务创建时间。
updated_atstring<date-time>, 必填
任务最后更新时间。

响应

[
  {
    "id": "bat-1753660800000000000-12345",
    "name": "离线摘要任务",
    "model": "gemini-2.5-pro",
    "description": "2026-07 文档摘要",
    "input_files_url": "https://example.com/batch/input.jsonl",
    "output_files_url": "",
    "status": "Running",
    "status_message": "任务运行中",
    "request_progress": {
      "total_request_counts": 1000,
      "completed_request_counts": 320,
      "failed_request_counts": 2
    },
    "created_at": "2026-07-28T09:00:00+08:00",
    "updated_at": "2026-07-28T09:05:00+08:00"
  }
]

查询批量推理任务

GEThttps://api.qnaigc.com

/v1/batchjob/inference/{id}

根据任务 ID 查询任务状态、处理进度和结果文件地址。任务完成后，output_files_url 会提供结果 JSONL 文件的临时下载地址。

认证方式

BearerAuthBEARER

在 Authorization 请求头中传入 API Key 或访问令牌，格式：Bearer {token}。

Bearer 格式：JWT

路径参数

Name
id
Type
string, 必填
Description
创建任务时返回的批量推理任务 ID。

请求体

暂无请求体

请求

GET/v1/batchjob/inference/{id}

curl https://api.qnaigc.com/v1/batchjob/inference/{id} \
  --header 'Authorization: Bearer YOUR_BEARER_AUTH' \
  --header 'Accept: application/json'

响应

object

成功返回任务详情。

响应体属性

idstring, 必填
批量推理任务 ID。
namestring, 必填
任务名称。
modelstring, 必填
任务使用的模型 ID。
descriptionstring, 必填
任务描述。
input_files_urlstring<uri>, 必填
创建任务时提交的 JSONL 输入文件 URL。
output_files_urlstring, 必填
结果 JSONL 文件的临时下载地址。任务尚未完成时通常为空字符串。
statusenum, 必填
任务当前状态。文件同步阶段可能出现 SyncingInputFile 或 SyncingOutputFile 等中间状态。
- Initializing
- SyncingInputFile
- Uploading
- Queued
- Running
- SyncingOutputFile
- Completed
- Terminating
- Terminated
- Failed
- Unknown
status_messagestring, 必填
任务状态的补充说明。
request_progressobject
任务处理进度。任务尚未取得进度数据时不返回该字段。
- total_request_countsinteger<int64>
  输入文件中的请求总数。
  minimum: 0
- completed_request_countsinteger<int64>
  已处理完成的请求数。
  minimum: 0
- failed_request_countsinteger<int64>
  处理失败的请求数。部分供应商可能不提供该值。
  minimum: 0
created_atstring<date-time>, 必填
任务创建时间。
updated_atstring<date-time>, 必填
任务最后更新时间。

响应

{
  "id": "bat-1753660800000000000-12345",
  "name": "离线摘要任务",
  "model": "gemini-2.5-pro",
  "description": "2026-07 文档摘要",
  "input_files_url": "https://example.com/batch/input.jsonl",
  "output_files_url": "",
  "status": "Running",
  "status_message": "任务运行中",
  "request_progress": {
    "total_request_counts": 1000,
    "completed_request_counts": 320,
    "failed_request_counts": 2
  },
  "created_at": "2026-07-28T09:00:00+08:00",
  "updated_at": "2026-07-28T09:05:00+08:00"
}

删除批量推理任务

DELETEhttps://api.qnaigc.com

/v1/batchjob/inference/{id}

删除指定任务及其任务记录。删除成功后，该任务不会再出现在列表和详情接口中。

认证方式

BearerAuthBEARER

在 Authorization 请求头中传入 API Key 或访问令牌，格式：Bearer {token}。

Bearer 格式：JWT

路径参数

Name
id
Type
string, 必填
Description
创建任务时返回的批量推理任务 ID。

请求体

暂无请求体

请求

DELETE/v1/batchjob/inference/{id}

curl https://api.qnaigc.com/v1/batchjob/inference/{id} \
  --request DELETE \
  --header 'Authorization: Bearer YOUR_BEARER_AUTH' \
  --header 'Accept: application/json'

响应

object

任务删除成功。

响应体属性

messagestring, 必填
操作结果消息。

响应

{
  "message": "delete_batch_inference_job_success"
}

停止批量推理任务

POSThttps://api.qnaigc.com

/v1/batchjob/inference/stop/{id}

停止尚未完成的批量推理任务。任务已停止、正在停止或已经失败时，接口返回状态冲突错误。

认证方式

BearerAuthBEARER

在 Authorization 请求头中传入 API Key 或访问令牌，格式：Bearer {token}。

Bearer 格式：JWT

路径参数

Name
id
Type
string, 必填
Description
创建任务时返回的批量推理任务 ID。

请求体

暂无请求体

请求

POST/v1/batchjob/inference/stop/{id}

curl https://api.qnaigc.com/v1/batchjob/inference/stop/{id} \
  --request POST \
  --header 'Authorization: Bearer YOUR_BEARER_AUTH' \
  --header 'Accept: application/json'

响应

object

认证失败，API Key 无效或缺失。

响应体属性

errorobject, 必填
- messagestring, 必填
  人类可读的错误描述。
- typestring, 必填
  机器可读的错误类型。

响应

{
  "error": {
    "message": "access denied for invalid api key",
    "type": "authentication_error"
  }
}

恢复批量推理任务

POSThttps://api.qnaigc.com

/v1/batchjob/inference/resume/{id}

恢复已停止或失败且允许恢复的批量推理任务。正在运行或已经完成的任务不能恢复。

认证方式

BearerAuthBEARER

在 Authorization 请求头中传入 API Key 或访问令牌，格式：Bearer {token}。

Bearer 格式：JWT

路径参数

Name
id
Type
string, 必填
Description
创建任务时返回的批量推理任务 ID。

请求体

暂无请求体

请求

POST/v1/batchjob/inference/resume/{id}

curl https://api.qnaigc.com/v1/batchjob/inference/resume/{id} \
  --request POST \
  --header 'Authorization: Bearer YOUR_BEARER_AUTH' \
  --header 'Accept: application/json'

响应

object

任务所用模型已下线。

响应体属性

errorobject, 必填
- messagestring, 必填
  人类可读的错误描述。
- typestring, 必填
  机器可读的错误类型。

响应

{
  "error": {
    "message": "string",
    "type": "string"
  }
}