Documentation

SenseNova AI API 文档

SenseNova 提供与 OpenAI 完全兼容的大模型 API 服务，覆盖纯文本对话、工具调用、流式响应与多模态理解生成能力。以下文档涵盖所有核心接口、参数与行为规范。

Base URL · https://token.sensenova.cn/compatible-mode/v3/llm

快速开始

使用 SenseNova API 只需 3 步：

注册账号并完成手机号验证
在控制台 → API Keys 创建一枚 sn- 开头的密钥
替换 OpenAI SDK 的 base_url 为 SenseNova 地址，即可调用

Python

Node.js

cURL

from openai import OpenAI

client = OpenAI(
    base_url="https://token.sensenova.cn/compatible-mode/v3/llm",
    api_key="sn-xxxxxxxxxxxxxxxxxxxx",
)

resp = client.chat.completions.create(
    model="SenseNova-U1",
    messages=[{"role": "user", "content": "Hello!"}],
)

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

鉴权

所有 API 请求必须在 HTTP Header 中携带 Bearer Token：

Authorization: Bearer sn-xxxxxxxxxxxxxxxxxxxx

建议为不同应用/环境创建独立的 API Key，以便独立监控与轮换。密钥可在控制台随时注销。

模型总览

SenseNova 当前开放两款核心模型，均采用原生多模态架构，兼顾效果与成本，可稳定支撑数据分析、PPT 生成、深度调研报告、信息图生成等复杂长链路办公任务。

SenseNova U1 旗舰

多模态理解与生成一体的旗舰模型

理解生成一体，面向更高上限的多模态能力
多模态理解能力强，适合复杂内容解析
图像生成能力突出，支持更丰富的内容表达
更适合高质量内容生产与复杂任务场景

model ID: SenseNova-U1

SenseNova 6.7 Flash 高效

面向真实工作流的轻量多模态智能体模型

轻量高效，兼顾效果、成本与落地性
办公场景增强，稳定支撑复杂长链路任务
原生多模态架构，适合真实办公内容处理
Token 效率更优，复杂任务成本更可控

model ID: SenseNova-6.7-Flash

能力对比

能力	SenseNova U1	SenseNova 6.7 Flash
文本输入 / 文本输出	✅	✅
图像输入（image_url）	✅	—
图像输出（助手 images 字段）	✅	—
工具调用 / Function Calling	✅	✅
流式响应 (SSE)	✅	✅
JSON / Structured Output	✅	✅

SenseNova U1

SenseNova U1 是理解与生成一体的旗舰多模态模型，支持完整的图文输入与图文输出。

典型场景

深度调研报告、结构化长文生成
复杂图像理解（图表、票据、文档扫描件）
PPT、信息图、海报等图像内容生成
需要图文混合输出的办公/创作类任务

专属能力

image_config 图像生成配置（纵横比、分辨率、字体输入、超分辨率参考）
message.images 返回生成的图片列表

SenseNova 6.7 Flash

SenseNova 6.7 Flash 是面向真实办公工作流的轻量多模态智能体模型，Token 效率更优，适合对延迟与成本敏感的高频调用场景。

典型场景

办公助手、信息抽取、文档摘要
工具调用与 Agent 长链路任务编排
数据分析、结构化结果输出（JSON / 表格）
对吞吐与成本敏感的线上业务

输出形态 · 该模型主要返回文本内容，不直接生成图片；如需图像生成能力，请使用 SenseNova U1。

Chat Completions

兼容 OpenAI 协议，支持流式 / 非流式、工具调用、多模态输入输出、推理模式等能力。

POST https://token.sensenova.cn/compatible-mode/v3/llm/chat/completions

最小请求示例

{
  "model": "SenseNova-U1",
  "messages": [
    { "role": "system", "content": "你是一个有用的助手。" },
    { "role": "user",   "content": "介绍一下商汤科技。" }
  ],
  "temperature": 0.7,
  "stream": false
}

请求参数

以下参数在 SenseNova U1 与 SenseNova 6.7 Flash 上均稳定支持，行为与 OpenAI Chat Completions 一致。

