アクセスと認証

包括的な開発者ガイドとベストプラクティスで、すばやく開発を始められます。

キーとヘッダー

保護されたエンドポイントへのアクセスには、X-API-Key ヘッダーによる認証が必要です。本章ではキーの取得方法、リクエストへの付与、安全運用のポイントを説明します。

API キーを取得する

デベロッパーコンソールにサインインします。
「API キー」ページに移動します。
「新しいキーを作成」をクリックし、キーに識別用ラベルを付けます。
キーは一度しか表示されません。必ずコピーして安全な場所に保管してください、ページを離れると再取得はできません。

キーのスコープ

キーは作成したアカウントに紐づき、当該アカウントの辞書と利用枠にアクセスできます。キーの作成・一覧・失効はコンソール UI でのみ行い、管理用の公開 API は提供していません。

リクエストにキーを付与する

リクエストパスと認証の対応

公開パス: /translations/*
公開アクセス: 翻訳の対応言語とモデル一覧を取得します。API キーは不要で、そのまま呼び出せます。
公開パス: /audio/*
公開アクセス: 音声認識の対応言語とモデル一覧を取得します。API キーは不要で、そのまま呼び出せます。
非公開パス: /api/v1/*
API キーが必要: X-API-Key ヘッダーにキーを設定してください。クエリ文字列やボディに渡すとキーなしとみなされます。

/api/v1 配下のすべてのエンドポイントで X-API-Key ヘッダーが必要です。クエリ文字列やボディに渡した場合はキーなしと見なされます。

HTTP ヘッダー例

http

X-API-Key: [YOUR_API_KEY]

完全なリクエスト例（curl）

bash

curl -X POST "https://abemono.abestar.com.tw/api/v1/translations/text" \
  -H "X-API-Key: [YOUR_API_KEY]" \
  -H "Content-Type: application/json" \
  -d '{"text":"Hello","target_language":"zh-TW"}'

未認証時の応答

キーが欠落・無効・失効している場合は 401（code = unauthorized）が返ります。details は通常空オブジェクトで、失敗の詳細は返しません（キーの存在判定を防ぐため）。

401 例

json

{
  "error": {
    "code": "unauthorized",
    "message": "API key is missing or invalid.",
    "details": {},
    "request_id": "0af7651916cd43dd8448eb211c80319c"
  }
}

安全運用の推奨事項

キーの保護

キーをブラウザのコード、モバイルアプリのバイナリ、公開 git リポジトリに埋め込まないでください。自身のバックエンドからプロキシ経由で呼び出し、環境変数から読み取ってください。

アプリケーション単位でキーを分けると、利用追跡と影響範囲の限定が容易になります。
定期的にキーを更新してください。手順は「新キーを作成 → トラフィックを切替 → 安定確認後に旧キーを失効」の順で行います。
漏えいの疑いがある場合は、コンソールから直ちに失効させ、新規キーを発行してください。