> For the complete documentation index, see [llms.txt](https://getsquish.gitbook.io/squish/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://getsquish.gitbook.io/squish/ja/rifarensu/http-api.md). # ホスト型 API ホスト型 API は、ある **意図的にアップロードされた** 動画を、タイムスタンプ付きのコンタクトシート JPEG と JSON メタデータ、そしてタイムコードに変換します。ワークフローでローカルの [CLI](/squish/ja/rifarensu/cli.md)/[MCP](/squish/ja/rifarensu/mcp.md) ツール（CI、serverless、ホスト型エージェント、ffmpeg なし）が使えない場合に利用します。ローカルのワークフローでは CLI/MCP サーバーを優先してください。これらはすべてを手元のマシンで処理し、何もアップロードしません。参照 [プライバシーとデータフロー](/squish/ja/purimitibu/privacy-and-data-flow.md). 契約文字列: `squish-http-v0` （参照 [安定性とバージョニング](/squish/ja/rifarensu/stability.md)). ## エンドポイント ``` POST https://api.getsquish.app/v1/squish ``` 1 回の同期リクエストで処理全体が完了します。ジョブキュー API も、ポーリング用エンドポイントも、webhook もありません。 ## 認証 * ヘッダー: `Authorization: Bearer ` * キーの形式: `sq_live_` + 40 文字の 16 進数で、発行されるのは [getsquish.app/api-keys](https://getsquish.app/api-keys) （メール OTP サインイン）。 * 平文キーは表示されます **一度** — 保存されるのは SHA-256 ハッシュのみのため、紛失したキーを復元することはできず、再発行のみ可能です。 * キーがない、形式が不正、または失効している場合は `401 invalid_key` を返し、本文は読み込まれる前に終了します。 ## リクエスト `multipart/form-data` は、ファイルフィールドをちょうど 1 つ含み、名前は **`video`** (`video=@clip.mov`である必要があります。その他のファイルパートは無視されます。 任意のフォームフィールド: | フィールド | 値 | デフォルト | 備考 | | --------- | -------------------------- | ------ | ----------------------------------------------------------- | | `density` | `3x3`, `4x4`, `5x5`, `6x6` | `3x3` | 密度が高いほど、シートあたりの消費クレジットは増えます（[クレジット](#credits-and-pricing)). | | `レスポンス` | `JSON`, `画像` | `JSON` | `画像` は最初のシート JPEG をそのまま返します（[以下](#responseimage)). | {% hint style="warning" %} **まだズームウィンドウはありません。** ホスト型 API は `start`/`end` を受け付けません。リクエストは常にクリップ全体を対象とし、送信された `start`/`end` フィールドはすべて無視されます。 [ナビゲーションループ](/squish/ja/purimitibu/the-navigation-loop.md)のズームステップは、現時点ではローカル CLI/MCP 専用です。ウィンドウ対応は動画セッション（1 回アップロード、複数回圧縮）で提供されます。 {% endhint %} ## JSON レスポンス ```json { "job_id": "...", "input": "clip.mov", "duration": 10.0, "frames": 9, "sheets": 1, "density": "3x3", "credits_charged": 1, "credits_remaining": 33, "files": ["https://api.getsquish.app/v1/sheets//video.sheet-1.jpg"], "timecodes": [["0:00", "0:01", "0:02", "0:03", "0:05", "0:06", "0:07", "0:08", "0:10"]], "warnings": [], "contract": "squish-http-v0" } ``` `ファイル` は一時的な capability URL です（参照 [ジョブのライフサイクル](#job-lifecycle)）。シートファイルの名前は常に `video.sheet-N.jpg` — サーバーはアップロードを独自の固定名で保存するため、元のファイル名が URL に現れることはありません。代わりに `input` フィールドでその名前が返されます（ [ファイル名契約](/squish/ja/rifarensu/sheet-format.md#filename-contract)). `timecodes[][]` シート上のピクセルに印字されたラベルと常に一致します。形式 `m:ss`、サブ秒 `m:ss.d` 短いクリップでは、全秒単位では隣接セルを区別できない場合があります（参照 [シート形式仕様](/squish/ja/rifarensu/sheet-format.md#timecode-grammar)）。長いクリップでは複数のシートが順に生成されます。すべて確認してください。 ### response=image `response=image` は **最初の** シート JPEG を JSON ではなく直接返し、メタデータはヘッダーに含まれます: `x-squish-job` （ジョブ ID）と `x-credits-remaining`。複数シートのジョブでは既定の JSON モードを使用してください。image モードでは他のシートの URL とタイムコードが返りません。 ## エラー | ステータス | エラー | 意味 | 対処方法 | | ----: | ---------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | `401` | `invalid_key` | 認証情報がない、失効している、または誤っている | からキーを作成/コピーしてください [`/api-keys`](https://getsquish.app/api-keys). | | `402` | `insufficient_credits` | 残高不足です。未課金アカウントの場合、このエラーが返る前に無料の日次枠はすでに自動適用されています | でチャージするか `/api-keys`を下げるか `density`、または短いクリップを送信してください。未課金アカウントは次の UTC 日まで待つこともできます。 | | `413` | `too_large` | アップロードが現在の上限を超えています（`max_mb` は本文内） | トリミング/圧縮するか、より短いクリップ／低い密度を使用してください。 | | `422` | `bad_request` | リクエストの形が正しくない、または値が不正です `density`/`レスポンス` 値 | 再試行する前にリクエストを修正してください。 | | `422` | `unreadable_video` | アップロードを動画として解析できませんでした | 一般的なコンテナ形式の実際の動画ファイルを送信してください。 | | `422` | `too_long` | 再生時間が上限を超えています（`max_s` は本文内） | クリップを短くするか、より短いものを送信してください。 | | `429` | `busy` | 単一ジョブのワーカーが満杯です | 待ってから再試行してください。 | | `500` | `processing_failed` | 課金後にエンジンが失敗しました | 本文は `{ "error": "processing_failed", "refunded": true\|false }` — **check `返金済み`**: `true` → 1 回だけ再試行してください。 `false` → 課金は確定しています。再試行せず報告してください。 | ## 再試行ポリシー 安全に再試行できるかは、いつお金が動くかで決まります。クレジットは原子的に差し引かれます *、* 正確な価格が判明した後に *前に* フレーム抽出: * **`401`** **`402`** **`413`** **`422` — 同じ内容のまま再試行しないでください。** 課金は発生していません。同じリクエストは同じように失敗します。まず原因を修正してください（新しいキー、チャージ、小さい/短いクリップ、修正済みフィールド）。 * **`429` — 再試行しても安全です。** 課金は発生していません。サービスは 1 件ずつ短いキューでジョブを処理します。ジョブは数秒で完了します（12 秒のクリップで約 6 秒）。そのため、少し待ってから再試行してください（約 10〜30 秒）。 `Retry-After` ヘッダーは `squish-http-v0`. * **`500` ありません。 `返金済み` 再試行する前に本文を読んでください。** `refunded: true` （通常のケース）：課金は自動的に戻されています。1 回再試行し、2 回失敗したら報告してください。 `refunded: false` （まれ）：自動返金そのものが失敗し、課金が確定しています。盲目的に **再試行しないでください** 。使用量テーブルに `/api-keys` 実際の正味コストが記録されます。 * **idempotency key はありません。** 受け付けられたリクエストは毎回新しいジョブと新しい課金になります。成功していた可能性のあるリクエストを、安易に再送しないでください（接続が切れても *、* 処理は課金対象です。使用量テーブルを確認してください。 `/api-keys`). ## ジョブのライフサイクル 1. アップロードはディスクにストリームされます（メモリにバッファされることはありません）。 2. 検証 → 計画 → 価格算出 → 原子的なクレジット差し引き → フレーム抽出 → レスポンス。 3. 接続は処理中ずっと維持されます（通常のクリップなら数秒です）。 4. `job_id` レスポンス内の値は領収書です。シート URL と使用量テーブルに表示されます。 `/api-keys`. ## データのライフサイクル ホスト型 API は **コンピュートサービスであり、ストレージサービスではありません** — 短期間だけ出力をキャッシュするステートレスなジョブです。2 種類のデータは別々の経路で扱われます: ``` アップロードされた動画 ──► 処理 ──► ジョブ終了と同時に削除 │　　　　　（成功または失敗） ▼ 生成されたシート ──► 一時キャッシュ（約 24 時間） ──► 自動期限切れ ``` * **アップロードされた動画** は、それを載せたリクエストの処理にのみ使われ、ジョブ終了の瞬間に削除されます。成功でも失敗でも同じです。保持されることはなく、学習にも使われず、メディアライブラリもありません。 * **生成されたシート** は、その capability URL にある一時キャッシュです。ダウンロードしたり URL を再取得したりできるよう約 24 時間保持され、その後は期限切れになり自動削除されます。これはストレージではありません。保存したいものは必ずダウンロードしてください。 より強い保証が必要ですか？ Squish をローカルで実行してください。ローカルの [CLI](/squish/ja/rifarensu/cli.md) と [MCP サーバー](/squish/ja/rifarensu/mcp.md) 動画をアップロードしないでください。 ## 制限 現在の v0 の制限: * アップロード上限: **300 MB** * 時間上限: **30 分** * 一度に処理できるジョブは 1 件で、小さなキューがあります。過負荷の場合は `429 busy` * 出力は一時的なもので、永続的な保存領域ではありません ## クレジットと価格 クレジットは前払いで、 **出力シートごとに**密度に応じて課金されます: | 密度 | 1 シートあたりのクレジット | | ----- | -------------: | | `3x3` | 1 | | `4x4` | 2 | | `5x5` | 3 | | `6x6` | 5 | 販売中のパック: **$3 = 30 クレジット · $9 = 120 クレジット · $29 = 500 クレジット。** ### 無料の日次枠 あるアカウントは **何も購入したことがない** （Web Pro なし、クレジットパックなし）は、少額の下限値まで補充されます — 現在は **7 クレジット** — 最大でも 1 回／ **UTC 日ごとに**は、その日の最初の有料リクエストで、残高が下限を下回っている場合に適用されます。これは下限までの補充であり、加算ではありません。未使用枠は繰り越されません（前日の残りは当日の付与額から差し引かれるため、1 UTC 日の消費が下限を超えることはありません）。下限以上では何も付与されず、購入済み残高は一切消費されません。 ## ヘルスチェック ``` GET https://api.getsquish.app/healthz ``` を返します `{ "ok": true, "contract": "squish-http-v0", "version": "…" }` — 認証不要です。エージェントが「API が落ちている」のか「自分のリクエストが間違っている」のかを見分けるのに便利です。 ## シートとは何か — そして何ではないか そのため、エージェントは期待値を適切に設定できます: * **見た目だけです。** シートには音声、会話、トランスクリプトはありません。Squish は見ますが、聞きません。 * **動きの代替ではなく、シーケンスの地図です。** フレームはクリップ全体からサンプリングされます。サンプル間で起こる出来事は見えません。より密なグリッド（`4x4`–`6x6`）は隙間を小さくしますが、なくすことはできません。 * **出力は JPEG コンタクトシートのみです** （品質 0.70）、密度 `3x3`–`6x6`. * **サーバー側では分析は行われません。** API はアーティファクトを返し、読み取り・推論は呼び出し元のモデルの役割です。 --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://getsquish.gitbook.io/squish/ja/rifarensu/http-api.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.