API 文档 · TMDB TG Proxy

§ 01 / 引言

引言

TMDB TG Proxy 是一个基于 Vercel Edge Function 的反向代理服务，统一入口转发三类上游请求：

TMDB 数据 API — api.themoviedb.org/3/*
TMDB 图片 — image.tmdb.org/t/p/*
Telegram Bot API — api.telegram.org/bot*

所有响应自动附带 CORS 头，TMDB 路由的 GET 请求会被边缘缓存 7 天，Telegram 路由实时透传不缓存。

§ 02 / Base URL

Base URL ANY

部署到 Vercel 后，你的代理域名即为 Base URL。本文档示例统一使用 https://your-domain.vercel.app 占位。

https://your-domain.vercel.app

→ 部署后由 Vercel 自动分配，亦可绑定自定义域名

CORS 全开 Edge Runtime HTTP/2

§ 03 / CORS

CORS 跨域

所有路由的响应均附带以下 CORS 头，任意前端可直接调用，无需额外配置：

access-control-allow-origin:  *
access-control-allow-methods: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS
access-control-allow-headers: *
access-control-max-age:       86400

对 OPTIONS 预检请求，代理直接返回 204 No Content 并附带上述头，不转发至上游。

§ 04 / 缓存策略

缓存策略

TMDB 路由的 GET 请求会被 Vercel 边缘节点缓存，减少回源、加速响应。Telegram 路由不缓存，确保实时性。

路由	方法	Cache-Control	说明
/3/*	GET	`public, max-age=604800, s-maxage=604800`	7 天边缘缓存
/t/p/*	GET	`public, max-age=604800, s-maxage=604800`	7 天边缘缓存
/bot*	ANY	`不设置`	Telegram 透传，不缓存

提示

非 GET 请求（POST/PUT/DELETE 等）不会被缓存，可放心用于写操作。缓存仅作用于 TMDB 路由的 GET 请求。

§ 05 / TMDB API

TMDB API GET

转发至 https://api.themoviedb.org/3/*，用于查询电影、剧集、人物等元数据。请求参数、响应格式与原 API 完全一致。

/3/{path}

→ https://api.themoviedb.org/3/{path}?{query}

TMDB API 7 天缓存 CORS

将原 api.themoviedb.org 域名替换为代理域名即可，api_key 等查询参数原样透传。

参数	类型	必填	说明
api_key	string	是	TMDB API 密钥（v3 auth），可在 URL 或 Header 中提供
language	string	否	语言代码，如 `zh-CN`、`en-US`，默认 `en-US`
page	integer	否	分页页码，从 1 开始
query	string	视场景	搜索接口（如 `/search/movie`）必填

§ 06 / TMDB 图片

TMDB 图片 GET

转发至 https://image.tmdb.org/t/p/*，用于加载海报、剧照、头像等图片资源。可直接用作 <img> 的 src。

/t/p/{size}/{file}

→ https://image.tmdb.org/t/p/{size}/{file}

TMDB 图片 7 天缓存 CORS

无需 API Key，直接拼接图片路径即可。代理会缓存图片 7 天，重复访问极快。

size	类型	说明
w92 / w154 / w185 / w342 / w500 / w780	width	按宽度缩放的常见尺寸
original	original	原始尺寸（文件较大，谨慎使用）

§ 07 / Telegram Bot

Telegram Bot API ANY

转发至 https://api.telegram.org/bot*，支持所有 Telegram Bot API 方法。不缓存，确保消息实时送达。

/bot{token}/{method}

→ https://api.telegram.org/bot{token}/{method}

Telegram Bot 不缓存 CORS

支持 GET 与 POST，请求体、表单、JSON 均原样透传。响应格式与 Telegram 官方一致。

常用方法	说明
/bot{token}/getMe	获取 Bot 基本信息（验证 Token 是否有效）
/bot{token}/sendMessage	发送文本消息到指定 chat_id
/bot{token}/sendPhoto	发送图片，可附带 caption
/bot{token}/getUpdates	获取 Bot 的更新（轮询模式）
/bot{token}/setWebhook	设置 Webhook（需 HTTPS 公网地址）

安全提示

Bot Token 等同于账户凭证。 通过 URL 传递的 Token 会出现在访问日志中，请勿在前端公开页面暴露真实 Token。建议仅在服务端调用。

§ 08 / TMDB 示例

TMDB 调用示例

获取正在上映的电影列表，包含中文语言与分页参数：

curl 'https://your-domain.vercel.app/3/movie/now_playing?api_key=YOUR_KEY&language=zh-CN&page=1'

const res = await fetch(
  'https://your-domain.vercel.app/3/movie/now_playing?api_key=YOUR_KEY&language=zh-CN&page=1'
);
const data = await res.json();
console.log(data.results); // 电影数组

§ 09 / 图片示例

图片引用示例

图片代理无需 API Key，直接拼接路径即可用作 <img> 的 src：

<img src="https://your-domain.vercel.app/t/p/w500/2ssWTSVklAEc98frZUQhgtGHx7s.jpg"
     alt="电影海报"
     loading="lazy">

background: url('https://your-domain.vercel.app/t/p/original/qVgZu5BTx6pu4owCvVOm4zjTfOi.jpg') center/cover;

§ 10 / Telegram 示例

Telegram 示例

发送一条文本消息到指定会话：

await fetch('https://your-domain.vercel.app/bot<TOKEN>/sendMessage', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    chat_id: 123456789,
    text: 'Hello from proxy!'
  })
});

验证 Token 是否有效：

const res = await fetch('https://your-domain.vercel.app/bot<TOKEN>/getMe');
const me = await res.json();
// { ok: true, result: { id: ..., is_bot: true, first_name: ..., username: ... } }

§ 11 / 一键部署

一键部署

无需配置环境变量，点击下方按钮克隆仓库并部署到 Vercel：

Deploy with Vercel

§ 12 / 本地开发

本地开发

项目零依赖，仅需 Vercel CLI 即可本地运行 Edge Function：

# 全局安装 Vercel CLI（已安装可跳过）
npm i -g vercel

# 进入项目目录启动本地开发服务器
vercel dev
# 默认监听 http://localhost:3000

本地开发模式下，/3/*、/t/p/*、/bot* 路由同样可用，落地页位于 /。

§ 13 / 限制与边界

限制与边界

代理不修改请求体与响应体，仅转发并附加 CORS / Cache-Control 头。
逐跳头（connection、transfer-encoding 等）会被清除，符合 HTTP 规范。
TMDB 路由仅对 GET 请求设置缓存；非 GET 请求实时透传。
Telegram Bot Token 通过 URL 传递，请妥善保管，避免在前端公开暴露。
Vercel Edge Function 有请求体大小与执行时长限制，详见 Vercel 官方文档。