# General Translation Platform: 概要
URL: https://generaltranslation.com/ja/docs/platform/openapi/overview.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 公開されている General Translation API のendpointを呼び出し、OpenAPI 仕様をダウンロードします。

General Translation API を使って、カスタムの自動化ワークフローを構築できます。

CLI がほとんどの API 呼び出しを処理します。生成されたリクエスト型・レスポンス型を利用するには [`generaltranslation/api` TypeScript クライアント](/docs/platform/core/reference/api-client) を使用し、カスタムの自動化が必要な場合はendpointを直接呼び出してください。

OpenAPI 仕様では、これらのendpointが機械可読な形式で定義されています。

## API の基本 [#api-basics]

### ベース URL

`POST /v2/translate` によるruntime translationを含むすべてのエンドポイントは、`https://api.gtx.dev` をベース URL とします。

### 認証

標準の `Authorization` ヘッダーに API キーを指定して認証します。

```bash
curl https://api.gtx.dev/v2/project/info/PROJECT_ID \
  -H "Authorization: Bearer gtx-api-..."
```

ワークフローに合った key スコープ を選択してください。

* **プロジェクト**、プレフィックス `gtx-api-`: 1 つのプロジェクトに紐づき、その権限の範囲内で任意の環境で利用できます
* **Organization**、プレフィックス `gtx-org-`: 紐づけられた Organization 内の複数のプロジェクトをまたいで、その権限の範囲内で利用できます

path にプロジェクト ID を含むプロジェクトスコープのendpointでは、その ID によって対象のプロジェクトが決まります。`gt-project-id` を任意で指定する場合は、その ID と一致している必要があります。一致しない場合、リクエストは `403` で失敗します。path にターゲットがない場合、プロジェクトキーは紐づけられたプロジェクトを使用します。Organization キーの場合は `gt-project-id` を送信する必要があります。プロジェクトおよび Organization の検出には、プロジェクトのターゲットは不要です。path にターゲットを含む Organization スコープのルートでは、その Organization が使用されます。また、Context Group のルート (`/v2/context-groups/{groupId}`) では、そのグループを所有する Organization が使用されます。

従来の API キーヘッダーも引き続きサポートされており、bearer ヘッダーよりも優先されます。API キーは、デプロイするブラウザ向けおよびモバイル向けのバンドルに含めないでください。

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

### 権限

ほとんどのendpointでは、リクエストの識別情報に権限が付与されている必要があります。[List Organizations](/docs/platform/openapi/reference/project/list-orgs)、[List Projects](/docs/platform/openapi/reference/project/list-projects)、[Get Project information](/docs/platform/openapi/reference/project/project-info) は、返される Organization またはプロジェクトへのアクセス権があれば、それ以外のリソース権限は必要ありません。Organization キー とプロジェクトキー はいずれも、Dashboard で **All** または **Custom** の権限設定に対応しており、作成者が付与できる権限に限定されます。[プロジェクトの API キーendpoint](/docs/platform/openapi/reference/project/create-api-key) では、権限を個別に選択することも、選択を省略して委譲可能なすべてのプロジェクト権限を付与することもできます。HTTP Write 権限を明示的に付与しても、Read 権限は暗黙的には含まれません。Context Management endpointには Organization の権限が必要なため、Organization キーを使用する必要があります。プロジェクトキーではこれらのendpointを呼び出せません。

一般的な権限:

* `org:projects:create` は、`POST /v2/orgs/{orgId}/projects` を使用してプロジェクトを作成するための権限です。
* `project:api_keys:write` は、`POST /v2/projects/{projectId}/api-keys` を使用してプロジェクトの API キー を作成するための権限です。
* `project:files:read` は、ファイルのダウンロード、および file info、翻訳ステータス、branch info、孤立ファイル、job infoの読み取りに使用します。
* `project:files:write` は、ファイル・翻訳・asset のアップロード、差分の送信、公開、branch と tag の作成、ファイルの移動に使用します。
* `project:translations:enqueue` は、翻訳のためにファイルをキューに追加するための権限です。
* `project:translations:generate` は、runtime translation のための権限です。
* `project:context:write` は、コンテキスト の生成に使用します。
* `org:context:read` は、Context Group とその用語集・Custom Prompts、プロジェクトへの割り当て、エクスポートの読み取りに使用します。
* `org:context:write` は、Context Group とそのコンテンツの作成・更新・削除、コンテンツの import、およびプロジェクトに対するグループの割り当て・割り当て解除・並べ替えに使用します。
* `project:write` は、プロジェクト の設定更新に使用します。

### バージョニング

レスポンス形式を固定するには、任意の `gt-api-version` ヘッダーを送信します。

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

ヘッダーを省略した場合、サポート対象の最も古いバージョンが使用されます。最新のバージョンは `2026-03-06.v1` です。

### ランタイムメタデータの上限

`POST /v2/translate` では、正の整数の `maxChars` を指定すると、対応する翻訳プロンプトに長さに関する指示が追加されます。ただし、出力長の上限を保証するものではありません。0 以下の値や小数は無視されます。型が正しくない値はリクエストの検証エラーになります。

各 `sourceCode` ファイルが保持できるコンテキストエントリは最大 5 件です。API は各エントリの `before` および `after` フィールドを 2,000 文字に、`target` フィールドを 500 文字に切り詰めます。

