xyq-nest-skill

小云雀セッション（動画生成）

小云雀のAPIを通じてセッションを作成し、メッセージを送信（画像生成、動画生成、動画編集など）したり、画像／動画ファイルをアップロードしたり、セッションメッセージの進捗を確認したりできます。

小云雀は、人間のクリエイターとエージェントの両方を対象に設計された、AI総合クリエイティブプラットフォームです。エージェントはSkillの入口からタスクを理解し、モデルを呼び出してワークフローを自動的に編成します。

プラットフォームの主な機能：

• 生成：テキストから画像を生成、テキストから動画を生成、画像から動画を生成、動画の続きを生成
• 編集：部分修正、要素の置き換え、ショットの調整、スタイル変換
• 複雑な制作：一言で短編ドラマ全体を生成（脚本→絵コンテ→完成映像）、既存動画のスタイルを再現してTVC／プロモーション動画を制作、音楽からMVを生成、製品紹介動画を制作

ユーザーのあらゆる制作・編集の要望は、自然言語のメッセージを送信することで実現します。エージェントがワークフローを自律的に編成します。短編ドラマやMVなどの複雑なタスクは時間がかかるため、根気よくポーリングしてください。

機能

1. セッションの作成／メッセージの送信 - 新しいセッションを作成するか、既存のセッションにメッセージを送信します（例：「動画を作って」）
2. セッションの進捗確認 - thread_id 、 run_id、after_seq に基づいてセッションのメッセージ一覧を差分取得し、制作過程のメッセージや最終成果物をポーリングします
3. ファイルのアップロード - 小云雀のアセットライブラリに画像1枚または動画ファイル1つをアップロードし、ファイルに対応する asset_id を取得します（既存の動画／画像を編集する場合は、先にアップロードが必要です）
4. 結果のダウンロード - セッションで生成された画像／動画をまとめてローカルにダウンロードします。出力ディレクトリとファイル名のプレフィックスを指定できます。

前提条件

export XYQ_ACCESS_KEY="your-access-key"

任意：XYQ_OPENAPI_BASE または XYQ_BASE_URL。デフォルトは https://xyq.jianying.com です。

追加の依存関係のインストールは不要で、Python標準ライブラリのみを使用します。

使用方法

1. セッションの作成／メッセージの送信

# 创建新会话并发送「生一个动漫视频」
python3 {baseDir}/scripts/submit_run.py --message "生一个动漫视频"

# 向已有会话发送消息
python3 {baseDir}/scripts/submit_run.py --message "再生成一个故事视频" --thread-id THREAD_ID

2. セッションの進捗確認

# 查询会话消息列表
python3 {baseDir}/scripts/get_thread.py --thread-id THREAD_ID --run-id RUN_ID --after-seq SEQUENCE

run_id は submit_run が返す値で、特定の実行結果を指定するために使用します。

3. ファイルのアップロード

• ユーザーから参照ファイルのパスが提供された場合は、先にファイルをアップロードしてください。対応しているのは画像と動画のみです。
• 1回のコマンド実行でアップロードできるファイルは1つだけです。複数のファイルは並行して呼び出せます。ファイルサイズは200MB未満である必要があります。

# 上传图片
python3 {baseDir}/scripts/upload_file.py /path/to/image.png

# 上传视频
python3 {baseDir}/scripts/upload_file.py /path/to/video.mp4

4. 結果のダウンロード

タスクの完了後、セッション内のすべての成果物をまとめてローカルにダウンロードできます。

# 指定 URL 列表，指定输出目录，指定文件名前缀（如 artifact_01.png, artifact_02.png ...）进行下载
python3 {baseDir}/scripts/download_results.py --urls URL1 URL2 URL3 --output-dir ./xyq_output --prefix "artifact"

代表的なワークフロー

以下のワークフローを理解し、上記のスクリプトを適切に組み合わせてユーザーの要望に対応してください。

シナリオ 1：ユーザーが画像または動画の生成を依頼する（最も一般的）

