これらのエンドポイントはこのプレビューでは稼働していますが、まだ一般公開されていません — APIキーの発行はまだなく、安定版リリースまでに仕様が変わる可能性があります。
APIの案内リストに登録概要
このアプリは、同一オリジンの小さなジョブAPIを提供しています。画像をアップロードし、復元またはアップスケールのジョブを送信して、結果をポーリングします。まだAPIキーはなく、すべてのリクエストはブラウザのゲストセッションCookieの範囲に限定されます。
- ベースURL
- /api以下のすべてのパスはこの同一オリジンのベースからの相対パスです — 設定が必要な別のAPIホストはありません。
- 認証
- ゲストとして続行した際に発行されるhttpOnly Cookieによってセッション単位で制御されます。APIキーはまだ存在しません(下記の「計画中」を参照)。
契約上の保証: ジョブのresult_urlは常に有効なimage_urlです — これを/api/restoreまたは/api/upscaleにそのまま送信して別の操作に連結できます(復元後の「この画像をアップスケール」は、まさにこの仕組みで動作しています)。
/api/uploads画像をアップロード
画像ファイルを1つアップロードし、RestoreやUpscaleにimage_urlとして渡せる同一オリジンのアセットURLを返します。
リクエストボディ
| 名前 | 型 | 必須 | 範囲 | 説明 |
|---|---|---|---|---|
| file | binary (multipart/form-data) | はい | — | multipart/form-dataとして送信される画像ファイルです。 |
レスポンスボディ
| 名前 | 型 | 必須 | 範囲 | 説明 |
|---|---|---|---|---|
| image_url | string | はい | — | 以前のアップロードで返された同一オリジンのアセットURLです — 受け付けられる唯一のimage_urlの形式です。 |
| bytes | number | はい | 0–9007199254740991 | 保存されたファイルサイズ(バイト単位)です。 |
| mime | string | はい | — | 保存されたファイルから検出されたMIMEタイプです(信頼できる値であり、クライアントが申告した値ではありません)。 |
201 レスポンス例
{
"image_url": "/api/mock-assets/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
"bytes": 2458112,
"mime": "image/jpeg"
}コードサンプル
curl -X POST 'https://your-app.example.com/api/uploads' \
-F "file=@photo.jpg"/api/restore復元ジョブを作成
事前にアップロードした画像に対して非同期の復元ジョブを開始します。pending状態のジョブ参照をすぐに返します — 進捗はGET /api/jobs/{job_id}でポーリングしてください。
リクエストボディ
| 名前 | 型 | 必須 | 範囲 | 説明 |
|---|---|---|---|---|
| image_url | string | はい | /api/mock-assets/<uuid> | 以前のアップロードで返された同一オリジンのアセットURLです — 受け付けられる唯一のimage_urlの形式です。 |
| user_hint | string | いいえ | max 300 chars | 写真を説明する任意の自由入力メモで、模擬解析ステップの誘導に使われます。 |
| params.colorize | boolean | はい | — | スキーマ互換性のために必須です。値は受け付けられますが処理モードの選択には使われず、どの値でも復元パイプラインは同一です。 |
| params.resolution | unknown | はい | — | |
| params.variant | unknown | はい | — |
レスポンスボディ
| 名前 | 型 | 必須 | 範囲 | 説明 |
|---|---|---|---|---|
| job_id | string | はい | job_<uuid> | このジョブの一意な識別子です。 |
| status | pending | processing | succeeded | failed | cancelled | はい | — | ジョブの現在のライフサイクル状態です。 |
202 レスポンス例
{
"job_id": "job_3fa85f64-5717-4562-b3fc-2c963f66afa6",
"status": "pending"
}コードサンプル
curl -X POST 'https://your-app.example.com/api/restore' \
-H 'Content-Type: application/json' \
-d '{ "image_url": "/api/mock-assets/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "user_hint": "the sky was blue", "params": { "colorize": true }}'/api/upscaleアップスケールジョブを作成
事前にアップロードした画像に対して、指定したモードと目標解像度で非同期のアップスケールジョブを開始します。pending状態のジョブ参照をすぐに返します。
リクエストボディ
| 名前 | 型 | 必須 | 範囲 | 説明 |
|---|---|---|---|---|
| image_url | string | はい | /api/mock-assets/<uuid> | 以前のアップロードで返された同一オリジンのアセットURLです — 受け付けられる唯一のimage_urlの形式です。 |
| user_hint | string | いいえ | max 300 chars | 写真を説明する任意の自由入力メモで、模擬解析ステップの誘導に使われます。 |
| params.mode | fast | balanced | high | はい | — | アップスケールの品質と速度のトレードオフです。 |
| params.target_megapixels | number | はい | 1–64 | 希望する出力解像度(メガピクセル)です。 |
レスポンスボディ
| 名前 | 型 | 必須 | 範囲 | 説明 |
|---|---|---|---|---|
| job_id | string | はい | job_<uuid> | このジョブの一意な識別子です。 |
| status | pending | processing | succeeded | failed | cancelled | はい | — | ジョブの現在のライフサイクル状態です。 |
202 レスポンス例
{
"job_id": "job_3fa85f64-5717-4562-b3fc-2c963f66afa6",
"status": "pending"
}コードサンプル
curl -X POST 'https://your-app.example.com/api/upscale' \
-H 'Content-Type: application/json' \
-d '{ "image_url": "/api/mock-assets/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "params": { "mode": "fast", "target_megapixels": 12 }}'/api/jobs/{job_id}ジョブのステータスを取得
ジョブの現在の状態(status、progress)を返し、succeededになると、ダウンロードするか新しいimage_urlとして再送信できるresult_urlを返します。
レスポンスボディ
| 名前 | 型 | 必須 | 範囲 | 説明 |
|---|---|---|---|---|
| job_id | string | はい | job_<uuid> | このジョブの一意な識別子です。 |
| type | restore | upscale | はい | — | このジョブを作成したツールです。 |
| status | pending | processing | succeeded | failed | cancelled | はい | — | ジョブの現在のライフサイクル状態です。 |
| progress | number | はい | 0–100 | 完了率(0〜100)です。 |
| result_url | string | いいえ | — | ジョブが成功すると存在します — 新しいimage_urlとしても送信できる同一オリジンのアセットURLです。 |
| result_urls.light | string | はい | — | |
| result_urls.strong | string | いいえ | — | |
| before_url | string | いいえ | — | |
| error.code | INVALID_REQUEST | UNSUPPORTED_FORMAT | FILE_TOO_LARGE | JOB_NOT_FOUND | VLM_FAILED | WORKFLOW_FAILED | TIMEOUT | CANCELLED | INTERNAL | INSUFFICIENT_CREDITS | STORAGE_QUOTA_EXCEEDED | はい | — | 機械可読な失敗理由です。 |
| error.message | string | はい | — | 人が読める失敗メッセージです。statusがfailedのときのみ存在します。 |
| created_at | string | はい | — | ジョブが作成された日時(ISO 8601形式)です。 |
| updated_at | string | はい | — | ジョブが最後に更新された日時(ISO 8601形式)です。 |
200 レスポンス例
{
"job_id": "job_3fa85f64-5717-4562-b3fc-2c963f66afa6",
"type": "restore",
"status": "succeeded",
"progress": 100,
"result_url": "/api/mock-assets/6c1d3a2e-4f5b-4a1e-9c2d-1a2b3c4d5e6f",
"created_at": "2026-08-03T10:15:00.000Z",
"updated_at": "2026-08-03T10:15:42.000Z"
}コードサンプル
curl -X GET 'https://your-app.example.com/api/jobs/job_3fa85f64-5717-4562-b3fc-2c963f66afa6'/api/jobs/{job_id}/cancelジョブをキャンセル
ジョブのキャンセルをリクエストします。すでに終了状態のジョブをキャンセルしても何も起こらず、現在の状態がそのまま返されます。
レスポンスボディ
| 名前 | 型 | 必須 | 範囲 | 説明 |
|---|---|---|---|---|
| job_id | string | はい | job_<uuid> | このジョブの一意な識別子です。 |
| status | pending | processing | succeeded | failed | cancelled | はい | — | ジョブの現在のライフサイクル状態です。 |
202 レスポンス例
{
"job_id": "job_3fa85f64-5717-4562-b3fc-2c963f66afa6",
"status": "cancelled"
}コードサンプル
curl -X POST 'https://your-app.example.com/api/jobs/job_3fa85f64-5717-4562-b3fc-2c963f66afa6/cancel'ジョブステータスのライフサイクル
すべてのジョブはこの状態遷移を経ます。pendingとprocessingは非終了状態で、succeeded、failed、cancelledは終了状態で二度と変化しません。
クライアントのポーリング期限内にジョブが終了状態に達しない場合、TIMEOUTによる失敗として扱われます。
エラーコード
すべてのエラーはこの固定されたコードセットを使用します。INVALID_REQUEST、UNSUPPORTED_FORMAT、FILE_TOO_LARGE、JOB_NOT_FOUNDはHTTPエラーレスポンスとして返され、それ以外はジョブがfailedまたはcancelledの終了状態に達したときに、ジョブオブジェクト内のerror.codeとして現れます。
| コード | 現れる場所 | 意味 |
|---|---|---|
| INVALID_REQUEST | HTTP 400 エラーレスポンス | このリクエストは無効です。入力内容を確認してもう一度お試しください。 |
| UNSUPPORTED_FORMAT | HTTP 415 エラーレスポンス | このファイル形式はサポートされていません。JPEG、PNG、WebP、HEIC、HEIFのいずれかをご使用ください。 |
| FILE_TOO_LARGE | HTTP 413 エラーレスポンス | このファイルは大きすぎます。より小さい画像を使用してください。 |
| JOB_NOT_FOUND | HTTP 404 エラーレスポンス | このジョブが見つかりませんでした。期限切れの可能性があります。 |
| VLM_FAILED | 終了状態のジョブのerrorフィールド内 | この画像を解析できませんでした。もう一度お試しください。 |
| WORKFLOW_FAILED | 終了状態のジョブのerrorフィールド内 | 処理に失敗しました。もう一度お試しください。 |
| TIMEOUT | 終了状態のジョブのerrorフィールド内 | 予想より時間がかかっています。もう一度お試しください。 |
| CANCELLED | 終了状態のジョブのerrorフィールド内 | このジョブはキャンセルされました。 |
| INTERNAL | HTTP 500 エラーレスポンス | こちら側で問題が発生しました。もう一度お試しください。 |
| INSUFFICIENT_CREDITS | HTTP 402 エラーレスポンス | このジョブに必要なクレジットが不足しています。追加購入して続けてください。 |
| STORAGE_QUOTA_EXCEEDED | HTTP 413 エラーレスポンス | アルバムが上限に達しています。写真を削除するかアップグレードしてください。 |
サードパーティ連携向けにバージョン管理された/v1ゲートウェイを計画しています — セッションCookieの代わりにAPIキー、ポーリングの代わりにジョブ完了時のWebhook、キーごとのレート制限などです。これらはまだ何一つ実装されておらず、リクエスト/レスポンスの形式、認証方式、Webhook署名、レート制限の数値のいずれも確定していません。このセクションより上にあるもの — このアプリが実際に提供している同一オリジンの/apiルート — だけが、現時点で有効な唯一の契約だと考えてください。/v1がリリースされる場合は、完全な仕様とともに別途文書化されます。この段落はプレビューではなく、あくまで事前のお知らせです。