الفيديو والمواد

إجراءات المواد (متوافقة مع Volc)

مرجع لـ 10 إجراءات للمواد ومجموعات المواد المتوافقة مع Volcengine.

POST
/api/v3

تدعم نقاط النهاية هذه إجراءات المواد والحقول المدرجة أدناه، باستخدام مصادقة TokenLab Bearer وغلاف ResponseMetadata + Result.

نقطة النهاية والمصادقة

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 أيضاً. جميع إجراءات المواد هي من نوع POST فقط. لا يتم قبول توقيعات Volcengine AK/SK؛ الطلب الذي لا يحتوي على مفتاح TokenLab Bearer صالح سيعيد 401 InvalidCredential.

يتم تعيين ProjectName افتراضياً على default وهو حد عزل حقيقي داخل المؤسسة الموثقة. استخدم نفس القيمة عند إنشاء أو سرد أو قراءة أو تحديث أو حذف المجموعات والأصول ذات الصلة.

إجراءات مجموعة المواد (Material-Group Actions)

الإجراءالغرضنص الطلب
CreateAssetGroupإنشاء مجموعة مواد للصور الرمزية الافتراضيةName؛ Description اختياري؛ GroupType: "AIGC" اختياري؛ ProjectName
ListAssetGroupsسرد المجموعات في مشروع واحدFilter.GroupIds اختياري، Filter.GroupType، Filter.Name؛ PageNumber، PageSize، SortBy، SortOrder، ProjectName
GetAssetGroupقراءة مجموعة واحدةId، ProjectName
UpdateAssetGroupتغيير اسم المجموعة أو وصفهاId؛ Name و/أو Description؛ ProjectName
DeleteAssetGroupحذف مجموعة وأصولهاId، ProjectName

يقبل CreateAssetGroup فقط GroupType: "AIGC". يتم إنشاء مجموعة LivenessFace من خلال التحقق الناجح من الشخص الحقيقي، وليس بواسطة هذا الإجراء. يمكن لـ ListAssetGroups تصفية مجموعات AIGC و LivenessFace. يتراوح طول Name بين 1-64 حرفاً، ويصل طول Description إلى 300 حرف، وهو أقصر من حدود نقاط نهاية REST الخاصة بـ /v1/videos/assets*.

إنشاء مجموعة

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)

الإجراءالغرضنص الطلب
CreateAssetاستيراد رابط صورة أو فيديو أو صوت عامGroupId، URL، Name، AssetType، ProjectName
ListAssetsسرد الأصول في مشروع واحدFilter.GroupIds اختياري، Filter.GroupType، Filter.Statuses، Filter.Name؛ PageNumber، PageSize، SortBy، SortOrder، ProjectName
GetAssetقراءة أصل واحد ورابطه المؤقتId، ProjectName
UpdateAssetإعادة تسمية أصلId؛ Name اختياري؛ ProjectName
DeleteAssetحذف أصل واحدId، ProjectName

يقبل AssetType كلاً من Image أو Video أو Audio. تحدد المجموعة المستهدفة ما إذا كان الأصل مادة AIGC عادية أو مادة LivenessFace تم التحقق منها.

إنشاء أصل

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. يعيد CreateAsset قيمة Result.Id قبل انتهاء المعالجة؛ قم بعمل استطلاع (poll) لـ GetAsset حتى تصبح Result.Status هي Active أو Failed. يقبل ListAssets أيضاً SortBy: "GroupId".

سلوك السرد (List Behavior)

يتم تعيين PageNumber افتراضياً على 1؛ ويتم تعيين PageSize افتراضياً على 10 ويقبل حتى 100. يقبل SortBy كلاً من CreateTime أو UpdateTime؛ ويقبل SortOrder كلاً من Desc أو Asc.

تعيد استجابات السرد:

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

قيم حالة الأصل هي Active و Processing و Failed. تعيد GetAsset و ListAssets رابط URL مؤقتاً صالحاً لمدة 12 ساعة؛ لا تقم بتخزينه كهوية دائمة للأصل. قم بتخزين Id بدلاً من ذلك.

