JoySpeech 开放 API

使用 JoySpeech 翻译 API，将实时多语言翻译能力集成到你的应用、脚本或服务中。

认证方式

所有翻译请求需在 HTTP 头中携带 API Key：

X-JoySpeech-API-Key: jsk_your_api_key_here

API Key 以 jsk_ 前缀开头，可在个人中心或通过 API 创建。每个 Key 有独立的速率限制和使用统计。

速率限制

参数	默认值	说明
每分钟请求	60 次	可在创建 Key 时自定义（1-1000）
单次文本上限	5000 字符	超出返回 400
超限响应	429	返回 retry_after 字段

API 端点

POST /api/v1/translate/

翻译文本。需要 API Key 认证。

请求体 (JSON):

参数	类型	必填	说明
text	string	是	待翻译文本（最多 5000 字符）
source_language	string	否	源语言代码，默认 "auto" 自动检测
target_language	string	否	目标语言显示名，默认 "中文"

成功响应 (200):

{
  "translated_text": "你好世界",
  "engine": "tencent",
  "characters": 11
}

错误响应:

// 401 — 未认证
{ "error": "缺少 API Key。请在请求头中添加 X-JoySpeech-API-Key。" }

// 429 — 超限
{ "error": "请求频率超限，请稍后重试。", "retry_after": 42 }

// 400 — 参数错误
{ "error": "请提供待翻译文本 (text)。" }

GET /api/v1/keys/

列出当前用户的所有 API Key。需要 Token 认证。

Authorization: Token your_django_token

响应:

{
  "keys": [
    {
      "id": 1,
      "name": "My App",
      "key_prefix": "jsk_aBcDeF",
      "rate_limit": 60,
      "is_active": true,
      "total_requests": 128,
      "created_at": "2026-09-01T10:00:00Z",
      "last_used_at": "2026-09-01T14:30:00Z"
    }
  ],
  "count": 1
}

POST /api/v1/keys/

创建新的 API Key。需要 Token 认证。明文密钥仅在创建时返回一次。

请求体:

{
  "name": "My App",
  "rate_limit": 100
}

响应 (201):

{
  "id": 2,
  "name": "My App",
  "key": "jsk_xxxxxxxxxxxxxxxxxxxxxxxx",
  "key_prefix": "jsk_xxxxxx",
  "rate_limit": 100,
  "created_at": "2026-09-01T10:00:00Z"
}

DELETE /api/v1/keys/<id>/

吊销（删除）指定的 API Key。需要 Token 认证。

响应:

{ "deleted": true, "id": 2 }

代码示例

Python

import requests

API_KEY = "jsk_your_api_key_here"
url = "https://www.joyspeech.cn/api/v1/translate/"

resp = requests.post(url, json={
    "text": "Hello, how are you?",
    "source_language": "en",
    "target_language": "中文"
}, headers={
    "X-JoySpeech-API-Key": API_KEY,
    "Content-Type": "application/json"
})

data = resp.json()
print(data["translated_text"])
# 输出: 你好，你怎么样？

JavaScript (fetch)

const API_KEY = "jsk_your_api_key_here";

const response = await fetch("https://www.joyspeech.cn/api/v1/translate/", {
  method: "POST",
  headers: {
    "X-JoySpeech-API-Key": API_KEY,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    text: "Hello, how are you?",
    source_language: "en",
    target_language: "中文"
  })
});

const data = await response.json();
console.log(data.translated_text);

curl

curl -X POST https://www.joyspeech.cn/api/v1/translate/ \
  -H "X-JoySpeech-API-Key: jsk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"text":"Hello world","source_language":"en","target_language":"中文"}'

支持的目标语言

中文、English、Deutsch、日本語、한국어、Français、Español、Português、Русский、العربية、Italiano、Türkçe、ภาษาไทย、Tiếng Việt、Bahasa Indonesia、Bahasa Melayu、हिन्दी