API Reference

低端影视开放 API

面向第三方客户端、浏览器插件、Telegram Bot 和 AI Agent 的 REST API 文档。当前页面按接口模块重组，完整机器可读说明请使用 Markdown 或接口 JSON 文件。

下载 MD 接口 JSON

概览

所有接口都位于同一个版本前缀下，默认返回 JSON。

Updated 2026-08-01
Base URL
Endpoints
28 个接口
Format
JSON / UTF-8
Methods
GET, POST, DELETE

快速开始

curl "https://ddys.io/api/v1/types"
curl "https://ddys.io/api/v1/movies?type=movie&page=1&per_page=3"
curl "https://ddys.io/api/v1/search?q=星际&type=movie"
curl "https://ddys.io/api/v1/latest?limit=5"

认证

公开读取接口无需认证。写入接口和当前用户接口需要在请求头中携带 API Key。 

Authorization: Bearer ddys_your_api_key_here

API Key 可在 个人资料 页面生成。真实 Key 不应写入前端源码或公开仓库。

DDYS 计费

所有 GET 查询接口免费，不扣除 DDYS。

POST /requests 从 API Key 所属用户扣除后台配置的求片费用，默认 5 DDYS；成功响应返回 charged 和 remaining，查重或业务写入失败不会扣费。

POST /comments 免费。影片每日首次有效短评按后台配置发放奖励，默认 5 DDYS；分享和求片评论不奖励。

DELETE /comments/{id}、POST /report、POST /follow 均免费。

响应格式

Success
{
  "success": true,
  "data": {},
  "meta": {
    "total": 100,
    "page": 1,
    "per_page": 20,
    "total_pages": 5
  }
}
Error
{
  "success": false,
  "message": "Error description"
}

对象字段

对象 主要字段 使用位置
MovieListItem id, title, aka, slug, year, poster, rating, douban_id, imdb_id, type, type_code, region, genres, url 影片列表、搜索、最新、片单、相关推荐
MovieDetail intro, director, actors, warning_tags, online_sources_count, download_sources_count, comments_count 影片详情
ResourceGroups online[], download[] 影片资源
Share / Request / User 详见完整 Markdown 分享、求片、用户接口

AI 资料

完整 Markdown 文档包含公开端点索引、鉴权、分页、对象字段、每个端点的参数、示例和错误行为。

影片 Movies

影片发现、详情、资源、相关推荐和评论。

GET /movies 公开

分页获取已发布影片，支持类型、题材、地区、年份和排序筛选。

Name In Required Type Description
type query 否 movie / series / variety / anime 按影片分类代码过滤。
genre query 否 active genre code 按题材代码过滤。
region query 否 active region code 按地区代码过滤。
year query 否 integer 按年份精确过滤。
sort query 否 latest / rating / popular 默认 latest；popular 只取最近 30 天更新。
page query 否 integer >= 1 默认 1。
per_page query 否 1-50 默认 24。
Response
data 为 MovieListItem[]，meta 为 PaginationMeta。
Errors
405, 500, 503
curl "https://ddys.io/api/v1/movies?type=movie&sort=rating&page=1&per_page=24"
GET /movies/{slug} 公开

按 slug 获取单部已发布影片详情，包含简介、导演、主演、警告标签和资源/评论计数。

Name In Required Type Description
slug path 是 string 影片 URL slug。
Response
data 为 MovieDetail。
Errors
400 Missing slug parameter; 404 Movie not found; 405, 500, 503
curl "https://ddys.io/api/v1/movies/interstellar"
GET /movies/{slug}/sources 公开

获取影片 active 状态的在线播放资源和网盘下载资源。

Name In Required Type Description
slug path 是 string 影片 URL slug。
Response
data.online 为在线播放资源数组，data.download 为下载资源数组。
Errors
400 Missing slug parameter; 404 Movie not found; 405, 500, 503
curl "https://ddys.io/api/v1/movies/interstellar/sources"
GET /movies/{slug}/comments 公开

分页获取影片 active 评论，按 created_at 倒序返回。

Name In Required Type Description
slug path 是 string 影片 URL slug。
page query 否 integer >= 1 默认 1。
per_page query 否 1-50 默认 20。
Response
data 为 Comment[]，meta 为 PaginationMeta。
Errors
400 Missing slug parameter; 404 Movie not found; 405, 500, 503
curl "https://ddys.io/api/v1/movies/interstellar/comments?page=1&per_page=20"

搜索与发现 Discovery

搜索、联想、热门、最新和月历。

GET /suggest 公开

