analyze_video

pro.aicut/aicut · Verify this server

Starts an AI analysis of an existing video on the signed-in aicut account and returns the new analysis's id immediately. It does NOT wait for the result. WHAT: reads the video and describes it in detail - what happens, who is in it, the on-screen text, the pacing and the cuts - as free-form text, plus the platform's own metadata (title, author, view count) when it has any. WHEN: the user wants to understand, break down, transcribe or copy the structure of a video they link to, or one they uploaded to aicut. This does NOT generate anything - use `generate_video` for that. WHICH VIDEOS: a public YouTube, TikTok or Instagram video url, or a video this account itself uploaded to aicut. Any other url is rejected, including another account's uploads - do not retry a rejected url with a different form of the same link. AFTER: poll `get_analysis` with the returned id every 5-10 seconds until `status` is `succeeded` or `failed`; do not poll faster than every 5 seconds. TIMING: an analysis usually finishes in under a minute, and can take a few minutes for a long window or a slow platform. Poll `get_analysis`; do not assume it failed before then, and do not spawn timers or background shells to wait - just poll on the interval above and stop when the status is terminal. COST: this spends NO tokens - it is free on this account, like every other analysis in aicut. There is nothing to confirm with the user about cost and no reason to check the balance first. It does count against a per-account daily analysis allowance: if you get `daily_limit_exceeded`, the answer is to wait rather than to top up, and running analyses in a loop to explore is what exhausts it. IDEMPOTENCY: `idempotency_key` is optional and makes a retry safe. Set it on the FIRST call, not only on a retry - the job is addressed by the key, so a key added afterwards cannot find a job that was created without one. Reusing a key REPLAYS the job that key already created and returns it unchanged - even if you send a different prompt or different settings, and even after that job has finished. A key is therefore spent permanently. Do NOT reuse one to make another generation: two deliberate generations are two jobs and need two different keys (or none). ONE EXCEPTION, on `render_story_video`: replaying a key whose render FAILED answers 409 `render_failed` rather than replaying the failure, because a spent key stays spent - retry that one with a NEW key or with none. A KEY IS NOT SCOPED TO A TOOL: it addresses a job on the whole account, so reusing the key you gave `generate_video` on `generate_story_video` replays that first video instead of starting an episode. One key, one thing you made. (`render_story_video` is the one door that namespaces its own, which is why an episode's key can be reused on its render without colliding - but there is no reason to reuse it there either.) Never derive the key from the request body. You do NOT need to pass one to be safe against a duplicated delivery: aicut already derives a per-call key server-side, so a retry the transport makes on its own replays rather than charging twice. Pass your own only when YOU want to retry a call whose answer you never saw. OUTPUT: this returns JSON for you to read. When you report back to the user, give them the media URL plus a one-line summary. Do not paste the raw JSON, job ids, or internal field names into the conversation.