إذا كنت تبني سير عمل للفيديو على Seedance 2.0 أو 2.0-Fast، فإن "مكتبة الأصول" (Asset Library) هي الطريقة التي يمكنك من خلالها إدخال الوسائط المرجعية - صور، فيديو، وصوت - إلى عمليات التوليد الخاصة بك بشكل نظيف. بدلاً من تمرير الوسائط الأولية في كل استدعاء، تقوم بتسجيل الملف مرة واحدة، ليقوم Atlas بالتحقق منه ومعالجته مسبقاً، ثم تشير إليه عبر معرف ثابت (ID) في أي عدد تريده من عمليات التوليد.

يأخذك هذا الدليل من البداية إلى الحصول على مرجع يعمل في ثلاثة استدعاءات cURL.

ما هي مكتبة الأصول (وما هي فوائدها)

هي متجر وسائط مُدار مخصص لتوليد الفيديو باستخدام Seedance 2.0 / 2.0-Fast. أنت تقوم بتسجيل الأصل (Asset)، ثم تتم معالجته، وبمجرد أن يصبح بحالة "نشط" (Active)، تشير إليه بالصيغة asset://<asset_id> في طلب التوليد الخاص بك.

هناك أمران يجب معرفتهما مسبقاً لتوفير وقتك في تصحيح الأخطاء:

• يجب تسجيل الفيديو والصوت هنا أولاً. لا يمكن تمريرهما ضمن طلب التوليد مباشرة كرابط (URL)، فالصور فقط هي التي يمكن تمريرها مباشرة. لذا، بالنسبة لأي سير عمل يعتمد على مرجع فيديو أو صوت، تُعد مكتبة الأصول نقطة الدخول الإلزامية وليست خياراً إضافياً.
• يتم الرفع عبر رابط عام (Public URL) فقط. صيغ Base64 أو روابط البيانات غير مدعومة. يجب أن يكون الملف متاحاً عبر رابط عام يمكن الوصول إليه عند تسجيله.

قبل البدء

ستحتاج إلى مفتاح API من Atlas Cloud عبر لوحة التحكم.

تفصيلة هامة قد يغفل عنها البعض: مكتبة الأصول وAPI التوليد يعملان على مضيفين (Hosts) مختلفين.

td {white-space:nowrap;border:0.5pt solid #dee0e3;font-size:10pt;font-style:normal;font-weight:normal;vertical-align:middle;word-break:normal;word-wrap:normal;}

كلاهما يستخدم نفس ترويسة المصادقة:

plaintextCopy
1export ATLASCLOUD_API_KEY="your-api-key-here"

plaintextCopy
1Authorization: Bearer $ATLASCLOUD_API_KEY

خطوات العمل الثلاث

التسجيل ← الفحص حتى يصبح "نشطاً" (Active) ← الإشارة إليه في التوليد.

الخطوة 1 — تسجيل أصل

وجّه Atlas إلى رابط عام. حدد النوع كـ Image أو Video أو Audio (الافتراضي هو Image).

plaintextCopy
1curl -X POST "https://console.atlascloud.ai/api/v1/sd/assets" \
2  -H "Authorization: Bearer $ATLASCLOUD_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "type": "Video",
6    "url": "https://your-public-host.com/reference-clip.mp4"
7  }'

ستعيد الاستجابة معرف الأصل (id) وحالة المعالجة (Processing).

سيبدو الأمر كما في الصورة أدناه:

احتفظ بالمعرف (id) الموضح أعلاه؛ فهو ما ستستخدمه للفحص والإشارة إليه.

ملاحظة سريعة: ما المقصود بـ "الرابط العام" (Public URL)؟

هذه الخطوة يخطئ فيها الكثيرون، لذا يجب توضيحها بدقة. يقوم Atlas بجلب ملفك عبر طلب HTTP GET عادي على الرابط. يجب أن يعيد ذلك الرابط بيانات الملف الخام مباشرة — بدون تسجيل دخول، بدون ملفات تعريف ارتباط (cookies)، بدون صفحة "اضغط للمشاهدة"، وبدون الحاجة إلى JavaScript لعرضه.

