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

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

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

OpenAPI 仕様では、これらのエンドポイントが機械可読な形式で定義されています。

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

### ベース URL

`POST /v2/projects/{projectId}/translate` による実行時翻訳を含むすべてのエンドポイントは、`https://api.gtx.dev` をベース URL とします。

### 認証

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

```bash
curl https://api.gtx.dev/v2/projects/PROJECT_ID \
  -H "Authorization: Bearer gtx-api-..." \
  -H "gt-api-version: 2026-10-08.v1"
```

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

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

リクエストの対象はパスによって決まります。`/v2/projects/{projectId}/...` ではプロジェクト、`/v2/orgs/{orgId}/...` では 組織、`/v2/context-groups/{groupId}/...` ではそのグループを所有する 組織 が対象となります。検出用のエンドポイント (`GET /v2/orgs` および `GET /v2/projects`) では ID を指定する必要はありません。キーには対象のプロジェクトまたは 組織 へのアクセス権が必要なため、プロジェクトキーは紐づけられたプロジェクトと、そのプロジェクトに割り当てられたコンテキストグループでのみ使用できます。

API キーは、デプロイするブラウザ向けおよびモバイル向けのバンドルに含めないでください。

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

### 権限

ほとんどのエンドポイントでは、リクエストの識別情報に権限が付与されている必要があります。[List Organizations](/docs/platform/openapi/reference/organizations/list-orgs)、[List Projects](/docs/platform/openapi/reference/projects/list-projects)、[Get a Project](/docs/platform/openapi/reference/projects/get-project) は、返される 組織 またはプロジェクトへのアクセス権があれば、それ以外のリソース権限は必要ありません。組織 キー とプロジェクトキー はいずれも、Dashboard で **All** または **カスタムプロンプト** の権限設定に対応しており、作成者が付与できる権限に限定されます。[プロジェクトの API キーエンドポイント](/docs/platform/openapi/reference/api-keys/create-project-api-key) では、権限を個別に選択することも、選択を省略して自分が委譲できるすべてのプロジェクト権限を付与することもできます。Write 権限には Read 権限は含まれません。プロジェクトキーは 組織 の権限 (`org:*`)、`project:api_keys:read`、`project:api_keys:write` を保持できないため、これらを必要とするエンドポイントには 組織 キーが必要です。

一般的な権限:

* `org:projects:create` は、`POST /v2/orgs/{orgId}/projects` を使用してプロジェクトを作成するための権限です。
* `project:api_keys:read` は、プロジェクトの API キー の一覧取得と読み取りに使用します。
* `project:api_keys:write` は、`POST /v2/projects/{projectId}/api-keys` を使用したプロジェクトの API キー の作成と、その削除に使用します。
* `org:assets:write` は、`POST /v2/orgs/{orgId}/assets` を使用してフォントをアップロードするための権限です。
* `project:files:read` は、ファイルのダウンロード、ファイルのメタデータとステータスの読み取り、ブランチとブランチ内ファイルの一覧取得、ジョブの読み取りに使用します。
* `project:files:write` は、原文ファイルと翻訳のアップロード、翻訳の上書き、公開、ブランチの作成と更新、タグの設定、ファイルの移動に使用します。
* `project:translations:enqueue` は、`POST /v2/projects/{projectId}/files/translate` を使用してファイルを翻訳するための権限です。
* `project:translations:generate` は、実行時翻訳 のための権限です。
* `project:context:read` は、プロジェクトに割り当てられたコンテキストグループとその用語集・カスタムプロンプト、およびエクスポートの読み取りに使用します。
* `project:context:write` は、文脈 の生成のほか、プロジェクトに割り当てられたコンテキストグループの用語集・カスタムプロンプトの編集、グループへのコンテンツのインポート、グループの並べ替えに使用します。
* `org:context:read` は、組織内のすべてのコンテキストグループとその用語集・カスタムプロンプト、プロジェクトへの割り当て、エクスポートの読み取りに使用します。
* `org:context:write` は、コンテキストグループ とそのコンテンツの作成・更新・削除、コンテンツの インポート、およびプロジェクトに対するグループの割り当て・割り当て解除・並べ替えに使用します。
* `project:write` は、プロジェクト の設定更新に使用します。

Context Management エンドポイントのうち、グループのコンテンツを読み取り・編集するもの、およびプロジェクトのグループを一覧取得・読み取り・並べ替えするものは、組織の権限と、グループが割り当てられているプロジェクトに対するプロジェクト権限のどちらでも利用できます。一方、組織のグループの一覧取得、グループの作成・更新・削除、グループの割り当て・割り当て解除には組織の権限が必要です。リクエストの識別情報で操作できないグループを指定した場合は、存在しないグループと同じ `403` が返されます。

