Getting started

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

Base URL

すべての例は本番環境のAPIを使用しています:

以下のすべてのパスはこのベースに対して相対的です（例：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" を返します。

エンドポイントとキー

最初のリクエスト (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"
  }'

成功したレスポンスには、リクエストした各ターゲット言語ごとに1つのエントリを持つ 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 — リクエストとレスポンスの形式、フォーマット、エラー、制限。