Funai-skill

Orange Star Dream Factory Agent Skill

Orange Star Dream Factory is an AI-driven comic drama production platform. Create projects, submit scripts, extract characters, generate storyboards, configure the final cut, and finally composite the video via API.

Beta Notice

You are currently using Funai-skill Beta. When interacting with users, the Agent should clearly inform them that it is currently in the beta stage.

Important Conclusion

The real backend is not a "linear flow that only looks at workflow.currentStep ", but rather:

One layer is project-level steps:workflow.currentStep

One layer is chapter-level hidden tasks:comicPreset.data.chapters[] in sceneCaptionsTaskStatus、dialogTaskStatus、sceneTaskStatus

If the Agent only looks at currentStep and continues to call the next step, errors are very likely.

Skill Update Constraints (must be executed before creation-type operations)

Local machine-readable version file：VERSION

Note: external copy no longer hardcodes the version number; the actual version is subject to the local VERSION and the latest_version / minimum_required_version in the remote setup metadata.

Whenever the Agent is about to call this Skill to perform any operation that creates, advances, or modifies platform tasks,it must first access the fixed update entry：

https://neirong.funshion.net/skills/setup-skill.md

Check at least the following fields:

latest_version
minimum_required_version
force_update
skill_package_url

Execution rules:

If this Skill is not yet installed locally, it must be installed automatically first.
If the remote requires a forced update, or the local version is lower than minimum_required_version, it must be updated automatically first.
Only after the version check is complete can operations such as creating projects, submitting scripts, advancing steps, generating images, generating videos, rolling back, and compositing continue.

Quick Configuration

1. Get Token

Guide the user to visit https://ai.fun.tv/#/openclaw and log in; after obtaining the Token, the Agent writes it to the configuration file on the user's behalf.

2. Configure Token

cp config/.env.example config/.env
# 编辑 config/.env
# AIFUN_TOKEN=...

3. Verify Configuration

./scripts/api-client.sh setup-check
./scripts/api-client.sh check

4. Run the Full Self-Check Example

./examples/create-comic.sh

The example script is aself-check script, which will automatically create a test project using the real-time default values returned by select-options .

In Agent interactions with real users, the real-time selectable options must still be read first; among them, aspect / style must be shown to the user for them to choose,generateType / scriptType can be used silently with the current default value,model / videoModel can continue to use the real-time default value when the user has not specified one.

In addition, to verify the entire chain, the example script will, in the self-check scenario, submit the script first and then show the "confirmation point"; this does not mean that real user interactions can skip the pacing requirement of "confirm first, then continue".

Execution Rules the Agent Must Follow

0. Use the default mode silently; do not proactively explain to the user

Unless the user explicitly requests to switch modes, the Agent should directly use the platform default mode:

generateType = 1(text-to-image)
scriptType = 解说漫模式(subject to the default script mode returned by select-options )

However, this "silent default"only applies at the mode level, not applicable to project visual configuration.

When creating a project, the following two fieldsmust not silently default, the user must be explicitly asked to choose:

aspect(aspect ratio)
style(style)

Important：

This is the Agent's internal default decision; do not proactively treat "currently defaulting to text-to-image / narration comic mode" as a configuration item that needs to be told to the user.
Only when the user explicitly requests switching to another mode does it need to be explained and adjusted.
Even if the default mode is used silently, the underlying layer must still first call select-options, and use the default values returned by that invocation's interface, rather than hardcoded constants.
aspect / style must not, just because the interface returned isDefault , decide on the user's behalf; the user must be shown the options and asked to confirm.

1. Before creating a project, you must first call `select-options`

POST /service/workflow/project/story/select-options
{"appCode":"ai-story","generateType":"1"}

Rules:

Must use the ratios、generateTypes、models、videoModels、styles、scriptTypes
ForbiddenHardcoding style, model, ratio, script type
isDefault isrequest-related, do not hardcode historical default values in code or documentation
If the user has not explicitly requested a mode switch, then directly and silently use the default returned by that invocation's interface generateType / scriptType
But aspect / style must be shown to the user and chosen by the user, and must not be silently defaulted
model / videoModel If the user has no additional requirements, you may continue to use select-options the current default value returned
For user-facing interactions, there is no need to proactively bring up "text-to-image / narration comic mode" as a default item to explain; but the user must be explicitly asked to choose aspect / style

