POST

https://maas-api.cn-huabei-1.xf-yun.com/v1/responses

API Key：点击 API调用 / APIKEY管理 界面获取，示例：ak-f30b1********fc84b82e86a

Model：点击 API调用 获取，示例：spark-x2.6

1 请求参数

model

string必填

可选值：spark-x2.6 / spark-x2.6-4b / spark-x2.6-preview / spark-x2.5 / spark-x2.5-4b / spark-x2.5-1.7b

指定用于生成响应的模型 ID。

input

string / array必填

可选值：字符串或输入项数组

模型输入。字符串形式用于直接传入文本；数组形式用于传入结构化输入项。当前服务支持的数组项可包含 message、function_call、tool_search 等类型。

instructions

string可选

插入模型上下文中的系统级或开发者级指令，用于约束模型整体行为。

stream

boolean可选

可选值：true / false

默认值：false

是否开启流式响应。设为 true 时，服务端通过 SSE 按事件持续返回响应增量。

tools

array可选

可选值：工具定义数组

模型在生成响应过程中可以调用的工具集合。

type

string必填

可选值：function / web_search

函数工具使用 function；内置网络搜索使用 web_search。

tool_choice

string / object可选

可选值：none / auto / required / 指定工具对象

默认值：auto

控制模型如何选择工具。none 表示不调用工具；auto 表示模型自行决定是否调用；required 表示必须调用一个或多个工具；对象形式可用于指定或限制具体工具。

reasoning

string / object可选

推理配置，用于控制模型在生成最终输出前投入的推理程度。本服务兼容直接传入 effort 字符串，也支持对象形式。

effort

string可选

可选值：none / low / medium / high / max

控制推理强度。none：关闭思考；low：低推理强度；medium：中等推理强度；high：高推理强度；max：最高推理强度。

text

object可选

配置模型文本输出，包括普通文本或结构化 JSON 输出格式。

format

object可选

默认值：{"type": "text"}

指定模型必须生成的文本格式。支持普通文本、JSON Schema 结构化输出以及兼容的 JSON Object 模式。

type

string可选

可选值：text / json_schema / json_object

默认值：text

输出格式类型。text 为普通文本；json_schema 使用 JSON Schema 约束输出结构；json_object 为兼容的 JSON 模式，保证输出为合法 JSON，但不提供完整 Schema 约束。

name

string条件必填

说明：type=json_schema 时使用

结构化输出 Schema 的名称，用于标识当前 JSON Schema。

schema

object条件必填

可选值：合法 JSON Schema

type=json_schema 时用于描述模型输出必须遵循的 JSON 结构。

strict

boolean可选

可选值：true / false

type=json_schema 时控制是否严格遵循所提供的 JSON Schema。

max_output_tokens

integer可选

可选值：非负整数；具体最大值受模型最大输出长度限制

本次响应允许生成的 Token 数上限，包含最终可见输出 Token 和推理 Token。

temperature

number可选

可选值：1

默认值：1

仅固定值 1 生效，建议不要显式传入该参数。

top_p

number可选

可选值：0.95

默认值：0.95

仅固定值 0.95 生效，建议不要显式传入该参数。

user

string可选

终端用户的稳定标识，用于区分不同调用用户。该字段为兼容保留字段。

2 请求示例

CURL

curl https://maas-api.cn-huabei-1.xf-yun.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $APIKEY" \
  -d '{
    "model": "spark-x2.6",
    "input": "你好",
    "stream": false
  }'

Python

import requests

response = requests.post(
    "https://maas-api.cn-huabei-1.xf-yun.com/v1/responses",
    headers={
        "Authorization": "Bearer <你的 APIKEY>",
        "Content-Type": "application/json",
    },
    json={
        "model": "spark-x2.6",
        "input": "你好",
        "stream": False,
    },
)

print(response.json())

Go

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
)

func main() {
    body := map[string]any{
        "model": "spark-x2.6",
        "input": "你好",
        "stream": false,
    }

    data, err := json.Marshal(body)
    if err != nil {
        panic(err)
    }

    req, err := http.NewRequest(
        http.MethodPost,
        "https://maas-api.cn-huabei-1.xf-yun.com/v1/responses",
        bytes.NewReader(data),
    )
    if err != nil {
        panic(err)
    }

    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("Authorization", "Bearer <你的 APIKEY>")

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    result, err := io.ReadAll(resp.Body)
    if err != nil {
        panic(err)
    }

    fmt.Println(string(result))
}

Node.js

const response = await fetch("https://maas-api.cn-huabei-1.xf-yun.com/v1/responses", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.APIKEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "spark-x2.6",
    input: "你好",
    stream: false,
  }),
});

console.log(await response.json());

3 响应

3.1 非流式

id

string

本次 Response 的唯一标识。

object

string

可选值：固定为 response

对象类型。

created_at

integer

Response 创建时间，Unix 时间戳，单位为秒。

status

string

可选值：completed / failed / in_progress / cancelled / queued / incomplete

Response 的生成状态。

model

string

实际用于生成响应的模型 ID。

output

array

模型生成的输出项数组。数组长度和各输出项顺序取决于实际模型响应，不应假设第一个输出项一定是 message 或固定按照某种类型顺序出现。

type

string

可选值：reasoning / message / function_call / tool_search_call

输出项类型。

id

string

当前输出项的唯一标识。

status

string

可选值：in_progress / completed / incomplete

当前输出项的状态。

summary

array

reasoning 类型输出中的推理摘要内容块数组。

type

string

可选值：固定为 summary_text

推理摘要块类型。

text

string

推理摘要文本。

role

string

可选值：固定为 assistant

message 类型输出的角色。

content

array

message 类型输出包含的内容块数组。

type

string

可选值：固定为 output_text

正文内容块类型。

text

string

模型生成的最终文本内容。

annotations

array

与输出文本关联的注解数组；无注解时为空数组。

call_id

string

工具调用关联 ID，用于关联 function_call / tool_search_call 与对应工具执行结果。

name

string

function_call 类型输出中模型选择调用的函数名称。

arguments

string / object

工具调用参数。function_call 通常为 JSON 字符串；tool_search_call 可返回结构化对象。

usage

object

本次响应的 Token 使用统计。

input_tokens

integer

输入消耗的 Token 数。

input_tokens_details

object

输入 Token 的详细统计信息。

cached_tokens

integer

输入 Token 中命中缓存的 Token 数。

output_tokens

integer

输出消耗的 Token 数，包含可见输出和推理相关 Token。

output_tokens_details

object

输出 Token 的详细统计信息。

reasoning_tokens

integer

输出 Token 中用于推理的 Token 数。

total_tokens

integer

输入与输出 Token 总数。

3.2 流式

type

string

当前 SSE 事件类型，例如 response.created、response.output_text.delta、response.completed。

output_index

integer

当前输出项在 response.output 数组中的索引，从 0 开始。不同输出项使用各自的索引，不应假设不同类型共享同一个索引。

item_id

string

当前输出项的唯一 ID，用于关联同一输出项的增量事件和完成事件。

content_index

integer

message.content 中内容块的索引，从 0 开始。

delta

string

当前事件携带的增量文本或增量参数片段，需要按对应索引顺序拼接。

part

object

内容块开始或完成事件中携带的完整内容块对象。

type

string

可选值：output_text / summary_text

内容块类型。

text

string

内容块中的完整文本。

response

object

response.created / response.in_progress / response.completed 等事件中携带的完整 Response 对象。

id

string

Response 唯一标识。

status

string

可选值：completed / failed / in_progress / cancelled / queued / incomplete

Response 状态。

model

string

实际用于生成响应的模型 ID。