API の例

バージョン

API

APIの使い方

APIキーを作成

ログインしてダッシュボードでキーを作成し、利用可能なクレジットを確認します。
アップロードして送信

V2：アップロードURLを取得し、ファイルをアップロードしてから翻訳タスクを送信します。
タスクの状態を確認

返された batch_id を使い、画像の処理が終わるまで進捗を確認します。
翻訳画像をダウンロード

処理に成功した画像の翻訳画像URLから結果を取得します。

入力例

API キー

翻訳元言語

翻訳先言語

モデル

翻訳エンジン

フォント

Python 3 · pip install requests

ルート

POST PUT POST

/api/v2/api/translate/uploads
R2 target
/api/v2/api/translate

パラメータ

パラメータ	必須	型	説明
`image`	はい	file[]	1つ以上の画像ファイル、または1つの ZIP アーカイブ
`source_language`	いいえ	string	任意。manga モデルを選択した場合は必須です（例: ja）
`target_language`	はい	string	翻訳先言語コード（例: en）
`model`	いいえ	string	認識モデル。省略すると API のデフォルト値を使用します
`translator`	いいえ	string	テキスト翻訳エンジン。省略または auto を指定すると、選択したモデルの既定の翻訳エンジンを使用します。V2 では最終リクエストにのみ含めます。
`font`	いいえ	string	フォントスタイル。省略すると API のデフォルト値を使用します
`context`	いいえ	string	物語の背景や名前の表記（任意、最大10,000文字）。空欄なら通常の翻訳です。V2では最終翻訳リクエストにのみ含めます。
`custom_prompt`	いいえ	string	空欄の場合は標準の翻訳指示を使用します。選択した言語と出力形式は維持されます。Ultra ではモデルへの追加指示として送信されます。 (1,000)

パラメータ	必須	型	説明
`Idempotency-Key`	はい	HTTP header	準備リクエストヘッダー：同じファイル一覧を8時間安全に再試行するための固定キー
`files[]`	はい	array<object>	準備リクエスト：filename、content_type、size、content_sha256 を含むファイルメタデータ
`upload_id`	はい	string	最終リクエスト：準備処理で返された非公開のアップロードバッチ ID
`files[].index files[].upload_intent`	はい	integer string	最終リクエスト：準備処理で返されたファイルごとの index と非公開の upload_intent。各 R2 アップロード完了後に送信します
`source_language`	いいえ	string	任意。manga モデルを選択した場合は必須です（例: ja）
`target_language`	はい	string	翻訳先言語コード（例: en）
`model`	いいえ	string	認識モデル。省略すると API のデフォルト値を使用します
`translator`	いいえ	string	テキスト翻訳エンジン。省略または auto を指定すると、選択したモデルの既定の翻訳エンジンを使用します。V2 では最終リクエストにのみ含めます。
`font`	いいえ	string	フォントスタイル。省略すると API のデフォルト値を使用します
`context`	いいえ	string	物語の背景や名前の表記（任意、最大10,000文字）。空欄なら通常の翻訳です。V2では最終翻訳リクエストにのみ含めます。
`custom_prompt`	いいえ	string	空欄の場合は標準の翻訳指示を使用します。選択した言語と出力形式は維持されます。Ultra ではモデルへの追加指示として送信されます。 (1,000)

パラメータ	必須	型	説明
`batch_id`	はい	string	タスク状態の照会に使用するバッチ識別子

パラメータ	必須	型	説明
パラメータなし

レスポンスパラメータ

フィールド	型	説明
`task_id`	string	タスク識別子
`batch_id`	string	タスク状態の照会に使用するバッチ識別子

フィールド	型	説明
`status`	integer	アプリケーションステータスコード。成功時は 200
`cost_ms`	integer	この API リクエストの処理時間（ミリ秒）
`request_id`	string	この API 呼び出しを追跡するためのリクエスト識別子
`data`	object	リクエスト受理後に返される翻訳タスク識別子
`message`	string	API 成功レスポンスでは常に success。翻訳タスクの完了を意味しません
`data.task_id`	string	タスク識別子
`data.batch_id`	string	タスク状態の照会に使用するバッチ識別子

