HTTP API サーバー

外部ツールから SeqLens のプロジェクトを操作するための HTTP API について説明します。

NOTE

HTTP API は実験的な機能（Experimental）です。エンドポイント、レスポンスの形、挙動は今後のリリースで予告なく変わることがあります。

SeqLens には、外部ツールからプロジェクトを操作するための ローカル HTTP API サーバー があります。シーケンス情報やフレームのメタデータを取得できるほか、再スキャンや書き出し・ジョブ操作などの書き込み系も呼び出せます。シェルスクリプト、ジョブ管理ツール、CI、Houdini / Nuke などから利用できます。

初期状態ではオフです。設定 → サーバー、または サーバー → サーバーを有効化 からオンにします。

設定項目

項目	説明
サーバーを有効化	サーバーの有効 / 無効トグル
ポート	リッスンポート。デフォルトは 5397（`SEQL` を意識した数字）
許可 IP	接続を許可する IP のリスト。初期状態では同じマシンからの接続だけを許可します
トークンを必須にする	Bearer トークン認証の有効化
トークン	有効化時に自動生成される読み取り専用のトークン。コピー / 再生成ボタンで扱えます

トークンを必須にすると、リクエスト時に Authorization: Bearer <token> ヘッダでトークンを指定します。トークン欄は自分で入力するものではなく、有効化したときに自動で生成されます。漏れた疑いがあるときは 再生成 で作り直せます。

サーバーが稼働中はポート・許可 IP・トークンを変更できません（設定がロックされます）。変更するには、いったんサーバーを停止してください。

サーバーの状態は設定タブと サーバー メニューに表示されます。たとえば稼働中は ステータス: 稼働中 (127.0.0.1:5397) のようにアドレス付きで表示され、ほかに 起動中… / 失敗 / 停止中 があります。

エンドポイント

以下は主要なエンドポイントの抜粋です。全量と詳細（パラメータ・レスポンス形式・書き込み系のリクエスト本文など）は、組み込みの API リファレンス（/docs）を参照してください。

プロジェクトを対象とする操作は、現在開いているプロジェクトを指す /api/v1/projects/current 配下にまとまっています。

パス	用途
`GET /api/health`	ヘルスチェック（認証不要。アプリのバージョン、API バージョン、プロジェクトが開いているか、開いているプロジェクトのキーを返す）
`GET /api/v1/projects/current`	現在開いているプロジェクトのメタデータ
`GET /api/v1/projects/current/sequences`	シーケンス一覧
`GET /api/v1/projects/current/sequences/{key}`	単一シーケンスの識別情報
`GET /api/v1/projects/current/sequences/{key}/scan`	最新スキャンの状態（欠番フレーム、合計サイズ、mtime など）
`GET /api/v1/projects/current/sequences/{key}/frames`	フレームごとのメタデータ
`POST /api/v1/projects/current/rescan`	プロジェクトの再スキャン
`GET /api/v1/projects/current/exports/...`	CSV / JSON / MHL / OpenTimelineIO / MP4 / ZIP などの書き出し
`GET /api/v1/projects/current/raw-keys`	`raw` 内で参照できる keypath 一覧

シーケンス一覧（/sequences）は、ページング（offset / limit）に加えて、フィルタ・ソート・include（scan / anomaly などの付加情報）といったクエリパラメータに対応します。指定できる値の一覧は /docs を参照してください。

ドキュメントとログ

サーバー起動中は http://<host>:<port>/openapi.json に OpenAPI 3.1 ドキュメントが公開され、http://<host>:<port>/docs で API リファレンス UI（Scalar）を閲覧できます。http://<host>:<port>/ を開くと /docs にリダイレクトされます。サーバー → API Docs を開く メニューから即座にブラウザで開けます。

サーバー固有のログは userData/logs/api-server.log に出力され、サーバー → サーバーログを表示 メニューから開けます。

セキュリティ上の注意

WARNING

初期状態の「同じマシンからのみ接続」が最も安全です。 LAN に公開する場合は、必ず認証を有効にしてください。

トークンは有効化時に自動生成されます。漏れた疑いがあるときは 再生成 してください。
インターネットへ直接公開しないでください。 外部からアクセスする必要がある場合は、VPN や安全な中継経路を使ってください。
認証を無効にしたまま許可 IP にループバック以外のアドレスを含めると、無認証でリモートからプロジェクトを読み取れる状態になります。UI は警告を表示し、サーバーはこの設定では起動を拒否します。
ブラウザ経由の DNS リバインディング攻撃に対しては、Origin ヘッダが付くリクエストを Host と照合してクロスオリジンを遮断します。