# api: API リファレンス
URL: https://generaltranslation.com/ja/docs/api.mdx
---
title: API リファレンス
description: 公開されている General Translation API のエンドポイント、認証、OpenAPI 仕様
index: true
---

General Translation API では、ソースコンテンツや翻訳済みファイルのアップロード、翻訳のダウンロード、コンテンツの翻訳とキューへの追加、ブランチとタグの管理、プロジェクトやジョブのステータス確認を行えます。ほとんどの SDK や CLI のワークフローではこれらのエンドポイントが自動的に呼び出されますが、独自の自動化のために直接呼び出すこともできます。

各エンドポイントにはこのセクション内に専用ページがあり、パラメータ、スキーマ、対話型のリクエストプレイグラウンドが用意されています。また、これらのページには機械可読な OpenAPI 3.1 仕様として `openapi.yaml` も付属しています。これを Postman、Insomnia、または OpenAPI クライアントにインポートすると、リクエストや型を生成できます。

## ベース URL

| API                            | ベース URL                   |
| ------------------------------ | ------------------------- |
| プロジェクトおよびファイルの API エンドポイント     | `https://api.gtx.dev`     |
| ランタイム翻訳 (`POST /v2/translate`) | `https://runtime.gtx.dev` |

## 認証

すべてのリクエストで、`x-gt-api-key` ヘッダーに API キーを指定して認証します。

```bash
curl https://api.gtx.dev/v2/project/info/PROJECT_ID \
  -H "x-gt-api-key: gtx-api-..."
```

| キータイプ          | プレフィックス    | メモ                                                               |
| -------------- | ---------- | ---------------------------------------------------------------- |
| プロジェクト (本番環境)  | `gtx-api-` | 1 つのプロジェクトに紐づきます                                                 |
| プロジェクト (開発環境)  | `gtx-dev-` | ローカルおよびプレビューで使用します。本番専用エンドポイントでは拒否されます                           |
| 組織             | `gtx-org-` | 複数のプロジェクトで使用できます。プロジェクトスコープのルートでは `x-gt-project-id` を送信する必要があります |

<Callout type="info">
  **Organization keys:** 組織キーで認証する場合は、プロジェクトスコープのエンドポイントで対象プロジェクトを `x-gt-project-id` ヘッダーに含めてください。
</Callout>

キーの作成方法とスコープの設定方法については、[API キー](/docs/platform/api-keys) を参照してください。

## 権限

各エンドポイントでは、API キーに対応する権限が必要です。組織キー ではこれらを明示的に設定し、Project keys ではプロジェクトのデフォルト設定が適用されます。

| 権限                              | 用途                                                            |
| ------------------------------- | ------------------------------------------------------------- |
| `project:files:read`            | ファイルのダウンロード、ファイル情報、翻訳ステータス、branch 情報、孤立したファイル、プロジェクト情報、job 情報 |
| `project:files:write`           | ファイルと翻訳のアップロード、差分、公開、branch の作成、tag の作成、移動                    |
| `project:translations:enqueue`  | 翻訳用にファイルをキューに追加                                               |
| `project:translations:generate` | ランタイム翻訳                                           |
| `project:context:read`          | context 生成ステータスの確認                                            |
| `project:context:write`         | context の生成                                                   |
| `project:write`                 | プロジェクト設定の更新                                                   |

## バージョニング

レスポンス形式を固定するには、任意の`gt-api-version` headerを送信します。省略した場合は、サポートされている最も古いバージョンが使用されます。最新バージョンは`2026-03-06.v1`です。

```bash
-H "gt-api-version: 2026-03-06.v1"
```

## レート制限

リクエストには、60 秒間のウィンドウ内で API キー (またはクライアント IP) ごとにレート制限が適用されます。制限値はエンドポイントによって異なります。

| Tier    | Limit     | Endpoints                                           |
| ------- | --------- | --------------------------------------------------- |
| Heavy   | 20 / min  | 翻訳のキュー登録                                            |
| Medium  | 60 / min  | アップロード、差分、context、移動、孤立項目                           |
| Light   | 120 / min | ファイルのダウンロード                                         |
| Default | 200 / min | 公開、ブランチ、タグ、プロジェクト情報、ジョブ情報、ファイル情報、翻訳ステータス、Runtime 翻訳 |

制限を超えると `429` が返されます。Organization トークンのクォータにより、`POST /v2/translate` でも `429` が返されることがあります。

## エラー

エラー時には、`error` メッセージを含む JSON ボディが返されます。

```json
{
  "error": "API key is missing required permission: project:files:write"
}
```

| ステータス | 意味                                        |
| ----- | ----------------------------------------- |
| `400` | 無効なリクエストボディ、query、またはバージョン                |
| `401` | API キー が存在しないか無効です                       |
| `403` | API キー に必要な権限がないか、現在のプランではこの操作は許可されていません |
| `404` | リソースが見つかりません                              |
| `429` | レート制限またはトークンの上限を超過しました                    |

## 次のステップ

* [API キー](/docs/platform/api-keys) - キーを作成し、スコープを設定する
* [Webhooks](/docs/platform/webhooks) - 翻訳イベントを受け取る
* [対応ロケール](/docs/platform/supported-locales) - リクエストで使用するロケールコード