Skip to main content
OpenAPI

モデル API

モデルのレベルと新モデルを照会し、組織内での表示範囲をグループ単位で管理します。

モデルのカタログは Qoder が一元管理しています。モデル API では、各シナリオのレベルと新モデルの照会、組織内での表示範囲のグループ単位での設定、今後リリースされるモデルのデフォルト表示設定を行えます。
対象プラン：Enterprise。
呼び出す前に API キーの取得を完了し、OpenAPI 共通仕様を確認してください。

前提条件

  • Authorization: Bearer <api_key> を送信します。Organization API キーのみ利用でき、個人の認証情報やサービスアカウントの認証情報は利用できません。
  • JSON リクエストボディがある場合は Content-Type: application/json を送信します。
  • API キーに紐づく組織を organization_id に指定します。
  • groupIds にはグループ ID を指定します。手動管理グループと SCIM グループのどちらも利用できます。

主な動作

  • モデルはシナリオ（scenarioType）ごとに構成されます：general（汎用コーディング）、experts（Experts）、qoderwork（QoderWork）。各シナリオには、表示範囲を個別に設定できる 2 種類の対象があります：レベル（level、例：auto、ultimate）と新モデル（modelKey）です。
  • 管理できるレベルと新モデルは、モデル一覧が返す内容が基準です。リージョンやモデルカタログのリリースによって変わるため、level や modelKey をハードコードしないでください。
  • 組織で一度も設定していない対象は all として扱われます。ただし、新モデルのデフォルト表示をオフにした後に初めてリリースされた対象は除きます。詳しくは新モデルのデフォルト表示設定の更新を参照してください。
  • グループを削除すると、そのグループはすべてのリストから除外されますが、scope は変わりません。リストが空になると、group の対象は組織全体に非表示、exclude_group の対象は組織全体に表示されます。このとき照会結果には、元の scope と空の groupIds が返ります。
  • この API が返すのは組織で設定したポリシーであり、特定のユーザーに最終的に表示されるモデルではありません。

表示範囲

各レベルと新モデルには scope があります。ユーザーがモデル一覧をリクエストすると、サーバーはユーザーの所属グループに基づいて判定します：
scopegroupIdsリスト内グループのメンバーその他のメンバー（どのグループにも属さないメンバーを含む）
all空であること表示表示
group1 件以上表示非表示
exclude_group1 件以上非表示表示
none空であること非表示非表示
ユーザーがリスト内のいずれかのグループに属していれば、リストに該当するとみなされます。

データモデル

Scenario

フィールド型説明
scenarioTypestringシナリオの種類
levelsModelPolicy 配列カタログ順のレベル一覧。レベルがない場合は []
newModelsModelPolicy 配列新モデル一覧。新モデルがない場合は []

ModelPolicy

フィールド型説明
levelstringレベルの識別子。levels のエントリにのみ含まれます
modelKeystring新モデルの識別子。newModels のエントリにのみ含まれます
displayNamestring表示名。表示専用で、クライアントのモデル一覧の名称と異なる場合があります
scopestring現在の表示範囲：all、group、exclude_group、none のいずれか
groupIdsstring 配列リスト内のグループ ID。順序は保証されません。all、none の場合は []
エントリには scenarioType が含まれません。シナリオは所属する Scenario で判断します。

API リファレンス

モデル一覧

GET /v1/organizations/{organization_id}/official-models
クエリパラメーター型必須説明
scenarioTypestringいいえ指定したシナリオのみ返します：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 の順で 3 件返ります。 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"
    }
  ]
}
フィールド型必須説明
policiesobject 配列はい1～100 件
policies[].scenarioTypestringはいgeneral、experts、qoderwork のいずれか
policies[].levelstring条件レベルの識別子。modelKey とどちらか一方を指定します
policies[].modelKeystring条件新モデルの識別子。level とどちらか一方を指定します
policies[].scopestringはいall、group、exclude_group、none のいずれか
policies[].groupIdsstring 配列条件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 が返った場合やリクエストがタイムアウトした場合、一部の対象がすでに反映されている可能性があります。この API は対象ごとに全体を置き換えるため、同じリクエストを再送しても結果は同じです。再試行の前にモデル一覧で現在の状態を確認してください。

新モデルのデフォルト表示設定の取得

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
}
フィールド型必須説明
defaultVisiblebooleanはい新しくリリースされる対象をデフォルトで表示するかどうか
成功時は 200 OK と設定後の値を返します。構造は新モデルのデフォルト表示設定の取得と同じです。 プラットフォームはモデルカタログをリリースするたびにこの値を読み取り、そのリリースで初めて登場するレベルと新モデルにのみ適用します：
defaultVisible新しくリリースされる対象の扱い
trueポリシーを書き込まず、all として組織全体に表示
false組織に対して scope: "none" を書き込み、組織全体に非表示
この値を変更しても、リリース済みの対象には遡って反映されず、既存のポリシーも上書きされません。false から true に戻した後も、以前 none が書き込まれた対象は非表示のままです。モデルポリシーの一括更新で明示的に変更してください。

エラー

エラーは OpenAPI 共通仕様で説明する標準レスポンス形式を使用します。ただし、scenarioType パラメーターのエラーは例外です。モデル一覧を参照してください。
HTTP ステータスエラーコード主な原因
400BadRequest不正なリクエストボディ、シナリオ・レベル・新モデルが存在しない、scope と groupIds が一致しない、グループが現在の組織に属さない、対象の重複
401UnauthorizedAPI キーがない、無効、期限切れ、または失効している
403ForbiddenAPI キーが対象組織に属していない、または Organization API キーではない
403OrganizationPlanCapabilityForbidden組織でモデルポリシー機能が有効でない
404NotFoundリクエストパスが存在しない
レート制限（429）とサーバーエラー（5xx）は、OpenAPI 共通仕様に従ってバックオフしながら再試行してください。