2. In narration drama / narration comic mode, AI ghostwritten scripts must be written as narrative-style novel prose

If the user asks the AI to help write a script, and the current mode isnarration drama / narration comic mode, the Agent must write the script asnarrative-style novel / story body text, not a storyboard script.

Must comply with:

Continuous narrative
Primarily continuous narration advancing the story
A small amount of natural dialogue may be interspersed, but overall it should still be narrative body text
Suitable for later automatic splitting of characters, storyboards and narration by the platform

The following styles of writing must not appear:

镜头1 / 镜头2
旁白：... such explicit script labels
林舟说：...
【音效：脚步声】 / 砰！ / 咚—— such sound effect descriptions
Stage-direction-style entries
Storyboard table / script format

Correct style illustration:

清晨，城市公园的林荫道上，年轻人林舟正在慢跑。阳光穿过树叶，在青石板路上投下斑驳的金色光影。

他刚想加快脚步，一只金毛犬忽然从灌木旁窜了出来，差点撞上他的膝盖。林舟猛地停住脚步，呼吸一乱，循声抬头望去。

不远处，一个扎着马尾的女孩正快步跑来。她一边抓紧手里的牵引绳，一边有些不好意思地朝林舟笑了笑。

Incorrect style illustration:

镜头1：公园远景。
旁白：清晨的城市公园里，林舟正在跑步。
林舟说：今天一定要把状态跑出来。
镜头2：金毛犬冲出。

3. After a project is successfully created, show the project link first

After successful creation, the project link must immediately be told to the user:

https://ai.fun.tv/#/comic/multiple?projectId={projectId}

4. Do not only look at `workflow.currentStep`

All three types of readiness below must be checked:

Scenario	Check location	Continue condition
Which major step the project is at	`GET /project/{projectId}` → `workflow.currentStep`	Current step is correct
Whether character images are complete	`GET /comic/roles/{presetResourceId}` → `roles[].taskStatus` / `imgUrl`	All `SUCCESS` and `imgUrl` non-empty
Whether chapter-level hidden tasks are complete	`GET /resource/comicPreset/{presetResourceId}` → `chapters[]`	Corresponding status field is `SUCCESS`

5. Do not hardcode `tts` / `voice-clone-select` input

novel_extract_roles is not just passing chapterNum and that's enough. The actual runnable approach is:

First call GET /comic/roles/{presetResourceId}
From data.voiceInputs[0] or data.roles[0].inputs[0] retrieve the live tts input object
Submit it together with chapterNum Submit together

6. Do not treat `sceneUuid` as `sceneId`

scene-list in sceneUuid is only a short ID and cannot be used directly for storyboard/video APIs.

Correct flow:

comicPreset/{presetResourceId}
→ chapters[].sceneTaskId
→ GET /task/{sceneTaskId}
→ data.resourceId (storyboardId)
→ GET /resource/{storyboardId}
→ data.data.scenes[].id (完整 sceneId)

7. Prefer to return to the user `videoPlayUrl`

If the backend returns a new playable field:

scene video resource:videoPlayUrl
final rendered resource:videoPlayUrl

then the correct approach is:

Externally return only videoPlayUrl
Do not expose the raw video in high-level helpers, example scripts, or model-visible output url
The project link can still be returned together as an additional entry point

8. `scene/ai/video` must use the scene's current base storyboard image

The correct image source for image-to-video is the current scene'sbase storyboard image：

Prefer to use GET /storyboard/scene/{sceneId}/prompt/detail?sceneId={sceneId} in video.imageId
then go to GET /storyboard/scene/{sceneId}/resources to find the image resource corresponding to this imageId Corresponding image resource
If there is still an image for selected == true , it is usually the same image

Do not directly use:

GET /comic/roles/{presetResourceId} returned by roles[].imgUrl

Important: This is not a constraint that "the backend will definitely report an error", but a constraint that "the Agent must proactively ensure semantic correctness".

In live tests, the backend accepted roles[].imgUrl + roles[].imageResourceIdand successfully generated a video resource. That is, when the wrong image is passed, the API may still return 200 success, but what is generated is asemantically incorrect video。

Therefore:

Correct image source = the scene's current base storyboard image (prefer the image corresponding to video.imageId )
Wrong image source = character image / other images that are not the current scene
Do not rely on the backend to cover for you

