ビデオと素材

Material Actions (Volc互換)

Volcengine互換の10種類のマテリアルおよびマテリアルグループActionのリファレンス。

POST
/api/v3

これらのエンドポイントは、TokenLab Bearer認証および ResponseMetadata + Result エンベロープを使用して、以下にリストされているマテリアルActionとフィールドをサポートしています。

エンドポイントと認証

POST https://api.tokenlab.sh/?Action=<ACTION>&Version=2024-01-01
Authorization: Bearer <TOKENLAB_API_KEY>
Content-Type: application/json

POST /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 を保存してください。

結果

ActionResult (主要フィールド)
CreateAssetGroup, CreateAsset, UpdateAssetGroup, UpdateAsset{ "Id": "..." }
DeleteAssetGroup, DeleteAsset{}
GetAssetGroupId, Name, Description, GroupType, ProjectName, CreateTime, UpdateTime
GetAssetId, GroupId, Name, AssetType, URL, Status, Error (Code および Message、アセットが失敗しない限り空), ProjectName, CreateTime, UpdateTime

時刻はISO 8601形式の文字列です。ListAssetGroups および ListAssets は、これらのオブジェクトを Result.Items 内に返します。

本人確認用マテリアル

本人確認用のアセットをインポートする前に:

  1. Create Visual Validation Session を呼び出します。
  2. H5検証フローを完了します。
  3. Result.GroupId が返されるまで Get Visual Validation Result を呼び出します。
  4. その検証済みグループ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
AuthorizationBearer <token>

APIキー認証。Dashboard > API > API KeysでAPIキーを作成または管理します。

場所: header

クエリパラメータ

Action?string

指定できる値

  • "CreateContentsGenerationsTasks"
  • "GetContentsGenerationsTask"
  • "ListContentsGenerationsTasks"
  • "DeleteContentsGenerationsTasks"
  • "CreateVisualValidateSession"
  • "GetVisualValidateResult"
  • "CreateAssetGroup"
  • "ListAssetGroups"
  • "GetAssetGroup"
  • "UpdateAssetGroup"
  • "DeleteAssetGroup"
  • "CreateAsset"
  • "ListAssets"
  • "GetAsset"
  • "UpdateAsset"
  • "DeleteAsset"
Version?string
デフォルト"2024-01-01"

ヘッダー

X-TokenLab-Delivery-Policy?string

リクエストごとの配信ポリシー。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