Skip to main content

创建 BYOK 模型

使用 Authorization: Bearer <API_KEY>。应用必须配置全部用户范围 subject_scope={"mode":"all"},受限范围返回 403。

使用 Authorization: Bearer <API_KEY>。应用必须配置全部用户范围 subject_scope={"mode":"all"},受限范围返回 403。各 Scope 独立授权。响应不应缓存。模型配置指 BYOK 自定义模型及系统模型查询。创建严格复用 UI 的“测试并保存”:先测试连接,失败不保存,成功保存但不自动启用。models/connection-tests 是独立预检,不保存模型或凭据。保留 BYOK 特性开关、管理开关、上游地址限制和凭据处理;列表保持分页。创建要求 Idempotency-Key。不新增模型修改、删除、启停或密钥轮换。

所需权限

所需权限资源Scope资源服务
模型配置管理(manage)modelsadmin.v1.models.manageqwenwork-biz-service
POST /api/openapi/v1/models/custom

公共请求头

适用《通过 API 配置 QwenWork 管理后台》的“认证与请求头”章节:Authorization 必填,X-Request-Id 可选;当前接口所需 Scope 见本页。 Idempotency-Key 是否适用及必填性以本页请求参数为准,不能用追踪标识替代幂等键。

请求参数

请求体:必填;Content-Type:application/json。
名称位置类型必填说明示例
Idempotency-Keyheaderstring是幂等键; maxLength=255-
api_keybodystring · password | null否上游模型 API Key; format="password", maxLength=8192-
descriptionbodystring否说明文本; maxLength=2000-
description_i18nbodyobject否多语言说明-
display_namebodystring是显示名称; maxLength=255-
display_name_i18nbodyobject否各语言的显示名称-
endpoint_urlbodystring · uri是上游服务地址; format="uri", maxLength=2048-
is_reasoningbodyboolean是是否为推理模型-
is_vlbodyboolean是是否支持视觉输入-
max_context_window_tokensbodyinteger · int64是沿用 UI 闭集:仅 200000、400000、1000000; format="int64", minimum=1-
pass_third_party_user_idbodyboolean是是否传递第三方用户 ID-
protocol_profilebodystring是protocol profile; enum=["openai_chat_completions_v1"] 取值:"openai_chat_completions_v1"-
provider_adapterbodystring是provider adapter; enum=["openai_compatible"] 取值:"openai_compatible"-
upstream_modelbodystring是上游模型名称; maxLength=255-

请求示例

将 <BASE_URL> 替换为企业部署的千问办公 API 服务地址,并填写实际参数。示例中的占位值不能直接用于请求。
curl --request POST \
  --url '<BASE_URL>/api/openapi/v1/models/custom' \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Idempotency-Key: <UNIQUE_REQUEST_ID>' \
  --header 'Content-Type: application/json' \
  --data '{
  "display_name": "<display_name>",
  "endpoint_url": "https://example.com",
  "is_reasoning": false,
  "is_vl": false,
  "max_context_window_tokens": 1,
  "pass_third_party_user_id": false,
  "protocol_profile": "openai_chat_completions_v1",
  "provider_adapter": "openai_compatible",
  "upstream_model": "<upstream_model>"
}'

响应状态表

HTTP 状态码触发条件响应结构引用客户端处理建议
201请求成功见本文“响应结果”读取响应结果。
default未单独列出的认证、授权、校验或依赖错误见《通过 API 配置 QwenWork 管理后台》的“通用错误”结构按状态与 code 处理;写操作重试前核实结果及幂等要求。

响应结果

Content-Type: application/json
名称类型必填说明示例
api_key_configuredboolean是是否已配置 API Key-
created_atstring · date-time是创建时间; format="date-time"-
created_byobject是创建主体 ID-
credential_configuredboolean是是否已配置凭据-
credential_fingerprintstring否凭据指纹-
credential_versioninteger · int64否凭据版本号; format="int64"-
descriptionstring否说明文本-
description_i18nobject否多语言说明-
display_namestring是显示名称-
display_name_i18nobject否各语言的显示名称-
endpoint_urlstring是上游服务地址-
idstring · uuid是记录 ID; format="uuid"-
is_reasoningboolean是是否为推理模型-
is_vlboolean是是否支持视觉输入-
last_test_codestring否最近一次测试的结果码-
last_test_resultstring否last test result; enum=["success", "failed"] 取值:"failed"、"success"-
last_tested_atstring · date-time否最近一次测试时间; format="date-time"-
lifecyclestring是lifecycle; enum=["draft", "test", "active", "disabled"] 取值:"active"、"disabled"、"draft"、"test"-
max_context_window_tokensinteger · int64是沿用 UI 闭集:仅 200000、400000、1000000; format="int64", minimum=1-
model_keystring是模型标识-
pass_third_party_user_idboolean是是否传递第三方用户 ID-
protocol_profilestring是protocol profile; enum=["openai_chat_completions_v1"] 取值:"openai_chat_completions_v1"-
provider_adapterstring是provider adapter; enum=["openai_compatible"] 取值:"openai_compatible"-
row_versioninteger · int64是记录版本号; format="int64"-
target_versioninteger · int64是目标版本号; format="int64"-
updated_atstring · date-time是更新时间; format="date-time"-
updated_byobject是更新主体 ID-
upstream_modelstring是上游模型名称-

created_by

字段类型必填说明
emailstring · email否邮箱; format="email"
namestring否名称
user_idstring · uuid是用户 ID; format="uuid"

updated_by

字段类型必填说明
emailstring · email否邮箱; format="email"
namestring否名称
user_idstring · uuid是用户 ID; format="uuid"

运行时限制与协议说明

连接验证失败时返回 HTTP 422 / custom_model_connection_test_failed,错误根含 test_code(string,必填),表示经过脱敏的失败分类;该字段不适用于其他校验错误,模型不会保存。

错误与重试

保留现有 UI 服务的错误码与校验。401/403 表示认证或授权失败;409 表示冲突,应重新读取后重试;413 表示请求过大;400/422 表示参数校验失败;503 表示依赖不可用。 以实际响应及机器契约为准。创建类幂等操作重试应使用相同 Idempotency-Key 与相同请求。