Authoritative execution order for Agents

Step 0: Do the setup check first

First read https://neirong.funshion.net/skills/setup-skill.mdto confirm the local skill version is available.

Step 1: Get project options

POST /service/workflow/project/story/select-options
{"appCode":"ai-story","generateType":"1"}

Step 2: Create a project

Create the project using the real-time values returned by the API in the previous step.

The live backend usually lets novel_config complete automatically, so after project creation the common currentStep is novel_input, which is normal.

If the user has not specifically stated otherwise, do not additionally tell the user "currently using text-to-image / narrated comic mode by default".

But before actually creating the project, you must first have the user explicitly choose:

Aspect ratio aspect

Style style

Only after these two fields are confirmed can you create the project combined with the real-time default generateType / scriptType / model / videoModel .

Step 3: Submit the script

POST /service/workflow/project/step/next
{
  "userProjectId": "项目ID",
  "step": "novel_input",
  "inputs": [
    {"name": "content", "type": "text", "value": "剧本内容"},
    {"name": "scriptType", "type": "text", "value": "0"},
    {"name": "isSplit", "type": "text", "value": "0"}
  ]
}

After returning resultId , poll GET /task/{resultId}。

If the script is AI-written and the current mode is narrated drama / narrated comic mode, the script body must remainnarrative novel style, do not write it as a storyboard script, and do not write sound effect descriptions.

Step 4: Intelligent episode splitting

POST /service/workflow/project/step/next
{"userProjectId":"项目ID","step":"novel_opt","inputs":[]}

After returning resultId , poll the task.

Step 5: Wait for character images to complete, then execute the character step

First call:

GET /service/workflow/comic/roles/{presetResourceId}

Must satisfy:

roles[].taskStatus == SUCCESS
roles[].imgUrl Not empty

Then call:

POST /service/workflow/project/step/next
{
  "userProjectId": "项目ID",
  "step": "novel_extract_roles",
  "inputs": [
    {"type": "number", "name": "chapterNum", "value": 1},
    { ...来自 roles/voiceInputs 的 tts 输入对象... }
  ]
}

If this step is skipped, a common error is:

角色 [xxx] 图片未完成

If the user asks to modify the character's appearance at this stage, the following must be satisfied:

Current workflow.currentStep == novel_extract_roles
First initiate a new image generation for the target character
Wait for the new image to become SUCCESS in the character candidate image list and for imgUrl to be non-empty
Then explicitly apply this new image
Finally re-read the character list, confirm that the character's main image has been switched, and return the new image URL to the user

Generating the image without applying it does not count as a completed modification.

Step 6: Wait for `sceneCaptionsTaskStatus=SUCCESS`, then run intelligent storyboarding

First call:

GET /service/workflow/resource/comicPreset/{presetResourceId}

Wait for:

chapters[chapterNum].sceneCaptionsTaskStatus == SUCCESS

Additional note: in live data, this kind of chapter field may first appear as a null value for a short time, then enter RUNNING / SUCCESS. A null value does not necessarily indicate an exception, and you must not use it as a reason to advance to the next step early.

Then call:

POST /service/workflow/project/step/next
{
  "userProjectId": "项目ID",
  "step": "novel_scene_captions",
  "inputs": [
    {"type": "number", "name": "chapterNum", "value": 1},
    {"name": "imgGenTypeRef", "value": 1}
  ]
}

This step returns dialogTaskId, not resultId。

If called too early, a common error is:

该章节提取分镜场景任务未完成，请稍后再试

Step 7: Poll `dialogTaskId` , and after that you still need to wait for `sceneTaskStatus=SUCCESS`

Poll dialogTaskId . Even after it succeeds, you still cannot immediately advance to the final video.

You also need to check:

chapters[chapterNum].sceneTaskStatus == SUCCESS

Additional note: in live data,sceneTaskStatus may be empty for a period of time, then become SUCCESS; when judging readiness, you should continue polling rather than treating an empty value directly as a failure.

If called too early, a common error is:

该章节分镜图任务未完成，请稍后再试

Step 8: Advance to the final video step

Wait for sceneTaskStatus=SUCCESS , then call:

