# 【必看】🔗 API 参数约定

## API 支持 3 种返回形式

除特殊说明，所有接口均支持返回以下三种格式,通过 query 参数 `encoding` 进行控制。不填或参数无效的情况下默认为 **JSON** 形式。

- **JSON（默认格式）**: 参数值为`json`，适合程序化处理、二次开发，更多的数据掌控
- **纯文本**: 参数值为 `text`，适合简单调用场景：格式清晰、人类可读性强、排版友好
- **Markdown**: 参数值为 `markdown`，AI 友好、适合在支持 Markdown 渲染的环境中查看

拿 `/v2/60s` API 举例：

```diff
- # 默认为 JSON 格式
- https://60s.viki.moe/v2/60s

# 建议显式指定响应格式
+ https://60s.viki.moe/v2/60s?encoding=json
+ https://60s.viki.moe/v2/60s?encoding=text
+ https://60s.viki.moe/v2/60s?encoding=markdown
```

## 时间戳字段

如非特殊说明，涉及返回时间戳的参数均有两种格式。

- **13 位时间戳**（含有 `_at` 字段命名后缀）
- 格式化的 **日期时间字符串**（无上述后缀）

> 如 `/v2/60s` 返回的 `updated` 字段是时间字符串 (`2025/01/13 07:22:32` 形式)，而 `updated_at` 字段则为其 13 位时间戳 (`1736770800082` 形式)。再比如 `active_time` 字段是时间字符串，而 `active_time_at` 字段则为其 13 位时间戳。

## 链接、原文字段

链接、原文 等类似语意的字段统一命名为 `link`。

## 封面图、主图字段

封面图、主图等类似语意的字段统一命名为 `cover`。