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:

json

{
  "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
4. Poll the task status until success or failure
5. 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/.

ScriptPurposechanjing-configwrite or inspect local app_id / secret_key configurationchanjing-get-tokenread local credentials and print a valid access_token``_auth.pyread local credentials, fetch or refresh access_token``get_upload_urlrequest an upload URL and return sign_url, mime_type, and file_id``upload_fileupload a local file, poll file_detail until ready, then print file_id``create_taskcreate a lip-sync task and print the returned task idpoll_taskpoll task status until completion and print the remote video_url

Usage Examples#

TTS-driven lip-sync#

bash

# 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#

bash

# 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:

http

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

Request body:

json

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

Important response fields:

FieldDescriptioncoderesponse status codemsgresponse messagedata.access_tokenvalid token for subsequent callsdata.expire_intoken expiration timestamp

Common status codes:

CodeDescription0success400invalid parameter format40000parameter error50000system internal error

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

http

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

Query parameters:

ParameterDescriptionserviceuse lip_sync_video for avatar video and lip_sync_audio for driving audionameoriginal file name with extension

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:

http

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:

http

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

TTS-driven example

json

{
  "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

json

{
  "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:

FieldDescriptionvideo_file_iduploaded avatar video file_id``screen_widthoutput width, default 1080``screen_heightoutput height, default 1920``model``0 basic, 1 high qualityaudio_type``tts or audio``tts_config.texttext content for TTS-driven modetts_config.audio_man_idvoice ID for TTS-driven modetts_config.speedspeech speed, range 0.5 to 2``tts_config.pitchpitch, usually keep 1``audio_file_iduploaded driving audio file_id for audio-driven modecallbackoptional callback URLvolumeoptional volume, range 1 to 100

Successful response:

json

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

Important response fields:

FieldDescriptioncoderesponse status codemsgresponse messagedatatask id used for polling

Query Task List#

List lip-sync tasks:

http

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

Request body:

json

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

Important response fields in each task item:

FieldDescriptionidtask idstatus``0 pending, 10 generating, 20 success, 30 failedprogressgeneration progressmsgtask messagevideo_urlremote generated video URLpreview_urlpreview image URLdurationvideo duration in mscreate_timeunix timestamp

Poll Task Detail#

Poll task status until completion:

http

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

Query parameter:

ParameterDescriptionidtask id

Important response fields:

FieldDescriptiondata.idtask iddata.status``0 pending, 10 generating, 20 success, 30 faileddata.progressprogress 0-100``data.msgtask messagedata.video_urlremote video URLdata.preview_urlpreview image URLdata.durationvideo duration in msdata.create_timeunix timestamp

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