### バージョニング

使用する API コントラクトを指定するには、すべてのリクエストに `gt-api-version` ヘッダーを付与してください。

```bash
-H "gt-api-version: 2026-10-08.v1"
```

* リファレンスページでヘッダーが必須とされているエンドポイントは、ヘッダーがない場合や古いバージョンが指定された場合に `400` を返します。
* それ以外のエンドポイントは、ヘッダーがない場合はサポート対象の最も古いバージョンを使用し、エラーを JSON ではなくプレーンテキストで返します。

古いバージョンのエンドポイントを確認するには、各 OpenAPI ページ上部の API バージョンメニューで該当するバージョンを選択してください。

### リクエストボディ

`Content-Type: application/json` を指定して JSON を送信します。ボディを gzip で圧縮し、`Content-Encoding` を `gzip` または `x-gzip` に設定することもできます。サイズ制限は展開後のボディに適用されます。エンコード済みのボディの時点でルートの制限を超えている場合は、デコード前に拒否されます。

### 書き込み時のレスポンス

書き込みリクエストは、変更した内容を、同じリソースを読み取ったときと同じ形式で返します。

* `POST` でプロジェクト、ブランチ、コンテキストグループ、またはプロジェクトのAPIキーを**作成**すると、`201` とともに新しいリソースが返されます。新しいAPIキーにはシークレットの `key` も含まれますが、これ以降のレスポンスで返されることはありません。
* `PATCH` で単一のリソースを**更新**すると、`200` とともに更新後のリソースが返されます。
* **`PUT`** エンドポイント (タグの設定、コンテキストグループの割り当て、用語集の用語に対する訳語の設定) は、リクエストによってリソースが新規作成された場合は `201`、すでに存在していた場合は `200` とともにリソースを返します。
* **削除**すると、`200` とともに `{ "deleted": true }` が返されます。

<Callout type="info">
  **`2026-10-08.v1` での変更点：** Context Management の書き込みは、`committed: true` ではなく、リソース、`counts`、または `deleted` を返すようになりました。プロジェクトまたはプロジェクトのAPIキーを作成した場合、`project` や `apiKey` でラップされずにリソースがそのまま返されます。実行時翻訳は `requests` を配列で受け取り、リクエストをキーとするオブジェクトではなく、`summary` と `results` を返します。以前のバージョンのレスポンスは従来どおりです。確認するには、APIバージョンメニューで該当するバージョンを選択してください。
</Callout>

### バッチリクエスト

以下のバッチエンドポイントは、項目ごとに1つの結果をリクエストの順序どおりに返します。

* **書き込み** (原文ファイルと翻訳のアップロード、ファイルの移動・公開・上書き、フォントアセットのアップロード) は、すべての項目が失敗した場合でも `200` を返し、`summary` (`total`、`succeeded`、`failed` の件数) と `results` を含みます。失敗した項目には `status: "failed"` と `error` が設定されますが、それ以外の項目は通常どおり適用されます。検証に失敗したリクエストは `400` を返し、何も適用されません。
* **実行時翻訳** (`POST /v2/projects/{projectId}/translate`) は `requests` を配列で受け取り、`summary` と `results` を含む `200` を返します。翻訳できなかったエントリには `status: "failed"` と `error`、`code` が設定されますが、それ以外のエントリは通常どおり翻訳されます。同じコンテンツが重複していてもエントリごとに翻訳されるため、各文字列は1回だけ送信してください。
* **読み取り** (ファイル、ファイルコンテンツ、ジョブのクエリ) は、`results` を含む `200` を返します。プロジェクトに存在しない項目は `not_found` になります。ファイルの翻訳が保存済みでもまだ完了していない場合 (レイアウト処理中など) は `pending` になるため、時間をおいて再度リクエストしてください。翻訳ジョブが翻訳をまだ保存していない間は、その翻訳は `not_found` になります。読み取る前に、`GET /v2/projects/{projectId}/jobs/{jobId}` または `POST /v2/projects/{projectId}/jobs/query` でジョブの完了を待ってください。`versionId` を指定しない場合は、ブランチ上で最新の完了済みバージョンが返され、完了済みのバージョンが1つもない間に限り `pending` になります。ジョブのクエリは各ジョブのステータスを返します。

その他のバッチエンドポイントは、それぞれ独自のレスポンスを返します。ファイル翻訳をキューに登録すると、作成された `jobs` を含む `202` が返されます。Context Management の用語集とカスタムプロンプトのアップサートは、バッチ全体を一括で適用するか、何も適用しないかのいずれかで、`counts` (`created`、`updated`、`unchanged`) と `items` を返します。`items` には、項目ごとに1つの `id` と `outcome` がリクエストの順序どおりに含まれます。

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

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

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

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