字段	类型	必填	默认值	说明
`model`	string	✅	—	模型 ID，目前可选 `SenseNova-U1` / `SenseNova-6.7-Flash`
`messages`	array	✅	—	对话消息列表，role ∈ {`system`, `user`, `assistant`, `tool`}；`content` 可为字符串或内容块数组（见多模态）
`stream`	boolean	—	`false`	是否以 SSE (text/event-stream) 流式返回
`stream_options`	object	—	—	仅 `stream=true` 生效。含 `include_usage` (boolean)：最后一个 chunk 是否返回 usage
`temperature`	number	—	`1`	采样温度，范围 [0, 2]，越高越随机
`top_p`	number	—	`1`	核采样，范围 (0, 1]
`max_completion_tokens`	integer	—	—	单次生成的最大 token 数（包含可见输出与推理 token）
`max_tokens` 已废弃	integer	—	—	已废弃，请改用 `max_completion_tokens`
`n`	integer	—	`1`	生成回复数量，范围 [1, 10]
`stop`	string \| array	—	—	停止序列，字符串或字符串数组
`frequency_penalty`	number	—	`0`	频率惩罚，范围 [-2, 2]，越大越少重复
`presence_penalty`	number	—	`0`	存在惩罚，范围 [-2, 2]，越大越倾向新话题
`response_format`	object	—	—	响应格式。可选 `{"type":"text"}` / `{"type":"json_object"}` / `{"type":"json_schema", "json_schema":{...}}`
`tools`	array	—	—	可用工具列表，详见工具调用
`tool_choice`	string \| object	—	`"auto"`	工具选择策略，可为 `"auto"` / `"none"` / `"required"` 或指定工具对象
`parallel_tool_calls`	boolean	—	`true`	是否允许并行调用多个工具

响应结构

非流式请求直接返回 JSON；流式请求返回 SSE，每个 chunk 格式与下方 chunk 结构一致，末尾以 data: [DONE] 收尾。

非流式响应示例

{
  "id": "chatcmpl-8aBcD...",
  "object": "chat.completion",
  "created": 1713167890,
  "model": "SenseNova-U1",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "Hello! How can I help?"
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 8,
    "total_tokens": 20,
    "prompt_tokens_details": { "cached_tokens": 0 },
    "completion_tokens_details": { "reasoning_tokens": 0 }
  },
  "request_id": "req_01HR..."
}

choices[].finish_reason 枚举

value	含义
`stop`	正常结束
`length`	达到 max_completion_tokens 或上下文上限
`tool_calls`	模型选择调用工具
`content_filter`	内容被合规审核拦截
`function_call` 已废弃	旧版 function_call 语义

流式响应 (SSE)

当 stream=true 时，响应的 Content-Type 为 text/event-stream，每行以 data: {json} 的形式推送一个 chat.completion.chunk，最后以 data: [DONE] 结束。

完整流式样例

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","created":1713167890,"model":"SenseNova-U1","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]}

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}]}

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"! How can I help?"},"finish_reason":null}]}

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"usage":{"prompt_tokens":12,"completion_tokens":8,"total_tokens":20}}

data: [DONE]

usage 字段 · 仅在 stream_options.include_usage=true 时在最后一个 chunk 中返回。
断线重连 · 建议客户端实现指数退避重试，请求重放需避免重复计费场景。

工具调用 (Function Calling)

通过 tools 字段声明可用函数，模型会在需要时以 tool_calls 的形式返回调用请求。工具执行后，以 role="tool" 的消息把结果回传，再次请求即可获得最终答复。

请求示例

{
  "model": "SenseNova-6.7-Flash",
  "messages": [
    { "role": "user", "content": "今天上海天气怎么样？" }
  ],
  "tools": [{
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "Get current weather of a city",
      "parameters": {
        "type": "object",
        "properties": {
          "city": { "type": "string" }
        },
        "required": ["city"]
      }
    }
  }],
  "tool_choice": "auto"
}

模型返回 tool_calls

{
  "choices": [{
    "message": {
      "role": "assistant",
      "content": null,
      "tool_calls": [{
        "index": 0,
        "id": "call_abc123",
        "type": "function",
        "function": {
          "name": "get_weather",
          "arguments": "{\"city\": \"上海\"}"
        }
      }]
    },
    "finish_reason": "tool_calls"
  }]
}

