# General Translation Platform: API クライアント
URL: https://generaltranslation.com/ja/docs/platform/core/reference/api-client.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: General Translation API 用の型付きクライアントを作成し、生成されたエンドポイントヘルパーを呼び出します。createApiClient の API リファレンス。

HTTP リクエストを自分で組み立てずに endpoint レベルで制御したい場合は、`generaltranslation/api` から TypeScript クライアントをインポートしてください。このモジュールは、認証・バージョニング・リトライに対応したトランスポートに、生成されたエンドポイントヘルパーと、batch 処理・翻訳 job のポーリング といった opt-in のユーティリティを組み合わせたものです。

`generaltranslation/api` は `generaltranslation` 9.2.0 以降で利用できます。以下の例は `generaltranslation` 9.4.0 および、それに相当する standalone の `@generaltranslation/api` 0.3.0 パッケージ を対象としています。

生成されるヘルパーは、インストールされているパッケージ に同梱された OpenAPI snapshot に従います。この snapshot は現在ホストされている[公開 OpenAPI コントラクト](/docs/platform/openapi/overview)と異なる場合があるため、どの endpoint やファイル形式が有効かを確認する際は公開リファレンスを参照してください。

## Overview [#overview]

| Export                                                                            | 説明                                            |
| --------------------------------------------------------------------------------- | --------------------------------------------- |
| [`createApiClient`](#create-client)                                               | バージョン管理、リトライ、timeout 処理に対応した認証済みクライアントを作成します。 |
| [`ApiClientConfig`](#client-config)                                               | クライアントのトランスポートと共通のリクエスト header を設定します。        |
| [`API_VERSION`](#api-version)                                                     | デフォルトで送信される現在の API コントラクトのバージョン。              |
| [エンドポイントヘルパー](#endpoint-helpers)                                              | 同梱の OpenAPI snapshot に含まれる各操作向けに生成される型付き関数。   |
| [`awaitJobs`](#job-polling) と [`pollJobs`](#job-polling)                          | translation job が完了するかタイムアウトするまで Poll します。    |
| [`processBatches`](#batch-processing) と [`DEFAULT_BATCH_SIZE`](#batch-processing) | input の array を任意のサイズの batch に分けて処理します。       |
| [生成された型](#types-errors)                                                           | エンドポイントのデータ、レスポンス、エラー、クライアントのコントラクトを定義します。    |
| [同梱の OpenAPI 仕様](#openapi-spec)                                                   | インストールされるパッケージ の生成に使用される JSON snapshot。    |

## `createApiClient` [#create-client]

```ts
function createApiClient(config: ApiClientConfig): Client;
```

クライアントは、設定された API バージョン、ベアラートークン、プロジェクト ID をすべてのリクエストに付与します。これを生成された endpoint helper に渡します:

```ts title="project-info.ts"
import { createApiClient, getProjectInfo } from 'generaltranslation/api';

const projectId = process.env.GT_PROJECT_ID!;
const client = createApiClient({
  apiKey: process.env.GT_API_KEY,
  baseUrl: 'https://api.gtx.dev',
  projectId,
});

const result = await getProjectInfo({
  client,
  path: { projectId },
});

if (result.error) {
  throw new Error('Could not load Project information');
}

console.log(result.data);
```

以下の例では、この設定済みの `client` を再利用します。

## `ApiClientConfig` [#client-config]

| Option                        | 説明                                                       | Type                                  | 任意  | Default            |
| ----------------------------- | -------------------------------------------------------- | ------------------------------------- | --- | ------------------ |
| [`apiKey`](#apikey)           | `Authorization` ヘッダーで送信される API キーまたは OAuth ユーザーアクセストークン。 | `string`                              | はい  | —                  |
| [`apiVersion`](#apiversion)   | `gt-api-version` として送信されるコントラクトバージョン。                    | `ApiVersion`                          | はい  | `API_VERSION`      |
| [`baseUrl`](#baseurl)         | API のオリジン。                                               | `string`                              | いいえ | —                  |
| [`fetch`](#fetch)             | カスタムの Fetch API 実装。                                      | `typeof fetch`                        | はい  | `globalThis.fetch` |
| [`projectId`](#projectid)     | `gt-project-id` として送信されるプロジェクト ID。                       | `string`                              | はい  | —                  |
| [`retryPolicy`](#retrypolicy) | 再試行の待機戦略。                                                | `'exponential' \| 'linear' \| 'none'` | はい  | `'exponential'`    |
| [`timeoutMs`](#timeoutms)     | 試行ごとの timeout。組み込みの timeout を無効にする場合は `false`。           | `number \| false`                     | はい  | `60000`            |

### `apiKey`

**Type** `string` · **任意**

`Authorization: Bearer <credential>` として送信される API キーまたは OAuth 2.1 ユーザーアクセストークン。クライアントが環境変数を自動的に読み取ることはありません。

### `apiVersion`

**Type** `ApiVersion` · **任意** · **Default** `API_VERSION`

`gt-api-version` ヘッダーで送信される API コントラクトのバージョン。

### `baseUrl`

**Type** `string` · **Required**

API のオリジン。ホスト版の General Translation API を使用する場合は `https://api.gtx.dev` を指定します。

### `fetch`

**Type** `typeof fetch` · **任意** · **Default** `globalThis.fetch`

カスタムの Fetch API 実装。計測やテスト、またはグローバルな fetch 実装を持たないランタイムで使用します。

### `projectId`

**Type** `string` · **任意**

`gt-project-id` header で送信するプロジェクト ID です。Organization keys や OAuth ユーザーアクセストークン を使用する場合、path にプロジェクト ID を含まないプロジェクトスコープの endpoint ではこの header が必要です。

### `retryPolicy`

**Type** `'exponential' | 'linear' | 'none'` · **任意** · **Default** `'exponential'`

冪等なリクエストは、ネットワークエラー、`429` レスポンス、`5xx` レスポンスに対して最大 3 回まで再試行します。冪等でないリクエストは `429` レスポンスのみ再試行し、ネットワークエラーや `5xx` レスポンスは再試行しません。再試行を呼び出し側で制御する場合は `'none'` を指定してください。

### `timeoutMs`

**Type** `number | false` · **任意** · **Default** `60000`

リクエスト試行ごとのタイムアウト (ミリ秒) 。カスタムの `fetch` 実装側でリクエストのタイムアウトを管理する場合は `false` を指定します。

## `API_VERSION` [#api-version]

**Type** `ApiVersion`

現在のデフォルトのコントラクトバージョンは `2026-03-06.v1` です。古いレスポンスコントラクトに合わせてインテグレーションを維持する場合は、`apiVersion` にサポート対象の別バージョンを渡してください。

## エンドポイントヘルパー [#endpoint-helpers]

生成された helpers は、共通の `client` に加えて、該当する endpoint の `body`、`headers`、`path`、`query` の各フィールドを持つ 1 つのオブジェクトを受け取ります。デフォルトでは `{ data, error, request, response }` を返します。

```ts title="project-info.ts"
import { getProjectInfo } from 'generaltranslation/api';

const result = await getProjectInfo({
  client,
  path: { projectId: 'your-project-id' },
  throwOnError: true,
});

console.log(result.data.name);
```

生成される主なオプションは次のとおりです。

| Option          | 説明                                   | 型                         | 任意    | Default    |
| --------------- | ------------------------------------ | ------------------------- | ----- | ---------- |
| `client`        | `createApiClient` が返すクライアント。         | `Client`                  | いいえ   | —          |
| `body`          | 型付きの JSON リクエストボディ。                  | endpoint 固有               | 場合による | —          |
| `path`          | 型付きのパスパラメータ。                         | endpoint 固有               | 場合による | —          |
| `query`         | 型付きのクエリパラメータ。                        | endpoint 固有               | 場合による | —          |
| `headers`       | 共有クライアントヘッダーを上書きする、呼び出しごとのヘッダー。      | endpoint 固有               | はい    | —          |
| `throwOnError`  | 失敗したレスポンスに対して `error` を返さず throw する。 | `boolean`                 | はい    | `false`    |
| `responseStyle` | すべてのレスポンスフィールドを返すか、解析済みデータのみを返すか。    | `'fields' \| 'data'`      | はい    | `'fields'` |
| `signal`        | Fetch API のシグナルでリクエストをキャンセルする。       | `AbortSignal`             | はい    | —          |
| `meta`          | カスタムクライアントインテグレーションに公開される値。          | `Record<string, unknown>` | はい    | —          |

インストール済みの 0.3.0 SDK は、以下の公開操作向けの生成済みヘルパーを提供します。

| Function                                                                           | 操作                                             |
| ---------------------------------------------------------------------------------- | ---------------------------------------------- |
| [`createProject`](/docs/platform/openapi/reference/project/create-project)         | 選択した Organization にプロジェクトを作成します。               |
| [`createProjectApiKey`](/docs/platform/openapi/reference/project/create-api-key)   | 呼び出し元が委譲した permissions を持つプロジェクト API キーを作成します。 |
| [`uploadSourceFiles`](/docs/platform/openapi/reference/files/upload-source)        | ソースファイルをアップロードします。                             |
| [`uploadTranslations`](/docs/platform/openapi/reference/files/upload-translations) | 既存のソースファイルに紐づく翻訳済みファイルをアップロードします。              |
| `uploadAssets`                                                                     | プロジェクトの asset をアップロードします。                      |
| `submitUserEditDiffs`                                                              | ローカルの翻訳編集内容を送信します。                             |
| `generateProjectContext`                                                           | プロジェクトの context を生成します。                        |
| `enqueueFileTranslations`                                                          | アップロード済みファイルを翻訳キューに追加します。                      |
| `publishFiles`                                                                     | ファイルを公開または公開解除します。                             |
| [`downloadFile`](/docs/platform/openapi/reference/files/download)                  | ファイルを 1 件ダウンロードします。                            |
| `downloadFiles`                                                                    | 複数のファイルをダウンロードします。                             |
| `getBranchInfo`                                                                    | branch 情報を取得します。                               |
| `createBranch`                                                                     | branch を作成します。                                 |
| [`createTag`](/docs/platform/openapi/reference/project/upsert-tag)                 | tag を作成または更新します。                               |
| `getProjectInfo`                                                                   | プロジェクト情報を取得します。                                |
| `updateProjectInfo`                                                                | プロジェクト情報を更新します。                                |
| `getTranslationJobInfo`                                                            | 翻訳 job のステータスを取得します。                           |
| [`translate`](/docs/platform/openapi/reference/translation/translate-runtime)      | 実行時にコンテンツを翻訳します。                               |
| `getFileInfo`                                                                      | ファイルのメタデータを取得します。                              |
| `getTranslationStatus`                                                             | ファイルの翻訳ステータスを取得します。                            |
| `processFileMoves`                                                                 | ファイルを移動または名前変更します。                             |
| `getOrphanedFiles`                                                                 | 孤立ファイルを検索します。                                  |

<Callout type="info">
  **v0.3.0 での変更点:** `encodeBase64`、`decodeBase64`、`encodeFileContent`、`decodeFileContent` はエクスポートされなくなりました。生成されたアップロードヘルパーに渡す前に、ファイル内容をエンコードしてください。

  **v0.2.1 での変更点:** [`createProject`](/docs/platform/openapi/reference/project/create-project) は `path.orgId` を必須とするようになり、`POST /v2/orgs/{orgId}/projects` を呼び出します。このリリースでは [`createProjectApiKey`](/docs/platform/openapi/reference/project/create-api-key) が追加され、`shouldGenerateProjectContext` と `getProjectContextGenerationStatus` が削除されました。
</Callout>

context の job には `generateProjectContext` と `getTranslationJobInfo` を使用してください。[`downloadFile`](/docs/platform/openapi/reference/files/download) ヘルパーは引き続き非推奨です。バッチダウンロードにも単一ファイルのダウンロードにも `downloadFiles` を使用してください。

最新の endpoint の permissions、レート制限、schema、ステータスコードについては、[公開 OpenAPI リファレンス](/docs/platform/openapi/overview) を参照してください。

## Job polling [#job-polling]

[`awaitJobs`](#job-polling) は、設定済みのクライアントを使って `getTranslationJobInfo` を呼び出し、リクエストしたすべての job が完了・失敗・不明・欠落のいずれかの状態になるまで、または全体の timeout に達するまで polling を繰り返します。

```ts
function awaitJobs(
  client: Client,
  jobIds: readonly string[],
  options?: AwaitJobsOptions
): Promise<AwaitJobsResult>;
```

| Option                   | 説明               | Type     | Optional | Default |
| ------------------------ | ---------------- | -------- | -------- | ------- |
| `pollingIntervalSeconds` | ステータス確認リクエストの間隔。 | `number` | はい       | `5`     |
| `timeoutSeconds`         | ポーリング全体の制限時間。    | `number` | はい       | `600`   |

```ts
import {
  awaitJobs,
  enqueueFileTranslations,
} from 'generaltranslation/api';

const result = await enqueueFileTranslations({
  client,
  body: {
    files: [{ fileId: 'homepage', versionId: 'version-1' }],
    sourceLocale: 'en',
    targetLocales: ['es'],
  },
  throwOnError: true,
});

if (!('jobData' in result.data)) {
  throw new Error('Expected the current enqueue response');
}

const jobs = await awaitJobs(client, Object.keys(result.data.jobData));

if (!jobs.complete) {
  console.warn('Translation jobs did not finish before the timeout');
}
```

`AwaitJobsResult` には `complete` と `jobs` が含まれます。`complete` はポーリングがタイムアウトした場合にのみ `false` になり、`jobs` にはリクエストされたすべての ID に対する最新の結果が含まれます。存在しない job には `unknown` ステータスが設定されます。空の配列を渡した場合は、`{ complete: true, jobs: [] }` を返して即座に解決します。

全体の期限に達する前に API またはステータスローダーでエラーが発生した場合、ポーリングの Promise は reject されます。期限が経過した後にリクエストが失敗した場合、ポーリングは `complete: false` とともに最新の結果を返します。

`pollJobs` は、ステータスローダーを注入する形で同じポーリングループを公開します:

```ts
function pollJobs(
  jobIds: readonly string[],
  getJobStatuses: GetJobStatuses,
  options?: AwaitJobsOptions
): Promise<AwaitJobsResult>;

type GetJobStatuses = (
  jobIds: string[],
  signal: AbortSignal
) => Promise<GetTranslationJobInfoResponse>;
```

リクエストやエラーの正規化をカスタマイズしたい場合に使用します。loader が受け取る中断シグナルには、全体の残り時間と 1 回のポーリングあたり 60 秒という上限が適用されます。

## バッチ処理 [#batch-processing]

`processBatches` は入力配列をチャンクに分割し、チャンクごとにプロセッサを呼び出し、返された配列をバッチ順にフラット化します。

```ts
function processBatches<TInput, TOutput>(
  items: readonly TInput[],
  processBatch: (batch: TInput[]) => Promise<TOutput[]>,
  options?: BatchOptions
): Promise<TOutput[]>;
```

| Option      | 説明                               | 型      | 任意 | Default              |
| ----------- | -------------------------------- | --------- | -- | -------------------- |
| `batchSize` | 各バッチに含める入力値の数。0 より大きい値を指定してください。 | `number`  | はい | `DEFAULT_BATCH_SIZE` |
| `parallel`  | すべてのバッチを逐次ではなく並行して処理します。         | `boolean` | はい | `true`               |

`DEFAULT_BATCH_SIZE` は `100` です。

バッチプロセッサーが reject した場合、`processBatches` も reject します。並行処理の場合、すでに開始済みの他のバッチは独立して処理が続行されます。

```ts
import { Buffer } from 'node:buffer';
import {
  processBatches,
  uploadSourceFiles,
} from 'generaltranslation/api';

// 生成されたエンドポイントヘルパーは、転送用にエンコードされたファイル内容を受け取ります。
const content = Buffer.from('{"greeting":"Hello"}', 'utf8').toString('base64');
const files = [{
  source: {
    content,
    fileName: 'en.json',
    fileFormat: 'JSON' as const,
    locale: 'en',
  },
}];

const results = await processBatches(files, async (batch) => {
  const result = await uploadSourceFiles({
    client,
    body: { data: batch },
    throwOnError: true,
  });
  return result.data.uploadedFiles;
});
```

## 型とエラー [#types-errors]

このモジュールは `Client`、`Options`、`ApiClientConfig`、`ApiVersion`、`RetryPolicy`、`AwaitJobsOptions`、`AwaitJobsResult`、`GetJobStatuses`、`JobResult`、`BatchOptions`、`RuntimeFileFormat`、および上記の公開オペレーション向けに生成された OpenAPI 型をエクスポートします。

上記の各公開オペレーションについて、パッケージは次の型をエクスポートします:

* `<Operation>Data`: 型付けされた body、headers、path、query の input。
* `<Operation>Errors`: ドキュメント化されたエラーのステータスコードマップ。
* `<Operation>Error`: ドキュメント化されたエラーの union。
* `<Operation>Responses`: ドキュメント化された成功レスポンスのステータスコードマップ。
* `<Operation>Response`: ドキュメント化された成功レスポンスの union。

デフォルトの `throwOnError: false` では、生成されたオペレーションは `data` または `error` のいずれかと、Fetch API の `request` を返します。HTTP レスポンスを受け取った場合は `response` が含まれ、レスポンスを受け取る前に失敗した場合は undefined のままになります。`throwOnError: true` の場合、API、ネットワーク、キャンセル、timeout の失敗は throw されます。

## OpenAPI 仕様 [#openapi-spec]

インストール済みクライアントの生成に使用された snapshot をインポートします。

```ts
import openApiSpec from 'generaltranslation/api/openapi.json' with {
  type: 'json',
};
```

スタンドアロンの `@generaltranslation/api` パッケージは同じ SDK を提供し、その snapshot を `@generaltranslation/api/spec/openapi.json` で公開しています。[`gt api --spec`](/docs/cli/reference/commands/api) コマンドは、その CLI にインストールされている Core 依存関係に同梱された snapshot を出力します。現在ホストされている仕様については、[`/openapi.json`](/openapi.json) を参照してください。

## Sitemap

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