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

xyq-nest-skill

Design & creation

View repository

Updated 10-15 21:47

About this skill

Xiao Yun Que Session (Video Generation)

Create sessions, send messages (generate images, generate videos, edit videos, etc.), upload image/video files, and query session message progress through the Xiao Yun Que API.

Xiao Yun Que is a comprehensive AI 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, camera 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 film, generate an MV with music, produce product showcase films

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 of the creation process and the final artifact results
  3. Upload files - Supports uploading单张图片or单个视频文件to the Xiao Yun Que asset library, obtaining the file's corresponding asset_id(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 returned by submit_run , used to specify querying the results of a specific run.

3. Upload files

  • When the user provides a reference file address, upload the file first; only images and videos are supported.
  • A single command 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 by referencing 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 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 a product result URL (image/video address)
  • Timeout: continuous polling 48 小时still has no result, tell the user "generation is taking a long time, you can check later", and stop polling
  • Error retry: a single query failure can be retried once; if it fails 3 times in a row, stop and tell 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 task submission: immediately display web_thread_link to the user, so the user can directly open the browser to view the task page
  • While the task is being created:
    • 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 → resubmit the task using the same thread_id → continue polling (may be multiple rounds)
    • If content contains a product URL:
    • Result address: from get_thread returned messages , when the task creation is complete it will contain the product URL; inform the user of the product 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 is to be aporter, not a 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 provides 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 the message list returned by get_thread.py , display the intent questions, creation information, etc., during the process
  4. Pick up：get_thread.py poll results → check results → download the product → display the result to the user

Things you must absolutely not do:

  • Do not expand, polish, or translate the prompt for the user (if the user says "help me derive the storyboard", just pass "help me derive the storyboard" directly; do not write a storyboard table yourself and then send it item by item)
  • Do not arrange shot descriptions, plot derivation, or style analysis on your own
  • Do not add prompts you made up yourself in the message (such as descriptive words 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 would be a disaster.

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, use --after-seq for incremental fetching, which is convenient for polling 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 generation, display the creative information from the process to the user; after the task is completed, provide theartifact result (image/video) URL linkand the downloadedlocal file list。