الفيديو والمواد
إجراءات المواد (متوافقة مع Volc)
مرجع لـ 10 إجراءات للمواد ومجموعات المواد المتوافقة مع Volcengine.
تدعم نقاط النهاية هذه إجراءات المواد والحقول المدرجة أدناه، باستخدام مصادقة 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 | {} |
GetAssetGroup | Id, Name, Description, GroupType, ProjectName, CreateTime, UpdateTime |
GetAsset | Id, GroupId, Name, AssetType, URL, Status, Error (Code و Message، فارغة ما لم يفشل الأصل)، ProjectName, CreateTime, UpdateTime |
الأوقات هي سلاسل نصية بتنسيق ISO 8601. تعيد ListAssetGroups و ListAssets هذه الكائنات في Result.Items.
مواد التحقق من الشخص الحقيقي
قبل استيراد أصل لشخص حقيقي:
- استدعِ إنشاء جلسة تحقق مرئي.
- أكمل تدفق التحقق عبر H5.
- استدعِ الحصول على نتيجة التحقق المرئي حتى تعيد
Result.GroupId. - استدعِ
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 مصادقة مفتاح API. قم بإنشاء أو إدارة مفاتيح API في Dashboard > API > API Keys.
الموضع: header
معاملات الاستعلام
القيم المتاحة
- "CreateContentsGenerationsTasks"
- "GetContentsGenerationsTask"
- "ListContentsGenerationsTasks"
- "DeleteContentsGenerationsTasks"
- "CreateVisualValidateSession"
- "GetVisualValidateResult"
- "CreateAssetGroup"
- "ListAssetGroups"
- "GetAssetGroup"
- "UpdateAssetGroup"
- "DeleteAssetGroup"
- "CreateAsset"
- "ListAssets"
- "GetAsset"
- "UpdateAsset"
- "DeleteAsset"
"2024-01-01"الترويسات
سياسة التسليم لكل طلب. تتجاوز إعدادات 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