フィールド	型	説明
`status_code`	integer	Task Status の成功レスポンスでは常に 200
`request_id`	string	この API 呼び出しを追跡するためのリクエスト識別子
`auth_type`	string	PAT 認証された Task Status リクエストでは常に account
`task_reference`	string	リクエストパスの batch_id をそのまま返す
`data`	object	画像ごとの結果とタスク全体の状態を格納するオブジェクト
`data.items`	array<object>	画像ごとのタスク結果の配列
`data.items[].image_id`	string	画像結果の安定した識別子
`data.items[].index`	integer	バッチ内での画像のゼロ始まりの位置
`data.items[].filename`	string	元画像のファイル名
`data.items[].status`	string	画像結果のステータス（pending \| processing \| completed \| failed \| canceled）
`data.items[].original_url`	string	元画像の URL。現在 API で作成されたタスクでは利用できます。
`data.items[].translated_url`	string	翻訳画像の URL。翻訳結果が利用可能になるまでは空文字列で、待機中・処理中・失敗した画像も該当します。
`data.items[].is_translated`	boolean	完了した翻訳画像 URL が利用可能な場合のみ true
`data.items[].output_file_path`	string	translated_url の互換エイリアス。翻訳画像がない場合は空文字列です。
`data.items[].message`	string \| null	任意の情報メッセージ
`data.items[].error`	string \| null	画像タスク失敗時のエラー詳細。それ以外は null
`data.items[].inpaint_image_url`	string \| null	文字消去画像の URL。選択したモデルまたは実行経路が生成しない場合は null です。
`data.items[].block_json`	array<object>	V1 に保持される構造化テキストブロック。選択したモデルまたは実行経路がブロックメタデータを返さない場合は空配列になることがあります。
`data.task_status`	string	タスク全体の状態（pending \| processing \| completed \| failed \| canceled）

フィールド	型	説明
`status`	integer	アプリケーションステータスコード。成功時は 200
`cost_ms`	integer	タスクの経過時間（ミリ秒）。有効なタスク時刻がない場合は 0
`request_id`	string	この API 呼び出しを追跡するためのリクエスト識別子
`data`	array<object>	画像ごとの簡潔な結果の配列
`message`	string	API 成功レスポンスでは常に success。翻訳タスクの完了を意味しません
`data[].image_id`	string	画像結果の安定した識別子
`data[].filename`	string	元画像のファイル名
`data[].status`	string	画像結果のステータス（pending \| processing \| completed \| failed \| canceled）
`data[].original_url`	string	元画像の URL。現在 API で作成されたタスクでは利用できます。
`data[].translated_url`	string	翻訳画像の URL。翻訳結果が利用可能になるまでは空文字列で、待機中・処理中・失敗した画像も該当します。
`data[].erased_url`	string	文字消去画像の URL。空文字列の場合があります。Manga + Auto の完成画像経路など、完成画像だけを返すモデルまたは実行経路では生成されません。
`data[].blocks`	array<object>	構造化された翻訳テキストブロック。Manga + Auto の完成画像経路など、選択したモデルまたは実行経路がブロックメタデータを返さない場合は空配列になることがあります。
`data[].blocks[].angle`	number	テキストブロックの回転角度
`data[].blocks[].color`	string	翻訳テキストに使用する 16 進カラー
`data[].blocks[].handwritten`	boolean	原文が手書きとして検出されたかどうか
`data[].blocks[].location`	object	テキストブロックの四隅の境界
`data[].blocks[].location.left_bottom`	array<number>	指定された隅の座標ペア
`data[].blocks[].location.right_bottom`	array<number>	指定された隅の座標ペア
`data[].blocks[].location.left_top`	array<number>	指定された隅の座標ペア
`data[].blocks[].location.right_top`	array<number>	指定された隅の座標ペア
`data[].blocks[].text`	string	ブロックに描画される翻訳テキスト
`data[].blocks[].direction`	string	翻訳テキストの書字方向

フィールド	型	説明
`subscription_credits`	integer	指定カテゴリのクレジット残高
`subscription_credits_expires_at`	string \| null	サブスクリプションクレジットの有効期限（ISO 8601 形式）。期限がない場合は null
`one_time_credits`	integer	指定カテゴリのクレジット残高
`one_time_credits_expires_at`	string \| null	ワンタイムクレジットの有効期限（ISO 8601 形式）。期限がない場合は null
`free_credits`	integer	指定カテゴリのクレジット残高
`total_credits`	integer	利用可能な全クレジット残高の合計
`is_temporary`	boolean	残高が一時アカウントに属するかどうか

フィールド	型	説明
`status`	integer	アプリケーションステータスコード。成功時は 200
`cost_ms`	integer	この API リクエストの処理時間（ミリ秒）
`request_id`	string	この API 呼び出しを追跡するためのリクエスト識別子
`data`	object	現在のクレジット残高を格納するオブジェクト
`message`	string	API 成功レスポンスでは常に success。翻訳タスクの完了を意味しません
`data.total_credits`	integer	利用可能な全クレジット残高の合計
`data.is_temporary`	boolean	残高が一時アカウントに属するかどうか
`data.detail`	object	カテゴリ別の利用可能クレジット内訳
`data.detail.subscription`	object	対象カテゴリのクレジット残高と有効期限
`data.detail.subscription.credits`	integer	指定カテゴリのクレジット残高
`data.detail.subscription.expires_at`	string \| null	クレジットの有効期限（ISO 8601 形式）。期限がない場合は null
`data.detail.one_time`	object	対象カテゴリのクレジット残高と有効期限
`data.detail.one_time.credits`	integer	指定カテゴリのクレジット残高
`data.detail.one_time.expires_at`	string \| null	クレジットの有効期限（ISO 8601 形式）。期限がない場合は null
`data.detail.free`	object	対象カテゴリのクレジット残高と有効期限
`data.detail.free.credits`	integer	指定カテゴリのクレジット残高
`data.detail.free.expires_at`	null	この集約 API では無料クレジットの単一の有効期限を提供しないため、常に null