`fileFormat` に `MD` または `MDX` を設定すると、文字列として渡したドキュメント全体を翻訳できます。ドキュメントのリクエストでは `dataFormat: STRING` を使用する必要があり、`maxChars` や `sourceCode` を含めることはできません。API はドキュメントをチャンクに分割し、各チャンクにリクエストのコンテキストを付与したうえで、検証済みのドキュメント文字列を 1 つ返します。チャンクが失敗した場合や最終的なドキュメントが不正な場合は、部分的な出力を返すのではなく、そのエントリが失敗となります。

### レート制限

レート制限は、60 秒間のウィンドウを使用して 2 つのレイヤーで適用されます。

* **認証前:** 提示された認証情報ごとに 1 分あたり 600 回まで試行でき、認証に失敗したリクエストもこれに含まれます。認証情報を含まないリクエストは、このレイヤーの対象外です。上限を超えると `429` が返され、`Retry-After: 60` が付与されますが、`RateLimit-*` ヘッダーは含まれません。
* **認証後:** 各ルートグループでは、APIキーなどの認証済み呼び出し元ごとにリクエスト数が制限されます。認証済み呼び出し元が存在しない制限対象ルートでは、クライアントIPが単位となります。

認証後の上限はendpointによって異なります。

* **Heavy:** 翻訳のキュー登録は 1 分あたり 30 リクエスト。
* **Medium:** アップロード、差分、コンテキスト生成、移動、孤立ファイル、公開は 1 分あたり 120 リクエスト。
* **Light:** ファイルのダウンロードは 1 分あたり 300 リクエスト。
* **Default:** プロジェクトおよび Organization の検出、プロジェクトおよびプロジェクトAPIキーの作成、branch、tag、プロジェクト info、job info、file info、翻訳ステータス、runtime translation、Context Management は 1 分あたり 200 リクエスト。

プロジェクトおよび Organization の検出と、プロジェクト/キーの作成は、同じリクエスト上限を共有します。

認証後の上限を超えると、`RateLimit-*` ヘッダー付きで `429` が返されます。Organization トークン の上限を超えると、`POST /v2/translate` から `402` が返されます。

### ページネーション

一覧系の endpoint は、結果を 1 ページ分ずつ `{ "items": [...], "nextCursor": ... }` の形式で返します。ページサイズは `limit` (1〜100、デフォルトは 50) で指定します。`nextCursor` が文字列の場合は、その値を `cursor` として送信すると次のページを取得できます。`null` の場合は、それ以上の結果はありません。カーソルは、そのカーソルを発行した一覧とフィルターの組み合わせでのみ使用できます。各ページは個別に読み取られるため、リクエストの合間に変更された項目は、取得から漏れたり重複して返されたりする場合があります。

### エラー

エラー時には `error` メッセージが返されます。API バージョン `2026-02-18.v1` 以降では、レスポンスボディは JSON です。それより前のバージョンでは、`gt-api-version` ヘッダー が送信されない場合に使われるデフォルトを含め、メッセージはプレーンテキストで返されます。これは、不正な形式の JSON (`400`)、サイズ超過のボディ (`413`)、レート制限 (`429`) を含む、すべてのエラーに適用されます。

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

一般的なステータスコード:

* リクエスト本文、クエリ、またはバージョンが無効な場合は `400`。
* ベアラー credential がない、または無効な場合は `401`。
* Organization のトークン上限を超えた場合は `402` (`POST /v2/translate`) 。
* リクエストの識別情報に権限がない、または現在のプランではその操作が許可されていない場合は `403`。
* リソースが見つからない場合は `404`。
* 競合が発生した場合は `409`。たとえば、プロジェクトの作成によって Organization のプロジェクト数の上限を超える場合や、変更後の名前が既存の用語集の用語または Custom Prompt と重複する場合などです。
* リクエスト本文がendpointの上限を超えた場合、または Context Management のレスポンスが 1 MiB を超える場合は `413` (より小さい `limit` を指定して再度リクエストしてください) 。
* 要求された翻訳済みファイルがまだ処理中の場合は `425`。
* レート制限を超えた場合は `429`。
* 内部サーバーエラーの場合は `500`。
* サービスが一時的に利用できない場合は `503`。

`425`、`429`、`503` のレスポンスは、時間をおいてから再試行してください。`429` の場合は、`Retry-After` ヘッダーに示された秒数だけ待ってから再試行してください。

## OpenAPI 仕様 [#openapi-spec]

機械可読な OpenAPI 3.1 仕様は [`/openapi.json`](/openapi.json) で公開されています。これを Postman、Insomnia、または OpenAPI クライアントにインポートすると、リクエストや型を生成できます。

型付きのエンドポイント helper については、[`generaltranslation/api` クライアント](/docs/platform/core/reference/api-client)を使用してください。

## リファレンス セクション

- /docs/platform/core/reference/api-client
- /docs/platform/openapi/reference/files/upload-source
- /docs/platform/openapi/reference/context/generate-context
- /docs/platform/openapi/reference/context-management/list-groups
- /docs/platform/openapi/reference/translation/translate-runtime
- /docs/platform/openapi/reference/project/create-project

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.