适用场景在开发涉及电影内容的项目时获取电影的详细信息评分、导演、演员、类型等是一个常见需求。豆瓣电影信息 API 允许开发者通过豆瓣电影 ID 或 URL 直接查询电影详情适用于以下场景影视资讯类应用展示电影评分、简介、主创团队等基础信息。个人学习或原型开发快速验证业务逻辑无需数据库即可获取结构化数据。数据分析采集电影元数据用于统计分析或推荐系统。自动化脚本批量查询多部电影的信息并写入本地文件。该接口返回 JSON 格式的数据结构紧凑非常适合作为 REST API 入门的练手素材。接口能力边界在使用之前需要明确该接口的能力范围维度说明请求方法GET接口地址https://v1.apizero.cn/api/douban-movie查询参数id必填豆瓣电影 ID数字字符串或豆瓣电影页面完整 URL鉴权方式在请求头X-API-Key中传递 API Key频率限制5 QPS每秒最多5次请求返回格式JSON 对象包含code、msg、data三层结构覆盖内容评分、导演、演员、类型、地区、片长、集数、热门短评等从豆瓣公开 JSON API 获取注意该接口仅支持通过电影 ID 或 URL 查询不支持按名称模糊搜索。如果需要搜索请使用其他搜索类接口。参数与鉴权请求参数接口只接受一个查询参数id其值可以是以下两种格式之一纯数字 ID例如1292052《肖申克的救赎》的豆瓣 ID。完整电影 URL例如https://movie.douban.com/subject/1292052/。两种格式效果相同推荐使用纯数字 ID避免 URL 解析开销。鉴权方式调用接口需要在 HTTP 头部添加X-API-Key字段值为你在 API 平台申请的密钥。具体获取方式请参考文档参见文末参考文档。示例 HeadersX-API-Key: your_api_key_here安全提示请勿将 API Key 硬编码在公开仓库中建议使用环境变量管理。curl 请求示例最小可运行以下是一个完整的 curl 命令可直接复制后替换API_KEY与电影 ID 运行curl -sS \ -X GET \ -H X-API-Key: API_KEY \ https://v1.apizero.cn/api/douban-movie?id1292052参数说明-sS静默模式并显示错误信息便于调试。-X GET显式指定请求方法默认 GET 可省略。-H设置请求头。id必填这里用1292052代表《肖申克的救赎》。预期返回示例{ code: 0, msg: 成功, data: { director: 弗兰克·德拉邦特, douban_id: 1292052, name: 肖申克的救赎, score: 9.7, year: 1994 } }注意实际返回的数据字段比示例更丰富下面的返回值解读会列出完整字段。代码接入示例Python为了在生产环境中更方便地调用可以使用 Python 的requests库。以下是一个最小可运行的脚本示例import requests import os def get_douban_movie(movie_id: str) - dict: 通过豆瓣电影 ID 查询电影详情 :param movie_id: 豆瓣电影 ID如 1292052 :return: 解析后的 JSON 字典 api_key os.getenv(DOUBAN_API_KEY) # 从环境变量获取 API Key url https://v1.apizero.cn/api/douban-movie headers {X-API-Key: api_key} params {id: movie_id} response requests.get(url, headersheaders, paramsparams) response.raise_for_status() # 非 2xx 状态码抛出异常 return response.json() if __name__ __main__: movie_id 1292052 result get_douban_movie(movie_id) print(result)运行前准备安装requests库pip install requests设置环境变量DOUBAN_API_KEYLinux/macOSexport DOUBAN_API_KEYyour_api_keyWindows (CMD)set DOUBAN_API_KEYyour_api_keyWindows (PowerShell)$env:DOUBAN_API_KEYyour_api_key执行脚本python douban_movie.py示例输出截取部分字段{ code: 0, msg: 成功, data: { director: 弗兰克·德拉邦特, douban_id: 1292052, name: 肖申克的救赎, score: 9.7, year: 1994, actors: [蒂姆·罗宾斯, 摩根·弗里曼, 鲍勃·冈顿], genres: [剧情, 犯罪], region: 美国, duration: 142分钟, episodes: 1 } }返回字段解读成功的响应code为 0中data字段包含电影详细信息。以下是常见字段及说明字段类型说明douban_idstring豆瓣电影 IDnamestring电影名称yearstring上映年份如1994scorestring豆瓣评分如9.7directorstring导演名称多人用/分隔actorsarray of strings演员列表前几位主演genresarray of strings电影类型如[剧情, 犯罪]regionstring制片国家/地区durationstring片长如142分钟episodesstring如果是剧集显示总集数电影一般为1hot_commentsarray of objects热门短评列表包含author,content,rating等字段注意hot_comments字段并非每次请求都会返回它与豆瓣公开 JSON API 的实时性有关。如果返回中缺少该字段无需担心。常见错误处理错误码一览错误码含义可能原因解决措施code: 400参数错误id参数缺失或格式无效检查是否传递了id且值符合数字或 URL 格式code: 401鉴权失败API Key 错误或未传递检查X-API-Key的值是否正确确认密钥未过期code: 404电影不存在提供的 ID 对应电影未收录或已下线核实电影 ID 是否正确例如在豆瓣页面地址中提取code: 429请求频率超限超过 5 QPS 限制加入延迟控制或使用队列串行请求code: 500服务器内部错误接口临时异常等待后重试若持续出现则反馈平台注意错误响应体中的msg字段会提供更详细的中文说明。例如{ code: 400, msg: 参数错误缺少id, data: null }网络层面异常requests.exceptions.ConnectionError网络不通或接口域名无法解析。requests.exceptions.Timeout请求超时建议设置合理的timeout参数如 10 秒。requests.exceptions.HTTPError服务端返回非 2xx 状态码可通过response.status_code判断。工程化注意事项API Key 安全不要将 API Key 写在代码中或上传到公开仓库。使用环境变量、配置文件.gitignore或密钥管理服务。频率控制接口限制 5 QPS注意不要短时间内发起大量请求。可以使用限流器如 Python 的time.sleep(0.2)或ratelimit库。错误重试机制至少重试一次 500 错误和网络异常使用指数退避策略。数据缓存电影元数据更新频率很低建议缓存结果减少重复请求。可以使用 Redis 或本地文件缓存TTL 设为 1 小时以上。接口版本稳定性v1路径表明当前版本如有更新文档会注明。建议订阅文档变化。参数处理如果从用户输入中获取电影 ID务必验证格式仅允许数字或特定域名 URL防止注入或其他攻击。超时设置建议设置 10 秒连接超时和 15 秒读取超时。参考文档豆瓣电影信息 API 文档原始 Markdown 文档以上文档包含更详细的参数说明、错误码列表及更新日志建议在实际集成前仔细阅读。
最小可运行示例：用豆瓣电影信息API查询电影详情
适用场景在开发涉及电影内容的项目时获取电影的详细信息评分、导演、演员、类型等是一个常见需求。豆瓣电影信息 API 允许开发者通过豆瓣电影 ID 或 URL 直接查询电影详情适用于以下场景影视资讯类应用展示电影评分、简介、主创团队等基础信息。个人学习或原型开发快速验证业务逻辑无需数据库即可获取结构化数据。数据分析采集电影元数据用于统计分析或推荐系统。自动化脚本批量查询多部电影的信息并写入本地文件。该接口返回 JSON 格式的数据结构紧凑非常适合作为 REST API 入门的练手素材。接口能力边界在使用之前需要明确该接口的能力范围维度说明请求方法GET接口地址https://v1.apizero.cn/api/douban-movie查询参数id必填豆瓣电影 ID数字字符串或豆瓣电影页面完整 URL鉴权方式在请求头X-API-Key中传递 API Key频率限制5 QPS每秒最多5次请求返回格式JSON 对象包含code、msg、data三层结构覆盖内容评分、导演、演员、类型、地区、片长、集数、热门短评等从豆瓣公开 JSON API 获取注意该接口仅支持通过电影 ID 或 URL 查询不支持按名称模糊搜索。如果需要搜索请使用其他搜索类接口。参数与鉴权请求参数接口只接受一个查询参数id其值可以是以下两种格式之一纯数字 ID例如1292052《肖申克的救赎》的豆瓣 ID。完整电影 URL例如https://movie.douban.com/subject/1292052/。两种格式效果相同推荐使用纯数字 ID避免 URL 解析开销。鉴权方式调用接口需要在 HTTP 头部添加X-API-Key字段值为你在 API 平台申请的密钥。具体获取方式请参考文档参见文末参考文档。示例 HeadersX-API-Key: your_api_key_here安全提示请勿将 API Key 硬编码在公开仓库中建议使用环境变量管理。curl 请求示例最小可运行以下是一个完整的 curl 命令可直接复制后替换API_KEY与电影 ID 运行curl -sS \ -X GET \ -H X-API-Key: API_KEY \ https://v1.apizero.cn/api/douban-movie?id1292052参数说明-sS静默模式并显示错误信息便于调试。-X GET显式指定请求方法默认 GET 可省略。-H设置请求头。id必填这里用1292052代表《肖申克的救赎》。预期返回示例{ code: 0, msg: 成功, data: { director: 弗兰克·德拉邦特, douban_id: 1292052, name: 肖申克的救赎, score: 9.7, year: 1994 } }注意实际返回的数据字段比示例更丰富下面的返回值解读会列出完整字段。代码接入示例Python为了在生产环境中更方便地调用可以使用 Python 的requests库。以下是一个最小可运行的脚本示例import requests import os def get_douban_movie(movie_id: str) - dict: 通过豆瓣电影 ID 查询电影详情 :param movie_id: 豆瓣电影 ID如 1292052 :return: 解析后的 JSON 字典 api_key os.getenv(DOUBAN_API_KEY) # 从环境变量获取 API Key url https://v1.apizero.cn/api/douban-movie headers {X-API-Key: api_key} params {id: movie_id} response requests.get(url, headersheaders, paramsparams) response.raise_for_status() # 非 2xx 状态码抛出异常 return response.json() if __name__ __main__: movie_id 1292052 result get_douban_movie(movie_id) print(result)运行前准备安装requests库pip install requests设置环境变量DOUBAN_API_KEYLinux/macOSexport DOUBAN_API_KEYyour_api_keyWindows (CMD)set DOUBAN_API_KEYyour_api_keyWindows (PowerShell)$env:DOUBAN_API_KEYyour_api_key执行脚本python douban_movie.py示例输出截取部分字段{ code: 0, msg: 成功, data: { director: 弗兰克·德拉邦特, douban_id: 1292052, name: 肖申克的救赎, score: 9.7, year: 1994, actors: [蒂姆·罗宾斯, 摩根·弗里曼, 鲍勃·冈顿], genres: [剧情, 犯罪], region: 美国, duration: 142分钟, episodes: 1 } }返回字段解读成功的响应code为 0中data字段包含电影详细信息。以下是常见字段及说明字段类型说明douban_idstring豆瓣电影 IDnamestring电影名称yearstring上映年份如1994scorestring豆瓣评分如9.7directorstring导演名称多人用/分隔actorsarray of strings演员列表前几位主演genresarray of strings电影类型如[剧情, 犯罪]regionstring制片国家/地区durationstring片长如142分钟episodesstring如果是剧集显示总集数电影一般为1hot_commentsarray of objects热门短评列表包含author,content,rating等字段注意hot_comments字段并非每次请求都会返回它与豆瓣公开 JSON API 的实时性有关。如果返回中缺少该字段无需担心。常见错误处理错误码一览错误码含义可能原因解决措施code: 400参数错误id参数缺失或格式无效检查是否传递了id且值符合数字或 URL 格式code: 401鉴权失败API Key 错误或未传递检查X-API-Key的值是否正确确认密钥未过期code: 404电影不存在提供的 ID 对应电影未收录或已下线核实电影 ID 是否正确例如在豆瓣页面地址中提取code: 429请求频率超限超过 5 QPS 限制加入延迟控制或使用队列串行请求code: 500服务器内部错误接口临时异常等待后重试若持续出现则反馈平台注意错误响应体中的msg字段会提供更详细的中文说明。例如{ code: 400, msg: 参数错误缺少id, data: null }网络层面异常requests.exceptions.ConnectionError网络不通或接口域名无法解析。requests.exceptions.Timeout请求超时建议设置合理的timeout参数如 10 秒。requests.exceptions.HTTPError服务端返回非 2xx 状态码可通过response.status_code判断。工程化注意事项API Key 安全不要将 API Key 写在代码中或上传到公开仓库。使用环境变量、配置文件.gitignore或密钥管理服务。频率控制接口限制 5 QPS注意不要短时间内发起大量请求。可以使用限流器如 Python 的time.sleep(0.2)或ratelimit库。错误重试机制至少重试一次 500 错误和网络异常使用指数退避策略。数据缓存电影元数据更新频率很低建议缓存结果减少重复请求。可以使用 Redis 或本地文件缓存TTL 设为 1 小时以上。接口版本稳定性v1路径表明当前版本如有更新文档会注明。建议订阅文档变化。参数处理如果从用户输入中获取电影 ID务必验证格式仅允许数字或特定域名 URL防止注入或其他攻击。超时设置建议设置 10 秒连接超时和 15 秒读取超时。参考文档豆瓣电影信息 API 文档原始 Markdown 文档以上文档包含更详细的参数说明、错误码列表及更新日志建议在实际集成前仔细阅读。