レスポンス例（JSON）

{
  "task_id": "00000000-0000-4000-8000-000000000001",
  "batch_id": "00000000-0000-4000-8000-000000000001"
}

レスポンス例（JSON）

{
  "status": 200,
  "cost_ms": 125,
  "request_id": "4b7370383cacccc7",
  "data": {
    "task_id": "00000000-0000-4000-8000-000000000001",
    "batch_id": "00000000-0000-4000-8000-000000000001"
  },
  "message": "success"
}

レスポンス例（JSON）

{
  "status_code": 200,
  "request_id": "4b7370383cacccc7",
  "auth_type": "account",
  "task_reference": "00000000-0000-4000-8000-000000000001",
  "data": {
    "items": [
      {
        "image_id": "00000000-0000-4000-8000-000000000001_0",
        "index": 0,
        "filename": "007.jpg",
        "status": "completed",
        "original_url": "https://storage.example.com/manga-demo/input/00000000-0000-4000-8000-000000000001/007.jpg",
        "translated_url": "https://storage.example.com/manga-demo/output/00000000-0000-4000-8000-000000000001/007.jpg",
        "is_translated": true,
        "output_file_path": "https://storage.example.com/manga-demo/output/00000000-0000-4000-8000-000000000001/007.jpg",
        "message": "ok",
        "error": null,
        "inpaint_image_url": "https://storage.example.com/manga-demo/output/00000000-0000-4000-8000-000000000001/007-erased.jpg",
        "block_json": []
      }
    ],
    "task_status": "completed"
  }
}

レスポンス例（JSON）

{
  "status": 200,
  "cost_ms": 5300,
  "request_id": "4b7370383cacccc7",
  "data": [
    {
      "image_id": "00000000-0000-4000-8000-000000000001_0",
      "filename": "007.jpg",
      "status": "completed",
      "original_url": "https://storage.example.com/manga-demo/input/00000000-0000-4000-8000-000000000001/007.jpg",
      "translated_url": "https://storage.example.com/manga-demo/output/00000000-0000-4000-8000-000000000001/007.jpg",
      "erased_url": "https://storage.example.com/manga-demo/output/00000000-0000-4000-8000-000000000001/007-erased.jpg",
      "blocks": [
        {
          "angle": 0,
          "color": "#484848",
          "handwritten": false,
          "location": {
            "left_bottom": [1685, 293],
            "right_bottom": [1786, 293],
            "left_top": [1685, 264],
            "right_top": [1786, 264]
          },
          "text": "OOOUGH!",
          "direction": "horizontal"
        }
      ]
    }
  ],
  "message": "success"
}

レスポンス例（JSON）

{
  "subscription_credits": 0,
  "subscription_credits_expires_at": null,
  "one_time_credits": 0,
  "one_time_credits_expires_at": null,
  "free_credits": 10,
  "total_credits": 10,
  "is_temporary": true
}

レスポンス例（JSON）

{
  "status": 200,
  "cost_ms": 4,
  "request_id": "4b7370383cacccc7",
  "data": {
    "total_credits": 10,
    "is_temporary": true,
    "detail": {
      "subscription": {
        "credits": 0,
        "expires_at": null
      },
      "one_time": {
        "credits": 0,
        "expires_at": null
      },
      "free": {
        "credits": 10,
        "expires_at": null
      }
    }
  },
  "message": "success"
}

エラーレスポンスパラメータ

V2 でエラーが発生した場合も HTTP ステータスを維持し、同じ 5 フィールドのエンベロープを返します。

フィールド	型	説明
`status`	integer	実際の HTTP エラーステータスコード
`cost_ms`	integer	この API リクエストの処理時間（ミリ秒）
`request_id`	string	この API 呼び出しを追跡するためのリクエスト識別子
`data`	object	安定した機械可読コードのみを含むエラーデータコンテナ
`message`	string	公開用エラーメッセージ。内部診断の詳細は公開されません
`data.code`	string	安定した機械可読エラーコード

エラーレスポンス例（JSON）

{
  "status": 400,
  "cost_ms": 1,
  "request_id": "4b7370383cacccc7",
  "data": {
    "code": "PZ_API_ACCESS_BAD_REQUEST"
  },
  "message": "Invalid target language"
}

APIの使い方

APIキーを作成

アップロードして送信

タスクの状態を確認

翻訳画像をダウンロード

入力例

ルート

パラメータ

レスポンスパラメータ

レスポンス例（JSON）

レスポンス例（JSON）

レスポンス例（JSON）

レスポンス例（JSON）

レスポンス例（JSON）

レスポンス例（JSON）

エラーレスポンスパラメータ

エラーレスポンス例（JSON）

Cookie 設定