回传工具结果

{
  "model": "SenseNova-6.7-Flash",
  "messages": [
    { "role": "user", "content": "今天上海天气怎么样？" },
    { "role": "assistant", "tool_calls": [ /* 上一步模型返回 */ ] },
    {
      "role": "tool",
      "tool_call_id": "call_abc123",
      "content": "{\"temp\": 22, \"desc\": \"多云\"}"
    }
  ]
}

图文输入输出

仅 SenseNova U1 支持图像输入与图像输出。在 messages[].content 中以内容块数组的形式传入图像，模型生成的图片会通过 message.images 字段返回。

图像输入

{
  "model": "SenseNova-U1",
  "messages": [{
    "role": "user",
    "content": [
      { "type": "text", "text": "请识别这张图中的文字" },
      { "type": "image_url", "image_url": {
          "url": "https://example.com/invoice.jpg"
      }}
    ]
  }]
}

image_url.url 支持 HTTPS 链接或 data:image/...;base64,... 格式的 base64 内联图片。

图像生成 SenseNova U1

SenseNova U1 可在回复中直接生成图像。启用方式：在 modalities 中加入 "image"，并通过 image_config 指定生成参数。

{
  "model": "SenseNova-U1",
  "messages": [
    { "role": "user", "content": "为下季度销售周报生成一张信息图封面" }
  ],
  "modalities": ["text", "image"],
  "image_config": {
    "aspect_ratio": "16:9",
    "image_size": "2K"
  }
}

响应中的 images 字段

{
  "choices": [{
    "message": {
      "role": "assistant",
      "content": "这是为你生成的信息图封面：",
      "images": [{
        "type": "image_url",
        "image_url": { "url": "https://cdn.sensenova.dev/gen/..." }
      }]
    }
  }]
}

image_config 字段

字段	类型	说明
`aspect_ratio`	string	纵横比，如 `1:1` / `16:9` / `9:16`
`image_size`	string	分辨率档位，如 `0.5K` / `1K` / `2K` / `4K`
`font_inputs`	array	指定字体输入（字体 URL + 文字）
`super_resolution_references`	array<string>	超分辨率参考图 URL 列表

错误码

所有错误响应遵循统一结构，error.type 标识错误大类，error.code 标识具体错误。

{
  "error": {
    "type":    "invalid_request_error",
    "code":    "invalid_parameter",
    "param":   "temperature",
    "message": "temperature must be between 0 and 2"
  }
}

错误码表

HTTP	类型 (type)	错误码 (code)	含义与处置建议
400	`invalid_request_error`	`invalid_parameter`	请求参数不合法（类型/取值范围）。请检查对应 param 字段
400	`invalid_request_error`	`missing_required_parameter`	缺少必填参数，如 messages / model
400	`invalid_request_error`	`context_length_exceeded`	输入 + 生成超过模型上下文长度，请缩减输入或 max_completion_tokens
400	`invalid_request_error`	`content_policy_violation`	输入或输出未通过合规审核，请调整内容
401	`authentication_error`	`invalid_api_key`	API Key 无效、已注销或格式错误
401	`authentication_error`	`missing_authorization`	缺少 Authorization 头
402	`billing_error`	`insufficient_quota`	账户余额或套餐额度不足
403	`permission_error`	`model_access_denied`	当前账号/套餐无权访问该模型
404	`invalid_request_error`	`model_not_found`	模型 ID 不存在或已下线
413	`invalid_request_error`	`payload_too_large`	请求体超出大小限制（含 base64 图像/文件）
415	`invalid_request_error`	`unsupported_media_type`	不支持的 Content-Type，请使用 application/json
429	`rate_limit_error`	`rate_limit_exceeded`	请求速率 (RPM) 超限，建议指数退避重试
429	`rate_limit_error`	`tokens_rate_limit_exceeded`	Token 速率 (TPM) 超限
500	`internal_server_error`	`internal_error`	服务器内部错误，可稍后重试
502 / 503	`internal_server_error`	`service_unavailable`	上游或下游服务暂不可用
504	`internal_server_error`	`timeout`	请求超时，请简化 prompt 或重试