翻译 API
翻译接口在一个响应中返回记录的所有语言版本:电影和剧集的标题或名称、简介、宣传语和主页,单集的名称和简介。每行带有 iso_639_1、iso_3166_1 和 english_name。可读取 language 参数未提供的语言,或构建回退链。
获取电影的翻译
GET / 为电影每种有文本的语言返回一行。每一行带有包含译文字段的 data 对象。该调用没有语言参数,因为它的意义就在于一次看到所有语言。
示例找到俄语那一行,打印其标题和简介开头。
curl -s "https://api.amodb.dev/3/movie/550/translations" \
-H "Authorization: Bearer $AMODB_KEY"const url = 'https://api.amodb.dev/3/movie/550/translations';
const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.AMODB_KEY}` } });
if (!res.ok) throw new Error(`amodb returned ${res.status}`);
const { translations } = await res.json();
const ru = translations.find((t) => t.iso_639_1 === 'ru');
console.log(ru ? `${ru.data.title}: ${ru.data.overview.slice(0, 80)}` : 'no Russian row');import os
import requests
r = requests.get(
"https://api.amodb.dev/3/movie/550/translations",
headers={"Authorization": f"Bearer {os.environ['AMODB_KEY']}"},
timeout=10,
)
r.raise_for_status()
ru = next((t for t in r.json()["translations"] if t["iso_639_1"] == "ru"), None)
print(f"{ru['data']['title']}: {ru['data']['overview'][:80]}" if ru else "no Russian row")<?php
$ch = curl_init('https://api.amodb.dev/3/movie/550/translations');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 10,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('AMODB_KEY')],
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($status !== 200) {
throw new RuntimeException("amodb returned $status");
}
foreach (json_decode($body, true)['translations'] as $t) {
if ($t['iso_639_1'] === 'ru') {
echo $t['data']['title'], ': ', mb_substr($t['data']['overview'], 0, 80), PHP_EOL;
exit;
}
}
echo 'no Russian row', PHP_EOL;package main
import (
"encoding/json"
"fmt"
"net/http"
"os"
"time"
)
type Translations struct {
Translations []struct {
ISO6391 string `json:"iso_639_1"`
Data struct {
Title string `json:"title"`
Overview string `json:"overview"`
} `json:"data"`
} `json:"translations"`
}
func main() {
req, _ := http.NewRequest("GET", "https://api.amodb.dev/3/movie/550/translations", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("AMODB_KEY"))
client := &http.Client{Timeout: 10 * time.Second}
res, err := client.Do(req)
if err != nil {
panic(err)
}
defer res.Body.Close()
if res.StatusCode != http.StatusOK {
panic(res.Status)
}
var t Translations
if err := json.NewDecoder(res.Body).Decode(&t); err != nil {
panic(err)
}
for _, row := range t.Translations {
if row.ISO6391 == "ru" {
text := []rune(row.Data.Overview)
if len(text) > 80 {
text = text[:80]
}
fmt.Printf("%s: %s\n", row.Data.Title, string(text))
return
}
}
fmt.Println("no Russian row")
}参数
movie_id路径必填数字形式的电影 ID,例如550。api_key查询二选一你的密钥。使用它,或使用Authorization: Bearer请求头。
响应字段
| 字段 | 类型 | 说明 |
|---|---|---|
id | integer | 电影 ID。 |
translations | array | 每种有文本的语言一行,按语言代码排序。电影 550 返回 50 行。 |
translations[].iso_ | string | 与语言配套的国家代码,例如 en 对应 US,pt 对应 BR。对于 14 种提供语言以外的语言,它把语言代码改成大写重复一遍。 |
translations[].iso_ | string | 语言代码,例如 ru 或 pt。在数组中唯一。 |
translations[].name | string | 用该语言书写的语言名称。 |
translations[].english_ | string | 英文的语言名称。 |
translations[].data | object | 译文字段。键取决于资源,见下表。 |
示例响应
这里显示了 50 行中的两行,简介已缩短。
{
"id": 550,
"translations": [
{
"iso_3166_1": "US",
"iso_639_1": "en",
"name": "English",
"english_name": "English",
"data": {
"title": "Fight Club",
"overview": "A ticking-time-bomb insomniac and a slippery soap salesman channel primal male aggression into a shocking new form of therapy....",
"homepage": "https://www.20thcenturystudios.com/movies/fight-club",
"tagline": "Mischief. Mayhem. Soap.",
"runtime": 0
}
},
{
"iso_3166_1": "RU",
"iso_639_1": "ru",
"name": "Русский",
"english_name": "Russian",
"data": {
"title": "Бойцовский клуб",
"overview": "Сотрудник страховой компании страдает хронической бессонницей и отчаянно пытается вырваться из мучительно скучной жизни. Однажд...",
"homepage": "https://www.20thcenturystudios.com/movies/fight-club",
"tagline": "«Интриги. Хаос. Мыло»",
"runtime": 0
}
}
]
}在 amodb 中,翻译行里的 runtime 始终为 0。请从电影详情记录读取片长。
翻译接口及其 data 键
所有路径使用同一个基础地址 https:/。每个都返回 id 和上述行结构的 translations 数组。只有 data 里的键不同。
| 方法和路径 | data 键 |
|---|---|
GET / | title、overview、homepage、tagline、runtime(始终为 0) |
GET / | name、overview、homepage、tagline |
GET / | 无,数组始终为空 |
GET / | name、overview |
剧集记录列出的语言数量与电影差不多。单集的行只覆盖该单集有文本的提供语言,在检查过的样本中为 2 到 14 种。把缺失的键当作空值处理,并忽略你不认识的键。上级记录见电视剧。
amodb 不提供人物或系列合集的翻译。人物传记遵循人物详情调用的 language 参数,系列合集的简介按存储的内容返回。
文本缺失时回退
一部作品可能有 14 种语言,但在用户选择的那种语言里简介仍为空。沿着语言链依次尝试,取第一个非空值,并记住它来自哪种语言。
function pickText(translations, wanted, field) {
for (const code of [...wanted, 'en']) {
const row = translations.find((t) => t.iso_639_1 === code);
const value = row?.data?.[field];
if (value) return { code, value };
}
return null;
}
// Prefer Ukrainian, then Russian, then English.
// const hit = pickText(translations, ['uk', 'ru'], 'overview');对于剧集,把字段改为传 'name' 而不是 'title'。在界面中标出来自回退语言的文本,让用户知道为什么乌克兰语页面显示的是英文剧情简介。
翻译接口还是 language 参数
| 需求 | 使用 |
|---|---|
| 向一个用户展示一种语言 | 详情调用上的 language |
| 在编辑界面列出作品的所有语言 | 此接口 |
读取 language 不提供的语言,例如 ja | 此接口,按 iso_639_1 选行 |
| 检查 14 种提供语言中哪些有文本 | 此接口,比较 iso_639_1 |
| 为页面构建多语言链接 | 此接口,读取存在的代码 |
language 接受的标签见语言。详情调用上任何其他标签都会回退到英文。
错误
| HTTP | status_code | 何时出现 |
|---|---|---|
| 401 | 7 | 密钥缺失或错误。 |
| 402 | 36 | 套餐周期已结束。 |
| 404 | 34 | 没有该 ID 的季或单集,或 ID 不是数字。 |
| 405 | 37 | 你对翻译路径使用了写入方法。 |
| 429 | 25 | 超过了每分钟请求数。请等待 Retry-After 秒。 |
不存在的电影或剧集 ID 在此路径上不算错误:它返回 200 和 "translations": [],而详情路径返回 404。更多见错误和速率限制。
实用说明
- 一次调用可以替代多达 14 次详情调用。需要同一作品两种以上语言时使用它。
- 各行按语言代码排序,这不是优先级顺序。请按
iso_639_1选行,不要按数组位置。 - 详情类调用在边缘缓存 6 小时,所以同样时长的客户端缓存不会损失新鲜度。
- 日语或韩语等其他文字的原始标题,始终可在详情记录的
original_title和original_name中获得。 - 要把翻译加入详情调用,请传
append_,并从响应中读取同样的数组。它适用于电影、剧集和单集。追加的数据块没有to_ response= translations id。