yoco-ppt-video

概述

YOCO PPT Video

Quick Start

Use scripts/yoco_ppt_video_client.mjs for repeatable calls. Configuration can come from environment variables or ~/.yoco_ppt_video_config.json.

Runtime requirements:

• The current helper has been validated with Node.js 24 and targets Node.js 22 or newer.
• Compatibility is determined by runtime capabilities, not only the version string: TTS requires global fetch and WebSocket.
• Run node scripts/yoco_ppt_video_client.mjs runtime-check to verify the current agent environment. Incompatible environments receive an explicit upgrade message before API or TTS execution.

Environment variables take precedence:

export YOCO_BASE_URL="https://www.yoco.me/ims"
export YOCO_SKILL_TOKEN="..."
export YOCO_ALI_TTS_INTERVAL_MS="500"

User-local configuration:

node scripts/yoco_ppt_video_client.mjs config-set --base-url https://www.yoco.me/ims --skill-token "..." --ali-tts-interval-ms 500
node scripts/yoco_ppt_video_client.mjs config-show
node scripts/yoco_ppt_video_client.mjs runtime-check

If no Skill Token is configured, guide the user to:

1. Open https://www.yoco.me.
2. Register or log in to YOCO.
3. Go to the YOCO Skill/Token management page.
4. Create a new Skill Token for the current agent.
5. Return to the agent and provide the token.
6. Save it locally with:

node scripts/yoco_ppt_video_client.mjs config-set --base-url https://www.yoco.me/ims --skill-token "USER_TOKEN"

Common commands:

node scripts/yoco_ppt_video_client.mjs me
node scripts/yoco_ppt_video_client.mjs config-show
node scripts/yoco_ppt_video_client.mjs course-list --json '{"pageNum":1,"pageSize":50}'
node scripts/yoco_ppt_video_client.mjs course-add --json '{"courseName":"AI生成课程"}'
node scripts/yoco_ppt_video_client.mjs template-page --json '{"pageNum":1,"pageSize":10}'
node scripts/yoco_ppt_video_client.mjs template-page --json-file request.json
node scripts/yoco_ppt_video_client.mjs resolve-images --json-file agent-ppt-content.json --output resolved-content.json
node scripts/yoco_ppt_video_client.mjs submit-content --json-file resolved-content.json
node scripts/yoco_ppt_video_client.mjs upload-ppt --course-id 1 --file ./demo.pptx
node scripts/yoco_ppt_video_client.mjs upload-image --file ./image.png
node scripts/yoco_ppt_video_client.mjs video-from-script --ppt-id 1234 --script-file narration.json --voice-speed 50 --embedded-subtitles true --tts-timeout 60 --tts-retry 3
node scripts/yoco_ppt_video_client.mjs wait-ppt --ppt-id 1234
node scripts/yoco_ppt_video_client.mjs clear-avatar --ppt-id 1234
node scripts/yoco_ppt_video_client.mjs submit-video --ppt-id 1234