الاختبار السريع: افتح الرابط في تبويب متصفح خاص (Incognito). إذا ظهرت الصورة أو تم تنزيل الفيديو دون طلب تسجيل دخول، فسيتمكن Atlas من جلبه. إذا ظهرت صفحة عرض أو طلب تسجيل دخول أو واجهة معاينة، فلن ينجح الأمر.

هذا يعني أن روابط مشاركة Google Photos أو Google Drive لن تعمل. فهذه الروابط تشير إلى صفحة ويب تعرض الوسائط خلف نظام المصادقة وإعادة التوجيه الخاص بـ Google، وليس إلى الملف نفسه. سيقوم Atlas بجلب غلاف الصفحة، وليس الوسائط.

ما الذي يعمل بدلاً من ذلك:

• تخزين الكائنات (Object storage) مع وصول عام أو رابط موقع مسبقاً (Presigned URL) — مثل Amazon S3، Google Cloud Storage، Cloudflare R2، أو Azure Blob. الروابط الموقعة مسبقاً هي الخيار المثالي: عامة ولكن محدودة زمنياً.
• شبكة توصيل محتوى (CDN) أو خادم ويب خاص بك يخدم الملف مباشرة.
• نقطة نهاية الرفع الخاصة بـ Atlas — إذا كان لديك ملف محلي فقط (أو ملف قمت بتصديره من Google Photos)، ارفعه إلى Atlas أولاً للحصول على رابط تخزين عام، ثم سجل ذلك الرابط:

plaintextCopy
1# رفع ملف محلي ← يعيد رابط public storage.atlascloud.ai
2curl -X POST "https://api.atlascloud.ai/api/v1/model/uploadMedia" \
3  -H "Authorization: Bearer $ATLASCLOUD_API_KEY" \
4  -F "file=@./reference-clip.mp4"

خذ رابط التنزيل (

1download_url

1url

الخطوة 2 — الفحص حتى يصبح "نشطاً" (Active)

يقوم Atlas بالتحقق من الملف ومعالجته. استمر في فحص الأصل حتى تتغير حالته إلى

1Active

plaintextCopy
1curl "https://console.atlascloud.ai/api/v1/sd/assets/<asset_id>" \
2  -H "Authorization: Bearer $ATLASCLOUD_API_KEY"

دورة الحياة هي:

plaintextCopy
1Create → Processing → Active → (ready to use)
2                  ↓
3                Failed → check error_code / error_message

إذا حصلت على حالة

1Failed

1error_code

1error_message

في بعض الأحيان، قد ترى أخطاء انتهاك السياسة كما هو موضح أدناه — يحدث هذا لأن الأصل ربما ينتهك قواعد الاستخدام. إذا كنت تعتقد اعتقاداً راسخاً أن الأصل لا ينتهك أي قواعد أو أنك صاحب حقوق الطبع والنشر بنفسك، يرجى التواصل معنا لحل المشكلة!

الخطوة 3 — الإشارة إليه في عملية التوليد

بمجرد أن يصبح الأصل

1Active

1asset://<asset_id>

1image

1last_image

1reference_images

1reference_video

1reference_audio

لاحظ تغيير المضيف هنا: التوليد يتم على

1api.atlascloud.ai

plaintextCopy
1curl -X POST "https://api.atlascloud.ai/api/v1/model/generateVideo" \
2  -H "Authorization: Bearer $ATLASCLOUD_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "model": "bytedance/seedance-2.0/image-to-video",
6    "input": {
7      "prompt": "A cinematic dolly shot, warm sunset light",
8      "image": "asset://<asset_id>"
9    }
10  }'

يعيد هذا معرف التنبؤ (prediction id). افحصه للحصول على الفيديو النهائي:

plaintextCopy
1curl "https://api.atlascloud.ai/api/v1/model/prediction/<prediction_id>" \
2  -H "Authorization: Bearer $ATLASCLOUD_API_KEY"

عندما تكون الحالة

1completed

1succeeded

1outputs

