Video & Materialien

Material Actions (Volc-kompatibel)

Referenz für die 10 Volcengine-kompatiblen Material- und Materialgruppen-Actions.

POST
/api/v3

Diese Endpunkte unterstützen die unten aufgeführten Material-Actions und -Felder unter Verwendung der TokenLab Bearer-Authentifizierung und des ResponseMetadata + Result-Envelopes.

Endpunkt und Authentifizierung

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 wird ebenfalls unterstützt. Alle Material-Actions sind nur per POST verfügbar. Volcengine AK/SK-Signaturen werden nicht akzeptiert; eine Anfrage ohne gültigen TokenLab Bearer-Key gibt 401 InvalidCredential zurück.

ProjectName ist standardmäßig auf default gesetzt und stellt eine echte Isolationsgrenze innerhalb der authentifizierten Organisation dar. Verwenden Sie denselben Wert beim Erstellen, Auflisten, Lesen, Aktualisieren oder Löschen zugehöriger Gruppen und Assets.

Materialgruppen-Actions

ActionZweckRequest Body
CreateAssetGroupErstellen einer Materialgruppe für virtuelle AvatareName; optional Description; optional GroupType: "AIGC"; ProjectName
ListAssetGroupsAuflisten von Gruppen in einem ProjektOptional Filter.GroupIds, Filter.GroupType, Filter.Name; PageNumber, PageSize, SortBy, SortOrder, ProjectName
GetAssetGroupLesen einer GruppeId, ProjectName
UpdateAssetGroupÄndern des Gruppennamens oder der BeschreibungId; Name und/oder Description; ProjectName
DeleteAssetGroupLöschen einer Gruppe und ihrer AssetsId, ProjectName

CreateAssetGroup akzeptiert nur GroupType: "AIGC". Eine LivenessFace-Gruppe wird durch eine erfolgreiche Identitätsprüfung einer echten Person erstellt, nicht durch diese Action. ListAssetGroups kann sowohl AIGC- als auch LivenessFace-Gruppen filtern. Name darf 1–64 Zeichen lang sein und Description bis zu 300 Zeichen, was kürzer ist als die Grenzwerte der /v1/videos/assets* REST-Endpunkte.

Erstellen einer Gruppe

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

Material-Asset-Actions

ActionZweckRequest Body
CreateAssetImportieren einer öffentlichen Bild-, Video- oder Audio-URLGroupId, URL, Name, AssetType, ProjectName
ListAssetsAuflisten von Assets in einem ProjektOptional Filter.GroupIds, Filter.GroupType, Filter.Statuses, Filter.Name; PageNumber, PageSize, SortBy, SortOrder, ProjectName
GetAssetLesen eines Assets und seiner temporären URLId, ProjectName
UpdateAssetUmbenennen eines AssetsId; optional Name; ProjectName
DeleteAssetLöschen eines AssetsId, ProjectName

AssetType akzeptiert Image, Video oder Audio. Die Zielgruppe bestimmt, ob das Asset ein normales AIGC-Material oder ein verifiziertes LivenessFace-Material ist.

Erstellen eines Assets

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

Verwenden Sie TokenLab-Material-IDs. CreateAsset gibt Result.Id zurück, bevor die Verarbeitung abgeschlossen ist; pollen Sie GetAsset, bis Result.Status den Wert Active oder Failed hat. ListAssets akzeptiert auch SortBy: "GroupId".

Listenverhalten

PageNumber ist standardmäßig 1; PageSize ist standardmäßig 10 und akzeptiert bis zu 100. SortBy akzeptiert CreateTime oder UpdateTime; SortOrder akzeptiert Desc oder Asc.

Listen-Antworten geben Folgendes zurück:

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

Asset-Statuswerte sind Active, Processing und Failed. GetAsset und ListAssets geben eine temporäre URL zurück, die 12 Stunden lang gültig ist; speichern Sie diese nicht als permanente Asset-Identität. Speichern Sie stattdessen die Id.

Ergebnisse

ActionResult (Hauptfelder)
CreateAssetGroup, CreateAsset, UpdateAssetGroup, UpdateAsset{ "Id": "..." }
DeleteAssetGroup, DeleteAsset{}
GetAssetGroupId, Name, Description, GroupType, ProjectName, CreateTime, UpdateTime
GetAssetId, GroupId, Name, AssetType, URL, Status, Error (Code und Message, leer, sofern das Asset nicht fehlgeschlagen ist), ProjectName, CreateTime, UpdateTime

Zeiten sind ISO 8601-Strings. ListAssetGroups und ListAssets geben diese Objekte in Result.Items zurück.

Materialien für echte Personen

Bevor Sie ein Asset für eine echte Person importieren:

  1. Rufen Sie Visuelle Validierungssitzung erstellen auf.
  2. Schließen Sie den H5-Verifizierungsprozess ab.
  3. Rufen Sie Ergebnis der visuellen Validierung abrufen auf, bis es Result.GroupId zurückgibt.
  4. Rufen Sie CreateAsset mit dieser verifizierten Gruppen-ID auf.

Uploads in eine LivenessFace-Gruppe werden gegen das verifizierte Gesicht geprüft. DeleteAssetGroup löscht keine verifizierte Gruppe einer echten Person; es gibt 409 OperationDenied zurück.

Fehler

Fehler behalten das Volcengine-Antwort-Envelope bei und platzieren den Code und die Nachricht unter ResponseMetadata.Error.

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

Zu den gängigen Codes gehören InvalidCredential, InvalidVersion, InvalidParameter, ResourceNotFound, Conflict, OperationDenied, MethodNotAllowed, AccessDenied, FlowLimitExceeded und InternalError. Der HTTP-Status ist 400 für fehlerhafte Anfragen, 404 für eine fehlende Gruppe oder ein fehlendes Asset, 409 für Konflikte und 405 für eine Nicht-POST-Methode.

REST-Alternative

Die /v1/videos/assets* REST-Endpunkte von TokenLab bleiben verfügbar. Neue TokenLab-native Integrationen bevorzugen möglicherweise deren snake_case-Bodies; bestehende Volcengine-Clients können die Actions auf dieser Seite verwenden, ohne Anfragen umzustrukturieren. Siehe Seedance-Materialien und Personenverifizierung für den vollständigen Asset-Lebenszyklus.

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

Autorisierung

BearerAuth
AuthorizationBearer <token>

API-Key-Authentifizierung. Erstellen oder verwalten Sie API-Keys unter Dashboard > API > API Keys.

Ort: header

Abfrageparameter

Action?string

Zulässige Werte

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

Header

X-TokenLab-Delivery-Policy?string

Zustellungsrichtlinie pro Anfrage. Überschreibt die API-Key- und Workspace-Standardeinstellungen. Versucht automatisch zuerst TokenLab Verified und kann vor der Ausgabe, der Annahme der Anfrage oder der Erstellung persistenter Ressourcen einmalig auf Official umstellen.

Zulässige Werte

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

Anfragekörper

application/json

Antwort

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json