analyze-video

Constraints

• Platform: TikTok only.
• Analyze source: Extract transcript and visual notes from the TikTok URL.
• The model's final user-facing response should match the user's input language, default English.
• Avoid technical wording in the user-facing reply unless the user explicitly needs details for debugging or to share with a developer.
• Follow shared guidance in ./references/common-rules.md.
• Input: TikTok URL.
• Artifacts must be written under analyze-video/.artifacts/<run_id>/....

The creatok CLI

Analysis runs through the creatok CLI. Never call HTTP endpoints directly.

• Auth is channel-specific: stable CLI uses CREATOK_API_KEY; preview CLI uses CREATOK_API_KEY_PREVIEW. These keys are parallel, and preview does not read or fall back to CREATOK_API_KEY.
• Command: creatok analyze --url "<tiktok-url>" --out <run_dir>.
• Analyze is synchronous: the command returns the full result on stdout as a JSON envelope (no task polling), and also writes result.json under artifacts.dir.
• On error, error.kind ∈ { auth, notfound, invalid, server, timeout, network, outdated_cli }; map via ./references/common-rules.md.

What to produce (minimum)

The CLI returns structured source data under the envelope's data:

• transcript segments
• video metadata
• normalized vision result
• remote response text and suggestions

Analysis Focus

The model should read the CLI's data (also persisted to result.json) and produce the final user-facing analysis in the conversation. Before deciding how to explain the result, the model should first infer what kind of TikTok video this is. This classification is mainly for better guidance and analysis focus; it should not feel like a rigid taxonomy to the user. Useful internal categories include:

• selling talking-head / direct pitch
• pain-point to solution
• product demo
• before / after
• review / comparison
• listicle / recommendation
• emotional or surprise hook
• non-selling content such as pet, entertainment, lifestyle, or story content

The model does not need to expose the category label unless it clearly helps the user.

Analysis Angles

The model can infer and explain items such as:

• hook / value / proof / CTA
• highlights with timestamps
• storyboard / reusable template
• final written analysis or recommendations
• why the video can or cannot go viral from a short-form content operations perspective
• how the video works from a selling conversion perspective, including script, cover, audience, and conversion logic

Two especially useful framing options for the final user-facing analysis are:

• explain why the video can or cannot become a strong short-form performer from an operator's point of view
• break down the script, cover, audience, and conversion logic from a selling and transaction point of view

The analysis emphasis should follow the inferred video type:

• for selling videos, focus on conversion structure, selling-point order, proof, trust-building, and CTA
• for product demos, focus on what is shown first, how the product is demonstrated, and what makes the demo persuasive
• for before / after videos, focus on contrast strength, believability, and payoff timing
• for review / comparison videos, focus on credibility, differentiation, and decision-making signals
• for non-selling content, focus on hook, pacing, emotional pull, and what structure can be reused without forcing a selling analysis

Output Preferences

• The default final response should include both:
  • the original script
  • a storyboard / scene breakdown table
• The final response should also include a short video-metrics section that evaluates the available data, such as:
  • duration
  • likes
  • views / plays
  • comments
  • shares / saves if available
  • a brief overall assessment of whether the public stats look healthy, weak, or unavailable
• Keep the metrics analysis simple and grounded in the available platform stats and source artifacts. The model should infer this directly in the final reply using the available raw metrics and source artifacts; do not invent platform engagement numbers or add a separate scripted metrics pipeline.
• Present the original script as a timestamped line-by-line script.
• Present the storyboard as a table with at least time range, scene summary, visual action, and spoken content / on-screen text.
• Prefer a clean readable structure such as one spoken line per row with its corresponding time range.
• Keep the final response easy for creators and sellers to scan and reuse.

Next-Step Handoff

After presenting the analysis, the model should naturally guide the user into the next step. Use a numbered list for the follow-up choices, and explicitly tell the user to reply with only the number. The user should not need to copy the full option text. Prefer a concise prompt such as:

1. Rewrite this for your product
2. Turn this into an AI-ready script
3. Break down the conversion logic

Then add a short instruction like:

• "Reply with 1, 2, or 3."
• "Just send the number, and I will continue."

The model should keep this handoff flexible and concise rather than forcing a rigid workflow. When phrasing the options, keep them short and action-oriented so they are easy to answer with a single digit.

The next-step options should also reflect the inferred video type:

• for selling videos, prioritize viewing the original script, viewing the original storyboard, adapting it to the user's own product, or making a differentiated version
• for non-selling content, prioritize viewing the original script, viewing the original storyboard, or adapting the idea to the user's own topic

Unless the user explicitly asks for a live-action shoot version, the model should treat recreation and follow-up generation as AI-generated video work by default. The default path is to help the user move toward an AI-generation-ready script or brief. After giving a useful AI-oriented version, the model may optionally ask whether the user also wants a live-action shoot version.

If the reference appears to be a product-selling video and the user wants to recreate it, the model should first collect the user's own product context before drafting the recreated script. Ask only for the highest-impact details first, such as:

• product name
• core selling points
• product images or reference materials if available
• price or offer details if they matter to the hook or CTA

If important details are still missing, the model should fill gaps through short follow-up questions step by step instead of requesting a large information dump up front. The model should not ask for a long form, a detailed brief, or a large batch of requirements before showing useful progress.

Workflow

1. Entry self-check

• Run creatok doctor. If the command is not found, the CLI is not installed — guide the user to install it (see ./references/common-rules.md) and stop.
• If data.api_key_configured is false or error.kind is auth, guide the user to configure the channel-specific key: CREATOK_API_KEY for stable, CREATOK_API_KEY_PREVIEW for preview.
• Check for a newer CLI and, if the user agrees, update before proceeding — follow ./references/common-rules.md (Outdated CLI).
• If data.skills_drift is true, the installed skills are out of sync with the CLI — run creatok skills install to resync (see ./references/common-rules.md).

2. Run analyze

• Run: creatok analyze --url "<tiktok-url>" --out <run_dir>
• The CLI returns the full analysis synchronously and writes result.json.

3. Analyze in conversation

• Read the envelope data (transcript, metadata, vision, suggestions) and produce the final user-facing analysis.

Notes

• Keep it deterministic and portable: write source data artifacts and let the model analyze them in the conversation.
• Favor momentum after the analysis. The default next step is to help the user view the original materials or move toward recreation / remix.
• For selling-video recreation, gather a small set of key product details first, then refine through lightweight follow-up questions only when needed.