هذه هي الحلقة الكاملة. الهدف من الأصل هو إعادة الاستخدام: سجل مرة واحدة، وأشر إلى نفس

1asset://<asset_id>

إدارة الأصول

تمنحك المكتبة تحكماً كاملاً في دورة الحياة.

plaintextCopy
1# سرد أصولك (مقسم لصفحات، يدعم الفلاتر)
2curl "https://console.atlascloud.ai/api/v1/sd/assets" \
3  -H "Authorization: Bearer $ATLASCLOUD_API_KEY"
4
5# إعادة تسمية أصل
6curl -X PUT "https://console.atlascloud.ai/api/v1/sd/assets/<asset_id>" \
7  -H "Authorization: Bearer $ATLASCLOUD_API_KEY" \
8  -H "Content-Type: application/json" \
9  -d '{ "name": "sunset-reference-v2" }'
10
11# النقل إلى سلة المهملات (قابل للاستعادة — هذا حذف مؤقت وليس نهائياً)
12curl -X DELETE "https://console.atlascloud.ai/api/v1/sd/assets/<asset_id>" \
13  -H "Authorization: Bearer $ATLASCLOUD_API_KEY"
14
15# سرد الأصول المحذوفة
16curl "https://console.atlascloud.ai/api/v1/sd/assets/trash" \
17  -H "Authorization: Bearer $ATLASCLOUD_API_KEY"
18
19# الاستعادة من سلة المهملات
20curl -X POST "https://console.atlascloud.ai/api/v1/sd/assets/<asset_id>/restore" \
21  -H "Authorization: Bearer $ATLASCLOUD_API_KEY"

الحذف قابل للاستعادة بطبيعته — الأصول تنتقل إلى سلة المهملات ويمكن استعادتها، لذا لن تخسر الأصل بسبب استدعاء خاطئ.

متطلبات الإدخال

يحدث التحقق عند التسجيل، لذا سيفشل الملف غير المتوافق هنا — قبل أن تستهلك رصيد التوليد عليه. طابق هذه الحدود لتجنب حالة

1Failed

الصورة (Image)

td {white-space:nowrap;border:0.5pt solid #dee0e3;font-size:10pt;font-style:normal;font-weight:normal;vertical-align:middle;word-break:normal;word-wrap:normal;}

الفيديو (Video)

td {white-space:nowrap;border:0.5pt solid #dee0e3;font-size:10pt;font-style:normal;font-weight:normal;vertical-align:middle;word-break:normal;word-wrap:normal;}

الصوت (Audio)

td {white-space:nowrap;border:0.5pt solid #dee0e3;font-size:10pt;font-style:normal;font-weight:normal;vertical-align:middle;word-break:normal;word-wrap:normal;}

رموز الأخطاء

td {white-space:nowrap;border:0.5pt solid #dee0e3;font-size:10pt;font-style:normal;font-weight:normal;vertical-align:middle;word-break:normal;word-wrap:normal;}

ملاحظات هامة للتذكر

• يجب تسجيل الفيديو والصوت مسبقاً. الصور فقط هي التي يمكن تمريرها مباشرة. تخطي التسجيل للفيديو/الصوت سيؤدي إلى عدم وجود مرجع لعملية التوليد.
• رابط URL فقط، لا توجد صيغة base64. يجب أن يكون الملف المصدري موجوداً على رابط عام عند التسجيل.
• مضيفان مختلفان. الأصول على
  textCopy

  1console.atlascloud.ai

  ؛ التوليد على
  textCopy

  1api.atlascloud.ai

  . الخلط بينهما هو السبب الأكثر شيوعاً لأخطاء 404 / 401.
• تحقق ثم ولد. المدخلات السيئة تفشل عند التسجيل، وليس أثناء التوليد — وهذا هو جوهر النظام. تحقق من جداول المتطلبات أولاً.

ابدأ البناء

احصل على مفتاح API وجرب سير العمل على نقطة نهاية Seedance 2.0 حقيقية.

• احصل على مفتاح API
• نماذج Seedance 2.0
• التوثيق