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.
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/jsonPOST /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ção | Objetivo | Corpo da solicitação |
|---|---|---|
CreateAssetGroup | Criar um grupo de materiais de avatar virtual | Name; Description opcional; GroupType: "AIGC" opcional; ProjectName |
ListAssetGroups | Listar grupos em um projeto | Filter.GroupIds, Filter.GroupType, Filter.Name opcionais; PageNumber, PageSize, SortBy, SortOrder, ProjectName |
GetAssetGroup | Ler um grupo | Id, ProjectName |
UpdateAssetGroup | Alterar nome ou descrição do grupo | Id; Name e/ou Description; ProjectName |
DeleteAssetGroup | Excluir um grupo e seus ativos | Id, 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ção | Objetivo | Corpo da solicitação |
|---|---|---|
CreateAsset | Importar uma URL pública de imagem, vídeo ou áudio | GroupId, URL, Name, AssetType, ProjectName |
ListAssets | Listar ativos em um projeto | Filter.GroupIds, Filter.GroupType, Filter.Statuses, Filter.Name opcionais; PageNumber, PageSize, SortBy, SortOrder, ProjectName |
GetAsset | Ler um ativo e sua URL temporária | Id, ProjectName |
UpdateAsset | Renomear um ativo | Id; Name opcional; ProjectName |
DeleteAsset | Excluir um ativo | Id, 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ção | Result (campos principais) |
|---|---|
CreateAssetGroup, CreateAsset, UpdateAssetGroup, UpdateAsset | { "Id": "..." } |
DeleteAssetGroup, DeleteAsset | {} |
GetAssetGroup | Id, Name, Description, GroupType, ProjectName, CreateTime, UpdateTime |
GetAsset | Id, 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:
- Chame Criar Sessão de Validação Visual.
- Conclua o fluxo de verificação H5.
- Chame Obter Resultado de Validação Visual até que ele retorne
Result.GroupId. - Chame
CreateAssetcom 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 Autenticação por Chave de API. Crie ou gerencie chaves de API em Dashboard > API > API Keys.
Local: header
Parâmetros de consulta
Valores permitidos
- "CreateContentsGenerationsTasks"
- "GetContentsGenerationsTask"
- "ListContentsGenerationsTasks"
- "DeleteContentsGenerationsTasks"
- "CreateVisualValidateSession"
- "GetVisualValidateResult"
- "CreateAssetGroup"
- "ListAssetGroups"
- "GetAssetGroup"
- "UpdateAssetGroup"
- "DeleteAssetGroup"
- "CreateAsset"
- "ListAssets"
- "GetAsset"
- "UpdateAsset"
- "DeleteAsset"
"2024-01-01"Cabeçalhos
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