# 快速开始

> 购买套餐，创建密钥，发出第一次请求 https://api.amodb.dev/3/movie/550，得到你熟悉的 TMDB v3 JSON。再用 poster_path 拼出海报 URL。已在用 TMDB 或 OMDb 的，只需更换基础 URL 和密钥。

## 1. 获取密钥

在[定价页](https://amodb.dev/zh/pricing/)选择套餐并支付一个周期。然后打开 **账户**，再打开 **API 密钥**，创建一个密钥。密钥是 32 位小写十六进制字符，与 TMDB v3 密钥的形式相同。

完整密钥只显示一次。请把它存为名为 `AMODB_KEY` 的环境变量，这样本页的示例就能原样运行。

```bash
export AMODB_KEY="0123456789abcdef0123456789abcdef"
```

## 2. 请求电影详情

调用 `GET /3/movie/{movie_id}`。把密钥作为 Bearer 令牌发送，或作为查询中的 `api_key`。两种方式在每个接口都被接受。

```bash
curl "https://api.amodb.dev/3/movie/550?language=en-US" \
  -H "Authorization: Bearer $AMODB_KEY"
```

```js
const res = await fetch("https://api.amodb.dev/3/movie/550?language=en-US", {
  headers: { Authorization: `Bearer ${process.env.AMODB_KEY}` },
});
if (!res.ok) throw new Error(`amodb ${res.status}`);
const movie = await res.json();
console.log(movie.title, movie.runtime);
```

```python
import os
import requests

res = requests.get(
    "https://api.amodb.dev/3/movie/550",
    params={"language": "en-US"},
    headers={"Authorization": f"Bearer {os.environ['AMODB_KEY']}"},
    timeout=10,
)
res.raise_for_status()
movie = res.json()
print(movie["title"], movie["runtime"])
```

```php
<?php
$ch = curl_init("https://api.amodb.dev/3/movie/550?language=en-US");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("AMODB_KEY")],
]);
$movie = json_decode(curl_exec($ch), true);
echo $movie["title"] . " " . $movie["runtime"];
```

```go
package main

import (
	"encoding/json"
	"fmt"
	"log"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.amodb.dev/3/movie/550?language=en-US", nil)
	req.Header.Set("Authorization", "Bearer "+os.Getenv("AMODB_KEY"))

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		log.Fatal(err)
	}
	defer res.Body.Close()

	var movie struct {
		Title   string `json:"title"`
		Runtime int    `json:"runtime"`
	}
	json.NewDecoder(res.Body).Decode(&movie)
	fmt.Println(movie.Title, movie.Runtime)
}
```

200 响应包含 TMDB v3 的字段。下面是其中的一小部分：

```json
{
  "id": 550,
  "imdb_id": "tt0137523",
  "title": "Fight Club",
  "release_date": "1999-10-15",
  "runtime": 139,
  "poster_path": "/pB8BM7pdSp6B6Ih7QZ4DrQ3PmJK.jpg"
}
```

## 3. 加载海报

把图片基础 URL、尺寸和 `poster_path` 拼在一起。图片无需密钥，缓存保留 30 天。

```bash
curl -o poster.jpg "https://img.amodb.dev/t/p/w500/pB8BM7pdSp6B6Ih7QZ4DrQ3PmJK.jpg"
```

```js
const poster = `https://img.amodb.dev/t/p/w500${movie.poster_path}`;
```

```python
poster = f"https://img.amodb.dev/t/p/w500{movie['poster_path']}"
```

各个尺寸，以及如何根据 `/3/configuration` 构造 URL，见[图片](https://amodb.dev/zh/images/)。

## 4. 迁移现有客户端

对于 TMDB v3 客户端，把基础 URL 从 `https://api.themoviedb.org/3` 改为 `https://api.amodb.dev/3`，并使用你的 amodb 密钥。对于 OMDb 客户端，改为 `https://api.amodb.dev/omdb/`，并把同一个密钥作为 `apikey` 传入。

TMDB 的账户、会话、评分和列表写入方法不提供。它们返回 HTTP 405 和 `status_code` 37，所以只读客户端不需要其他改动。

## 5. 处理限制和错误

每个密钥有由套餐决定的每分钟速率。请读取 `X-RateLimit-Remaining`，收到 429 后等待 `Retry-After` 秒。错误使用 TMDB 的响应体，包含 `success`、`status_code` 和 `status_message`。

上线之前，请阅读[速率限制](https://amodb.dev/zh/rate-limits/)和[错误](https://amodb.dev/zh/errors/)。

## 常见问题

### 在哪里找到我的密钥？

在 amodb.dev 登录，打开“账户”，再打开“API 密钥”，然后创建一个密钥。完整密钥只显示一次，所以请立即把它复制到你的密钥存储中。

### 可以在浏览器应用中使用这个密钥吗？

只能放在你自己的服务器之后。客户端代码中的密钥是公开的，任何复制它的人都会占用你的请求速率。

## 相关页面

- [认证](https://amodb.dev/zh/authentication/): 如何发送 amodb 密钥：查询中的 api_key、Bearer 请求头，或 OMDb 的 apikey。含密钥格式、保管和 401 错误。
- [图片](https://amodb.dev/zh/images/): 从 img.amodb.dev 加载海报、背景图和人物照片，路径和尺寸与 TMDB 相同，从 w92 到 original。无需密钥，缓存 30 天。
- [错误](https://amodb.dev/zh/errors/): amodb 的每个错误及其 HTTP 状态、TMDB status_code 和消息，以及 OMDb 错误结构。每个错误的含义和客户端下一步该做什么。
- [速率限制](https://amodb.dev/zh/rate-limits/): amodb 按滑动 60 秒窗口内每分钟请求数限制每个密钥：按套餐为 20、40 或 120。读取速率限制响应头，并用 Retry-After 处理 429。

更新于: 2026-10-18. Source: https://amodb.dev/zh/quickstart/