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

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

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) は、返される Organization またはプロジェクトへのアクセス権があれば、それ以外のリソース権限は必要ありません。Organization キー とプロジェクトキー はいずれも、Dashboard で **All** または **カスタムプロンプト** の権限設定に対応しており、作成者が付与できる権限に限定されます。[プロジェクトの API キーエンドポイント](/docs/platform/openapi/reference/projects/create-project-api-key) では、権限を個別に選択することも、選択を省略して自分が委譲できるすべてのプロジェクト権限を付与することもできます。Write 権限には Read 権限は含まれません。プロジェクトキーは Organization の権限 (`org:*`) や `project:api_keys:write` を保持できないため、これらを必要とするエンドポイントには Organization キーが必要です。

一般的な権限:

* `org:projects:create` は、`POST /v2/orgs/{orgId}/projects` を使用してプロジェクトを作成するための権限です。
* `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:write` は、文脈 の生成に使用します。
* `org:context:read` は、文脈 Group とその用語集・カスタムプロンプト、プロジェクトへの割り当て、エクスポートの読み取りに使用します。
* `org:context:write` は、文脈 Group とそのコンテンツの作成・更新・削除、コンテンツの import、およびプロジェクトに対するグループの割り当て・割り当て解除・並べ替えに使用します。
* `project:write` は、プロジェクト の設定更新に使用します。

### バージョニング

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

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

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

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

### バッチリクエスト

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

* **書き込み** (原文ファイルと翻訳のアップロード、ファイルの移動・公開・上書き、フォントアセットのアップロード) は、すべての項目が失敗した場合でも `200` を返し、`summary` (`total`、`succeeded`、`failed` の件数) と `results` を含みます。失敗した項目には `status: "failed"` と `error` が設定されますが、それ以外の項目は通常どおり適用されます。検証に失敗したリクエストは `400` を返し、何も適用されません。
* **読み取り** (ファイル、ファイルコンテンツ、ジョブのクエリ) は、`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` を含む `committed` を返します。

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

`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 つ返します。チャンクが失敗した場合や最終的なドキュメントが不正な場合は、部分的な出力を返すのではなく、そのエントリが失敗となります。

### レート制限

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

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

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

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

プロジェクトの一覧取得、プロジェクトの作成、プロジェクトAPIキーの作成は、同じ上限を共有します。

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

### ページネーション

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

### エラー

`gt-api-version` を設定している場合、エラー時には `error` メッセージを含む JSON ボディが返されます。これは、不正な形式の JSON (`400`)、サイズ超過のボディ (`413`)、レート制限 (`429`) を含む、すべてのエラーに適用されます。

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

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

* リクエストボディ、クエリ、またはバージョンが無効な場合は `400`。
* ベアラー 認証情報 がない、または無効な場合は `401`。
* Organization の請求アカウントがブロックされている場合、または利用上限やクレジット残高ではリクエストを賄えない場合は `402` (ファイルの翻訳および実行時翻訳) 。
* リクエストの識別情報に権限がない、または現在のプランではその操作が許可されていない場合は `403`。
* リソースが見つからない場合は `404`。
* 競合が発生した場合は `409`。たとえば、プロジェクトの作成によって Organization のプロジェクト数の上限を超える場合、分岐名がすでに使用されている場合、変更後の名前が既存の用語集の用語または カスタムプロンプト と重複する場合などです。
* リクエストボディがエンドポイントの上限を超えた場合、または Context Management のレスポンスが 1 MiB を超える場合は `413` (より小さい `limit` を指定して再度リクエストしてください) 。
* リクエストボディの `Content-Type` が指定されていない、または `application/json` ではない場合は `415`。
* レート制限を超えた場合は `429`。
* 内部サーバーエラーの場合は `500`。
* サービスが一時的に利用できない場合は `503`。

`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.