1. submit_run.py --message "用户的描述"  →  拿到 thread_id、run_id 和 web_thread_link
2. **立即**将 `web_thread_link` 展示给用户（如"任务已提交，可在此查看：{web_thread_link}"）
3. 每隔 `10` 秒钟调用 get_thread.py --thread-id THREAD_ID --run-id RUN_ID --after-seq SEQUENCE 进行轮询
4. 检查 messages：
  - 当任务还在创作中：
    - 将过程创作信息展示给用户，继续轮询
  - 当任务完成（run 结束）：
    - 如果涉及意图确认/流程中断（如"请回答以下问题"）：
      → 向用户展示问题，等待用户回复
      → 使用 `thread_id` 重新提交任务（保持同一会话，产生新的 run_id）
      → 回到步骤 2 继续轮询（可能多轮，直到不再意图确认）
    - 如果 content 中包含产物 URL：
      → 信息展示 → 下载产物 → 结果展示
5. 自动下载：download_results.py --urls URL1 URL2 URL3 --output-dir 输出目录 --prefix 有意义的前缀
6. 向用户展示：过程中的创作信息，以及下载后的本地文件列表

シナリオ 2：ユーザーが画像／動画を提供し、編集を依頼する（例：「この動画を参考に新しい動画を作って」）

1. upload_file.py /path/to/video.mp4  →  拿到 asset_id
2. submit_run.py --message "参考这个视频做一个新的" --asset-ids asset_id  →  拿到 thread_id、run_id、web_thread_link
3. 后续同场景 1 的步骤 2-6

ユーザーからファイルパスと編集指示が提供された場合は、まずファイルをアップロードし、編集指示とすべてのasset_idを一緒に送信します。

シナリオ 3：ユーザーが参考画像／動画を提供し、新しいコンテンツの生成を依頼する

1. upload_file.py /path/to/ref1.png  →  拿到 asset_id1
2. upload_file.py /path/to/ref2.mp4  →  拿到 asset_id2
3. 直到所有文件上传完成，拿到所有 asset_id
4. submit_run.py --message "根据参考图、视频生成xxx" --asset-ids asset_id1 asset_id2, ...  →  拿到 thread_id、run_id、web_thread_link
5. 后续同场景 1 的步骤 2-6

シナリオ 4：既存のセッションに新しい要望を追加する

1. submit_run.py --message "新的描述" --thread-id THREAD_ID  →  拿到 thread_id、run_id、web_thread_link
2. 后续同场景 1 的步骤 2-6

ポーリング戦略

• 間隔：10秒ごとに1回確認します
• 差分取得：初回は --after-seq 0 を使用し、以降はmessages一覧の長さに基づいて新しいseq値を計算します
• 完了判定：制作タスクが完了し、messagesのcontentに成果物の結果URL（画像／動画のアドレス）が含まれている場合
• タイムアウト：48時間ポーリングを続けても結果がない場合は、ユーザーに「生成に時間がかかっています。しばらくしてからご確認ください」と伝え、ポーリングを終了します
• エラー時の再試行：1回の確認に失敗した場合は1回再試行します。3回連続で失敗した場合は停止し、ユーザーに伝えます

出力形式

submit_run の戻り値：

{
  "thread_id": "90f05e0c-...",
  "run_id": "abc123-...",
  "web_thread_link": "https://xyq.jianying.com/..."
}

get_thread の戻り値：

{
  "messages": [
    {"id": "1", "role": "user", "content": "生一个动漫视频"},
    {"id": "2", "role": "assistant", "content": [
      {
        "type": "{type}",
        "subtype": "{sub_type}",
        "data": {...}
      }
    ]},
    {"id": "3", "role": "assistant", "content": [
      {
        "type": "{type}",
        "subtype": "{sub_type}",
        "data": {..., "url": "{url}"....}
      }
    ]}
  ]
}

upload_file の戻り値：

{
  "asset_id": "{asset_id}"
}

download_results の戻り値：

{
  "output_dir": "./xyq_output",
  "downloaded": ["./xyq_output/01.png", "..."],
  "total": 10
}

ユーザーへの表示内容