POST /service/workflow/project/step/next
{
  "userProjectId": "项目ID",
  "step": "novel_chapter_scenes",
  "inputs": [{"type": "number", "name": "chapterNum", "value": 1}]
}

Step 9: Parse storyboard and sceneId

Use the sceneTaskId -> task -> resourceId -> resource chain to obtain:

storyboardId
scenes[].id
scenes[].image

Step 9.5: Convert a single scene image to video (if the user explicitly requests it)

First confirm:

The current step is already at novel_chapter_scenes
sceneTaskStatus == SUCCESS
Use the full sceneId
First get prompt/detail.video.imageId, then from resources find the corresponding image resource

Recommended payload form:

{
  "sceneId": "完整 sceneId",
  "prompt": "来自 prompt/detail 的视频提示词",
  "cameraPrompt": "来自 prompt/detail 的镜头提示词",
  "model": "doubao-pro",
  "duration": "-1",
  "firstImage": "scene 当前基准分镜图 URL",
  "tailImage": "",
  "clarity": "720p",
  "imageId": "scene 当前基准 image 资源ID"
}

Do not write it as:

firstImage = roles[].imgUrl
imageId = roles[].imageResourceId

Because this may not raise an error, but it will generate a video with incorrect semantics.

Step 10: Final video configuration and composition

Here you must clearly distinguishthe final video settings stageandthe video composition stage。

Step 10A: Enter `novel_chapter_video` = enter the final video settings stage

When the chapter advances from novel_chapter_scenes to novel_chapter_video , the user cannot immediately see the final video.

In live testing, common characteristics of this stage are:

workflow.currentStep = novel_chapter_video
chapters[].currentStep = novel_chapter_video
chapters[].currentSubStep = setting

This indicates that it is currently in thefinal video settings stage, and at this point the final video parameters need to be prepared and confirmed.

Step 10B: Save the final video settings

The order is as follows:

POST /storyboard/prepareVideoComposite
GET /storyboard/getVideoSetting?userProjectId=...&type=2&chapterNum=1
POST /storyboard/saveVideoComposeConfig

This stage mainly corresponds to:

Cover settings
Subtitle settings
Background music
and the composition-related parameters that need to be confirmed before subsequently generating the video

In live testing, aftersaveVideoComposeConfig succeeds, the chapter may still remain:

currentSubStep = setting

That is to say,Saving the settings successfully ≠ video synthesis has started。

Step 10C: Clicking "Generate Video" = actually initiating video synthesis

Only when calling:

POST /project/step/action with step=novel_chapter_video

does video synthesis actually begin.

In live testing, this step will:

Return a new resultId(video synthesis task ID)
Update the chapter's videoTaskId to the new task ID
Move the chapter currentSubStep from setting into video

Only then is it necessary to:

Poll the returned resultId

In live self-checks, this final synthesis task may stay in the QUEUED state noticeably longer than ordinary steps; do not reuse the short polling budget of earlier ordinary tasks and directly judge it as timed out.

Step 10D: Only after the synthesis task succeeds can the user see the final finished video

Only after the video synthesis task SUCCESS :

will a new final video resourceId
Only then can the user see the final finished result in the platform

In other words:

Entering novel_chapter_video does not mean the final finished video is complete
Saving the cover / subtitles / background music also does not mean the final finished video is complete
The final finished video only truly becomes visible after the video synthesis task succeeds

saveVideoComposeConfig runnable payload must contain at least:

selectCover
coverList
selectCoverUrl
selectMusicId
selectTitleFont
selectSubtitleFont
title
bgmVolume
type
chapterNum
userProjectId

After rolling back, synthesis must be performed again

Live testing confirms:

After novel_chapter_video synthesis succeeds, the chapter records the current videoTaskId
Once you roll back to novel_chapter_scenes to make adjustments and re-enter novel_chapter_video , the old synthesis result will not automatically become the new final finished video
Calling project/step/action again will producea new videoTaskId
and ultimately will also generatea newvideo resourceId

This shows:

Each time you roll back from the finished-video step to make adjustments, the video must be synthesized again.

Task briefing and step-by-step confirmation mechanism

The Agent's role should be like "an intelligent comic-drama assistant that accompanies continuously", not a head-down executor.

Each time an important user-perceivable task is completed, a briefing should be given to the user immediately, containing at least:

What was just completed
What key result this step produced
What is planned for the next step
If a user decision is needed, clearly tell the user what to choose
Clearly ask the user: whether to continue; if the current step supports modification, also ask whether to modify the current result

If the project has been created, the briefing should preferably include the project link:

https://ai.fun.tv/#/comic/multiple?projectId={projectId}

Mandatory pacing requirements

Except for purely technical intermediate actions, the Agent must notautomatically complete the entire chain all the way through without user confirmation.

The correct pacing is:

完成一个大步骤
→ 详细汇报当前结果
→ 询问用户是否满意、是否继续下一步；如果当前步骤支持修改，再询问是否需要修改
→ 等用户确认后再继续

The "major steps" here include at least:

Project creation completed
Script written / submission completed
Character organization completed
Intelligent storyboarding completed
Storyboard image generation completed
Image-to-video conversion completed
Finished-video configuration completed / synthesis completed

Three mandatory stop points (cannot be skipped)

After the following three nodes are completed, the Agent mustimmediately stop and wait for user confirmation, and must not automatically proceed to the next step:

After novel / script generation is completed
- must return the complete or core script content to the user
- explicitly ask: whether the plot, character settings, or tone style need to be modified
- only after user confirmation may it continue to submit the script or proceed to subsequent steps
After character generation is completed
- must return each character'scharacter image URLto the user
- If the current project is still at the novel_extract_roles(characters and voiceover) step, it should proactively ask the user whether a character's appearance needs to be modified
- If the user requests a modification, it must first generate a new image, wait for the new image to complete, and then explicitly apply the new image; only after the main image has actually switched is the modification considered complete
- After the modification is complete, it must return the new character image URL to the user
- Only after the user confirms it is correct may it continue to the scene / storyboard related steps
After scene / storyboard generation is completed
- must return the scene'sscene descriptionto the user
- If there are storyboard images that can be displayed, they should also be returned or the viewing method in the project link should be explained
- If the user is dissatisfied with one or more scenes, they should be allowed to continue adjusting the image prompt or video prompt of a single scene at the novel_chapter_scenes step and then regenerate
- must proactively ask the user:
  1. whether to continue converting the storyboard images into video
  2. or to directly enter the "final cut" interface and composite directly with the current storyboard images
- Only after the user makes an explicit choice may it continue to the image-to-video or final cut step

Content that must be included in character confirmation

The report in the character confirmation stage must include at least:

Character name
Character image

It must not merely say "character generation is complete" without returning the character image to the user.

Modification rules during character confirmation

Character appearance modifications are only allowed at the characters and voiceover step.

Character confirmation stage:

May ask "whether the character appearance needs to be modified"
But only on the premise that it is still at novel_extract_roles
If the project has already advanced to subsequent steps, it can no longer be modified via the character image modification flow
As long as a modification is performed, it must wait for the new image to complete, explicitly apply it, and return the new image URL to the user

Content that must be included in scene confirmation

The report in the scene confirmation stage must include at least:

Scene name or scene number
Scene description
If visual results have been generated, storyboard images or a viewing method via the project link may be attached

It must not merely say "scene generation is complete" without returning the scene description to the user for confirmation.

Adjustment rules when dissatisfied with a scene

If the user is dissatisfied with the result of one or more scenes, the Agent should first determine which category the problem belongs to:

The image itself is wrong: adjust sceneDescription + prompt and then regenerate the image
The image is basically correct, but the video performance is wrong: adjust prompt(动作) + cameraPrompt(运镜) then regenerate the video

Storyboard image regeneration

When regenerating an image, the real prompt is composed of two parts:

sceneDescription
prompt

Among them, prompt may contain:

@[人物](id:xxxx)

This type of live character reference is used to maintain character consistency and should not be deleted arbitrarily.

Image to video

When converting an image to video, distinguish between:

prompt = action
cameraPrompt = camera movement

Do not use the image-side @[人物](id:xxxx) structure here; instead write pure-text action and camera descriptions directly.

Optional enhancement for multimodal models

If the current Agent / model has multimodal image-viewing capability, it can first view the current result after each image regeneration or video regeneration, then decide whether to continue fine-tuning:

On the image side, first check the current selected=true scene image
On the video side, first check the current video resource's videoCover

Then modify the prompt in a targeted way based on the problem, rather than retrying blindly.

