README.md

metadata

title: Copa Video Kling
emoji: 👁
colorFrom: indigo
colorTo: pink
sdk: gradio
sdk_version: 5.34.1
app_file: app.py
pinned: false

Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

Kling AI Creative Toolkit

🎬 UseAPI.net経由でKling AIのAPIを使用した高品質なループ動画生成ツール

📋 主要機能

動画生成

• ループ動画生成: 開始フレームと終了フレームからシームレスなループ動画を作成
• AI自動プロンプト分割: OpenAI APIを使用した高度なプロンプト生成（日本語→英語自動翻訳対応）
• 複数モデル対応:
  • Kling v2-1（最新モデル、高品質）- 中間クリップ生成用
  • Kling v1-6 Professional（tail_image対応）- 最終ループ生成用
  • Kling v1-5（基本モデル）- フォールバック用

🚀 セットアップ

1. 依存関係のインストール

pip install -r requirements.txt

2. 環境変数の設定

.envファイルを作成し、以下の内容を記入してください：

# UseAPI.net認証情報（必須）
# UseAPI.netは、Kling AIへのアクセスを提供するサードパーティAPIサービスです
# MEMBERSHIPプランが必要（v2モデル使用のため）
USEAPI_NET_TOKEN=your_useapi_net_token_here
USEAPI_NET_EMAIL=your_email@example.com  # オプション - 複数アカウント利用時

# OpenAI API認証情報（オプション）
# AI自動プロンプト分割、画像解析機能を使用する場合
OPENAI_API_KEY=your_openai_api_key_here

注意: UseAPI.netのトークンは https://useapi.net で取得できます。 Kling v2モデルを使用するにはMEMBERSHIPプランへのアップグレードが必要です。

3. アプリケーションの起動

python app.py

ブラウザで http://localhost:7860 にアクセスしてください。

📝 使い方

動画生成

1. 開始フレームと終了フレームをアップロード
2. プロンプトを入力（日本語OK - 自動英訳されます）
3. 動画の長さを設定（0.5分〜10分）
4. AI自動プロンプト分割を有効化（オプション）
5. 「ループ動画を生成」をクリック

🔧 技術仕様

API仕様

• APIプロバイダー: UseAPI.net（Bearer Token認証）
• 非同期処理: タスクのポーリング（最大60分、指数バックオフ）
• 同時実行制限: 1タスク（完了まで待機）

画像仕様

• 最小サイズ: 300x300px
• 最大サイズ: 10MB
• 動画用アスペクト比: 16:9, 9:16, 1:1（厳密なチェック）

動画仕様

• 生成単位: 5秒または10秒のクリップ
• 最大プロンプト: 2,500文字
• 動画時間: 0.5〜10分

🏗️ アーキテクチャ

コアモジュール

• app.py: Gradioベースのメインアプリケーション
• utils/kling_api.py: UseAPI.net Kling AI APIクライアント
• utils/openai_api.py: OpenAI統合（プロンプト分割、画像解析）
• utils/video_processing.py: OpenCV/FFmpegによる動画処理

主要な設計パターン

• 非同期通信: httpxによる非同期HTTP通信
• 並行処理: ProcessPoolExecutorでCPU集約的なタスクを処理
• 一時ファイル管理: TempFileManagerによる自動クリーンアップ
• エラーハンドリング: グレースフルフォールバック（OpenAIはオプショナル）

🧪 テスト

テストの実行

# 全テストを実行
python tests/run_all_tests.py

# 個別のテストを実行
python tests/test_image_validation.py
python tests/test_video_processing.py
python tests/test_kling_api.py

注意: このプロジェクトはpytestやunittestではなく、シンプルなassert文によるテストフレームワークを使用しています。

📂 ディレクトリ構造

copa-video-kling/
├── app.py                  # メインアプリケーション
├── utils/                  # ユーティリティモジュール
│   ├── __init__.py
│   ├── kling_api.py       # Kling AI APIクライアント
│   ├── openai_api.py      # OpenAI統合
│   └── video_processing.py # 動画処理
├── tests/                  # テストスイート
├── logs/                   # タスクログ（JSON形式）
├── output/                 # 生成された画像・動画
├── temp/                   # 一時ファイル（自動削除）
└── requirements.txt        # 依存関係

🔒 セキュリティ

• APIトークンは環境変数で管理
• 一時ファイルは自動的にクリーンアップ
• アップロードされたファイルは処理後に削除

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

よくある問題

1. 「APIが初期化されていません」エラー

   • .envファイルにUSEAPI_NET_TOKENが正しく設定されているか確認
   • UseAPI.netのMEMBERSHIPプランに加入しているか確認

2. 「アスペクト比が対応していません」エラー

   • 動画生成: 16:9, 9:16, 1:1のいずれかにリサイズ
   • 画像生成: サポートされているアスペクト比を選択

3. タスクのタイムアウト

   • 生成には時間がかかる場合があります（最大60分）
   • 同時に実行できるタスクは1つのみ

📊 使用状況とコスト

• Kling v2-1: 中間クリップ生成（高速・低コスト）
• Kling v1-6 Professional: 最終ループ生成（高品質・高コスト）
• コストはUseAPI.netの料金体系に従います

🤝 貢献

バグ報告や機能提案はIssuesまでお願いします。

📄 ライセンス

このプロジェクトはMITライセンスの下で公開されています。