Do not call /pptWorker/** or /pptAvatar/** from this skill. Those are worker protocols. Use /agent/**.

Workflow

1. Resolve configuration:
   • Prefer YOCO_BASE_URL and YOCO_SKILL_TOKEN from environment variables.
   • Otherwise read ~/.yoco_ppt_video_config.json.
   • The local config stores only connection/auth data such as baseUrl and skillToken; do not store default course ids or default template ids.
   • If baseUrl is missing, the helper defaults to https://www.yoco.me/ims unless the user explicitly wants test or private deployment.
   • If skillToken is missing, tell the user to log in or register at https://www.yoco.me, create a Skill Token in YOCO, and paste it back into the agent.
   • After the user provides them, save them with config-set if the user agrees or if the user has asked for persistent local configuration.
2. Check identity with /agent/me.
3. Resolve course:
   • If the user names a course, call /agent/course/list and match by courseName.
   • If no matching course exists for the named course, create it with /agent/course/add.
   • If the user does not name a course, call /agent/course/list and use the first returned course.
   • If the user has no courses, create a course automatically.
   • Default course name: use the PPT/video topic when clear; otherwise use AI生成课程.
   • Default course language is Chinese. Resolve the cn item from /agent/language/list; do not hardcode its numeric value. Only use another language when the user explicitly requests it.
   • Query /agent/language/list before selecting a non-default course language. Do not rely on a locally memorized language list or numeric value.
   • Generate narration in the course language unless the user explicitly requests a different narration language.
   • Do not ask ordinary users for courseId unless they explicitly provide one.
4. List or select a template with /agent/ppt/templatePage and /agent/ppt/templateDetail.
   • Choose the template dynamically from the user's topic, audience, page count, visual style, and template descriptions.
   • If the user does not specify a PPT visual style, do not ask for one; choose the most generally suitable template from the topic and template descriptions.
   • Do not use or persist a default template id.
5. Generate or upload PPT:
   • Agent-first mode: read references/template-understanding.md, generate outline/page content/images in the agent, then call /agent/ppt/submitContent.

Always provide a non-empty top-level pptName; submit-content can promote aiContent.pptName only as a compatibility fallback. Submit no more than 60 slides in one PPT. Every replaceable image placeholder used by a selected layout must appear in aiContent with an explicit imageAction: use resolved with a YOCO OSS URL, backend_search with a complete image requirement, or keep_template with a decision reason. If image placeholders use local files, run resolve-images first so the files are uploaded with isTempFile=true and url is written back into aiContent.

• Existing PPT file: call /agent/ppt/getUploadUrl, upload the file to putUrl, then call /agent/ppt/addPpt and poll the returned pptId.

1. Poll /agent/ppt/info until PPT is ready for editing/script generation.
2. Read /agent/ppt/pages, combine it with the user's context or connected knowledge base, and generate narration.json in the agent.
3. Choose video options with /agent/ppt/videoOptions, or let the helper script choose defaults.
4. Convert script text to audio through /agent/tts/websocket, upload audio through the pre-sign flow, then save notes through /agent/ppt/editPageNotes.
5. Submit video generation with /agent/ppt/submitVideo.
6. Poll /agent/ppt/info until genVideoUrl is available or a failure status appears.
   • If a previous video is already in GENERATED=6, video-from-script first calls /agent/ppt/continueEdit before replacing narration or style.

Interaction Modes

Natural-Language Video Option Resolution

Users normally describe the desired result in natural language. Do not expect them to provide CLI flags or internal ids. Before applying video options, infer intent, query /agent/ppt/videoOptions, resolve names to ids, and only then call the helper or API.

Apply these rules in order:

1. Determine avatar intent independently from narration intent.
   • Select an avatar when the user explicitly asks for a digital human, virtual presenter, on-screen teacher/host, talking head, avatar appearance, or names a specific avatar. Chinese signals include 数字人, 虚拟人, AI讲师, 老师出镜, 主持人出镜, 画面中有人讲解, and 用某某数字人.
   • Do not select an avatar when the user says no avatar, no person on screen, voice-over only, PPT narration only, or similar exclusions. Chinese signals include 不要数字人, 不出镜, 纯PPT, 只配音, and 只要旁白.
   • When the user does not mention an on-screen person, default to no avatar.
   • Words such as narration, explanation, voice-over, dubbing, TTS, or "generate a video" alone require a voice but do not imply an avatar. The same applies to 讲解, 讲解词, 配音, 旁白, 口播稿, TTS, and 生成视频 when no on-screen-person intent is present.
2. Resolve the avatar when needed.
   • If the user names or describes one, match it against myAvatars and publicAvatars; ask for a choice only when no reliable match exists.
   • If the user only asks for a digital human without naming one, choose a generally suitable available avatar and briefly report the choice.
   • Pass --avatar-id <materialId> or API avatarId only when an avatar was selected. Otherwise omit the field and keep notes.avatar.hidden=true.
   • In no-avatar video workflows, call /agent/ppt/clearAvatar after saving notes and applying style, immediately before /agent/ppt/submitVideo. This clears a previously selected avatar without changing page-level avatar position, scale, or hidden settings.
3. Resolve the voice independently.
   • If the user names a voice, speaker, gender, language, or voice style, select the best matching voices[] entry and pass its personId as voiceId.
   • If an avatar is selected and no voice preference is given, prefer the voice whose personId equals the avatar's personId; the helper also performs this fallback when --voice-id is omitted.
   • If no avatar is selected and no voice preference is given, use the default available voice. Do not add an avatar merely because TTS is required.
4. Resolve the style from the avatar decision.
   • Without an avatar, prefer a clean/full-screen PPT style.
   • With an avatar, prefer a non-full-screen style so the layout reserves a dedicated avatar area, and preserve its avatarX/avatarY/avatarScale. Respect an explicitly selected style even when it is full-screen.
   • The helper intentionally applies the selected style's default avatar position uniformly to all pages; it does not perform page-level avatar choreography.
5. Resolve subtitle intent.
   • Embedded subtitles default to enabled. Pass --embedded-subtitles false when the user asks for external SRT subtitles instead of subtitles rendered into the video.
   • For bilingual subtitles, query /agent/language/list and pass the selected subtitleLanguages[].value as --subtitle-lang2. This works with both embedded subtitles and external SRT subtitles.
   • Do not choose the same language as both the course language and secondary subtitle language.

For example, "给这个 PPT 配讲解并生成视频" means voice plus a clean/full-screen PPT style, with no --avatar-id. "让一位数字人老师出镜讲解" means select an avatar and pass --avatar-id; omit --voice-id unless the user specifies a different voice.

Fully Automatic Mode

Use this when the user asks for one-step generation or does not want to make choices.

The agent may choose defaults from YOCO:

• PPT template: choose a suitable template from /agent/ppt/templatePage.
• Course: choose the named course from /agent/course/list, use the first course if the user did not name one, or create a new course when no suitable course exists.
• Voice, optional avatar, video style, and subtitles: query /agent/ppt/videoOptions and select available defaults. If the user does not explicitly ask for a digital human/avatar, do not select one; use a clean/full-screen PPT style when available so the PPT occupies the main canvas. Opening/closing bumpers remain available through a separate direct /agent/ppt/editStyle call and are not helper CLI options.
• If the user chooses or asks for a digital human/avatar, select the requested avatar and prefer that avatar's bound voice (avatar.personId) when the user did not explicitly choose another voice.
• Video style layout: after choosing a style, respect its playbackWindowX/Y/Width/Height and avatarX/avatarY/avatarScale. These fields describe where the PPT playback area and digital human appear in the final video. Do not invent a separate avatar position unless the user explicitly asks and the selected style supports it.
• Narration: generate page scripts in the host agent from PPT pages, screenshots, user context, and any connected customer knowledge base. Pass the result to video-from-script; the helper validates it, runs TTS, and saves notes.
• Voice speed: use YOCO's front-end slider semantics. 0 is slowest, 50 is normal speed, and 100 is fastest. Default to 50 unless the user asks for a different speed.
• Ali TTS throttling: use a 500ms interval by default. Override it with YOCO_ALI_TTS_INTERVAL_MS, local config aliTtsIntervalMs, or --ali-tts-interval-ms only when deployment limits require it.

This mode should still summarize selected options before submitting video generation when the host conversation allows it.

Interactive Selection Mode

Use this when the user wants control over presentation style or says they want to choose.

The agent should:

1. Query candidate PPT templates and show a short list with templateId, name, preview image, and suitable usage.
2. Let the user pick a template before generating/uploading PPT.
3. Query /agent/ppt/videoOptions.
4. Let the user pick voice, avatar, video style, and subtitle mode. Optional opening/closing bumpers require a separate direct /agent/ppt/editStyle call.
5. Generate or adjust narration with the user, write it to the documented script JSON, then let the helper validate, synthesize, and save it before submitting video.

Keep candidate lists concise by default, usually 3-5 items, and support keyword/category filtering when needed.

Video Style Layout

/agent/ppt/videoOptions returns styles.records[]. A style is not only a visual theme; it also defines the video composition layout:

• styleId: style identifier passed to /agent/ppt/editStyle.
• styleName, styleImageUrl, bgImageUrl: user-facing name, preview image, and background image.
• playbackWindowX, playbackWindowY, playbackWindowWidth, playbackWindowHeight: the PPT playback window in the final video canvas. Use this to understand where the slide content will appear.
• avatarX, avatarY, avatarScale: the default digital-human position and scale for this style. When saving page notes, use these values in notes.avatar.x/y/scale.
• flipEnabled: whether the style supports left/right mirror placement for the digital human. If the user asks for the avatar on the other side, prefer a style whose built-in layout already matches that side. Only mirror coordinates when the API/front-end contract explicitly provides a supported mirror parameter.
• roundedEnabled: whether the PPT playback window may use rounded clipping in the final style.

When no video style is specified:

• Without a digital human/avatar: prefer a clean/full-screen style where the PPT playback window is 0,0,1920,1080; set notes.avatar.hidden=true.
• With a digital human/avatar: choose a style designed for avatar placement and keep its default avatarX/avatarY/avatarScale.

Narration Strategy

Prefer agent-generated narration because the host agent may have access to customer knowledge bases and conversation context that YOCO does not have.

Recommended division of responsibility:

• Host agent: understand PPT pages, screenshots, customer knowledge, target audience, tone, duration, and feedback; generate or revise the structured per-page narration.
• Skill helper: validate the agent-generated script against page animation structure, synthesize TTS, assemble front-end-compatible notes, and save notes.
• YOCO backend/workers: provide TTS access, store notes, generate subtitles/SRT, deduct points/rights, dispatch tasks, and synthesize digital-human/PPT video.

For animated PPT pages, narration must be generated by animation scene, not only by slide:

• Read /agent/ppt/pages.
• Use slideContent[].order as the 1-based text/appearance order for narration planning.
• animationInfo is used to provide animation-state screenshots; the helper builds the front-end-compatible section array.
• YOCO front-end notes.content.section[] is an interleaved timeline, not only text:

text(order=0, number=0), animation(order=1, number=0), text(order=2, number=1), ....

• For AI narration output, keep content[].order as 1-based text order. The helper maps it to the text section whose number = order - 1.
• content[].order is strict: it must be an integer from 1 through animationCount + 1; 0, missing values, duplicates, and out-of-range values are rejected.
• section.order is the index in the interleaved section array. Do not set it directly to animationInfo.num.
• Do not put the whole slide narration into the first text section. That causes video to speak on an empty initial frame and then play all animations in a batch.
• For a page without animations (animationCount=0), the generated script must contain exactly one narration item. After TTS, save exactly one text section with order=0 and number=0; do not create additional text scenes for a non-animated page.
• Before TTS, the helper validates every generated page script against the page's animation structure. On failure it reports pageId, animationCount, and validation errors, then stops before TTS. The host agent must correct only the invalid pages in the script file and run the command again.
• For animated pages, animationInfo must contain exactly animationCount non-zero entries with unique num=1..animationCount and a non-empty animationImage. The helper rejects inconsistent animation metadata before TTS.

The host agent generates narration content but must not manually construct notes.content.section; the helper owns deterministic validation, TTS, and notes assembly.

References

Read only what is needed:

• references/api.md: endpoint list, headers, parameters.
• references/workflow.md: front-end-derived generation flow and WebSocket handling.
• references/template-understanding.md: required rules for reading template layouts/placeholders and generating valid PPT JSON.
• references/statuses.md: known PPT/video status meanings and polling guidance.

Rules

• Always send X-YOCO-Skill-Token.
• When required parameters are missing, first run config-show; if skillToken is still missing, guide the user to https://www.yoco.me to register/log in and create a Skill Token, then save it with config-set.
• Do not persist or reuse a default courseId or templateId; resolve them per task.
• If no YOCO course exists for the user, create one with /agent/course/add and continue.
• If the user does not specify a PPT/video style, use YOCO's default style, but when no avatar is selected prefer a clean/full-screen style. Do not block the workflow to ask for style selection.
• Do not select a digital human/avatar by default. Only select one when the user asks for a digital human, avatar, presenter, talking-head video, or explicitly provides an avatar.
• Treat narration, voice-over, dubbing, TTS, and generic video-generation requests as voice intent only; they must not enable an avatar by themselves.
• When an avatar is selected and the user did not specify a voice, use the avatar's bound voice if it exists in /agent/ppt/videoOptions.voices.
• Explicit voiceId, avatarId, and styleId values must exist in /agent/ppt/videoOptions; the helper rejects unavailable ids instead of silently substituting another option.
• Each narration content item corresponds to one animation stage and must be sent to TTS as one complete request. Never split one content item into multiple TTS requests.
• Validate returned MP3 frames and require at least 0.2 seconds of audio before upload; invalid audio participates in the normal TTS retry flow.
• Before submitting a no-avatar video, call /agent/ppt/clearAvatar; omitting avatarId from /agent/ppt/editStyle does not clear a previously saved avatar.
• Use JSON POST requests.
• Before calling /agent/ppt/submitContent, read references/template-understanding.md and follow its layout/placeholder rules.
• Always submit pptName as a non-empty top-level field. Do not rely on aiContent.pptName as the primary contract.
• /agent/ppt/submitContent accepts at most 60 slides. When updating an existing PPT, reuse its pptId only when pptStatus is PARSED=2 or AI_GENERATE_PPT_FAILED=12.
• Agent-selected or AI-generated PPT images must be uploaded through /agent/ppt/getUploadUrl with isTempFile=true, then referenced by the returned YOCO OSS URL.
• For repeatable CLI workflows, put a local image path in an image placeholder as localFile, run resolve-images, then submit the resolved JSON.
• When the host agent cannot search or generate an image, submit imageAction=backend_search. YOCO will try Pexels and multimodal scoring; low scores or provider failures preserve the template image and do not fail PPT generation.
• For every replaceable image placeholder, proactively choose the image source from the slide content, placeholder purpose, template visual style, and target aspect ratio. Explicit user image intent overrides this normal decision: use generation when requested, or real/internet images when requested. Follow the complete decision rules in references/template-understanding.md.
• Never log or persist full Skill Token values.
• Do not print full Skill Token values. config-show masks the token.
• On Linux and macOS, the helper stores ~/.yoco_ppt_video_config.json with permission 0600.
• Before first use in an unfamiliar agent environment, run runtime-check; use Node.js 22 or newer when global WebSocket support is unavailable.
• For missed WebSocket messages, fall back to /agent/ppt/info.
• Interpret numeric pptStatus values using references/statuses.md; stop on terminal failure states instead of polling until timeout.
• For TTS speed, always treat the agent-facing value as YOCO slider speed 0-100; 50 means normal. The helper maps it per provider before calling Xunfei, Ali, Azure, or ElevenLabs.
• For narration/TTS troubleshooting, watch helper events: script_validation_failed, script_validation_done, tts_prepare, tts_start, tts_done, tts_uploaded, and notes_saved. If TTS appears stuck, lower --tts-timeout temporarily, for example --tts-timeout 30 --tts-retry 1.
• Agent APIs are intentionally not documented in ApiKit.
• Do not use /agent/ppt/generate or /agent/ppt/submitOutline; those are not part of the Agent-first API surface.