素材グループ

素材グループは素材の入れ物です。画像を送信する前に、まずバーチャル素材グループが必要です。

素材グループの作成

POST/api/v1/materials/groups

認証方式

Authorization: Bearer <API_KEY>。コンソールの「API キー」で作成したプラットフォーム API キーを使用します。

リクエストボディ · application/json

Prop

Type

同じアカウント内で同名・同タイプのグループが重複して作成されることはなく、重複して呼び出した場合は既存のグループがそのまま返ります。

リクエスト例

curl -X POST "$LOCOPAL_BASE_URL/api/v1/materials/groups" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "name": "品牌虚拟角色",
  "description": "电商视频人物设定图",
  "type": "virtual"
}
JSON

実在人物グループを作成する場合も同じ API を使用し、type を real に変更するだけです：

curl -X POST "$LOCOPAL_BASE_URL/api/v1/materials/groups" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "name": "真人素材库",
  "description": "已完成授权的真人素材",
  "type": "real"
}
JSON

レスポンスパラメータ

パラメータ	型	説明
`code`	integer	成功時は `0`
`msg`	string	成功時は `素材分组已创建`
`data.group.id`	string	現在のアカウントが使用するグループ ID。後続の素材送信時に `group_id` として使用します
`data.group.platform_group_id`	string	素材サービスのプラットフォームグループ ID。調査用で、現在のデプロイでは通常 `id` と同じです
`data.group.name`	string	グループ名
`data.group.type`	string	`virtual` または `real`
`data.group.description`	string / null	グループの説明。未入力の場合は `null`
`data.group.created_at`	integer	作成日時（Unix 秒）
`data.group.updated_at`	integer	更新日時（Unix 秒）

レスポンスボディ

{
  "code": 0,
  "data": {
    "group": {
      "id": "group-1789069780-5762d1",
      "platform_group_id": "group-1789069780-5762d1",
      "name": "品牌虚拟角色",
      "type": "virtual",
      "description": "电商视频人物设定图",
      "created_at": 1789069780,
      "updated_at": 1789069780
    }
  },
  "msg": "素材分组已创建"
}

エラーレスポンス

HTTP	msg	説明
`400`	`请求体必须是 JSON 对象`	リクエストボディが有効な JSON ではありません
`400`	`type 只能是 virtual 或 real`	`type` の値が誤っています
`400`	`素材分组名称不能为空`	`name` がありません
`400`	`素材分组名称不能超过 64 个字符`	`name` が長すぎます
`400`	`素材分组说明不能超过 300 个字符`	`description` が長すぎます
`401`	`Invalid token`	API キーが欠落、誤り、または失効しています
`502` / `503`	`素材服务暂不可用`	素材サービスに異常があります。リクエスト情報を保持してから再試行してください

素材グループの照会

GET/api/v1/materials/groups

認証方式

Authorization: Bearer <API_KEY>。GET リクエストにも必ず付与してください。

リクエストパラメータ · query

パラメータ	型	必須	デフォルト	説明
`page`	integer	いいえ	`1`	ページ番号。1 未満の場合は 1 として処理されます
`page_size`	integer	いいえ	`20`	1 ページあたりの件数。最大 100 で、範囲外の場合は 20 として処理されます

リクエスト例

curl "$LOCOPAL_BASE_URL/api/v1/materials/groups?page=1&page_size=20" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY"

レスポンスパラメータ

パラメータ	型	説明
`code`	integer	成功時は `0`
`msg`	string	成功時は `OK`
`data.total`	integer	現在のアカウントのグループ総数
`data.page`	integer	今回のページ番号
`data.page_size`	integer	今回の 1 ページあたりの件数
`data.groups`	array	グループ一覧。フィールドは作成 API と同じで、現在のアカウント自身のグループのみが含まれます

レスポンスボディ

{
  "code": 0,
  "data": {
    "groups": [
      {
        "id": "group-1789069780-5762d1",
        "platform_group_id": "group-1789069780-5762d1",
        "name": "品牌虚拟角色",
        "type": "virtual",
        "description": "电商视频人物设定图",
        "created_at": 1789069780,
        "updated_at": 1789069780
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 20
  },
  "msg": "OK"
}

エラーレスポンス

HTTP	msg	説明
`401`	`Invalid token`	API キーが欠落、誤り、または失効しています
`500` / `502` / `503`	`素材服务暂不可用`	素材サービスに異常があります。リクエスト情報を保持してから再試行してください

このページの目次