chanjing-avatar

Name: chanjing-avatar
Author: chanjing-ai

github.com/chanjing-aiクリエイティブ・メディア22107 回インストール6 日前に更新

chanjing-avatar について

蝉镜 Avatar Open API を使って、リップシンクしたデジタルアバター動画を作成するスキルです。テキストまたは音声を使うワークフロー向けに、メディアのアップロード、タスク作成、状態確認、結果リンク取得用の Python スクリプトを備えています。

主な機能

01動画と音声素材のアップロード
02テキストまたは音声駆動のリップシンクタスク作成
03動画解像度と音声パラメーターの設定
04タスク状態のポーリングと結果リンク取得
05タスク完了コールバックへの対応

活用シーン

01アバター動画にテキスト読み上げのリップシンクを追加
02既存の音声素材と動画素材を同期
03複数のリップシンクタスクの進捗確認
04完了した動画のダウンロードリンク取得

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/chanjing-ai/chan-skills --skill chanjing-avatar

インストール後、Claude Code で/chanjing-avatarを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

manifest.yaml

scripts/

_auth.py

create_task.py

get_upload_url.py

poll_task.py

upload_file.py

詳細

Chanjing Avatar（リップシンク）

機能の説明

蝉镜 Avatar Open API を呼び出します。音声・動画素材のアップロード、リップシンクタスクの作成、ポーリング、結果リンクの取得を行います。スクリプトは Python の HTTP／アップロードクライアントで、ffmpeg/ffprobe には依存しません。

実行時の依存関係