### ロケール許可リスト

プロジェクトのロケールリストが空でなく、`targetLocale` がそのリストに含まれていない場合、実行時翻訳は `403` (コード `locale_not_allowed`) を返します。ロケールリストが空の場合、ターゲットロケールは制限されません。バッチ全体がキャッシュから返される場合はこのチェックがスキップされるため、プロジェクトから削除したロケールでも、キャッシュ済みの翻訳が返されることがあります。

### レート制限

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

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

認証後の上限はエンドポイントによって異なります。

* **Heavy:** ファイルの翻訳は 1 分あたり 30 リクエスト。
* **Medium:** 原文ファイル・翻訳・フォントのアップロード、翻訳の上書き、文脈の生成、ファイルの移動、ブランチ内ファイルの一覧取得、公開は 1 分あたり 120 リクエスト。
* **Light:** ファイルのダウンロードは 1 分あたり 300 リクエスト。
* **Default:** プロジェクトおよび 組織 の検出、プロジェクトの作成、プロジェクトAPIキー、プロジェクト設定、ブランチ、タグ、ジョブ、ファイルのメタデータとステータス、実行時翻訳、Context Management は 1 分あたり 200 リクエスト。

プロジェクトの一覧取得、プロジェクトの作成、およびプロジェクトAPIキーの一覧取得・読み取り・作成・削除は、同じ上限を共有します。

認証後の上限を超えると、`RateLimit-*` ヘッダー付きで `429` が返されます。

### ページネーション

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

### エラー

API バージョン `2026-02-18.v1` 以降では、エラー発生時に `error` メッセージと安定した `code` を含む JSON ボディが返されます。これは、不正な形式の JSON (`400`) 、サイズ上限を超えたボディ (`413`) 、レート制限 (`429`) の場合も同様です。それより前のバージョンでは、ほとんどのエラーが `code` を含まないプレーンテキストで返されます。

```json
{
  "error": "Missing required permission: project:files:write",
  "code": "permission_missing"
}
```

`code` はエラーの原因を示します。ルートによっては、ステータスに対応する汎用コードよりも具体的なコードを返す場合があります。各エンドポイントのリファレンスに、返される可能性のあるコードが記載されています。コードは今後追加される可能性があるため、認識できないコードは対応する HTTP ステータスと同様に扱ってください。

主なステータスコードと、対応する汎用 `code`：

* `400` `invalid_request`：リクエストのボディ、クエリ、またはバージョンが無効な場合。gzip ボディが破損しているか途中で切れている場合は `invalid_content_encoding` が返されます。
* `401` `unauthenticated`：bearer 認証情報がないか、無効な場合。
* `402` `payment_required`：組織の請求アカウントがブロックされている場合、またはプランの利用上限、月間支出上限、クレジット残高がリクエストに対して不足している場合 (ファイルの翻訳および実行時翻訳) 。
* `403` `permission_denied`：リクエスト元の ID に権限がない場合、または現在のプランでその操作が許可されていない場合。権限が不足している場合は `permission_missing` が返され、`error` に不足している権限名が示されます。
* `404` `not_found`：リソースが見つからない場合。
* `409` `conflict`：競合が発生した場合。例：組織のプロジェクト数上限を超えるプロジェクトの作成、使用中のブランチ名の指定、既存の用語集の用語やカスタムプロンプトと重複する名前への変更など。
* `410` `route_retired`：リクエストされた API バージョンでそのルートが廃止されている場合。`error` に代替ルートが示されます。
* `413` `payload_too_large`：リクエストボディがエンドポイントの上限を超える場合、または Context Management のレスポンスが 1 MiB を超える場合 (より小さい `limit` を指定してください) 。
* `415` `unsupported_media_type`：リクエストボディの `Content-Type` が指定されていないか、`application/json` ではない場合。サポートされていない `Content-Encoding` が指定された場合は `unsupported_content_encoding` が返されます。ボディは非圧縮のまま、または gzip でエンコードして送信してください。
* `423` `locked`：進行中の操作によってリソースがロックされている場合。
* `425` `not_ready`：リクエストされた結果がまだ準備できていない場合。
* `429` `rate_limited`：レート制限を超えた場合。
* `500` `internal_error`：サーバー内部エラーが発生した場合。
* `502` `upstream_error`：上流のサービスがリクエストを完了できなかった場合。
* `503` `unavailable`：サービスが一時的に利用できない場合。

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

## OpenAPI 仕様 [#openapi-spec]

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

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

## Sitemap

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