模型 API

模型目录由 Qoder 统一维护。模型 API 用于查询各场景下的档位和新模型、按群组设置它们在本组织内的可见范围，以及设置后续新发布模型的默认可见性。

适用版本：Enterprise。

调用前请先完成获取 API Key，并阅读 OpenAPI 约定与规范。

前置条件

请求头携带 Authorization: Bearer <api_key>。仅支持 Organization API Key，不支持个人凭证或服务账号凭证。
带 JSON 请求体时，发送 Content-Type: application/json。
organization_id 必须是 API Key 所属组织。
groupIds 使用群组 ID，手动群组和 SCIM 同步群组均可使用。

关键行为

模型按场景（scenarioType）组织：general（通用编码）、experts（Experts）、qoderwork（QoderWork）。每个场景下有两类可独立设置可见范围的目标：档位（level，例如 auto、ultimate）和新模型（modelKey）。
实际可管理的档位和新模型以列出模型的返回结果为准，会随区域和模型目录发布而变化。请勿硬编码 level 或 modelKey。
组织从未配置过的目标按 all 处理；关闭新模型默认可见性后首次发布的目标除外，见更新新模型默认可见性。
删除群组会将该群组从所有名单中移除，但不会改变 scope。名单被删空后，group 目标对全组织不可见，exclude_group 目标对全组织可见；此时查询返回原 scope 和空 groupIds。
本 API 返回组织配置的策略，不返回某个用户最终可见的模型。

可见范围

每个档位或新模型都有一个 scope。用户请求模型列表时，服务端按用户所属群组判定：

`scope`	`groupIds`	名单内群组的成员	其他成员（含未加入任何群组）
`all`	必须为空	可见	可见
`group`	至少 1 项	可见	不可见
`exclude_group`	至少 1 项	不可见	可见
`none`	必须为空	不可见	不可见

用户属于名单中任一群组即视为命中名单。

数据模型

Scenario

字段	类型	说明
`scenarioType`	string	场景类型
`levels`	ModelPolicy 数组	档位列表，按目录顺序；无档位时为 `[]`
`newModels`	ModelPolicy 数组	新模型列表；无新模型时为 `[]`

ModelPolicy

字段	类型	说明
`level`	string	档位标识；仅出现在 `levels` 条目中
`modelKey`	string	新模型标识；仅出现在 `newModels` 条目中
`displayName`	string	展示名，仅用于展示；可能与客户端模型列表中的名称不同
`scope`	string	当前可见范围：`all`、`group`、`exclude_group` 或 `none`
`groupIds`	string 数组	名单群组 ID，顺序不保证；`all`、`none` 时为 `[]`

条目不包含 scenarioType，场景以所在的 Scenario 为准。

API 参考

列出模型

GET /v1/organizations/{organization_id}/official-models

查询参数	类型	必填	说明
`scenarioType`	string	否	只返回指定场景：`general`、`experts` 或 `qoderwork`；省略时返回全部场景

成功响应（200 OK）

{
  "scenarios": [
    {
      "scenarioType": "general",
      "levels": [
        {
          "level": "auto",
          "displayName": "Auto",
          "scope": "all",
          "groupIds": []
        },
        {
          "level": "ultimate",
          "displayName": "Ultimate",
          "scope": "exclude_group",
          "groupIds": ["1c8f3ee2-b970-4b61-93f9-f8be080ae945"]
        }
      ],
      "newModels": [
        {
          "modelKey": "example-model",
          "displayName": "Example Model",
          "scope": "group",
          "groupIds": ["1c8f3ee2-b970-4b61-93f9-f8be080ae945"]
        }
      ]
    },
    {
      "scenarioType": "experts",
      "levels": [],
      "newModels": []
    },
    {
      "scenarioType": "qoderwork",
      "levels": [],
      "newModels": []
    }
  ]
}

省略 scenarioType 时，scenarios 固定按 general、experts、qoderwork 顺序返回三项。 scenarioType 取值无效时返回 400，但响应体为 {"error": "invalid scenarioType: must be one of general/experts/qoderwork"}，不含 requestId 和 code。请按 HTTP 状态码判断该错误。

批量更新模型策略

PUT /v1/organizations/{organization_id}/official-models/policy 更新请求中列出的档位或新模型的可见范围，未列出的目标保持不变。每个列出的目标按请求内容整体替换其 scope 和名单。

请求体

