# General Translation Platform: 概要
URL: https://generaltranslation.com/ja/docs/platform/openapi/overview.mdx
---
title: 概要
description: 公開されている General Translation API のエンドポイントと OpenAPI 仕様の使い方を学びます。

related:
  title: リファレンス セクション
  links:
    - /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/project-info
---

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

SDK と CLI がほとんどの API 呼び出しを処理します。ファイルのアップロード、翻訳ジョブのキュー登録、翻訳のダウンロード、branch や tag の管理、Project やジョブのステータス確認を独自のシステムから行う必要がある場合は、API を直接呼び出してください。

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

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

### ベースURL

* プロジェクトおよびファイルのエンドポイントには `https://api2.gtx.dev` を使用します。
* `POST /v2/translate` を含む runtime translation には `https://runtime2.gtx.dev` を使用します。

### 認証

`x-gt-api-key` ヘッダーに APIキーを含めて送信します。

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

適切なキータイプを使用してください。

* **Project (development)**、プレフィックス `gtx-dev-`: ローカル環境およびプレビュー環境向けで、Production 専用エンドポイントでは拒否されます
* **Project (production)**、プレフィックス `gtx-api-`: 1 つの Project に紐づきます
* **Organization**、プレフィックス `gtx-org-`: 複数の Project をまたいで利用できます。Organization キーを Project スコープのエンドポイントで使用する場合は、`x-gt-project-id` を送信する必要があります。

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

### 権限

各エンドポイントでは、API キー に権限が付与されている必要があります。Organization keys では権限を明示的に設定します。Project keys では Project のデフォルト設定を使用します。

一般的な権限:

* `project:files:read` は、ファイルのダウンロード、ファイル情報、翻訳ステータス、branch 情報、orphaned ファイル、Project 情報、job 情報の読み取りに使用します。
* `project:files:write` は、ファイルと翻訳のアップロード、差分の取得、公開、branch と tag の作成、ファイルの移動に使用します。
* `project:translations:enqueue` は、翻訳のためにファイルをキューに追加するための権限です。
* `project:translations:generate` は、runtime translation のための権限です。
* `project:context:read` は、コンテキスト 生成のステータス確認に使用します。
* `project:context:write` は、コンテキスト の生成に使用します。
* `project:write` は、Project の設定更新に使用します。

### バージョニング

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

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

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

### レート制限

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

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

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

### エラー

エラー時には `error` メッセージが返されます。API バージョン `2026-02-18.v1` 以降では、レスポンスボディは JSON です。それより前のバージョンでは、`gt-api-version` header が送信されない場合に使われるデフォルトを含め、メッセージはプレーンテキストで返されます。

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

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

* リクエスト本文、クエリ、またはバージョンが無効な場合は `400`。
* API キーがない、または無効な場合は `401`。
* Organization のトークン上限を超えた場合は `402` (`POST /v2/translate`) 。
* API キーに権限がない、または現在のプランではその操作が許可されていない場合は `403`。
* リソースが見つからない場合は `404`。
* レート制限を超えた場合は `429`。

## OpenAPI 仕様 [#openapi-spec]

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

- /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/project-info