响应对象和错误

本页面介绍了 Tenor API 使用的不同 JSON 响应和错误对象。

响应对象

下表详细介绍了响应对象的属性：

属性
created

float

表示此帖子创建时间的 Unix 时间戳。
hasaudio

boolean

如果此帖子包含音频，则返回 true。
id

string

Tenor 结果标识符
media_formats

{ CONTENT_FORMAT : MEDIA_OBJECT }

一个字典，其中内容格式作为键，媒体对象作为值。
tags

string[]

帖子的标记数组
title

string

帖子的标题
content_description

string

内容的文字说明。

我们建议您使用 content_description 来实现用户无障碍功能。
itemurl

string

在 tenor.com 上查看帖子的完整网址。
hascaption

boolean

如果此帖子包含字幕，则返回 true。
flags

string

逗号分隔列表，用于表示内容是贴纸还是静态图片、是否包含音频，或者以上各项的任意组合。如果 sticker 和 static 不存在，则表示内容是 GIF。空白 flags 字段表示没有音频的 GIF。
bg_color

string

内容最常见的背景像素颜色
url

string

用于在 tenor.com 上查看帖子的短网址。

类别对象

下表详细介绍了类别对象的属性：

属性
searchterm

string

与相应类别对应的搜索字词。系统会转换搜索字词，使其与相应请求的 locale 匹配。
path

string

用户选择类别时请求的搜索网址
image

string

指向类别示例 GIF 的媒体来源的网址
name

string

要叠加到图片上的类别名称。该名称会翻译为相应请求的 locale。

媒体对象

下表详细介绍了媒体对象的属性：

属性
url

string

媒体来源的网址
dims

int[]

媒体的宽度和高度（以像素为单位）
duration

float

表示内容的一个循环的时间（以秒为单位）。如果内容是静态的，则时长会设置为 0。
size

int

文件的大小（以字节为单位）

内容格式

Tenor 的 API 提供五种不同尺寸的基础格式：

  • 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 格式的大小
  • 尺寸：宽度和高度可变，最大边界框为 320x320 像素
  • 使用说明：在移动设备上使用此大小分享 GIF。

GIF 和贴纸支持此格式。
nanowebm
  • 分辨率和大小：WebM 格式的最小尺寸
  • 尺寸：可变宽度和高度，最大边界框为 150x150 像素
  • 使用说明：在移动设备上预览 GIF 时使用此尺寸。

GIF 和贴纸支持此格式。
webp_transparent
  • 分辨率和大小：采用高品质 WebP 贴纸格式，文件最大
  • 维度：原始上传维度（无限制）
  • 使用说明：对于高带宽用户，请使用该尺寸分享贴纸。

贴纸支持此格式。
tinywebp_transparent
  • 分辨率和大小：缩减了 WebP 贴纸格式的大小；大小不超过 500 KB
  • 尺寸：最多可放大至 220x220 像素，高度保持不变，以保持宽高比不变。
  • 使用说明：对于高带宽用户，使用此尺寸预览贴纸；对于低带宽用户，使用此尺寸进行分享。

贴纸支持此格式。
nanowebp_transparent
  • 分辨率和大小：WebP 贴纸格式的最小尺寸；大小上限为 100 KB
  • 尺寸：最多可缩放至 90x90 像素，但系统会调整宽度以保持宽高比。
  • 使用说明：对于低带宽用户，使用此尺寸即可预览贴纸。

贴纸支持此格式。
gif_transparent
  • 分辨率和大小：高画质 GIF 贴纸格式；文件最大
  • 维度：原始上传维度（无限制）
  • 使用说明：对于高带宽用户，请使用该尺寸分享贴纸。

贴纸支持此格式。
tinygif_transparent
  • 分辨率和大小：缩减了 GIF 贴纸格式的大小；大小不超过 500 KB
  • 尺寸：最高可达 220x220 像素，高度保持不变，宽高比保持不变。
  • 使用说明：对于高带宽用户，使用此尺寸预览贴纸；对于低带宽用户，使用此尺寸进行分享。

贴纸支持此格式。
nanogif_transparent
  • 分辨率和大小：GIF 贴纸格式的最小尺寸；大小上限为 100 KB
  • 尺寸：最多可缩放至 90x90 像素，但系统会调整宽度以保持宽高比。
  • 使用说明：对于低带宽用户，使用此尺寸即可预览贴纸。

此格式支持贴纸。

最佳实践

  • 对于移动设备，请使用 nano 或 small 大小的文件进行预览，并使用 small 大小的文件进行共享。
  • 将 media_filter 参数设置为您要使用的格式。这可以将 API 响应大小缩减 70%。

设置尺寸

每种内容格式的文件大小取决于所选 GIF 的尺寸和长度。因此，请参考下表中提供的平均值和中位数，而不是常规值。

文件格式 平均文件大小 (KB) 文件大小中位数 (KB)
gif 3356 956
mediumgif 2548 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 的 API 会返回 HTTP 响应代码 4xx 或 5xx 以及采用标准 Google API 错误格式的错误。如需了解详情，请参阅错误。