• タスクの送信後：web_thread_link をすぐにユーザーに表示し、ブラウザーからタスクページを直接開けるようにします
• タスクの制作中：
  • 制作過程の情報などを表示し、ポーリングを続けます
• タスクの完了（runの終了）：
  • 意図の確認やフローの中断が発生した場合（例：「以下の質問に回答してください」）→ 質問を表示 → ユーザーの返信を待つ → 同じ thread_id でタスクを再送信 → ポーリングを続ける（複数回行う場合があります）
  • contentに成果物のURLが含まれている場合：
  • 結果のアドレス：get_thread が返す messages に含まれます。制作タスクが完了すると成果物のURLが含まれるため、成果物のリンクやダウンロードしたローカルファイルなどの情報をユーザーに伝えます。

基本原則：ユーザー側では制作せず、伝言だけを行う

あなた（ユーザー側のエージェント）の役割は運び役であり、クリエイターではありません。バックエンドには、要望の理解、絵コンテの分解、ワークフローの編成、モデルの選択、プロンプトの作成を担当する専用エージェントがいます。あなたが行うことは次の4つだけです。

1. アップロード：ユーザーがローカルファイルを提供した場合 → upload_file.py で asset_id を取得
2. タスクの送信：ユーザーの元の説明とasset_idを一切変更せずに submit_run.py へ送信
3. 伝達：get_thread.py が返すメッセージ一覧に基づき、制作過程の意図確認や制作情報などを表示
4. 受け取り：get_thread.py で結果をポーリング → 結果を確認 → 成果物をダウンロード → 結果をユーザーに表示

絶対にしてはいけないこと：

• ユーザーの代わりにプロンプトを膨らませたり、整えたり、翻訳したりしないでください（ユーザーが「絵コンテを考えて」と言ったら、そのまま「絵コンテを考えて」と伝えてください。自分で先に絵コンテを作成し、項目ごとに送ることはしないでください）
• ショットの説明、ストーリーの展開、スタイル分析を独自に編成しないでください
• メッセージに自分で考えたプロンプトを追加しないでください（「超写実的なスタイル、映画のような照明、8K解像度」などの描写語）

バックエンドのエージェントは、モデルの能力、パラメーター設定、プロンプトエンジニアリングについて、ユーザー側よりはるかに専門的です。ユーザー側が差し出がましく介入すると生成品質を下げるだけであり、弱いモデルに置き換えるのはさらに問題です。

正しい例：

用户说：「根据多张参考图，做个科普故事视频」
用户给了参考图：/path/to/ref1.png, /path/to/ref2.png, /path/to/ref3.png

→ upload_file.py /path/to/ref1.png →  拿到 asset_id1
→ upload_file.py /path/to/ref2.png →  拿到 asset_id2
→ upload_file.py /path/to/ref3.png →  拿到 asset_id3
→ submit_run.py --message "根据参考图、视频生成xxx" --asset-ids asset_id1 asset_id2, asset_id3  →  拿到 web_thread_link，立即展示给用户
→ 轮询 ─┬─ 意图确认 → 用户确认 → 使用 thread_id 重新提交 → 继续轮询
        └─ 无意图确认 → 信息展示 → 下载产物 → 结果展示

誤った例：

❌ 用户侧自己先写了个九宫格分镜表（对峙、交锋、危机...）
❌ 然后把自己编的描述发给后端
❌ 或者拆成9次 submit_run 分别发送

注意事項

• 認証にはリクエストヘッダー Authorization: Bearer <XYQ_ACCESS_KEY> を使用します
• セッション作成時の message はユーザーの指示であり、空にできません
• セッションの確認には --after-seq を使用して差分取得できます。新しいメッセージ（assistantの返信、画像／動画生成の結果を含む）のポーリングに便利です
• アップロードできるのは画像（image/）と動画（video/）のみです。それ以外のファイル形式は拒否されます。ファイルサイズは200MB未満である必要があります
• 生成中は制作過程の情報をユーザーに表示してください。タスク完了後は、成果物（画像／動画）のURLリンクとダウンロードしたローカルファイル一覧を提示してください。