After the storyboard images are complete, the next step must give the user a choice between two options

When the storyboard images have been generated, the Agent must not default directly to the final video.

It must proactively ask the user:

Whether to convert the storyboard images to video(this will increase Dream Value consumption)
or go directly to the final video interface for compositing(cheaper by default)

Only after receiving this choice can execution continue.

Which actions do not require separate confirmation

The following are still technical actions within the same step and can be completed together in one step:

Polling task status
Read comicPreset / storyboard / task
Parse sceneId / storyboardId
Fall back to the storyboard image step
Read select-options

However, once a new user-perceivable result is produced, it must stop and wait for confirmation.

Image generation / video generation constraints

Image generation or video generation must be executed under the storyboard image step , and cannot be executed directly in the final video step.

Check order:

GET /project/{projectId} check workflow.currentStep
If the current step is novel_chapter_video, first POST /project/step/prev
return to novel_chapter_scenes and then continue

Live test confirmation:

After a successful fallback,workflow.currentStep will become novel_chapter_scenes
The chapter's currentSubStep may still remain as video

This does not indicate an anomaly. Before actually continuing, keep confirming:

sceneTaskStatus == SUCCESS
the scene's current base image resource is available

Dream Value rules

Recommended flow that consumes no Dream Value by default

The default flow is:

分镜图生成完成 → 直接配置成片 → 合成最终视频

But this does not mean the Agent can automatically execute all the way to the end.

The correct approach is:

分镜图生成完成
→ 先向用户展示分镜结果并询问是否修改 / 是否继续
→ 用户确认后再进入成片配置与合成

High-consumption operations that require user confirmation

The following operations consume Dream Value and must obtain explicit user consent first:

Batch convert to video check/batchAiVideo the corresponding real video conversion action
Single image to video scene/ai/video
Redraw storyboard image scene/ai/image

`check/batchAiVideo` is only a query, not an execution

It returns:

noVideoCount
how many frames still have not been converted to motion

Do not mistake this interface for "batch video conversion has already started".

Common Problems and Solutions

1. Token Expired

Error:401 / 未登录或登陆状态已失效
Solution: Re-obtain the token, update config/.env

2. Character Step Failed

Error:角色 [xxx] 图片未完成
Cause: The character image has not finished generating, or live tts input was not passed
Solution: First check GET /comic/roles/{presetResourceId}, then after the character is ready, submit voiceInputs[0] together

3. Smart Storyboard Step Failed

Error:该章节提取分镜场景任务未完成，请稍后再试
Solution: Wait for sceneCaptionsTaskStatus=SUCCESS

4. Advance to Final Cut Step Failed

Error:该章节分镜图任务未完成，请稍后再试
Solution: Wait for sceneTaskStatus=SUCCESS

5. `sceneUuid` misuse

Error:分镜场景资源不存在
Cause: A short ID was treated as a complete sceneId
Solution: Resolve the complete sceneId according to sceneTaskId -> storyboardId -> scenes[].id Parse the complete sceneId

6. Wrong Image Source Used for Image-to-Video

Symptom: The interface may return 200 success, but the generated video content does not match the current storyboard
Cause: roles[].imgUrl / roles[].imageResourceId was treated as the scene/ai/video of firstImage / imageId
Solution: Must switch to the scene's current baseline storyboard image resource (prefer the image resource corresponding to prompt/detail.video.imageId )

7. Video Configuration Save Failed

Error:请选择封面
Cause:saveVideoComposeConfig is missing coverList / selectCover / selectCoverUrl
Solution: First retrieve getVideoSetting, then construct the complete payload according to the returned content

Code and Reference Documentation

scripts/api-client.sh: Reusable API utility functions and waiting logic
examples/create-comic.sh: Complete self-check flow executed according to real backend behavior
references/01-project-management.md: Project creation and configuration options
references/02-script-management.md: Request bodies for each step and hidden chapter states
references/03-character-management.md: Character image states and tts input
references/05-storyboard-management.md: storyboard / sceneId / storyboard resources
references/06-video-generation.md: Final cut configuration, batch video check, and compositing
references/07-task-status.md: task polling and chapter-level hidden states
references/09-error-codes.md: Common errors and handling methods
references/10-models-and-config.md: Real-time configuration and workflow overview
references/11-best-practices.md: Execution recommendations for Agents