zyt-avatar（zyt 头像）

Chanjing Avatar

When to Use This Skill

Use this skill when the user wants to create lip-sync avatar videos with Chanjing Avatar.

Typical uses:

• create text-driven lip-sync videos from a source avatar video
• create audio-driven lip-sync videos from a source avatar video plus uploaded audio
• upload video or audio assets and obtain file_id
• create a lip-sync generation task
• poll task status until completion and return the remote video URL

How to Use This Skill

This skill includes its own local configuration and authentication flow.

Local Configuration

This skill reads credentials from:

• ~/.chanjing/credentials.json
• or $CHANJING_CONFIG_DIR/credentials.json

The credentials file should contain:

{
  "app_id": "<your_app_id>",
  "secret_key": "<your_secret_key>"
}

Supported environment variables:

• CHANJING_CONFIG_DIR: custom local config directory
• CHANJING_API_BASE: custom API base URL, default is https://open-api.chanjing.cc

If credentials are missing or invalid, scripts return login guidance with the official Chanjing login URL (no browser auto-open by default):

• https://www.chanjing.cc/openapi/login

Optional behavior:

• set CHANJING_AUTO_OPEN_LOGIN=1 only when you explicitly want local scripts to try opening the login page in your default browser.

Standard Workflow

All API calls use JSON and UTF-8.

1. Read local credentials and obtain a valid access_token
2. Upload the source avatar video and optional driving audio to obtain file_id
3. Create a lip-sync task with either:

- text-driven TTS input, or - uploaded audio input

1. Poll the task status until success or failure
2. On success, return the remote video URL from the API response

By default, return the remote video URL only. Do not auto-download the generated video unless the user explicitly asks to save it locally.

Covered APIs

This skill currently covers:

• POST /open/v1/access_token
• GET /open/v1/common/create_upload_url
• GET /open/v1/common/file_detail
• POST /open/v1/video_lip_sync/create
• POST /open/v1/video_lip_sync/list
• GET /open/v1/video_lip_sync/detail

Scripts

Scripts are located in scripts/.

Usage Examples

TTS-driven lip-sync

# 0. Configure credentials
python scripts/chanjing-config \
  --ak "<your_app_id>" \
  --sk "<your_secret_key>"

# 1. Upload source video and get video_file_id
VIDEO_FILE_ID=$(python scripts/upload_file \
  --service lip_sync_video \
  --file ./my_video.mp4)

# 2. Create a TTS-driven lip-sync task
TASK_ID=$(python scripts/create_task \
  --video-file-id "$VIDEO_FILE_ID" \
  --text "君不见黄河之水天上来" \
  --audio-man-id "C-f2429d07554749839849497589199916")

# 3. Poll until completion and get the remote video URL
python scripts/poll_task --id "$TASK_ID"

Audio-driven lip-sync

# 1. Upload source video
VIDEO_FILE_ID=$(python scripts/upload_file \
  --service lip_sync_video \
  --file ./my_video.mp4)

# 2. Upload driving audio
AUDIO_FILE_ID=$(python scripts/upload_file \
  --service lip_sync_audio \
  --file ./my_audio.wav)

# 3. Create an audio-driven lip-sync task
TASK_ID=$(python scripts/create_task \
  --video-file-id "$VIDEO_FILE_ID" \
  --audio-file-id "$AUDIO_FILE_ID")

# 4. Poll until completion and get the remote video URL
python scripts/poll_task --id "$TASK_ID"

API Notes

Access Token

Read app_id and secret_key from the local credentials file. If there is no valid token, request one from:

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

Request body:

{
  "app_id": "<from local credentials>",
  "secret_key": "<from local credentials>"
}

Important response fields:

Common status codes:

Upload Media Files

Before creating a lip-sync task, upload the source avatar video and optional driving audio through the File Management API.

Get upload URL

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

Query parameters:

The response includes:

• sign_url
• mime_type
• file_id

Use the returned sign_url with HTTP PUT to upload the file, and set Content-Type to the returned mime_type.

After upload completes, poll the file detail API until the file is ready:

GET /open/v1/common/file_detail?id={{file_id}}
access_token: {{access_token}}

Only use the returned file_id for task creation after the file status is ready.

Create Lip-Sync Task

Create a lip-sync task:

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

TTS-driven example

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

Audio-driven example

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

Important request fields:

Successful response:

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

Important response fields:

Query Task List

List lip-sync tasks:

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

Request body:

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

Important response fields in each task item:

Poll Task Detail

Poll task status until completion:

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

Query parameter:

Important response fields:

Callback Notification

If a callback URL is provided, the system may send a POST request after task completion with the same task detail payload shape.

Output Convention

Default behavior:

• return the remote video URL from data.video_url
• return task status and progress when polling
• do not auto-download the generated file unless the user explicitly asks