Vídeo e materiais

Ações de Material (Compatível com Volc)

Referência para as 10 Ações de material e grupo de materiais compatíveis com Volcengine.

POST
/api/v3

Estes endpoints suportam as Ações e campos de material listados abaixo, utilizando a autenticação TokenLab Bearer e o envelope ResponseMetadata + Result.

Endpoint e Autenticação

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 também é suportado. Todas as Ações de material são apenas POST. Assinaturas AK/SK do Volcengine não são aceitas; uma solicitação sem uma chave TokenLab Bearer válida retorna 401 InvalidCredential.

ProjectName tem como padrão default e é um limite de isolamento real dentro da organização autenticada. Use o mesmo valor ao criar, listar, ler, atualizar ou excluir grupos e ativos relacionados.

Ações de Grupo de Materiais

AçãoObjetivoCorpo da solicitação
CreateAssetGroupCriar um grupo de materiais de avatar virtualName; Description opcional; GroupType: "AIGC" opcional; ProjectName
ListAssetGroupsListar grupos em um projetoFilter.GroupIds, Filter.GroupType, Filter.Name opcionais; PageNumber, PageSize, SortBy, SortOrder, ProjectName
GetAssetGroupLer um grupoId, ProjectName
UpdateAssetGroupAlterar nome ou descrição do grupoId; Name e/ou Description; ProjectName
DeleteAssetGroupExcluir um grupo e seus ativosId, ProjectName

CreateAssetGroup aceita apenas GroupType: "AIGC". Um grupo LivenessFace é criado através de uma verificação de pessoa real bem-sucedida, não por esta Ação. ListAssetGroups pode filtrar grupos AIGC e LivenessFace. Name tem de 1 a 64 caracteres e Description tem até 300, o que é menor que os limites dos endpoints REST /v1/videos/assets*.

Criar um Grupo

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" }
}

Ações de Ativo de Material

AçãoObjetivoCorpo da solicitação
CreateAssetImportar uma URL pública de imagem, vídeo ou áudioGroupId, URL, Name, AssetType, ProjectName
ListAssetsListar ativos em um projetoFilter.GroupIds, Filter.GroupType, Filter.Statuses, Filter.Name opcionais; PageNumber, PageSize, SortBy, SortOrder, ProjectName
GetAssetLer um ativo e sua URL temporáriaId, ProjectName
UpdateAssetRenomear um ativoId; Name opcional; ProjectName
DeleteAssetExcluir um ativoId, ProjectName

AssetType aceita Image, Video ou Audio. O grupo de destino determina se o ativo é um material AIGC normal ou um material LivenessFace verificado.

Criar um Ativo

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"
  }'

Use IDs de material TokenLab. CreateAsset retorna Result.Id antes que o processamento termine; faça polling em GetAsset até que Result.Status seja Active ou Failed. ListAssets também aceita SortBy: "GroupId".

Comportamento de Listagem

PageNumber tem como padrão 1; PageSize tem como padrão 10 e aceita até 100. SortBy aceita CreateTime ou UpdateTime; SortOrder aceita Desc ou Asc.

As respostas de listagem retornam:

{
  "ResponseMetadata": {
    "RequestId": "req-id",
    "Action": "ListAssets",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "Items": [],
    "TotalCount": 0,
    "PageNumber": 1,
    "PageSize": 10
  }
}

Os valores de status do ativo são Active, Processing e Failed. GetAsset e ListAssets retornam uma URL temporária válida por 12 horas; não a armazene como a identidade permanente do ativo. Armazene o Id em vez disso.

Resultados

AçãoResult (campos principais)
CreateAssetGroup, CreateAsset, UpdateAssetGroup, UpdateAsset{ "Id": "..." }
DeleteAssetGroup, DeleteAsset{}
GetAssetGroupId, Name, Description, GroupType, ProjectName, CreateTime, UpdateTime
GetAssetId, GroupId, Name, AssetType, URL, Status, Error (Code e Message, vazio a menos que o ativo tenha falhado), ProjectName, CreateTime, UpdateTime

Os horários são strings ISO 8601. ListAssetGroups e ListAssets retornam esses objetos em Result.Items.

Materiais de Pessoa Real

Antes de importar um ativo para uma pessoa real:

  1. Chame Criar Sessão de Validação Visual.
  2. Conclua o fluxo de verificação H5.
  3. Chame Obter Resultado de Validação Visual até que ele retorne Result.GroupId.
  4. Chame CreateAsset com esse ID de grupo verificado.

Uploads para um grupo LivenessFace são verificados em relação ao rosto verificado. DeleteAssetGroup não exclui um grupo de pessoa real verificado; ele retorna 409 OperationDenied.

Erros

Os erros mantêm o envelope de resposta do Volcengine e colocam o código e a mensagem em ResponseMetadata.Error.

{
  "ResponseMetadata": {
    "RequestId": "req-id",
    "Action": "CreateAsset",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing",
    "Error": {
      "Code": "InvalidParameter",
      "Message": "GroupId is required"
    }
  }
}

Códigos comuns incluem InvalidCredential, InvalidVersion, InvalidParameter, ResourceNotFound, Conflict, OperationDenied, MethodNotAllowed, AccessDenied, FlowLimitExceeded e InternalError. O status HTTP é 400 para solicitações incorretas, 404 para um grupo ou ativo ausente, 409 para conflitos e 405 para um método que não seja POST.

Alternativa REST

Os endpoints REST /v1/videos/assets* do TokenLab permanecem disponíveis. Novas integrações nativas do TokenLab podem preferir seus corpos em snake_case; clientes existentes do Volcengine podem usar as Ações nesta página sem reformular as solicitações. Veja Materiais Seedance e verificação de pessoas para o ciclo de vida completo do ativo.

curl -X POST "https://example.com/api/v3" \  -H "Content-Type: application/json" \  -d '{    "CallbackURL": "http://example.com"  }'
{  "id": "string"}

Autorização

BearerAuth
AuthorizationBearer <token>

Autenticação por Chave de API. Crie ou gerencie chaves de API em Dashboard > API > API Keys.

Local: header

Parâmetros de consulta

Action?string

Valores permitidos

  • "CreateContentsGenerationsTasks"
  • "GetContentsGenerationsTask"
  • "ListContentsGenerationsTasks"
  • "DeleteContentsGenerationsTasks"
  • "CreateVisualValidateSession"
  • "GetVisualValidateResult"
  • "CreateAssetGroup"
  • "ListAssetGroups"
  • "GetAssetGroup"
  • "UpdateAssetGroup"
  • "DeleteAssetGroup"
  • "CreateAsset"
  • "ListAssets"
  • "GetAsset"
  • "UpdateAsset"
  • "DeleteAsset"
Version?string
padrão"2024-01-01"

Cabeçalhos

X-TokenLab-Delivery-Policy?string

Política de entrega por solicitação. Substitui os padrões da API key e do Workspace. Tenta automaticamente o TokenLab Verified primeiro e pode alternar uma vez para Official apenas antes da saída, aceitação da solicitação ou criação de recurso persistente.

Valores permitidos

  • "auto"
  • "verified"
  • "official"

Corpo da requisição

application/json

Resposta

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json