Material Actions (Volc-kompatibel)

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 AuthentifizierungCopy Anchor Link

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-ActionsCopy Anchor Link

CreateAssetGroup akzeptiert nur GroupType: "AIGC". Eine LivenessFace-Gruppe wird durch eine erfolgreiche Identitätsprüfung (Real-Person Verification) erstellt, nicht durch diese Action. ListAssetGroups kann sowohl AIGC- als auch LivenessFace-Gruppen filtern.

Erstellen einer GruppeCopy Anchor Link

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-ActionsCopy Anchor Link

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

Erstellen eines AssetsCopy Anchor Link

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 annimmt. ListAssets akzeptiert auch SortBy: "GroupId".

ListenverhaltenCopy Anchor Link

PageNumber ist standardmäßig 1; PageSize ist standardmäßig 10 und akzeptiert Werte 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.

Materialien für echte Personen (Real-Person Materials)Copy Anchor Link

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

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

Uploads in eine LivenessFace-Gruppe werden mit dem verifizierten Gesicht abgeglichen. Aktive verifizierte Gruppen können zudem strengere Löschregeln haben als gewöhnliche AIGC-Gruppen.

FehlerCopy Anchor Link

Fehler behalten das Volcengine-Antwort-Envelope bei und platzieren den Code sowie 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, NotFound, Conflict, OperationDenied, MethodNotAllowed und InternalError.

REST-AlternativeCopy Anchor Link

Die REST-Endpunkte /v1/videos/assets* 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 umstrukturieren zu müssen. 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"}