搜索联想，最多返回 8 条匹配影片。关键词长度非法时返回 success=true 的空数组。

Name In Required Type Description
q query 是 1-100 chars 联想关键词。
Response
data 为轻量影片建议数组。
Errors
405, 500, 503
curl "https://ddys.io/api/v1/suggest?q=星际"
GET /hot 公开

获取最近 7 天更新的热门影片，按评分和资源数量综合排序，最多 10 条。

Response
data 为热门影片数组，包含 online_sources 和 download_sources。
Errors
405, 500, 503
curl "https://ddys.io/api/v1/hot"
GET /latest 公开

获取最新更新影片，按 updated_at 倒序。

Name In Required Type Description
limit query 否 1-50 默认 30。
Response
data 为最新影片数组。
Errors
405, 500, 503
curl "https://ddys.io/api/v1/latest?limit=30"
GET /calendar 公开

获取指定年月的影片日历数据。超出范围会回落到当前年月。

Name In Required Type Description
year query 否 2020-2030 默认当前年份。
month query 否 1-12 默认当前月份。
Response
data 为日历缓存或实时抓取结果。
Errors
404 Calendar data not available; 405
curl "https://ddys.io/api/v1/calendar?year=2026&month=6"
GET /movie-calendar 公开

读取站点电影日历缓存（热门 / 正在上映 / 即将上映 / 高分），不向外部源发起查询。

Name In Required Type Description
tab query 否 popular / now_playing / upcoming / top_rated 默认 popular。
page query 否 1-20 默认 1，对应站点已缓存的页。
Response
data 含 movies 与按日期分组的 days。站内有对应影片时带 slug。
Errors
405
curl "https://ddys.io/api/v1/movie-calendar?tab=now_playing&page=1"
GET /discover 公开

热门发现：电影日历首页缓存 + 站点片单。不向外部源发起查询。

Response
data 含 trending、now_playing、upcoming、high_score、popular、collections。
Errors
405
curl "https://ddys.io/api/v1/discover"

字典 Dictionaries

分类、题材和地区代码。建议客户端先读取这些接口，再构造筛选参数。

GET /types 公开

获取 active 分类字典，按 sort_order 排序。

Response
data 为 { id, name, code }[]。
Errors
405, 500, 503
curl "https://ddys.io/api/v1/types"
GET /genres 公开

获取 active 题材字典，按 sort_order 排序。

Response
data 为 { id, name, code }[]。
Errors
405, 500, 503
curl "https://ddys.io/api/v1/genres"
GET /regions 公开

获取 active 地区字典，按 sort_order 排序。

Response
data 为 { id, name, code }[]。
Errors
405, 500, 503
curl "https://ddys.io/api/v1/regions"

片单与分享 Collections & Shares

片单、用户分享和分享详情。

GET /collections 公开

分页获取片单，按 created_at 倒序，返回每个片单的影片数量。

Name In Required Type Description
page query 否 integer >= 1 默认 1。
per_page query 否 1-50 默认 10。
Response
data 为 Collection[]，meta 为 PaginationMeta。
Errors
405, 500, 503
curl "https://ddys.io/api/v1/collections?page=1&per_page=10"
GET /collections/{slug} 公开

获取片单详情和该片单下的已发布影片分页列表。

Name In Required Type Description
slug path 是 string 片单 slug。
page query 否 integer >= 1 默认 1。
per_page query 否 1-50 默认 20。
Response
data 为片单对象，内含 movies 数组；meta 为影片分页信息。
Errors
400 Missing slug parameter; 404 Collection not found; 405, 500, 503
curl "https://ddys.io/api/v1/collections/best-sci-fi?page=1&per_page=20"
GET /shares 公开

分页获取 approved 用户分享，仅返回 active 用户的分享。

Name In Required Type Description
page query 否 integer >= 1 默认 1。
per_page query 否 1-50 默认 20。
Response
data 为 Share[]，包含 resource_types、作者头像和分享标签。
Errors
405, 500, 503
curl "https://ddys.io/api/v1/shares?page=1&per_page=20"
GET /shares/{id} 公开

获取单条 approved 分享、资源列表和评论数量。

Name In Required Type Description
id path 是 integer > 0 分享 ID。
Response
data 为 ShareDetail，resources 为该分享附属资源。
Errors
400 Invalid share ID; 404 Share not found; 405, 500, 503
curl "https://ddys.io/api/v1/shares/1081"

社区 Community

求片、动态、用户资料、评论、举报和关注。

GET /requests 公开

分页获取 active 用户提交的求片记录，按 created_at 倒序。

