# 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/translate` によるruntime translationを含むすべてのエンドポイントは、`https://api.gtx.dev` をベース URL とします。

### 認証

すべてのエンドポイントでは、標準の `Authorization` ヘッダーで ベアラー credential を送信する必要があります。エンドポイントのリファレンスには、各操作が API キー、OAuth 2.1 のユーザーアクセストークン、またはその両方のいずれを受け付けるかが示されています。

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

適切な種類を使用してください。

* **プロジェクト (development)**、プレフィックス `gtx-dev-`: ローカル環境およびプレビュー環境向けで、Production 専用エンドポイントでは拒否されます
* **プロジェクト (production)**、プレフィックス `gtx-api-`: 1 つのプロジェクトに紐づきます
* **Organization**、プレフィックス `gtx-org-`: 複数のプロジェクトをまたいで利用できます。ほとんどのプロジェクトスコープのエンドポイントでは `gt-project-id` が必要です。`GET /v2/project/info/{projectId}` でもこのヘッダーは必須で、2 つの ID が一致するかどうかが検証されます。`POST /v2/projects/{projectId}/api-keys` では代わりに path パラメータが使用されます。`POST /v2/orgs/{orgId}/projects` などの Organization スコープのエンドポイントでは、path 内の Organization が使用され、credential がその Organization へのアクセス権を持っている必要があります。

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

OAuth アプリケーションは、Proof Key for Code Exchange (PKCE) を用いた Authorization Code フローを使用します。`https://dash.generaltranslation.com/.well-known/oauth-authorization-server/api/auth` で認可サーバーを検出し、アプリケーションに必要なスコープのみをリクエストして、得られたユーザーアクセストークンを同じ bearer ヘッダーで送信してください。このトークンは、付与されたスコープと、ターゲットの Organization またはプロジェクトに対するユーザーの現在のアクセス権の両方によって制限されます。

### 権限

各エンドポイントでは、リクエストの識別情報に権限が付与されている必要があります。Organization keys では権限を明示的に設定します。ダッシュボードで作成したプロジェクト keys は、その種類のデフォルト設定を使用します。Organization API を通じて作成した keys は、リクエストの識別情報が委譲できる権限に限定されるため、権限が少なくなる場合があります。OAuth ユーザーアクセストークン には対応する スコープ が含まれている必要があり、さらにサインイン中のユーザー自身がその権限を保持している必要があります。

一般的な権限:

* `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、孤立ファイル、プロジェクト info、job infoの読み取りに使用します。
* `project:files:write` は、ファイル・翻訳・asset のアップロード、差分の送信、公開、branch と tag の作成、ファイルの移動に使用します。
* `project:translations:enqueue` は、翻訳のためにファイルをキューに追加するための権限です。
* `project:translations:generate` は、runtime translation のための権限です。
* `project:context:write` は、コンテキスト の生成に使用します。
* `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 つ返します。チャンクが失敗した場合や最終的なドキュメントが不正な場合は、部分的な出力を返すのではなく、そのエントリが失敗となります。

### レート制限

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

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

上限を超えると `429` が返されます。Organization トークン の上限を超えると、`POST /v2/translate` から `402` が返されます。

### エラー

認証済みアプリケーションのエラー時には `error` メッセージが返されます。API バージョン `2026-02-18.v1` 以降では、レスポンスボディは JSON です。それより前のバージョンでは、`gt-api-version` ヘッダー が送信されない場合に使われるデフォルトを含め、メッセージはプレーンテキストで返されます。解析エラー、ペイロード上限超過、レート制限超過では、認証前にプレーンテキストが返されることがあります。

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

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

* リクエスト本文、クエリ、またはバージョンが無効な場合は `400`。
* ベアラー credential がない、または無効な場合は `401`。
* Organization のトークン上限を超えた場合は `402` (`POST /v2/translate`) 。
* リクエストの識別情報に権限がない、または現在のプランではその操作が許可されていない場合は `403`。
* リソースが見つからない場合は `404`。
* リクエスト本文がエンドポイントの上限を超えた場合は `413`。
* 要求された翻訳済みファイルがまだ処理中の場合は `425`。
* レート制限を超えた場合は `429`。
* 内部サーバーエラーの場合は `500`。
* サービスが一時的に利用できない場合は `503`。

## OpenAPI 仕様 [#openapi-spec]

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

JavaScript ツールには、インストール済みの SDK バージョンの生成に使用された OpenAPI スナップショットも同梱されています。同梱されたスナップショットは、現在ホストされている API 契約とは異なる場合があります。

* `gt` 2.20.0 以降で [`npx gt api --spec`](/docs/cli/reference/commands/api) を実行する。
* `generaltranslation` 9.2.0 以降から `generaltranslation/api/openapi.json` をインポートする。
* standalone で生成された SDK から `@generaltranslation/api/spec/openapi.json` をインポートする。

型付きのエンドポイント 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/translation/translate-runtime
- /docs/platform/openapi/reference/project/create-project

## Sitemap

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