python3 と同じリポジトリ内の scripts/*.py
ffmpeg/ffprobe によるゲートなし

環境変数と機械可読な宣言

環境変数のキー名と説明：manifest.yaml（environment セクション）および本文
変数、認証情報、コンプライアンス関連の permissions、clientPermissions、agentPolicy：manifest.yaml

実行コマンド

ClawHub（slug はレジストリに準拠）：clawhub run chanjing-avatar
このリポジトリ：python skills/chanjing-avatar/scripts/create_task.py …（手順は本文の 使用方法 を参照）

登録と審査（単一の信頼できる情報源）

主要な認証情報、アップロード／ダウンロードの境界、ブラウザーの動作などについては、manifest.yaml を参照してください。本記事の 使用方法 以降では API の手順を説明します。

このスキルを使用する場面

ユーザーが、口の動きが同期したリップシンク動画（デジタルアバター動画）の作成を必要としている場合に、このスキルを使用します。

Chanjing Avatar は次の機能をサポートしています。

テキストまたは音声によるリップシンク
TTS 用の複数のシステム音声
動画解像度のカスタマイズ
タスクステータスのポーリングとコールバック

このスキルの使用方法

前提条件：このスキルを実行する前に、必ず chanjing-credentials-guard を通じて AK/SK と Token の検証を完了してください。認証情報と審査項目の照合については manifest.yaml を参照してください。

セキュリティと認証情報（参照）

manifest.yaml の credentials と clientPermissions（ローカルアップロード、結果 URL、ブラウザーの動作を含む）を参照してください。コンプライアンスについては、トップレベルの permissions を参照してください。

複数の API を呼び出す必要があります。すべての API で共通のドメインは「https://open-api.chanjing.cc」です。すべてのリクエストは json 形式で通信します。このタスク全体を通して、テキストのエンコードとデコードには UTF-8 を使用してください。

後続のすべての API 呼び出しに必要な access_token を取得します
ファイル管理 API を使用して動画／音声ファイルをアップロードし、file_id を取得します
これらの file_id を使用して、動画と音声／テキストを指定したリップシンクタスクを作成します
タスク詳細照会 API をポーリングするか、タスクリスト API を使用してステータスを確認します
ステータスが完了になったら、レスポンス内の URL を使用して生成された動画をダウンロードします

AccessToken の取得

~/.chanjing/credentials.json から app_id と secret_key を読み取ります。有効な Token がない場合は、次を呼び出します。

POST /open/v1/access_token
Content-Type: application/json

リクエストボディ（ローカルに設定された app_id、secret_key を使用）：

{
  "app_id": "<从 credentials.json 读取>",
  "secret_key": "<从 credentials.json 读取>"
}

レスポンスの例：

{
  "trace_id": "8ff3fcd57b33566048ef28568c6cee96",
  "code": 0,
  "msg": "success",
  "data": {
    "access_token": "1208CuZcV1Vlzj8MxqbO0kd1Wcl4yxwoHl6pYIzvAGoP3DpwmCCa73zmgR5NCrNu",
    "expire_in": 1721289220
  }
}

レスポンスフィールドの説明：

第1階層のフィールド	第2階層のフィールド	説明
code		レスポンスステータスコード
msg		レスポンスメッセージ
data		レスポンスデータ
	access_token	有効期間は1日です。以前のトークンは無効になります
	expire_in	トークンの有効期限

レスポンスステータスコードの説明

コード	説明
0	成功
400	パラメーターの形式が無効です
40000	パラメーターエラー
50000	システム内部エラー

メディアファイルのアップロード（ファイル管理）

リップシンクタスクを作成する前に、ファイル管理 API を使用して動画（および任意の音声）ファイルを必ずアップロードし、file_id を取得してください。

ドキュメント全文はこちらです：ファイル管理。

手順1：アップロード URL の取得

GET /open/v1/common/create_upload_url
access_token: {{access_token}}

クエリパラメーター：

キー	例	説明
service	lip_sync_video / lip_sync_audio	ファイルの用途です。駆動用動画には `lip_sync_video` を、音声駆動の場合は音声に `lip_sync_audio` を使用します。
name	1.mp4	拡張子を含む元のファイル名

レスポンスには sign_url、mime_type、file_id が含まれます。sign_url を使用して HTTP PUT でファイルをアップロードし、Content-Type には返された mime_type を設定します。PUT の完了後、ファイルの準備ができるまでファイル詳細 API をポーリングしてください（一定時間待てばよいと仮定しないでください）。返された file_id は、以下の video_file_id／audio_file_id に使用するため保存してください。

ポーリング： access_token を指定して GET /open/v1/common/file_detail?id={{file_id}} を呼び出し、レスポンスの data.status が成功を示すまでポーリングします（例：status === 2）。その後でのみ、タスク作成 API に file_id を使用してください。

リップシンクタスクの作成

リップシンク動画の作成タスクを送信します。後でポーリングするための動画 ID が返されます。

POST /open/v1/video_lip_sync/create
access_token: {{access_token}}
Content-Type: application/json

リクエストボディの例（TTS 駆動）：

{
  "video_file_id": "e284db4d95de4220afe78132158156b5",
  "screen_width": 1080,
  "screen_height": 1920,
  "callback": "https://example.com/openapi/callback",
  "model": 0,
  "audio_type": "tts",
  "tts_config": {
    "text": "君不见黄河之水天上来，奔流到海不复回。",
    "audio_man_id": "C-f2429d07554749839849497589199916",
    "speed": 1,
    "pitch": 1
  }
}

リクエストボディの例（音声駆動）：

{
  "video_file_id": "e284db4d95de4220afe78132158156b5",
  "screen_width": 1080,
  "screen_height": 1920,
  "model": 0,
  "audio_type": "audio",
  "audio_file_id": "audio_file_id_from_file_management"
}

リクエストフィールドの説明：

パラメーター名	型	必須	説明
video_file_id	string	はい	File Management の動画ファイル ID（`data.file_id`）。mp4、mov、webm に対応
screen_width	int	いいえ	画面の幅。デフォルトは 1080
screen_height	int	いいえ	画面の高さ。デフォルトは 1920
backway	int	いいえ	再生終了時の再生順：1-通常、2-逆再生。デフォルトは 1
drive_mode	string	いいえ	駆動モード：""-通常、"random"-ランダムフレーム。デフォルトは ""
callback	string	いいえ	非同期通知用のコールバック URL
model	int	いいえ	モデルのバージョン：0-基本、1-高品質。デフォルトは 0
audio_type	string	いいえ	音声の種類："tts"-テキスト駆動、"audio"-音声駆動。デフォルトは "tts"
tts_config	object	はい（tts の場合）	audio_type="tts" の場合の TTS 設定
tts_config.text	string	はい（tts の場合）	合成するテキスト
tts_config.audio_man_id	string	はい（tts の場合）	音声 ID
tts_config.speed	number	いいえ	話速：0.5～2。デフォルトは 1
tts_config.pitch	number	いいえ	ピッチ。デフォルトは 1
audio_file_id	string	はい（audio の場合）	`audio_type="audio"` の場合の File Management の音声ファイル ID（`data.file_id`）。mp3、m4a、wav に対応
volume	int	いいえ	音量：1～100。デフォルトは 100

レスポンスの例：

{
  "trace_id": "8d10659438827bd4d59eaa2696f9d391",
  "code": 0,
  "msg": "success",
  "data": "9499ed79995c4bdb95f0d66ca84419fd"
}

レスポンスフィールドの説明：

フィールド	説明
code	レスポンスのステータスコード
msg	レスポンスメッセージ
data	後続のポーリングに使用する動画 ID

タスクリストの取得

リップシンクタスクの一覧を取得します。

POST /open/v1/video_lip_sync/list
access_token: {{access_token}}
Content-Type: application/json

リクエストボディ：

{
  "page": 1,
  "page_size": 10
}

リクエストフィールドの説明：

パラメーター	型	必須	説明
page	int	いいえ	ページ番号。デフォルトは 1
page_size	int	いいえ	ページサイズ。デフォルトは 10

レスポンスの例：

{
  "trace_id": "8d10659438827bd4d59eaa2696f9d391",
  "code": 0,
  "msg": "success",
  "data": {
    "list": [
      {
        "id": "9499ed79995c4bdb95f0d66ca84419fd",
        "status": 20,
        "progress": 100,
        "msg": "success",
        "video_url": "https://res.chanjing.cc/xxx/lip-sync/9499ed79995c4bdb95f0d66ca84419fd.mp4",
        "preview_url": "https://res.chanjing.cc/xxx/lip-sync/9499ed79995c4bdb95f0d66ca84419fd.jpg",
        "duration": 300,
        "create_time": 1738636800
      }
    ],
    "page_info": {
      "page": 1,
      "size": 10,
      "total_count": 1,
      "total_page": 1
    }
  }
}

レスポンスフィールドの説明：

第 1 レベルのフィールド	第 2 レベルのフィールド	説明
code		レスポンスのステータスコード
msg		レスポンスメッセージ
data		レスポンスデータ
	list	タスクリスト
		id：動画 ID
		status：タスクのステータス（0-保留中、10-生成中、20-成功、30-失敗）
		progress：進行状況 0～100
		msg：タスクメッセージ
		video_url：動画のダウンロード URL
		preview_url：カバー画像の URL
		duration：動画の長さ（ミリ秒）
		create_time：作成時刻（Unix タイムスタンプ）
	page_info	ページネーション情報

タスク詳細の取得

タスクが完了するまで、次の API をポーリングしてステータスを確認します。

GET /open/v1/video_lip_sync/detail
access_token: {{access_token}}

クエリパラメーター：

パラメーター	説明
id	動画 ID

例：GET /open/v1/video_lip_sync/detail?id=9499ed79995c4bdb95f0d66ca84419fd

レスポンスの例：

{
  "trace_id": "8d10659438827bd4d59eaa2696f9d391",
  "code": 0,
  "msg": "success",
  "data": {
    "id": "9499ed79995c4bdb95f0d66ca84419fd",
    "status": 20,
    "progress": 100,
    "msg": "success",
    "video_url": "https://res.chanjing.cc/xxx/lip-sync/9499ed79995c4bdb95f0d66ca84419fd.mp4",
    "preview_url": "https://res.chanjing.cc/xxx/lip-sync/9499ed79995c4bdb95f0d66ca84419fd.jpg",
    "duration": 300,
    "create_time": 1738636800
  }
}

レスポンスフィールドの説明：

第 1 レベルのフィールド	第 2 レベルのフィールド	説明
code		レスポンスのステータスコード
msg		レスポンスメッセージ
data		レスポンスデータ
	id	動画 ID
	status	タスクのステータス：0-保留中、10-生成中、20-成功、30-失敗
	progress	進行状況 0～100
	msg	タスクメッセージ
	video_url	動画のダウンロード URL
	preview_url	カバー画像の URL
	duration	動画の長さ（ミリ秒）
	create_time	作成時刻（Unix タイムスタンプ）

コールバック通知

コールバック URL が指定されている場合、タスクの完了時にシステムから POST リクエストが送信されます。

{
  "trace_id": "8d10659438827bd4d59eaa2696f9d391",
  "code": 0,
  "msg": "success",
  "data": {
    "id": "9499ed79995c4bdb95f0d66ca84419fd",
    "status": 20,
    "progress": 100,
    "msg": "success",
    "video_url": "https://res.chanjing.cc/xxx/lip-sync/9499ed79995c4bdb95f0d66ca84419fd.mp4",
    "preview_url": "https://res.chanjing.cc/xxx/lip-sync/9499ed79995c4bdb95f0d66ca84419fd.jpg",
    "duration": 300,
    "create_time": 1738636800
  }
}

スクリプト

この Skill が提供するスクリプト（skills/chanjing-avatar/scripts/）は、chanjing-credentials-guard と同じ設定ファイル（~/.chanjing/credentials.json）を使用して Token を取得します。

スクリプト	説明
`get_upload_url.py`	アップロードリンクを取得し、`sign_url`、`mime_type`、`file_id` を出力します
`upload_file.py`	ローカルファイルをアップロードし、準備が完了するまで file_detail をポーリングした後、`file_id` を出力します
`create_task.py`	リップシンクタスク（TTS または音声駆動）を作成し、動画タスク ID を出力します
`poll_task.py`	タスクが完了するまでポーリングし、`video_url` を出力します

例（プロジェクトルートまたは skill ディレクトリで実行します）：

# 1. 上传驱动视频，得到 video_file_id
VIDEO_FILE_ID=$(python skills/chanjing-avatar/scripts/upload_file.py --service lip_sync_video --file ./my_video.mp4)

# 2. 创建 TTS 对口型任务（需先通过 list_common_audio 获取 audio_man_id）
TASK_ID=$(python skills/chanjing-avatar/scripts/create_task.py \
  --video-file-id "$VIDEO_FILE_ID" \
  --text "君不见黄河之水天上来" \
  --audio-man-id "C-f2429d07554749839849497589199916")

# 3. 轮询直到完成，得到视频下载链接
python skills/chanjing-avatar/scripts/poll_task.py --id "$TASK_ID"

音声駆動の場合：まず音声をアップロードして audio_file_id を取得し、次に create_task.py --video-file-id <id> --audio-file-id <audio_file_id> を実行します。

レスポンスステータスコードの説明

Code	説明
0	レスポンス成功
10400	AccessToken の検証に失敗しました
40000	パラメーターエラー
40001	RPM/QPS の上限を超えています
50000	システム内部エラー

Markdown 対応

ログインしてコメント

基本情報

作者: chanjing-ai
リポジトリ: chanjing-ai/chan-skills
カテゴリ: クリエイティブ・メディア
インストール数: 107
GitHub スター: 22

問題を報告