Name In Required Type Description
page query 否 integer >= 1 默认 1。
per_page query 否 1-50 默认 20。
Response
data 为 Request[]，meta 为 PaginationMeta。
Errors
405, 500, 503
curl "https://ddys.io/api/v1/requests?page=1&per_page=20"
POST /requests Bearer

提交新求片。会检查豆瓣 ID 已收录、30 秒防刷、同用户同标题 pending 去重，并从 API Key 所属用户扣除后台配置的 DDYS，默认 5 DDYS。

Name In Required Type Description
title body 是 1-255 chars 求片标题。
year body 否 1900-2099 年份，空值转 null。
type body 否 movie / series / variety / anime 类型，空值转 null。
description body 否 max 1000 chars 补充说明。
douban_id body 否 string 规范化后用于查重，并写入说明。
expected_cost body 否 integer >= 1 客户端预期扣费；与当前价格不一致时返回 409 且不扣费。
Response
data 为新建 pending 求片，包含 charged、remaining 和 url。
Errors
400, 401, 403, 409, 429, 500, 503
curl -X POST "https://ddys.io/api/v1/requests" \
  -H "Authorization: Bearer ddys_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"title":"沙丘 2","year":2024,"type":"movie","douban_id":"35652650","expected_cost":5}'
GET /activities 公开

获取分享和求片组成的社区动态。type 为空时会合并两类数据后按创建时间排序。

Name In Required Type Description
type query 否 share / request 非法值视为空。
page query 否 integer >= 1 默认 1。
per_page query 否 1-50 默认 20。
Response
data 为 Activity[]，url 指向 /shares/{id} 或 /requests/{id}。
Errors
405, 500, 503
curl "https://ddys.io/api/v1/activities?type=share&page=1&per_page=20"
GET /user/{username} 公开

获取 active 用户公开资料、分享数、关注数和粉丝数。

Name In Required Type Description
username path 是 letters / digits / underscore 用户名。
Response
data 为 PublicUser。
Errors
400 Missing username parameter; 404 User not found; 405, 500, 503
curl "https://ddys.io/api/v1/user/diduan"
GET /me Bearer

获取当前认证用户资料，包含 email。

Response
data 为 CurrentUser。
Errors
401, 403, 404, 405, 500, 503
curl "https://ddys.io/api/v1/me" \
  -H "Authorization: Bearer ddys_your_api_key_here"
POST /comments Bearer

免费对影片、分享或求片发表评论。影片短评参与每日首次短评奖励，默认奖励 5 DDYS；分享与求片评论不奖励。

Name In Required Type Description
target_type body 是 movie / share / request 评论目标类型。
target_id body 是 integer > 0 目标 ID；影片用 movie_id，不是 slug。
content body 是 1-300 chars 评论内容；影片短评至少 5 个字符。
Response
data 为新评论基础信息，rewarded 表示本次是否获得奖励，reward 为奖励数量。
Errors
400（影片短评少于 5 字符等）, 401, 403, 404, 405, 429, 500
curl -X POST "https://ddys.io/api/v1/comments" \
  -H "Authorization: Bearer ddys_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"target_type":"movie","target_id":4786,"content":"剧情很有意思"}'
DELETE /comments/{id} Bearer

免费永久删除当前用户自己的评论，删除后不再保留评论记录。

Name In Required Type Description
id path 是 integer > 0 评论 ID。
Response
data 为 { id, deleted: true }。
Errors
400 Invalid comment ID; 401, 403, 404, 405, 500
curl -X DELETE "https://ddys.io/api/v1/comments/12345" \
  -H "Authorization: Bearer ddys_your_api_key_here"
POST /report Bearer

免费举报失效下载资源。只接受 active 的 download 资源，且 24 小时内同资源同影片只能举报一次。

Name In Required Type Description
resource_id body 是 integer > 0 资源 ID。
movie_id body 是 integer > 0 资源所属影片 ID。
Response
data 为 { reported: true }。
Errors
400, 401, 403, 404, 405, 409, 500
curl -X POST "https://ddys.io/api/v1/report" \
  -H "Authorization: Bearer ddys_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"resource_id":1002,"movie_id":4786}'
POST /follow Bearer

免费关注或取消关注 active 用户。禁止关注自己，重复关注返回 409。

Name In Required Type Description
username body 是 string 目标用户名。
action body 是 follow / unfollow 操作类型。
Response
data 为 { action: followed|unfollowed, username }。
Errors
400, 401, 403, 404, 405, 409, 500
curl -X POST "https://ddys.io/api/v1/follow" \
  -H "Authorization: Bearer ddys_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"username":"diduan","action":"follow"}'