ビデオと素材
Material Actions (Volc互換)
Volcengine互換の10種類のマテリアルおよびマテリアルグループActionのリファレンス。
これらのエンドポイントは、TokenLab Bearer認証および ResponseMetadata + Result エンベロープを使用して、以下にリストされているマテリアルActionとフィールドをサポートしています。
エンドポイントと認証
POST https://api.tokenlab.sh/?Action=<ACTION>&Version=2024-01-01
Authorization: Bearer <TOKENLAB_API_KEY>
Content-Type: application/jsonPOST /api/v3?Action=<ACTION>&Version=2024-01-01 もサポートされています。すべてのマテリアルActionはPOST専用です。VolcengineのAK/SK署名は受け付けられません。有効なTokenLab Bearerキーがないリクエストは 401 InvalidCredential を返します。
ProjectName のデフォルトは default であり、認証された組織内の実際の分離境界となります。関連するグループやアセットを作成、一覧表示、読み取り、更新、または削除する際は、同じ値を使用してください。
マテリアルグループAction
| Action | 目的 | リクエストボディ |
|---|---|---|
CreateAssetGroup | バーチャルアバターのマテリアルグループを作成 | Name; オプション Description; オプション GroupType: "AIGC"; ProjectName |
ListAssetGroups | プロジェクト内のグループを一覧表示 | オプション Filter.GroupIds, Filter.GroupType, Filter.Name; PageNumber, PageSize, SortBy, SortOrder, ProjectName |
GetAssetGroup | グループを1つ読み取り | Id, ProjectName |
UpdateAssetGroup | グループ名または説明を変更 | Id; Name および/または Description; ProjectName |
DeleteAssetGroup | グループとそのアセットを削除 | Id, ProjectName |
CreateAssetGroup は GroupType: "AIGC" のみを受け付けます。LivenessFace グループは、このActionではなく、本人確認の成功によって作成されます。ListAssetGroups は AIGC グループと LivenessFace グループの両方をフィルタリングできます。Name は1〜64文字、Description は最大300文字です。これは /v1/videos/assets* RESTエンドポイントの制限よりも短くなっています。
グループの作成
curl 'https://api.tokenlab.sh/?Action=CreateAssetGroup&Version=2024-01-01' \
-H "Authorization: Bearer $TOKENLAB_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"Name":"Product references",
"Description":"Reusable product shots",
"GroupType":"AIGC",
"ProjectName":"default"
}'{
"ResponseMetadata": {
"RequestId": "req-id",
"Action": "CreateAssetGroup",
"Version": "2024-01-01",
"Service": "ark",
"Region": "cn-beijing"
},
"Result": { "Id": "group-20260720123456-abc12" }
}マテリアルアセットAction
| Action | 目的 | リクエストボディ |
|---|---|---|
CreateAsset | 公開されている画像、動画、または音声URLを1つインポート | GroupId, URL, Name, AssetType, ProjectName |
ListAssets | プロジェクト内のアセットを一覧表示 | オプション Filter.GroupIds, Filter.GroupType, Filter.Statuses, Filter.Name; PageNumber, PageSize, SortBy, SortOrder, ProjectName |
GetAsset | アセット1つとその一時URLを読み取り | Id, ProjectName |
UpdateAsset | アセットの名前を変更 | Id; オプション Name; ProjectName |
DeleteAsset | アセットを1つ削除 | Id, ProjectName |
AssetType は Image、Video、または Audio を受け付けます。ターゲットグループによって、そのアセットが通常のマテリアル(AIGC)か、検証済みマテリアル(LivenessFace)かが決まります。
アセットの作成
curl 'https://api.tokenlab.sh/?Action=CreateAsset&Version=2024-01-01' \
-H "Authorization: Bearer $TOKENLAB_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"GroupId":"group-20260720123456-abc12",
"URL":"https://example.com/reference.png",
"Name":"Front view",
"AssetType":"Image",
"ProjectName":"default"
}'TokenLabのマテリアルIDを使用してください。CreateAsset は処理完了前に Result.Id を返します。Result.Status が Active または Failed になるまで GetAsset をポーリングしてください。ListAssets は SortBy: "GroupId" も受け付けます。
一覧表示の動作
PageNumber のデフォルトは 1、PageSize のデフォルトは 10 で、最大 100 まで受け付けます。SortBy は CreateTime または UpdateTime を受け付け、SortOrder は Desc または Asc を受け付けます。
一覧表示のレスポンスは以下を返します:
{
"ResponseMetadata": {
"RequestId": "req-id",
"Action": "ListAssets",
"Version": "2024-01-01",
"Service": "ark",
"Region": "cn-beijing"
},
"Result": {
"Items": [],
"TotalCount": 0,
"PageNumber": 1,
"PageSize": 10
}
}アセットのステータス値は Active、Processing、Failed です。GetAsset および ListAssets は12時間有効な一時的な URL を返します。これを永続的なアセットIDとして保存しないでください。代わりに Id を保存してください。
結果
| Action | Result (主要フィールド) |
|---|---|
CreateAssetGroup, CreateAsset, UpdateAssetGroup, UpdateAsset | { "Id": "..." } |
DeleteAssetGroup, DeleteAsset | {} |
GetAssetGroup | Id, Name, Description, GroupType, ProjectName, CreateTime, UpdateTime |
GetAsset | Id, GroupId, Name, AssetType, URL, Status, Error (Code および Message、アセットが失敗しない限り空), ProjectName, CreateTime, UpdateTime |
時刻はISO 8601形式の文字列です。ListAssetGroups および ListAssets は、これらのオブジェクトを Result.Items 内に返します。
本人確認用マテリアル
本人確認用のアセットをインポートする前に:
- Create Visual Validation Session を呼び出します。
- H5検証フローを完了します。
Result.GroupIdが返されるまで Get Visual Validation Result を呼び出します。- その検証済みグループIDを使用して
CreateAssetを呼び出します。
LivenessFace グループへのアップロードは、検証済みの顔と照合されます。DeleteAssetGroup は検証済みの本人確認グループを削除しません。削除しようとすると 409 OperationDenied が返されます。
エラー
エラーはVolcengineのレスポンスエンベロープを維持し、コードとメッセージを ResponseMetadata.Error の下に配置します。
{
"ResponseMetadata": {
"RequestId": "req-id",
"Action": "CreateAsset",
"Version": "2024-01-01",
"Service": "ark",
"Region": "cn-beijing",
"Error": {
"Code": "InvalidParameter",
"Message": "GroupId is required"
}
}
}一般的なコードには InvalidCredential、InvalidVersion、InvalidParameter、ResourceNotFound、Conflict、OperationDenied、MethodNotAllowed、AccessDenied、FlowLimitExceeded、InternalError が含まれます。HTTPステータスは、不正なリクエストの場合は 400、グループまたはアセットが見つからない場合は 404、競合の場合は 409、POST以外のメソッドの場合は 405 となります。
RESTの代替手段
TokenLabの /v1/videos/assets* RESTエンドポイントも引き続き利用可能です。新しいTokenLabネイティブの統合では、snake_caseのボディが好まれる場合があります。既存のVolcengineクライアントは、リクエストを再構築することなく、このページにあるActionを使用できます。アセットのライフサイクル全体については、Seedance 素材と実在人物の認証 を参照してください。
curl -X POST "https://example.com/api/v3" \ -H "Content-Type: application/json" \ -d '{ "CallbackURL": "http://example.com" }'{ "id": "string"}認証
BearerAuth APIキー認証。Dashboard > API > API KeysでAPIキーを作成または管理します。
場所: header
クエリパラメータ
指定できる値
- "CreateContentsGenerationsTasks"
- "GetContentsGenerationsTask"
- "ListContentsGenerationsTasks"
- "DeleteContentsGenerationsTasks"
- "CreateVisualValidateSession"
- "GetVisualValidateResult"
- "CreateAssetGroup"
- "ListAssetGroups"
- "GetAssetGroup"
- "UpdateAssetGroup"
- "DeleteAssetGroup"
- "CreateAsset"
- "ListAssets"
- "GetAsset"
- "UpdateAsset"
- "DeleteAsset"
"2024-01-01"ヘッダー
リクエストごとの配信ポリシー。APIキーおよびWorkspaceのデフォルト設定を上書きします。自動的にまず TokenLab Verified を試行し、出力、リクエストの受け入れ、または永続的なリソース作成の前に、一度だけ Official に切り替える場合があります。
指定できる値
- "auto"
- "verified"
- "official"
リクエストボディ
application/json
レスポンス
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json