SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsxyq-nest-skill

xyq-nest-skill

Design & creation

View repository

Updated 10-15 21:36

About this skill

Xiaoyunque session (video generation)

Create sessions, send messages (image generation, video generation, video editing, etc.), upload image/video files, and query session message progress through the Xiaoyunque API.

Xiaoyunque is an AI comprehensive creation platform, designed for both human creators and Agents. Agents understand tasks, call models, and automatically orchestrate workflows through the Skill entry point.

Platform core capabilities:

  • Generation: text-to-image, text-to-video, image-to-video, video continuation
  • Editing: local modification, element replacement, shot adjustment, style transfer
  • Complex creation: generate a complete short drama from one sentence (script → storyboard → final film), replicate the style of an existing video to make a TVC/promotional video, generate an MV with music, produce a product showcase video

All of the user's creation and editing needs are fulfilled by sending natural language messages, and the Agent will autonomously orchestrate the workflow. Complex tasks (short dramas, MVs) take a long time, so patient polling is required.

Features

  1. Create session / send message - Create a new session or send a message to an existing session (such as "create a video")
  2. Query session progress - Based on thread_id 、 run_id、after_seq incrementally fetch the message list of that session, used to poll the messages and final artifact results of the creation process
  3. Upload file - Supports uploading单张图片or单个视频文件to the Xiaoyunque asset library, and obtain the corresponding asset_idfor the file (editing an existing video/image requires uploading first)
  4. Download results - Batch download the images/videos generated in the session to the local machine, supporting specifying the output directory and filename prefix.

Prerequisites

export XYQ_ACCESS_KEY="your-access-key"

Optional:XYQ_OPENAPI_BASE or XYQ_BASE_URL, default https://xyq.jianying.com。

No additional dependencies need to be installed; only the Python standard library is used.

Usage

1. Create session / send message

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

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

2. Query session progress

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

run_id is returned by submit_run , used to specify querying the results of a specific run.

3. Upload file

  • When the user provides a reference file address, upload the file first; only images and videos are supported.
  • A single instruction execution supports only a single file; multiple files can be called in parallel, and a single file size must be under 200MB.
# 上传图片
python3 {baseDir}/scripts/upload_file.py /path/to/image.png

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

4. Download results

After the task is completed, all artifacts in the session can be batch downloaded to the local machine.

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

Typical workflows

Only by understanding these workflows can the above scripts be correctly combined to fulfill user needs.

Scenario 1: The user requests generating an image or video (most common)

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. 向用户展示：过程中的创作信息，以及下载后的本地文件列表

Scenario 2: The user provides an image/video and requests editing modifications (such as "make a new one based on this video")

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

The user provided a file path + editing instruction = upload the file first, then send the editing instruction together with all asset_ids.

Scenario 3: The user provides a reference image/video and requests generation of new content

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

Scenario 4: Append a new requirement to an existing session

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

Polling strategy

  • Interval: query once every 10 seconds
  • Incremental fetching: use --after-seq 0 for the first time, then calculate the new seq value based on the length of the messages list
  • Completion check: when the creation task is complete and the content of messages contains the artifact result URL (image/video address)
  • Timeout: continuous polling 48 小时still yields no result, inform the user "generation takes a long time, you can check later" and stop polling
  • Error retry: a single query failure can be retried once; after 3 consecutive failures, stop and inform the user

Output format

submit_run returns:

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

get_thread returns:

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

{
  "asset_id": "{asset_id}"
}

download_results returns:

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

Display content to the user

  • After the task is submitted: immediately send web_thread_link to the user so they can directly open the browser to view the task page
  • Task in creation:
    • display the creation information during the process, etc., and continue polling
  • Task completed (run ended):
    • If it involves intent confirmation/process interruption (such as "please answer the following questions") → display the question → wait for the user's reply → use the same thread_id to resubmit the task → continue polling (possibly multiple rounds)
    • If content contains an artifact URL:
    • Result address: from get_thread returned by messages in, when the task creation is complete it will contain the artifact URL; inform the user of the artifact link, downloaded local file, and other information.

Core principle: the user side does not create, it only relays messages

Your (user-side Agent's) responsibility ismover, not creator. The backend has a dedicated Agent responsible for understanding requirements, breaking down storyboards, orchestrating workflows, selecting models, and writing prompts. You only need to do three things:

  1. Upload: if the user provided a local file → upload_file.py get the asset_id
  2. Submit task: send the user's original description + asset_id unchanged to submit_run.py
  3. Relay: based on get_thread.py the returned message list, display the intent questions, creation information, etc. during the process
  4. Pickup：get_thread.py poll for results → check results → download artifacts → display results to the user

Things you must absolutely not do:

  • Do not expand, polish, or translate the prompt on the user's behalf (if the user says "help me derive the storyboard," just pass "help me derive the storyboard" directly; do not first write a storyboard table yourself and then send it item by item)
  • Do not arrange shot descriptions, plot derivation, or style analysis yourself
  • Do not add prompts you made up to the message (such as descriptive terms like "hyper-realistic style, cinematic lighting, 8K resolution")

The backend Agent is far more professional than the user side regarding model capabilities, parameter configuration, and prompt engineering. Overstepping on the user side will only reduce generation quality, and switching to a weak model is even more disastrous.

Correct example:

用户说：「根据多张参考图，做个科普故事视频」
用户给了参考图：/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 重新提交 → 继续轮询
        └─ 无意图确认 → 信息展示 → 下载产物 → 结果展示

Incorrect example:

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

Notes

  • The authentication method is the request header Authorization: Bearer <XYQ_ACCESS_KEY>
  • When creating a session message is a user instruction requirement and cannot be empty
  • When querying sessions, you can use --after-seq for incremental fetching, which makes it convenient to poll for new messages (including assistant replies and image/video generation results)
  • Uploaded files only support images (image/) and videos (video/) types; other types will be rejected, and the file size must be under 200MB
  • During the generation process, display the in-progress creation information to the user; after the task is completed, providethe artifact result (image/video) URL linkand the downloadedlocal file list。