{
  "policies": [
    {
      "scenarioType": "general",
      "level": "ultimate",
      "scope": "exclude_group",
      "groupIds": ["1c8f3ee2-b970-4b61-93f9-f8be080ae945"]
    },
    {
      "scenarioType": "experts",
      "modelKey": "example-model",
      "scope": "group",
      "groupIds": ["1c8f3ee2-b970-4b61-93f9-f8be080ae945"]
    },
    {
      "scenarioType": "qoderwork",
      "level": "premium",
      "scope": "none"
    }
  ]
}

字段	类型	必填	说明
`policies`	object 数组	是	1–100 项
`policies[].scenarioType`	string	是	`general`、`experts` 或 `qoderwork`
`policies[].level`	string	条件	档位标识；与 `modelKey` 二选一
`policies[].modelKey`	string	条件	新模型标识；与 `level` 二选一
`policies[].scope`	string	是	`all`、`group`、`exclude_group` 或 `none`
`policies[].groupIds`	string 数组	条件	`group`、`exclude_group` 时至少 1 项；`all`、`none` 时省略或传 `[]`

level 或 modelKey 必须存在于列出模型返回的对应场景中。
同一请求中不得重复更新同一目标。
字符串字段会去除首尾空格；groupIds 会丢弃空字符串并去重后再校验。每个群组都必须属于当前组织。
每项只接受上表中的 5 个字段。从列出接口的响应复制条目时，请删除 displayName 并补上 scenarioType。

成功时返回 200 OK。响应中的 policies 与请求顺序一致，每项包含 scenarioType、level 或 modelKey、scope 和去重后的 groupIds，不包含 displayName。

{
  "policies": [
    {
      "scenarioType": "qoderwork",
      "level": "premium",
      "scope": "none",
      "groupIds": []
    }
  ]
}

服务端先校验整批请求，任一项失败则返回 400 BadRequest，不写入任何数据。校验通过后的写入不是单一事务：返回 5xx 或请求超时时，部分目标可能已经生效。该接口按目标整体替换，重复提交同一请求结果相同；重试前请先调用列出模型确认现状。

获取新模型默认可见性

GET /v1/organizations/{organization_id}/official-models/new-model-default

成功响应（200 OK）

{
  "defaultVisible": true
}

组织从未设置时，defaultVisible 为 true。

更新新模型默认可见性

PUT /v1/organizations/{organization_id}/official-models/new-model-default 设置后续新发布的档位和新模型是否默认对本组织可见。

请求体

{
  "defaultVisible": false
}

字段	类型	必填	说明
`defaultVisible`	boolean	是	新发布目标是否默认可见

成功时返回 200 OK 和设置后的值，结构同获取新模型默认可见性。平台每次发布模型目录时读取该值，并只作用于本次首次出现的档位和新模型：

`defaultVisible`	新发布目标的处理
`true`	不写入策略，按 `all` 对全组织可见
`false`	为本组织写入 `scope: "none"`，全组织不可见

修改该值不会回溯调整已发布的目标，也不会覆盖已有策略。从 false 改回 true 后，之前已写入 none 的目标仍不可见，需通过批量更新模型策略显式修改。

错误

错误响应使用 OpenAPI 约定与规范中定义的通用结构；scenarioType 参数错误例外，见列出模型。

HTTP 状态码	错误码	常见原因
400	`BadRequest`	请求体格式错误；场景、档位或新模型不存在；`scope` 与 `groupIds` 不匹配；群组不属于当前组织；同一目标重复
401	`Unauthorized`	API Key 缺失、无效、过期或已吊销
403	`Forbidden`	API Key 不属于目标组织，或不是 Organization API Key
403	`OrganizationPlanCapabilityForbidden`	组织未开通模型策略能力
404	`NotFound`	请求路径不存在

限流（429）和服务端错误（5xx）请按 OpenAPI 约定与规范退避重试。

​前置条件

​关键行为

​可见范围

​数据模型

​Scenario

​ModelPolicy

​API 参考

​列出模型

​成功响应（200 OK）

​批量更新模型策略

​请求体

​获取新模型默认可见性

​成功响应（200 OK）

​更新新模型默认可见性

​请求体

​错误

前置条件

关键行为

可见范围

数据模型

Scenario

ModelPolicy

API 参考

列出模型

成功响应（200 OK）

批量更新模型策略

请求体

获取新模型默认可见性

成功响应（200 OK）

更新新模型默认可见性

请求体

错误