Video ve materyaller

Materyal Eylemleri (Volc Uyumlu)

10 adet Volcengine uyumlu materyal ve materyal grubu Eylemi için referans.

POST
/api/v3

Bu uç noktalar, TokenLab Bearer kimlik doğrulaması ve ResponseMetadata + Result zarfı kullanılarak aşağıda listelenen materyal Eylemlerini ve alanlarını destekler.

Uç Nokta ve Kimlik Doğrulama

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 da desteklenmektedir. Tüm materyal Eylemleri yalnızca POST yöntemini kullanır. Volcengine AK/SK imzaları kabul edilmez; geçerli bir TokenLab Bearer anahtarı içermeyen istekler 401 InvalidCredential hatası döndürür.

ProjectName varsayılan olarak default değerindedir ve kimliği doğrulanmış organizasyon içinde gerçek bir izolasyon sınırıdır. İlgili grupları ve varlıkları oluştururken, listelerken, okurken, güncellerken veya silerken aynı değeri kullanın.

Materyal Grubu Eylemleri

EylemAmaçİstek gövdesi
CreateAssetGroupSanal avatar materyal grubu oluşturmaName; isteğe bağlı Description; isteğe bağlı GroupType: "AIGC"; ProjectName
ListAssetGroupsBir projedeki grupları listelemeİsteğe bağlı Filter.GroupIds, Filter.GroupType, Filter.Name; PageNumber, PageSize, SortBy, SortOrder, ProjectName
GetAssetGroupBir grubu okumaId, ProjectName
UpdateAssetGroupGrup adını veya açıklamasını değiştirmeId; Name ve/veya Description; ProjectName
DeleteAssetGroupBir grubu ve varlıklarını silmeId, ProjectName

CreateAssetGroup yalnızca GroupType: "AIGC" değerini kabul eder. Bir LivenessFace grubu, bu Eylem ile değil, başarılı bir gerçek kişi doğrulaması ile oluşturulur. ListAssetGroups hem AIGC hem de LivenessFace gruplarını filtreleyebilir. Name 1–64 karakter, Description ise en fazla 300 karakter olabilir; bu, /v1/videos/assets* REST uç noktalarının limitlerinden daha kısadır.

Bir Grup Oluşturma

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

Materyal Varlığı Eylemleri

EylemAmaçİstek gövdesi
CreateAssetHalka açık bir görsel, video veya ses URL'sini içe aktarmaGroupId, URL, Name, AssetType, ProjectName
ListAssetsBir projedeki varlıkları listelemeİsteğe bağlı Filter.GroupIds, Filter.GroupType, Filter.Statuses, Filter.Name; PageNumber, PageSize, SortBy, SortOrder, ProjectName
GetAssetBir varlığı ve geçici URL'sini okumaId, ProjectName
UpdateAssetBir varlığı yeniden adlandırmaId; isteğe bağlı Name; ProjectName
DeleteAssetBir varlığı silmeId, ProjectName

AssetType, Image, Video veya Audio değerlerini kabul eder. Hedef grup, varlığın normal bir AIGC materyali mi yoksa doğrulanmış bir LivenessFace materyali mi olduğunu belirler.

Bir Varlık Oluşturma

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 materyal kimliklerini (ID) kullanın. CreateAsset, işlem tamamlanmadan önce Result.Id değerini döndürür; Result.Status değeri Active veya Failed olana kadar GetAsset ile sorgulama yapın. ListAssets ayrıca SortBy: "GroupId" parametresini kabul eder.

Listeleme Davranışı

PageNumber varsayılan olarak 1'dir; PageSize varsayılan olarak 10'dur ve en fazla 100 değerini kabul eder. SortBy, CreateTime veya UpdateTime değerlerini; SortOrder ise Desc veya Asc değerlerini kabul eder.

Liste yanıtları şunları döndürür:

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

Varlık durum değerleri Active, Processing ve Failed şeklindedir. GetAsset ve ListAssets, 12 saat boyunca geçerli olan geçici bir URL döndürür; bunu kalıcı varlık kimliği olarak saklamayın. Bunun yerine Id değerini saklayın.

Sonuçlar

EylemResult (ana alanlar)
CreateAssetGroup, CreateAsset, UpdateAssetGroup, UpdateAsset{ "Id": "..." }
DeleteAssetGroup, DeleteAsset{}
GetAssetGroupId, Name, Description, GroupType, ProjectName, CreateTime, UpdateTime
GetAssetId, GroupId, Name, AssetType, URL, Status, Error (Code ve Message, varlık başarısız olmadıkça boştur), ProjectName, CreateTime, UpdateTime

Zamanlar ISO 8601 dizeleridir. ListAssetGroups ve ListAssets, bu nesneleri Result.Items içinde döndürür.

Gerçek Kişi Materyalleri

Gerçek bir kişi için varlık içe aktarmadan önce:

  1. Görsel Doğrulama Oturumu Oluştur işlevini çağırın.
  2. H5 doğrulama akışını tamamlayın.
  3. Result.GroupId dönene kadar Görsel Doğrulama Sonucunu Al işlevini çağırın.
  4. Doğrulanmış grup kimliği ile CreateAsset işlevini çağırın.

LivenessFace grubuna yapılan yüklemeler, doğrulanmış yüz ile karşılaştırılarak kontrol edilir. DeleteAssetGroup, doğrulanmış bir gerçek kişi grubunu silmez; 409 OperationDenied hatası döndürür.

Hatalar

Hatalar, Volcengine yanıt zarfını korur ve kodu ile mesajı ResponseMetadata.Error altında tutar.

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

Yaygın kodlar arasında InvalidCredential, InvalidVersion, InvalidParameter, ResourceNotFound, Conflict, OperationDenied, MethodNotAllowed, AccessDenied, FlowLimitExceeded ve InternalError bulunur. HTTP durumu; hatalı istekler için 400, eksik grup veya varlık için 404, çakışmalar için 409 ve POST olmayan yöntemler için 405 şeklindedir.

REST Alternatifi

TokenLab'in /v1/videos/assets* REST uç noktaları kullanılabilir durumdadır. Yeni TokenLab yerel entegrasyonları, snake_case gövdelerini tercih edebilir; mevcut Volcengine istemcileri, istekleri yeniden şekillendirmeye gerek kalmadan bu sayfadaki Eylemleri kullanabilir. Eksiksiz varlık yaşam döngüsü için Seedance Materyalleri ve Gerçek Kişi Doğrulaması bölümüne bakın.

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

Yetkilendirme

BearerAuth
AuthorizationBearer <token>

API Anahtarı kimlik doğrulaması. API anahtarlarını Dashboard > API > API Keys bölümünden oluşturun veya yönetin.

Konum: header

Sorgu parametreleri

Action?string

Geçerli değerler

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

Başlıklar

X-TokenLab-Delivery-Policy?string

İstek bazlı Teslimat politikası. API anahtarı ve Çalışma Alanı varsayılanlarını geçersiz kılar. Otomatik olarak önce TokenLab Verified dener ve çıktı, istek kabulü veya kalıcı kaynak oluşturma öncesinde bir kez Official seçeneğine geçiş yapabilir.

Geçerli değerler

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

İstek gövdesi

application/json

Yanıt

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json