使用 Authorization: Bearer <API_KEY>。应用必须配置全部用户范围 subject_scope={"mode":"all"},受限范围返回 403。
使用
适用《通过 API 配置 QwenWork 管理后台》的“认证与请求头”章节:
将 <BASE_URL> 替换为企业部署的千问办公 API 服务地址,并填写实际参数。示例中的占位值不能直接用于请求。
Content-Type: application/json
保留现有 UI 服务的错误码与校验。401/403 表示认证或授权失败;409 表示冲突,应重新读取后重试;413 表示请求过大;400/422 表示参数校验失败;503 表示依赖不可用。
以实际响应及机器契约为准。创建类幂等操作重试应使用相同 Idempotency-Key 与相同请求。
Authorization: Bearer <API_KEY>。应用必须配置全部用户范围 subject_scope={"mode":"all"},受限范围返回 403。各 Scope 独立授权。响应不应缓存。模型配置指 BYOK 自定义模型及系统模型查询。创建严格复用 UI 的“测试并保存”:先测试连接,失败不保存,成功保存但不自动启用。models/connection-tests 是独立预检,不保存模型或凭据。保留 BYOK 特性开关、管理开关、上游地址限制和凭据处理;列表保持分页。创建要求 Idempotency-Key。不新增模型修改、删除、启停或密钥轮换。
所需权限
| 所需权限 | 资源 | Scope | 资源服务 |
|---|---|---|---|
| 模型配置读取(read) | models | admin.v1.models.read | qwenwork-biz-service |
公共请求头
适用《通过 API 配置 QwenWork 管理后台》的“认证与请求头”章节:Authorization 必填,X-Request-Id 可选;当前接口所需 Scope 见本页。
Idempotency-Key 是否适用及必填性以本页请求参数为准,不能用追踪标识替代幂等键。
请求参数
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
| id | path | string · uuid | 是 | 记录 ID; format="uuid" | - |
请求示例
将 <BASE_URL> 替换为企业部署的千问办公 API 服务地址,并填写实际参数。示例中的占位值不能直接用于请求。
响应状态表
| HTTP 状态码 | 触发条件 | 响应结构引用 | 客户端处理建议 |
|---|---|---|---|
| 200 | 请求成功 | 见本文“响应结果” | 读取响应结果。 |
| default | 未单独列出的认证、授权、校验或依赖错误 | 见《通过 API 配置 QwenWork 管理后台》的“通用错误”结构 | 按状态与 code 处理;写操作重试前核实结果及幂等要求。 |
响应结果
Content-Type: application/json
| 名称 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
| api_key_configured | boolean | 是 | 是否已配置 API Key | - |
| created_at | string · date-time | 是 | 创建时间; format="date-time" | - |
| created_by | object | 是 | 创建主体 ID | - |
| credential_configured | boolean | 是 | 是否已配置凭据 | - |
| credential_fingerprint | string | 否 | 凭据指纹 | - |
| credential_version | integer · int64 | 否 | 凭据版本号; format="int64" | - |
| description | string | 否 | 说明文本 | - |
| description_i18n | object | 否 | 多语言说明 | - |
| display_name | string | 是 | 显示名称 | - |
| display_name_i18n | object | 否 | 各语言的显示名称 | - |
| endpoint_url | string | 是 | 上游服务地址 | - |
| id | string · uuid | 是 | 记录 ID; format="uuid" | - |
| is_reasoning | boolean | 是 | 是否为推理模型 | - |
| is_vl | boolean | 是 | 是否支持视觉输入 | - |
| last_test_code | string | 否 | 最近一次测试的结果码 | - |
| last_test_result | string | 否 | last test result; enum=["success", "failed"] 取值:"failed"、"success" | - |
| last_tested_at | string · date-time | 否 | 最近一次测试时间; format="date-time" | - |
| lifecycle | string | 是 | lifecycle; enum=["draft", "test", "active", "disabled"] 取值:"active"、"disabled"、"draft"、"test" | - |
| max_context_window_tokens | integer · int64 | 是 | 最大上下文长度,单位为 token; format="int64", minimum=1 | - |
| model_key | string | 是 | 模型标识 | - |
| pass_third_party_user_id | boolean | 是 | 是否传递第三方用户 ID | - |
| protocol_profile | string | 是 | protocol profile; enum=["openai_chat_completions_v1"] 取值:"openai_chat_completions_v1" | - |
| provider_adapter | string | 是 | provider adapter; enum=["openai_compatible"] 取值:"openai_compatible" | - |
| row_version | integer · int64 | 是 | 记录版本号; format="int64" | - |
| target_version | integer · int64 | 是 | 目标版本号; format="int64" | - |
| updated_at | string · date-time | 是 | 更新时间; format="date-time" | - |
| updated_by | object | 是 | 更新主体 ID | - |
| upstream_model | string | 是 | 上游模型名称 | - |
created_by
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| string · email | 否 | 邮箱; format="email" | |
| name | string | 否 | 名称 |
| user_id | string · uuid | 是 | 用户 ID; format="uuid" |
updated_by
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| string · email | 否 | 邮箱; format="email" | |
| name | string | 否 | 名称 |
| user_id | string · uuid | 是 | 用户 ID; format="uuid" |