كائنات الاستجابة والأخطاء

تقدّم هذه الصفحة معلومات حول عناصر استجابة JSON وعناصر الخطأ المختلفة التي تستخدمها Tenor API.

عنصر الاستجابة

يقدّم الجدول التالي تفاصيل حول سمات "عناصر الرد":

الخصائص
created	float طابع زمني بتنسيق Unix يمثّل وقت إنشاء هذه المشاركة.
hasaudio	boolean تعرض هذه السمة القيمة true إذا كانت هذه المشاركة تتضمّن محتوًى صوتيًا. ملاحظة: تتوافق تنسيقات الفيديو فقط مع الصوت. لا يمكن أن يحتوي تنسيق ملف صورة GIF على معلومات صوتية.
id	string معرّف نتيجة Tenor
media_formats	{ CONTENT_FORMAT : MEDIA_OBJECT } قاموس يتضمّن تنسيق محتوى كمفتاح وعنصر وسائط كقيمة
tags	string[] مصفوفة من العلامات للمشاركة
title	string تمثّل هذه السمة عنوان المشاركة.
content_description	string تمثّل هذه السمة وصفًا نصيًا للمحتوى. ننصحك باستخدام content_description لميزات تسهيل الاستخدام.
itemurl	string عنوان URL الكامل لعرض المشاركة على tenor.com
hascaption	boolean تعرض هذه السمة القيمة true إذا كانت هذه المشاركة تتضمّن ترجمة وشرحًا.
flags	string قائمة مفصولة بفواصل لتحديد ما إذا كان المحتوى ملصقًا أو صورة ثابتة أو يتضمّن صوتًا أو أي مجموعة من هذه العناصر إذا لم تكن العلامتان sticker وstatic متوفّرتَين، يعني ذلك أنّ المحتوى هو صورة GIF. يشير الحقل flags الفارغ إلى صورة GIF بدون صوت.
bg_color	string لون الخلفية الأكثر شيوعًا للمحتوى
url	string عنوان URL مختصر لعرض المشاركة على tenor.com

عنصر الفئة

يقدّم الجدول التالي تفاصيل حول سمات "عناصر الفئات":

الخصائص
searchterm	string عبارة البحث التي تتوافق مع الفئة. تتم ترجمة عبارة البحث لتتطابق مع locale للطلب ذي الصلة.
path	string عنوان URL الخاص بالبحث الذي سيتم طلبه إذا اختار المستخدم الفئة
image	string عنوان URL لمصدر الوسائط الخاص بملف GIF كمثال للفئة
name	string اسم الفئة المطلوب عرضه فوق الصورة يتم ترجمة الاسم ليتطابق مع locale الطلب ذي الصلة.

كائن الوسائط

يقدّم الجدول التالي تفاصيل حول سمات "كائنات الوسائط":

الخصائص
url	string عنوان URL لمصدر الوسائط
dims	int[] عرض الوسائط وارتفاعها بالبكسل
duration	float تمثّل هذه السمة المدة الزمنية بالثواني لتكرار المحتوى مرة واحدة. إذا كان المحتوى ثابتًا، يتم ضبط المدة على 0.
size	int حجم الملف بالبايت

تنسيقات المحتوى

تقدّم واجهة برمجة التطبيقات من Tenor خمسة تنسيقات أساسية بأحجام مختلفة:

• GIF
• MP4
• WebM
• ملف WebP شفاف
• ملف GIF شفاف

لا يتم تشغيل مقطع بتنسيق MP4 أو WebM إلا مرة واحدة، باستثناء loopedmp4 الذي يشغّل المقطع عدة مرات. يتم تشغيل مقطع GIF في حلقة متواصلة. تُستخدم التنسيقات الشفافة للمحتوى على شكل ملصقات، وهي غير متاحة في نتائج البحث عن صور GIF.

أنواع التنسيقات

يقدّم الجدول التالي تفاصيل حول أنواع تنسيقات الوسائط المتاحة على Tenor:

أنواع التنسيقات
preview	درجة الدقة والحجم: تنسيق GIF عالي الجودة للقطة واحدة، حجمه أصغر من حجم تنسيق GIF الأبعاد: أبعاد التحميل الأصلية (بدون حدود) ملاحظات الاستخدام: اجعل هذا الإطار هو الإطار الأول للمحتوى. وهي مخصّصة للاستخدام كمعاينة مصغّرة. يتوافق هذا التنسيق مع ملفات GIF والملصقات.
gif	درجة الدقة والحجم: تنسيق GIF عالي الجودة، وأكبر حجم ملف متاح الأبعاد: أبعاد التحميل الأصلية (بدون حدود) ملاحظات حول الاستخدام: استخدِم هذا الحجم لمشاركة ملفات GIF على الكمبيوتر. يتوافق هذا التنسيق مع ملفات GIF والملصقات.
mediumgif	درجة الدقة والحجم: انخفاض طفيف في حجم تنسيق GIF الأبعاد: أبعاد التحميل الأصلية (بدون حدود)، ولكن بمعدّل ضغط أعلى بكثير ملاحظات حول الاستخدام: استخدِم هذا الحجم لمعاينات ملفات GIF على الكمبيوتر المكتبي. يتوافق هذا التنسيق مع ملفات GIF والملصقات.
tinygif	درجة الدقة والحجم: تم تقليل حجم تنسيق GIF الأبعاد: ما يصل إلى 220 بكسل عرضًا تم تغيير حجم الارتفاع للحفاظ على نسبة العرض إلى الارتفاع. ملاحظات حول الاستخدام: استخدِم هذا الحجم لمعاينة ملفات GIF ومشاركتها على الأجهزة الجوّالة. يتوافق هذا التنسيق مع ملفات GIF والملصقات.
nanogif	درجة الدقة والحجم: أصغر حجم لتنسيق GIF الأبعاد: ما يصل إلى 90 بكسل ارتفاعًا تم تغيير حجم العرض للحفاظ على نسبة العرض إلى الارتفاع. ملاحظات حول الاستخدام: استخدِم هذا الحجم لمعاينات صور GIF على الأجهزة الجوّالة. يتوافق هذا التنسيق مع ملفات GIF والملصقات.
mp4	درجة الدقة والحجم: تنسيق الفيديو الأعلى جودة والأكبر حجمًا بين تنسيقات الفيديو، ولكنّه أصغر من GIF الأبعاد: مشابهة لملف GIF ولكن مع إضافة مساحة فارغة لتناسب مواصفات حاوية الفيديو، والتي تكون عادةً بزيادات قدرها 8 وحدات بكسل. ملاحظات حول الاستخدام: استخدِم هذا الحجم لمعاينات MP4 ومشاركتها على الكمبيوتر. يتوافق هذا التنسيق مع ملفات GIF والملصقات.
loopedmp4	درجة الدقة والحجم: تنسيق فيديو بأعلى جودة، وحجمه أكبر من حجم ملف MP4 الأبعاد: مشابهة لملف GIF ولكن مع إضافة مساحة فارغة لتناسب مواصفات حاوية الفيديو، والتي تكون عادةً بزيادات قدرها 8 وحدات بكسل. ملاحظات حول الاستخدام: استخدِم هذا الحجم لمشاركة ملفات MP4 عندما تريد تشغيل مقطع الفيديو عدة مرات بدلاً من مرة واحدة فقط. يتوافق هذا التنسيق مع ملفات GIF والملصقات.
tinymp4	درجة الدقة والحجم: حجم أقل لتنسيق MP4 الأبعاد: عرض وارتفاع متغيّران، مع مربّع حدود أقصى يبلغ 320x320 بكسل ملاحظات حول الاستخدام: استخدِم هذا الحجم لمعاينات ومشاركات MP4 على الأجهزة الجوّالة. يتوافق هذا التنسيق مع ملفات GIF والملصقات.
nanomp4	درجة الدقة والحجم: أصغر حجم لتنسيق MP4 الأبعاد: عرض وارتفاع متغيّران، مع مربّع حدود تظليل أقصى يبلغ 150x150 بكسل ملاحظات حول الاستخدام: استخدِم هذا الحجم لمعاينات MP4 على الأجهزة الجوّالة. يتوافق هذا التنسيق مع ملفات GIF والملصقات.
webm	درجة الدقة والحجم: تنسيق فيديو بجودة أقل وحجم أصغر من MP4 الأبعاد: مشابهة لملف GIF ولكن مع إضافة مساحة فارغة لتناسب مواصفات حاوية الفيديو، والتي تكون عادةً بزيادات قدرها 8 وحدات بكسل. ملاحظات حول الاستخدام: استخدِم هذا الحجم لمعاينة ملفات WebM ومشاركتها على الكمبيوتر. يتوافق هذا التنسيق مع ملفات GIF والملصقات.
tinywebm	درجة الدقة والحجم: حجم أقل لتنسيق WebM الأبعاد: عرض وارتفاع متغيّران، مع مربّع حدود أقصى يبلغ 320×320 بكسل ملاحظات حول الاستخدام: استخدِم هذا الحجم لمشاركة ملفات GIF على الأجهزة الجوّالة. يتوافق هذا التنسيق مع ملفات GIF والملصقات.
nanowebm	درجة الدقة والحجم: أصغر حجم لتنسيق WebM الأبعاد: عرض وارتفاع متغيّران، مع مربّع حدود تظليل أقصى يبلغ 150x150 بكسل ملاحظات حول الاستخدام: استخدِم هذا الحجم لمعاينات صور GIF على الأجهزة الجوّالة. يتوافق هذا التنسيق مع ملفات GIF والملصقات.
webp_transparent	درجة الدقة والحجم: تنسيق ملصق WebP عالي الجودة، وأكبر حجم ملف متاح الأبعاد: أبعاد التحميل الأصلية (بدون حدود) ملاحظات حول الاستخدام: استخدِم هذا الحجم لمشاركة الملصقات مع المستخدمين الذين لديهم نطاق ترددي عالٍ. هذه الصيغة متوافقة مع الملصقات.
tinywebp_transparent	درجة الدقة والحجم: تم تقليل حجم تنسيق ملصق WebP، والحد الأقصى للحجم هو 500 كيلوبايت. الأبعاد: ما يصل إلى 220x220 بكسل، ويتم تغيير حجم الارتفاع للحفاظ على نسبة العرض إلى الارتفاع. ملاحظات حول الاستخدام: استخدِم هذا الحجم لمعاينة الملصقات للمستخدمين الذين لديهم نطاق ترددي عالٍ، ولمشاركة الملصقات مع المستخدمين الذين لديهم نطاق ترددي منخفض. هذه الصيغة متوافقة مع الملصقات.
nanowebp_transparent	درجة الدقة والحجم: أصغر حجم لتنسيق ملصق WebP، والحد الأقصى للحجم هو 100 كيلوبايت الأبعاد: تصل إلى 90×90 بكسل، مع تغيير حجم العرض للحفاظ على نسبة العرض إلى الارتفاع. ملاحظات حول الاستخدام: استخدِم هذا الحجم لمعاينة الملصقات للمستخدمين الذين لديهم نطاق ترددي منخفض. هذه الصيغة متوافقة مع الملصقات.
gif_transparent	الدقة والحجم: تنسيق ملصق GIF عالي الجودة، وأكبر حجم ملف متاح الأبعاد: أبعاد التحميل الأصلية (بدون حدود) ملاحظات حول الاستخدام: استخدِم هذا الحجم لمشاركة الملصقات مع المستخدمين الذين لديهم نطاق ترددي عالٍ. هذه الصيغة متوافقة مع الملصقات.
tinygif_transparent	درجة الدقة والحجم: تم تقليل حجم تنسيق ملصق GIF، والحد الأقصى للحجم هو 500 كيلوبايت. الأبعاد: ما يصل إلى 220x220 بكسل، مع تغيير حجم الارتفاع للحفاظ على نسبة العرض إلى الارتفاع ملاحظات حول الاستخدام: استخدِم هذا الحجم لمعاينة الملصقات للمستخدمين الذين لديهم نطاق ترددي عالٍ، ولمشاركة الملصقات مع المستخدمين الذين لديهم نطاق ترددي منخفض. هذه الصيغة متوافقة مع الملصقات.
nanogif_transparent	درجة الدقة والحجم: أصغر حجم لتنسيق ملصق GIF، والحد الأقصى للحجم هو 100 كيلوبايت الأبعاد: تصل إلى 90×90 بكسل، مع تغيير حجم العرض للحفاظ على نسبة العرض إلى الارتفاع. ملاحظات حول الاستخدام: استخدِم هذا الحجم لمعاينة الملصقات للمستخدمين الذين لديهم نطاق ترددي منخفض. هذا التنسيق متوافق مع الملصقات.