النتائج

الإجراءResult (الحقول الرئيسية)
CreateAssetGroup, CreateAsset, UpdateAssetGroup, UpdateAsset{ "Id": "..." }
DeleteAssetGroup, DeleteAsset{}
GetAssetGroupId, Name, Description, GroupType, ProjectName, CreateTime, UpdateTime
GetAssetId, GroupId, Name, AssetType, URL, Status, Error (Code و Message، فارغة ما لم يفشل الأصل)، ProjectName, CreateTime, UpdateTime

الأوقات هي سلاسل نصية بتنسيق ISO 8601. تعيد ListAssetGroups و ListAssets هذه الكائنات في Result.Items.

مواد التحقق من الشخص الحقيقي

قبل استيراد أصل لشخص حقيقي:

  1. استدعِ إنشاء جلسة تحقق مرئي.
  2. أكمل تدفق التحقق عبر H5.
  3. استدعِ الحصول على نتيجة التحقق المرئي حتى تعيد Result.GroupId.
  4. استدعِ CreateAsset باستخدام معرف المجموعة الذي تم التحقق منه.

يتم فحص عمليات الرفع إلى مجموعة LivenessFace مقابل الوجه الذي تم التحقق منه. لا يقوم DeleteAssetGroup بحذف مجموعة شخص حقيقي تم التحقق منها؛ بل يعيد 409 OperationDenied.

الأخطاء

تحتفظ الأخطاء بغلاف استجابة Volcengine وتضع الكود والرسالة تحت ResponseMetadata.Error.

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

تشمل الأكواد الشائعة InvalidCredential و InvalidVersion و InvalidParameter و ResourceNotFound و Conflict و OperationDenied و MethodNotAllowed و AccessDenied و FlowLimitExceeded و InternalError. حالة HTTP هي 400 للطلبات غير الصحيحة، و 404 للمجموعة أو الأصل المفقود، و 409 للتعارضات، و 405 لطريقة غير POST.

بديل REST

لا تزال نقاط نهاية REST الخاصة بـ /v1/videos/assets* في TokenLab متاحة. قد تفضل عمليات التكامل الأصلية الجديدة مع TokenLab أجسام الطلبات بتنسيق snake_case؛ يمكن لعملاء Volcengine الحاليين استخدام الإجراءات الموجودة في هذه الصفحة دون إعادة تشكيل الطلبات. راجع مواد Seedance والتحقق من الشخص الحقيقي للاطلاع على دورة حياة الأصل الكاملة.

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

التفويض

BearerAuth
AuthorizationBearer <token>

مصادقة مفتاح API. قم بإنشاء أو إدارة مفاتيح API في Dashboard > API > API Keys.

الموضع: header

معاملات الاستعلام

Action?string

القيم المتاحة

  • "CreateContentsGenerationsTasks"
  • "GetContentsGenerationsTask"
  • "ListContentsGenerationsTasks"
  • "DeleteContentsGenerationsTasks"
  • "CreateVisualValidateSession"
  • "GetVisualValidateResult"
  • "CreateAssetGroup"
  • "ListAssetGroups"
  • "GetAssetGroup"
  • "UpdateAssetGroup"
  • "DeleteAssetGroup"
  • "CreateAsset"
  • "ListAssets"
  • "GetAsset"
  • "UpdateAsset"
  • "DeleteAsset"
Version?string
الافتراضي"2024-01-01"

الترويسات

X-TokenLab-Delivery-Policy?string

سياسة التسليم لكل طلب. تتجاوز إعدادات API key و Workspace الافتراضية. يحاول النظام تلقائياً استخدام TokenLab Verified أولاً، وقد ينتقل مرة واحدة إلى Official فقط قبل المخرجات، أو قبول الطلب، أو إنشاء مورد دائم.

القيم المتاحة

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

جسم الطلب

application/json

الاستجابة

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json