はじめに

PolyLingo HTTP API を使用して、プレーンテキスト、Markdown、JSON、または HTML を構造を保ったまま翻訳します。このガイドでは、本番環境のエンドポイント、認証、および最初の成功したリクエストについて説明します。

ベースURL

すべての例は本番APIを使用しています：

URL
本番https://api.usepolylingo.com/v1

以下の各パスはこのベースに対する相対パスです（例：POST /translate は POST https://api.usepolylingo.com/v1/translate を意味します）。

もしご自身の PolyLingo API インスタンスを運用している場合は、ホストをデプロイメントのURLに置き換え、特に設定していなければ /v1 プレフィックスは維持してください。

認証

保護されたエンドポイントは Authorization ヘッダーにAPIキーを期待します：

Authorization: Bearer <your_api_key>

キーの取得方法： PolyLingoアプリの API keys セクションで作成します。キーは完全なものを一度だけ表示されるため、安全な場所（環境変数やシークレットマネージャー）に保存してください。キーは同じ画面から取り消すことができます。

セキュリティ： キーはパスワードのように扱ってください。キーがユーザーに露出しないよう、APIは公開ブラウザコードではなく、サーバーから呼び出すことを推奨します。

ヘッダーがない、間違っている、またはキーが無効・取り消されている場合、APIは 401 と error: "invalid_api_key" を返します。

エンドポイントとキー

キー不要GET /health — 簡単な稼働確認
GET /languages — 対応言語コード
キー必要POST /translate — コンテンツを翻訳
POST /translate/batch — 複数アイテムを翻訳
POST /jobs — 長時間の翻訳をキューに入れる（即座に 202 を返す）
GET /jobs/:id — ジョブの状態をポーリング；待機中は queue_position を含む
GET /usage — 認証済みアカウントの使用状況

最初のリクエスト (cURL)

export POLYLINGO_API_KEY="pl_your_key_here"

curl -sS -X POST "https://api.usepolylingo.com/v1/translate" \
  -H "Authorization: Bearer $POLYLINGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "# Hello\n\nThis is **bold**.",
    "format": "markdown",
    "targets": ["es", "fr"],
    "model": "standard"
  }'

成功したレスポンスには、リクエストした各ターゲット言語ごとのエントリを持つ translations オブジェクトと、トークン数を含む usage オブジェクトが含まれます。

最初のリクエスト (Node.js)

Node.js 18+ には fetch が含まれています：

const API_KEY = process.env.POLYLINGO_API_KEY
const res = await fetch('https://api.usepolylingo.com/v1/translate', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${API_KEY}`,
  },
  body: JSON.stringify({
    content: '# Hello\n\n**Bold** text.',
    format: 'markdown',
    targets: ['de', 'ja'],
    model: 'standard',
  }),
})
const data = await res.json()
if (!res.ok) throw new Error(`${data.error}: ${data.message}`)
console.log(data.translations)

APIが到達可能か確認する

ヘルスチェックにはキーは不要です：

curl -sS "https://api.usepolylingo.com/v1/health"

サービスが稼働中であることを示す小さなJSONペイロードが表示されるはずです。targets として渡せるコードの一覧は GET /languages を使ってください。

CORS とブラウザアプリ

APIはどのブラウザオリジンが直接呼び出せるか制限する場合があり、信頼できないサイトからキーが使われるのを防ぎます。サーバーサイドの呼び出し（Node、Python、エッジ関数、バックエンド）はCORSの制限を受けません。

シングルページアプリの場合、一般的なパターンは：フロントエンドがバックエンドと通信し、バックエンドがAPIキーを使ってPolyLingoを呼び出します。

次のステップ

  • API reference — リクエストとレスポンスの形状、フォーマット、エラー、制限。
はじめに | PolyLingo | PolyLingo