> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sambanova.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# TwelveLabs

[TwelveLabs](https://www.twelvelabs.io/) は、動画コンテンツを即座に検索可能かつインテリジェントに分析可能にする、最先端の動画理解技術を提供します。SambaNova の高性能な AI モデルと組み合わせることで、教育用動画をインタラクティブなゲームや学習体験へと変換できます。

## 前提条件

* [SambaCloud](https://cloud.sambanova.ai/?utm_source=twelvelabs\&utm_medium=external\&utm_campaign=cloud_signup) アカウントと [API キー](https://cloud.sambanova.ai/apis?utm_source=twelvelabs\&utm_medium=external\&utm_campaign=cloud_signup)。
* [TwelveLabs](https://playground.twelvelabs.io/dashboard/api-key) アカウントと API キー。
* 動画をアップロード済みの TwelveLabs インデックスが 1 つ以上あること (インデックス ID を控えておいてください)。
* Python 3.9 以降のインストール済み環境。
* Node.js 18 以降 (フロントエンドに必要)。
* ローカルマシンにクローンした [Video2Game リポジトリ](https://github.com/Hrishikesh332/Video2Game)。

## セットアップ

この連携では、動画理解に TwelveLabs を、ゲームコードの生成に SambaNova を使用し、教育用動画をインタラクティブな学習体験へと変換できます。

Video2Game プロジェクトは、同時に実行する必要がある 2 つのサービスで構成されています。

* **バックエンド** (Flask、`:8000`) — TwelveLabs による分析と SambaNova による生成を処理します。
* **フロントエンド** (Next.js、`:3000`) — 操作対象となる UI です。

<Steps>
  <Step title="環境変数の設定">
    `backend/.env` を作成します。

    ```bash theme={}
    TWELVELABS_API_KEY=your_twelvelabs_api_key
    TWELVELABS_INDEX_ID=your_twelvelabs_index_id
    SAMBANOVA_API_KEY=your_sambanova_api_key
    SAMBANOVA_BASE_URL=https://api.sambanova.ai/v1
    SAMBANOVA_MODEL=DeepSeek-V3.1   # any current SambaCloud model — see link below
    BASE_URL=http://127.0.0.1:8000
    ```

    モデル ID は、[SambaCloud モデル](/docs/ja/models/sambacloud-models)のページに掲載されている任意のものを指定できます (例: `DeepSeek-V3.1`、`Meta-Llama-3.3-70B-Instruct`、`Llama-4-Maverick-17B-128E-Instruct`)。[モデルの提供終了](/docs/ja/models/deprecations)ページに記載された提供終了済みの ID は避けてください。

    <Note>
      `TWELVELABS_INDEX_ID` は必須です。未設定の場合、バックエンドは `RuntimeError: Missing required configuration` をスローします。
    </Note>

    <Note>
      `SAMBANOVA_MODEL` は、Video2Game が `backend/config.py:18` に提供終了済みのモデルをハードコードしているアップストリームのバグに対する回避策です。アップストリームでの修正 ([Hrishikesh332/Video2Game#1](https://github.com/Hrishikesh332/Video2Game/issues/1)) が反映されるまでは、環境変数から読み取るように `config.py` にパッチを適用してください。

      ```python theme={}
      SAMBANOVA_MODEL = os.getenv("SAMBANOVA_MODEL", "DeepSeek-V3.1")
      ```
    </Note>
  </Step>

  <Step title="バックエンドの依存関係のインストール">
    必要な Python パッケージをインストールします。

    ```bash theme={}
    cd backend
    pip install -r requirements.txt
    ```
  </Step>

  <Step title="バックエンドの起動">
    `backend/` ディレクトリで、以下を実行します。

    ```bash theme={}
    python app.py
    ```

    バックエンドは [http://127.0.0.1:8000](http://127.0.0.1:8000/) で稼働します。
  </Step>

  <Step title="フロントエンドの設定">
    新しいターミナルを開き、リポジトリのルートで `www.video2game.vercel.app/.env.local` を作成します。

    ```bash theme={}
    NEXT_PUBLIC_API_URL=http://127.0.0.1:8000
    ```
  </Step>

  <Step title="フロントエンドのインストールと起動">
    ```bash theme={}
    cd www.video2game.vercel.app
    npm install --legacy-peer-deps
    npm run dev
    ```

    アプリは [http://localhost:3000](http://localhost:3000) で開きます。
  </Step>

  <Step title="動画からのゲーム生成">
    1. [http://localhost:3000](http://localhost:3000) を開きます。
    2. **TwelveLabs** タブをクリックします。
    3. TwelveLabs の API キーを入力し、**Connect** をクリックします。
    4. **Video Index** を選択します (動画がアップロード済みのインデックスのみ表示されます)。
    5. **Video** を選択します。
    6. **Generate from TwelveLabs** をクリックすると、SambaNova を利用したインタラクティブなゲームが生成されます。

    生成が完了すると、右側のパネルに動画コンテンツから作成されたインタラクティブなゲームが表示されます。**App** (ライブプレビュー) タブと **Code** (生成された HTML) タブを切り替えられます。

    <Frame>
      <img src="https://mintcdn.com/sambanova-systems/C4G2fLYCRAafrtsi/images/docs/integrations/twelvelabs/twelvelabs_1.png?fit=max&auto=format&n=C4G2fLYCRAafrtsi&q=85&s=25737367d6d0f356f3353a34ad9df797" alt="右側のパネルに生成されたインタラクティブなゲームが表示された Video2Game アプリ" width="2988" height="1614" data-path="images/docs/integrations/twelvelabs/twelvelabs_1.png" />
    </Frame>
  </Step>
</Steps>

## トラブルシューティング

<AccordionGroup>
  <Accordion title="`The requested model (DeepSeek-R1-0528) is not available on SambaNova Cloud`">
    アップストリームの Video2Game は、`backend/config.py:18` に提供終了済みの SambaCloud モデルをハードコードしています。該当行を次のようにパッチしてください。

    ```python theme={}
    SAMBANOVA_MODEL = os.getenv("SAMBANOVA_MODEL", "DeepSeek-V3.1")
    ```

    その上で、`backend/.env` に `SAMBANOVA_MODEL=DeepSeek-V3.1` を追加します。この問題はアップストリームの [Hrishikesh332/Video2Game#1](https://github.com/Hrishikesh332/Video2Game/issues/1) で追跡されています。
  </Accordion>

  <Accordion title="バックエンド起動時の `RuntimeError: Missing required configuration`">
    `backend/.env` には 6 つの `.env` キーをすべて設定する必要があります。特に `TWELVELABS_INDEX_ID` にご注意ください。
  </Accordion>

  <Accordion title="Connect 後もインデックスのドロップダウンが空になる">
    お使いの TwelveLabs API キーに、動画がアップロード済みのインデックスが 1 つ以上あることを確認してください。以下で検証できます。

    ```bash theme={}
    curl http://127.0.0.1:8000/indexes -H "X-Twelvelabs-Api-Key: <key>"
    ```
  </Accordion>

  <Accordion title="新規生成ではなく古い/キャッシュ済みのゲームが返される">
    バックエンドは、生成したゲームを `video_id` ごとにキャッシュします。以下のリクエストで再生成を実行できます。

    ```bash theme={}
    curl -X POST http://127.0.0.1:8000/analyze \
      -H "X-Twelvelabs-Api-Key: <key>" \
      -H "Content-Type: application/json" \
      -d '{"video_id": "<video_id>", "regenerate": true}'
    ```
  </Accordion>
</AccordionGroup>

## 参考情報

* [TwelveLabs のドキュメント](https://docs.twelvelabs.io/docs/get-started/introduction)
* [Video2Game リポジトリ](https://github.com/Hrishikesh332/Video2Game)