عرض فيديوهات حساب TikTok عبر واجهة برمجة التطبيقات (API)
تعرض واجهة TikTok للأعمال منشورات الحساب العامة عبر GET /business/video/list/، بدءًا من الأحدث، بحد أقصى 20 منشورًا في الصفحة. سمِّ الحقول المطلوبة، مثل item_id وcaption وshare_url وvideo_views، وتنقّل بين الصفحات باستخدام cursor ما دام has_more هو true. يحدد filters.video_ids منشورات بعينها، وكل item_id هو المعرّف الذي تأخذه استدعاءات التعليقات.
يعرض easyCoexistence منشورات الحساب الأخيرة على TikTok بواسطة list_social_posts من Claude أو ChatGPT أو من شيفرتك البرمجية، مع item_id والوصف والرابط والأعداد لكل منشور، ويمنح get_social_credentials شيفرتك البرمجية token للصفحات اللاحقة والحقول الأخرى.
أقصى عدد من المنشورات يعيده /business/video/list/ في الصفحة الواحدة، وقيمة max_count الافتراضية 10.
وحدة cursor هي طابع زمني من نوع Unix بالتوقيت العالمي UTC؛ وتعيد الواجهة المنشورات التي نُشرت قبله.
الحقل الافتراضي يجب أن يتضمنه أي طلب يسمي عدة حقول، وإلا قد يظهر خطأ.
عدد الاستدعاءات المسموح بها لكل حساب مرخص في هذه النقطة، كما في كل نقطة من Accounts API.
ماذا تعيد الواجهة؟
المنشورات العامة للحساب: الفيديوهات المعروضة على ملفه الشخصي، ومنشورات الصور والنصوص، وفيديوهات «Only show in ads» التي تعمل إعلانات دون أن تظهر على الملف الشخصي. يميّز media_type بين VIDEO وPHOTO، وهو ما يشمل منشورات الصور والنصوص. تُستبعد من القائمة المنشورات التي حجبتها TikTok بسبب مخالفات، مثل حقوق نشر الموسيقى.
كيف تستدعيها؟
بطلب GET ومعاملات في عنوان URL: business_id وfields كمصفوفة JSON، واختياريًا filters وcursor وmax_count، وقيمته الافتراضية 10. يوضع رمز الوصول (token) في الترويسة Access-Token، وتحتاج صلاحية Get Account Media ضمن TikTok Accounts:
curl -G 'https://business-api.tiktok.com/open_api/v1.3/business/video/list/' \
-H 'Access-Token: <ACCESS_TOKEN>' \
--data-urlencode 'business_id=<OPEN_ID>' \
--data-urlencode 'fields=["item_id","create_time","media_type","caption","share_url","thumbnail_url","video_views","likes","comments","shares"]' \
--data-urlencode 'max_count=20'أي الحقول تصف المنشور؟
إلى جانب المقاييس، التي تمتد من video_views إلى impression_sources، تتضمن القائمة الحقول التالية، وكلها ضمن النطاق video.list:
item_id: معرّف المنشور، وتستخدمه استدعاءات التعليقات وfilters.video_ids.media_type: VIDEO أو PHOTO لمنشور صورة أو نص.is_ad: هل يُستخدم المنشور في إعلان.create_time: وقت نشر المنشور، وهو عدد ثوانٍ من نوع Unix في التوقيت العالمي.- caption: وصف المنشور، بما في ذلك الهاشتاغات.
share_url: رابط قابل للمشاركة، ويتصرف بشكل مختلف على الجوال وسطح المكتب.embed_url: رابط مشغّل لمواقع أخرى، ولا يعمل مع المنشورات المضبوطة على Only you أو Friends.thumbnail_url: معاينة مؤقتة، وينتهي صلاحيتها في المعامل x-expires.video_duration: مدة الفيديو بالثواني، بثلاث خانات عشرية.
كيف تبدو صفحة النتائج؟
مصفوفة videos بالترتيب الذي تعيده TikTok، إضافة إلى cursor، وهي القيمة التي تُرسل لطلب الصفحة التالية، وhas_more، الذي يحدد هل توجد صفحة تالية. يأتي create_time نصًا يحمل ثوانيَ Unix. مثال TikTok، مختصر إلى الحقول الوصفية والأعداد:
{
"code": 0,
"message": "OK",
"request_id": "2021080307532501024502410704A7306F",
"data": {
"videos": [
{
"item_id": "6990565363377392901",
"create_time": "1627617835",
"caption": "little coco",
"share_url": "https://www.tiktok.com/@feather_in_the_w1nd/video/6990565363377392901?utm_campaign=tt4d_open_api&utm_source=6979330045630218242",
"likes": 10,
"comments": 2,
"shares": 0,
"video_views": 1231
}
],
"cursor": 0,
"has_more": false
}
}كيف يعمل التصفح؟
بالزمن. القيمة الافتراضية لـ cursor هي اللحظة الحالية بالمللي ثانية، فتحتوي الصفحة الأولى على أحدث المنشورات، ويعيد كل رد قيمة cursor للطلب التالي. أرسلها ما دام has_more مساويًا لـ true. يعرض طابع زمني مخصص المنشورات التي نُشرت قبل تلك اللحظة، وقد تجعل قواعد الثقة والسلامة في TikTok الصفحة أقصر من max_count حتى مع بقاء منشورات أخرى.
import json, requests
API = "https://business-api.tiktok.com/open_api/v1.3"
def all_posts(token: str, business_id: str, fields: list[str]):
params = {"business_id": business_id, "fields": json.dumps(fields), "max_count": 20}
while True:
r = requests.get(f"{API}/business/video/list/", headers={"Access-Token": token},
params=params, timeout=30).json()
if r["code"] != 0:
raise RuntimeError(f"{r['code']}: {r['message']}")
yield from r["data"].get("videos", [])
if not r["data"].get("has_more"):
return
params["cursor"] = r["data"]["cursor"]كيف تجلب منشورات بعينها؟
بواسطة filters، وهو كائن JSON: يسرد video_ids معرّفات المنشورات المطلوبة، مثل post_ids من حالة النشر. يُبقي ad_post_only، ولا يصح إلا إلى جانب video_ids، المنشورات المصرّح للمعلنين باستخدامها في Spark Ads فقط. يأخذ الطلب المصفّى الحقول نفسها التي تأخذها أي طلب آخر، فيمكن لاستدعاء واحد أن يعيد أحدث الأرقام لعدد قليل من المنشورات المعروفة.
filters={"video_ids":["6995316737801538821","8015388216995316737"]}ما الحدود المطبقة؟
تسمح Accounts API بـ 40 استدعاء في الدقيقة لكل حساب مرخص في هذه النقطة، وتحصل استدعاءات Accounts API للتطبيق مجتمعةً على 600 في الدقيقة في المستوى Basic، و1,000 فوقه. الحقول الوصفية فورية، أما الأعداد فتتأخر عادة من 24 إلى 48 ساعة، وتتوقف بيانات المنشور عن التحديث بعد 365 يومًا من نشره.
كيف يعرض easyCoexistence الفيديوهات؟
بواسطة list_social_posts، الذي يأخذ account_id وlimit اختياريًا، من 1 إلى 20 لـ TikTok. يعيد الصفحة الأولى من TikTok: أحدث المنشورات مع item_id وcreate_time وcaption وshare_url وthumbnail_url وvideo_views وlikes وcomments وshares، إضافة إلى cursor وhas_more. وتُجلب الصفحات اللاحقة والحقول الأخرى من الكود الخاص بك، بواسطة token وbusiness_id من get_social_credentials:
GET https://business-api.tiktok.com/open_api/v1.3/business/video/list/
?business_id=<BUSINESS_ID>
&fields=["item_id","media_type","caption","embed_url"]
&cursor=1793404800000
&max_count=20
Access-Token: <ACCESS_TOKEN>الأخطاء الشائعة
- طلب حقول دون item_id. يحذّر مرجع TikTok من أن الطلب الذي يسمي عدة حقول دون هذا الحقل قد يفشل.
- التوقف عند وصول صفحة أقصر من المعتاد. قد تعيد TikTok منشورات أقل من max_count بينما يبقى has_more مساويًا لـ true، لذا اتبع has_more بدلًا من ذلك.
- تخزين thumbnail_url لاستخدامه لاحقًا. هو رابط مؤقت ينتهي في الوقت الوارد في معامله x-expires، لذا اجلب رابطًا جديدًا عند الحاجة إليه.
- البحث عن منشورات خاصة في القائمة. تعيد الواجهة المنشورات العامة فقط.
من US$ 9 إلى US$ 0.75 لكل اتصال شهريًا، ويقل السعر كلما أضفت اتصالات، مع فترة تجريبية مجانية مدتها 3 أيام.
الأسئلة الشائعة
كم عدد فيديوهات TikTok التي تستطيع API سردها دفعة واحدة؟
حتى 20 في الصفحة الواحدة من /business/video/list/. يحدد max_count حجم الصفحة، وقيمته الافتراضية 10؛ اتبع cursor لجلب المزيد.
هل تعيد واجهة TikTok منشورات الصور أيضًا؟
نعم. يعيد /business/video/list/ فيديوهات وصورًا ونصوصًا عامة، ويميّز media_type بين VIDEO وPHOTO.
هل تتضمن قائمة الفيديوهات في TikTok منشورات الإعلانات فقط؟
نعم. يعيد /business/video/list/ أيضًا فيديوهات «Only show in ads» التي تعمل إعلانات دون أن تظهر على الملف الشخصي، ويبيّن is_ad إن كان المنشور مستخدمًا في إعلان.
لماذا يغيب منشور على TikTok من قائمة API؟
تسرد الواجهة المنشورات العامة فقط، وتستبعد TikTok المنشورات التي حجبتها بسبب مخالفات مثل حقوق نشر الموسيقى.
تابع القراءة
اربط قناتك الأولى في دقيقتين.
لا حاجة لانتظار مراجعات المنصات. اربط WhatsApp أو Instagram أو TikTok أو أي قناة أخرى، ثم اطلب من الذكاء الاصطناعي النشر أو الرد أو إعداد التقارير، وشاهده يعمل.
- 3 أيام مجانًا
- إلغاء في أي وقت
- واجهات API الرسمية فقط
- مراقبة على مدار الساعة 24/7
تم التحقق في