أفضل الممارسات

• على الأجهزة الجوّالة، استخدِم الملفات ذات الحجم النانوي أو الصغير جدًا للمعاينات والملفات ذات الحجم الصغير جدًا للمشاركة.
• اضبط المَعلمة media_filter على التنسيقات التي تنوي استخدامها. ويمكن أن يؤدي ذلك إلى تقليل حجم استجابة واجهة برمجة التطبيقات بنسبة %70.

أحجام التنسيقات

يختلف حجم ملف كل تنسيق محتوى حسب أبعاد صورة GIF المحدّدة ومدتها. لذلك، ننصحك بالاستناد إلى المتوسطات الحسابية والوسائط المقدَّمة في الجدول التالي كإرشادات عامة وليس كقيم ثابتة.

تنسيق الملف	متوسط حجم الملف (كيلوبايت)	متوسط حجم الملف (كيلوبايت)
gif	3,356	956
mediumgif	2,548	574
tinygif	521	101
nanogif	175	56
mp4	207	91
loopedmp4	515	228
tinymp4	84	81
nanomp4	37	28
webm	76	61
tinywebm	57	45
nanowebm	35	25
webp_transparent	530	95
tinywebp_transparent	249	60
nanowebp_transparent	107	25
gif_transparent	643	35
tinygif_transparent	349	20
nanogif_transparent	116	10

رموز الاستجابة

يوضّح الجدول التالي رموز استجابة حالة HTTP المستخدَمة للإشارة إلى نجاح الطلب:

رمز حالة HTTP‬
200 أو 202	موافق أو مقبول

الأخطاء

تعرض واجهة برمجة التطبيقات من Tenor أخطاءً مع رموز استجابة HTTP 4xx أو 5xx وبتنسيق الخطأ العادي لواجهة Google API. لمزيد من التفاصيل، يُرجى الاطّلاع على الأخطاء.