HTTP API サーバー

SeqLens は、同マシン上（または同じネットワーク上）からプロジェクトを参照できるローカル HTTP API サーバーを内蔵しています。

SeqLens は、同マシン上（または同じネットワーク上）からプロジェクトを参照できる ローカル HTTP API サーバー を内蔵しています。シェルスクリプトやジョブ管理ツール、CI、Houdini / Nuke といった外部 DCC からシーケンス情報の取得やエクスポートを呼び出すための窓口です。

既定では OFF になっており、Settings → サーバー タブ、またはトップメニューの サーバー → サーバーを有効化 から有効化します。

設定項目

項目	説明
サーバーを有効化	サーバーの有効 / 無効トグル
ポート	リッスンポート。デフォルトは 5397（`SEQL` を意識した数字）
許可 IP	接続を許可する IP のリスト。既定はループバックのみ（`127.0.0.1` / `::1`）で、ループバック以外を含めると外部からも到達可能な状態でバインドされます
トークンを必須にする	Bearer トークン認証の有効化
トークン	任意のシークレット文字列。リクエスト時に `Authorization: Bearer <token>` ヘッダで指定します

サーバーの状態は stopped / starting / running / failed の 4 種類があり、設定タブと サーバー メニューにアドレス付きで表示されます（例: Running at 127.0.0.1:5397）。IPv6 ホストの場合は [::1]:5397 のように角括弧で囲まれます。

エンドポイント

業務 API は /api/v1/... 以下、ヘルスチェックと API ドキュメントは /api/ 直下に提供されます。

パス	用途
`GET /api/health`	ヘルスチェック（認証不要。アプリのバージョンと API のメジャーバージョンを返す）
`GET /api/v1/project`	現在開いているプロジェクトのメタデータ
`GET /api/v1/sequences`	シーケンス一覧（ページング対応、既定 100 件・上限 1000 件）
`GET /api/v1/sequences/{key}`	単一シーケンスの識別情報
`GET /api/v1/sequences/{key}/scan`	最新スキャンの状態（欠番フレーム、合計サイズ、mtime など）
`GET /api/v1/sequences/{key}/image`	先頭フレームの画像メタデータ（OIIO ImageSpec）
`GET /api/v1/sequences/{key}/frames`	フレームごとのメタデータ。`?from=&to=` または `?frames=1,5,10-20` で範囲を絞り込み可能。`Accept: application/x-ndjson` を付けると無制限の NDJSON ストリーミング
`GET /api/v1/sequences/{key}/frames/{frame}`	単一フレームのメタデータ
`GET /api/v1/sequences/{key}/frames/{frame}/thumbnail`	サムネイル画像のバイト列(`?size=small\|large`、ETag / If-None-Match 対応)
`GET /api/v1/export/sequences.json`	プロジェクト全体を JSON で一括ダウンロード
`GET /api/v1/export/sequences.csv`	プロジェクト全体を CSV（1 行 1 シーケンス）でダウンロード
`GET /api/v1/export/files.csv`	1 行 1 フレームの CSV をストリーミング出力
`GET /api/v1/export/raw-keys`	`raw` 内で参照できる keypath 一覧(`?fields=` の補助)

ドキュメントとログ

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

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

セキュリティ上の注意

WARNING

既定のループバック限定設定が最も安全です。 LAN に公開する場合は、必ず認証を有効化してください。

認証トークンは十分に長くランダムな文字列にしてください。
ファイアウォール越しに直接インターネットへ公開しないでください。 外部からアクセスする必要がある場合は VPN や逆プロキシ経由を推奨します。
認証を無効にしたまま許可 IP にループバック以外のアドレスを含めると、無認証でリモートからプロジェクトを読み取れる状態になります。UI 側はこの組み合わせを弾き、設定を直接編集した場合もサーバー起動時に拒否されます。
ブラウザ経由の DNS リバインディング攻撃に対しては、Origin ヘッダが付くリクエストを Host と照合してクロスオリジンを遮断します。