# 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 クライアントをインポートしてください。このモジュールは、認証・バージョニング・再試行に対応したトランスポートに、生成されたエンドポイントヘルパーと、バッチ 処理・翻訳 job のポーリング といった opt-in のユーティリティを組み合わせたものです。 `generaltranslation/api` は `generaltranslation` 9.2.0 以降で利用できます。以下の例は `generaltranslation` 9.5.4 および、それに相当する standalone の `@generaltranslation/api` 0.5.2 パッケージ を対象としています。 生成されるヘルパーはインストールされているパッケージのバージョンに準拠しており、現在ホストされている[公開 OpenAPI コントラクト](/docs/platform/openapi/overview)とは異なる場合があります。どの endpoint やファイル形式が有効かを確認する際は、公開リファレンスを参照してください。 ## Overview [#overview] | Export | 説明 | | --------------------------------------------------------------------------------- | --------------------------------------------- | | [`createApiClient`](#create-client) | バージョン管理、リトライ、timeout 処理に対応した認証済みクライアントを作成します。 | | [`ApiClientConfig`](#client-config) | クライアントのトランスポートと共通のリクエスト header を設定します。 | | [`API_VERSION`](#api-version) | デフォルトで送信される現在の API コントラクトのバージョン。 | | [エンドポイントヘルパー](#endpoint-helpers) | 以下に示す各公開操作用の型付き関数。 | | [`paginate`](#pagination) | list 操作の全項目を順に反復処理します。 | | [`awaitJobs`](#job-polling) と [`pollJobs`](#job-polling) | translation job が完了するかタイムアウトするまで Poll します。 | | [`processBatches`](#batch-processing) と [`DEFAULT_BATCH_SIZE`](#batch-processing) | input の array を任意のサイズの batch に分けて処理します。 | | [`ApiError`](#api-error) | HTTP レスポンスが失敗した際に throw されるエラー。 | | [生成された型](#types-errors) | エンドポイントのデータ、レスポンス、エラー、クライアントのコントラクトを定義します。 | | [公開 OpenAPI 仕様](#openapi-spec) | 現在ホストされている API コントラクト。 | ## `createApiClient` [#create-client] ```ts function createApiClient(config: ApiClientConfig): Client; ``` クライアントは、設定された API バージョン、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 キー。 | `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 ` として送信される API キー。クライアントが環境変数を自動的に読み取ることはありません。 ### `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 を使用する場合、path にプロジェクト ID を含まないプロジェクトスコープの endpoint ではこの header が必要です。 ### `retryPolicy` **型** `'exponential' | 'linear' | 'none'` · **任意** · **デフォルト** `'exponential'` GET、HEAD、OPTIONS、PUT、DELETE は、ネットワークエラーおよび `5xx` レスポンスに対して、初回の試行後に最大 3 回まで再試行します。POST は、論理的には読み取り専用の操作であっても、これらの失敗を再試行しません。`429` レスポンスは、すべてのメソッドで再試行の対象になります。トランスポートレベルの再試行を無効にするには、`'none'` を設定します。 `429` の場合、待機時間は `Retry-After` (秒数または HTTP 日付) 、`RateLimit-Reset` (秒数) の順に参照して決まり、どちらもなければ 60 秒のフォールバック値が使われます。それ以外の場合、exponential の待機時間は 500、1000、2000 ms、linear の待機時間は 500、1000、1500 ms です。再試行時のスリープは中断 (abort) に対応していないため、キャンセルしても待機がすぐに中断されるとは限りません。 クラスベースのランタイム翻訳では、`429` を含め、これらのトランスポートレベルの再試行は無効になります。生成されるランタイム翻訳ヘルパーは、代わりに渡されたクライアントの再試行ポリシーに従います。 ### `timeoutMs` **Type** `number | false` · **任意** · **Default** `60000` リクエスト試行ごとのタイムアウト (ミリ秒) 。省略した場合は 60000 が使用され、`0` はそのままゼロとして扱われます。`false` を指定すると組み込みのタイマーが無効になりますが、呼び出し元やカスタム fetch によるキャンセルは引き続き有効です。この値は、リトライやレスポンス処理を含む操作全体の期限ではありません。fetch の実装は、渡された signal に従う必要があります。 これらの設定は [`GT`](/docs/platform/core/reference/gt-class/constructor) コンストラクタのオプションではありません ([翻訳設定](/docs/platform/core/reference/types/translation-config)を参照してください) 。 ## `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 | 説明 | 型 | 任意 | デフォルト | | --------------- | ------------------------------------ | ------------------------- | ----- | ---------- | | `client` | `createApiClient` が返すクライアント。 | `Client` | いいえ | — | | `body` | 型付きの JSON リクエスト body。 | endpoint 固有 | 場合による | — | | `path` | 型付きのパスパラメータ。 | endpoint 固有 | 場合による | — | | `query` | 型付きのクエリパラメータ。 | endpoint 固有 | 場合による | — | | `headers` | 共有クライアントヘッダーを上書きする、呼び出しごとのヘッダー。 | endpoint 固有 | はい | — | | `throwOnError` | 失敗したレスポンスに対して `error` を返さず throw する。 | `boolean` | はい | `false` | | `responseStyle` | すべてのレスポンスフィールドを返すか、解析済みデータのみを返すか。 | `'fields' \| 'data'` | はい | `'fields'` | | `signal` | Fetch API のシグナルでリクエストをキャンセルする。 | `AbortSignal` | はい | — | | `meta` | カスタムクライアントインテグレーションに公開される値。 | `Record` | はい | — | インストール済みの 0.5.2 SDK は、以下の 48 個の公開操作向けの生成済みヘルパーを提供します。 | Function | 操作 | | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | | [`listProjects`](/docs/platform/openapi/reference/project/list-projects) | API キーのバインディングで選択されたプロジェクトを 1 ページ分一覧表示します。 | | [`listOrgs`](/docs/platform/openapi/reference/project/list-orgs) | Organization またはプロジェクト API キーに関連付けられた Organization を一覧表示します。 | | [`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` | 孤立ファイルを検索します。 | | [`listContextGroups`](/docs/platform/openapi/reference/context-management/list-groups) | Organization 内の Context Group を一覧表示します。 | | [`createContextGroup`](/docs/platform/openapi/reference/context-management/create-group) | Context Group を作成します。 | | [`getContextGroup`](/docs/platform/openapi/reference/context-management/get-group) | Context Group を取得します。 | | [`updateContextGroup`](/docs/platform/openapi/reference/context-management/update-group) | Context Group を更新します。 | | [`deleteContextGroup`](/docs/platform/openapi/reference/context-management/delete-group) | Context Group を削除します。 | | [`listProjectContextGroups`](/docs/platform/openapi/reference/context-management/list-project-groups) | プロジェクトに割り当てられた Context Group を一覧表示します。 | | [`getProjectContextGroup`](/docs/platform/openapi/reference/context-management/get-project-group) | 割り当てられた Context Group を 1 件取得します。 | | [`assignContextGroup`](/docs/platform/openapi/reference/context-management/assign-group) | Context Group をプロジェクトに割り当てます。 | | [`unassignContextGroup`](/docs/platform/openapi/reference/context-management/unassign-group) | プロジェクトから Context Group の割り当てを解除します。 | | [`reorderContextGroup`](/docs/platform/openapi/reference/context-management/reorder-group) | 割り当てられた Context Group の優先度を変更します。 | | [`listContextGlossary`](/docs/platform/openapi/reference/context-management/list-glossary) | Context Group 内の用語集の用語を一覧表示します。 | | [`upsertContextGlossary`](/docs/platform/openapi/reference/context-management/upsert-glossary) | 用語集の用語を作成または更新します。 | | [`getContextGlossaryEntry`](/docs/platform/openapi/reference/context-management/get-glossary-entry) | 用語集の用語を 1 件取得します。 | | [`updateContextGlossaryEntry`](/docs/platform/openapi/reference/context-management/update-glossary-entry) | 用語集の用語を 1 件更新します。 | | [`deleteContextGlossaryEntry`](/docs/platform/openapi/reference/context-management/delete-glossary-entry) | 用語集の用語を 1 件削除します。 | | [`listContextGlossaryTranslations`](/docs/platform/openapi/reference/context-management/list-glossary-translations) | 用語集の用語の翻訳を一覧表示します。 | | [`setContextGlossaryTranslation`](/docs/platform/openapi/reference/context-management/set-glossary-translation) | 用語集の用語の翻訳を設定します。 | | [`deleteContextGlossaryTranslation`](/docs/platform/openapi/reference/context-management/delete-glossary-translation) | 用語集の用語の翻訳を削除します。 | | [`listContextCustomPrompts`](/docs/platform/openapi/reference/context-management/list-custom-prompts) | Context Group 内のカスタムプロンプトを一覧表示します。 | | [`upsertContextCustomPrompts`](/docs/platform/openapi/reference/context-management/upsert-custom-prompts) | カスタムプロンプトを作成または更新します。 | | [`updateContextCustomPrompt`](/docs/platform/openapi/reference/context-management/update-custom-prompt) | カスタムプロンプトを 1 件更新します。 | | [`deleteContextCustomPrompt`](/docs/platform/openapi/reference/context-management/delete-custom-prompt) | カスタムプロンプトを 1 件削除します。 | | [`importContextContent`](/docs/platform/openapi/reference/context-management/import-content) | 用語集の用語とカスタムプロンプトをインポートします。 | | [`exportContextContent`](/docs/platform/openapi/reference/context-management/export-content) | 用語集の用語とカスタムプロンプトをエクスポートします。 | **v0.5.2 での変更点:** 生成されたクライアントに、Context Group、割り当て、用語集の用語、カスタムプロンプト、インポートとエクスポートを扱う Context Management ヘルパーが追加されました。 **v0.5.0 での変更点:** 一覧系のレスポンスは、現行の API に合わせて `projects` や `orgs` ではなく `items` を返すようになりました。`throwOnError` を指定した呼び出しが失敗した場合は、デコードされたレスポンス body ではなく [`ApiError`](#api-error) が throw されます。 **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` が削除されました。 コンテキストの job には、`generateProjectContext` と `getTranslationJobInfo` を組み合わせて使用してください。[`downloadFile`](/docs/platform/openapi/reference/files/download) ヘルパーは引き続き非推奨です。複数ファイルでも単一ファイルでも、ダウンロードには `downloadFiles` を使用してください。 endpoint ごとの最新の permissions、レート制限、schema、ステータスコードについては、[公開 OpenAPI リファレンス](/docs/platform/openapi/overview)を参照してください。 ### 検出とプロビジョニング [`listOrgs`](/docs/platform/openapi/reference/project/list-orgs) を使用すると、API キーに関連付けられた Organization を取得できます。Organization キーとプロジェクトキーのどちらでも使用でき、この参照にプロジェクト作成の権限は不要です。 プロジェクトの検出では、API キーのバインディングに応じて選択されたプロジェクトが 1 ページ分返されます。プロジェクトキーの場合はそのキーのプロジェクトが、Organization キーの場合はその Organization 内のプロジェクトが返されます。リソースに対する権限は不要です。すべてのプロジェクトを反復処理するには、[`paginate`](#pagination) を使用します： ```ts title="list-projects.ts" import { listProjects, paginate } from 'generaltranslation/api'; for await (const project of paginate(listProjects, { client, query: { limit: 100 }, })) { console.log(project.id, project.name); } ``` プロジェクトの作成には、`org:projects:create` 権限を持つ Organization キー が必要です。引数には `path: { orgId }` と `body: { name, defaultLocale, cdnEnabled? }` を指定します。 [`createProjectApiKey`](/docs/platform/openapi/reference/project/create-api-key) では、最小権限の原則に従い、`permissions` を明示的に指定してください。省略すると、呼び出し元が保持している委任可能なプロジェクト権限がすべてリクエストされます。また、指定する権限はすべて呼び出し元自身が保持している必要があります。返されたシークレットは安全に保管し、ログには絶対に出力しないでください。 これらの自動生成された検出用・作成用ヘルパーは、[`GT`](/docs/platform/core/reference/gt-class/constructor) のメソッドではありません。 ## `paginate` [#pagination] ```ts function paginate< Options extends { client?: Client; query?: { cursor?: string; limit?: number }; }, Item, >( list: (options: Options & { throwOnError: true }) => Promise<{ data: { items: Item[]; nextCursor: string | null }; }>, options: Options ): AsyncGenerator; ``` `paginate` は、[`listProjects`](/docs/platform/openapi/reference/project/list-projects) や [`listOrgs`](/docs/platform/openapi/reference/project/list-orgs) などの一覧取得操作の全項目を順に返し、各ページのリクエストに `options` を渡します。次のページは反復処理がそのページに到達した時点で初めてリクエストされるため、ループを抜ければ以降のリクエストは発生しません。途中から再開するには、保存しておいた `nextCursor` を `query.cursor` として渡します。ページの取得に失敗した場合は、`throwOnError` を指定した呼び出しと同様に例外がスローされます。 各ページは個別に読み込まれるため、反復処理中に変更された項目は、取りこぼされたり重複して返されたりする可能性があります。 ## Job polling [#job-polling] [`awaitJobs`](#job-polling) は、設定済みのクライアントを使って `getTranslationJobInfo` を呼び出し、リクエストしたすべての job が完了・失敗・不明・欠落のいずれかの状態になるまで、または全体の timeout に達するまで polling を繰り返します。 ```ts function awaitJobs( client: Client, jobIds: readonly string[], options?: AwaitJobsOptions ): Promise; ``` | Option | 説明 | Type | Optional | Default | | ------------------------ | ------------------------------------------ | --------------------------------------------------- | -------- | ------- | | `pollingIntervalSeconds` | ステータス確認リクエストの間隔。 | `number` | はい | `5` | | `timeoutSeconds` | ポーリング全体の制限時間。 | `number` | はい | `600` | | `onPoll` | 終了状態を記録する前に、成功したステータスレスポンスを未加工のまま毎回受け取ります。 | `(statuses: GetTranslationJobInfoResponse) => void` | はい | — | ```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; type GetJobStatuses = ( jobIds: string[], signal: AbortSignal ) => Promise; ``` リクエストやエラーの正規化をカスタマイズしたい場合に使用します。ポーリングは逐次実行され、保留中の ID のみをリクエストします。loader が受け取る中断シグナルには、全体の残り時間と 1 回のポーリングあたり 60 秒という上限が適用されます。遅れて届いた結果は破棄されます。timeout 時には最後に受け付けたステータスが返されるため、キュー待ち、処理中、または初期状態の不明のままの場合があります。シグナルを無視する loader は、解決を遅らせる可能性があります。 `complete: true` は保留中の job がないことを示すだけで、すべての job が成功したことを意味するわけではありません。結果を使用する前に、各ステータスを確認してください。どちらの API ポーリングヘルパーも `onPoll` を受け付けますが、クラスの [`awaitJobs`](/docs/platform/core/reference/gt-class-methods/translation/await-jobs) のオプションは受け付けません。呼び出し元のシグナルを渡せるポーリングオプションはなく、ローカルでポーリングを停止してもリモートの job はキャンセルされません。 ## バッチ処理 [#batch-processing] `processBatches` は入力配列をチャンクに分割し、チャンクごとにプロセッサを呼び出し、返された配列をバッチ順にフラット化します。 ```ts function processBatches( items: readonly TInput[], processBatch: (batch: TInput[]) => Promise, options?: BatchOptions ): Promise; ``` | 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 型をエクスポートします。 上記の各公開オペレーションについて、パッケージは次の型をエクスポートします: * `Data`: 型付けされた body、headers、path、query の input。 * `Errors`: ドキュメント化されたエラーのステータスコードマップ。 * `Error`: ドキュメント化されたエラーの union。 * `Responses`: ドキュメント化された成功レスポンスのステータスコードマップ。 * `Response`: ドキュメント化された成功レスポンスの union。 デフォルトの `throwOnError: false` では、生成されたオペレーションは `data` または `error` のいずれかと、Fetch API の `request` を返します。HTTP レスポンスを受け取った場合は `response` が含まれ、レスポンスを受け取る前に失敗した場合は undefined のままになります。`throwOnError: true` の場合、`createApiClient` クライアントが HTTP エラーレスポンスを受け取ると [`ApiError`](#api-error) が throw されます。ネットワークエラーやキャンセルによる失敗では元のエラーがそのまま throw され、組み込みの timeout では `Error('Request timed out after ms')` が throw されます。 ### `ApiError` [#api-error] `createApiClient` クライアントでは、`throwOnError` を指定した呼び出し、[`paginate`](#pagination)、[`awaitJobs`](#job-polling)、および [`GT`](/docs/platform/core/reference/gt-class/constructor) クラスのメソッドで HTTP レスポンスが失敗すると、`ApiError` が throw されます。このエラーは `name: 'ApiError'`、HTTP ステータスを表す数値の `code`、および `message` を持ちます。`generaltranslation/api` または `generaltranslation/errors` からインポートできます。`throwOnError` を指定しない呼び出しでは、従来どおりデコードされたレスポンスボディが `error` に返されます。ネットワーク、設定、キャンセル、timeout による失敗では、クラスの呼び出し全体が reject される場合があります。これらは必ずしも項目ごとの翻訳失敗とは限りません。 ```ts import { ApiError } from 'generaltranslation/errors'; export function describeFailure(error: unknown): string { return error instanceof ApiError ? `${error.code}: ${error.message}` : String(error); } ``` ## OpenAPI 仕様 [#openapi-spec] 現在ホストされている公開 API のコントラクトについては、[`/openapi.json`](/openapi.json) を参照してください。[OpenAPI リファレンス](/docs/platform/openapi/overview) には、endpoint の permissions、リクエストの schema、レスポンスが記載されています。 ## Sitemap See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.