List ClipUGC AI characters (AI influencers). Same as clipugc characters list. scope "mine" (default) lists the authenticated user's own characters, "discover" the public feed, "feed" own characters first then public ones. Returns items with id, display_name, age, gender, is_public, status, plus pagination. Costs no credits.

Create a new AI character from a plain-text description. Same as clipugc characters create. The server extracts the appearance DNA and generates the first look automatically (2 credits; confirm with get_credits). Be specific: nationality, age, hair, eyes, face shape, skin, style, and a realism anchor such as "natural skin texture, not airbrushed". Characters are public by default; set private=true to opt out. make_video=true also stages the first clip (extra clip cost). Returns the character with first_look_id. Looks generate in the background. Poll list_images with the same character id every 5 to 10 seconds until each new look has status "completed" (or "failed"), then pass the look id to create_clip. Advanced: pass name (2-120 chars) plus optional age, gender, dna_json instead of description for a structured create.

Generate one or more new looks (reference images) of an existing character. Same as clipugc images generate. Every look is generated from the character's base image, so the face stays the same person: only describe the new setting, outfit and light in scene, never the person again. Costs 2 credits per shot (confirm with get_credits). Returns the created image ids. Looks generate in the background. Poll list_images with the same character id every 5 to 10 seconds until each new look has status "completed" (or "failed"), then pass the look id to create_clip.

List the looks (reference images) of a character with id, status (pending, processing, completed, failed), scene_prompt and image url when ready. Same as clipugc images list --character <id>. Also the poll call for generate_image and create_character. Costs no credits.

Animate a character look (or your own photo) into a short video clip. Same as clipugc videos create. Costs 7 credits for 5 seconds or 13 for 10 seconds; adding scene makes it a scene-staged clip (9 at 5s, 15 at 10s). Confirm with get_credits first. Prefer a silent reaction prompt (mouth closed, no talking, an arc in beats, ambient motion): lip-sync from a still image is what makes AI video look fake. Provide exactly one of image or photo. Returns the clip id and status. Generation runs in the background. Poll get_video with {"id": , "kind": "clip"} every 5 to 10 seconds until status is "completed" or "failed", then call download_video.

Animate a character look (or your own photo) by copying the motion of a driver video. Same as clipugc videos motion. Costs 3 credits per second of driver video, rounded up, capped at 30 seconds (confirm with get_credits). The driver must be mp4/mov, at most 50 MB and 30 seconds; it is uploaded first. Provide exactly one of image or photo. Returns the clip id and status. Generation runs in the background. Poll get_video with {"id": , "kind": "clip"} every 5 to 10 seconds until status is "completed" or "failed", then call download_video.

Merge a completed clip with an app screen recording and a hook text overlay (plus optional background music) into the final UGC ad. Same as clipugc videos merge <clipId>. The clip must have status "completed" (check with get_video). Merging is free at the time of writing; the live cost is the "merge" entry of get_credits. Files are uploaded first. Returns merged_video_id: the AD id, which is a different id space from the clip id. The merge renders in the background. Poll get_video with {"id": , "kind": "ad"} every 5 to 10 seconds until status is "completed" or "failed", then call download_video with kind "ad".

Get the current status of a clip (kind "clip", default; same as clipugc videos status <id>) or of a merged ad (kind "ad"; same as clipugc ads show <adId>). This is the poll tool for create_clip, create_motion_clip and merge_ad. Status is pending, processing, completed or failed. A clip record also carries merge_status and merged_video_id once merged. Costs no credits.

Download a completed clip (kind "clip", default; same as clipugc videos download <id>) or a completed merged ad (kind "ad"; same as clipugc ads download <adId>) to a local mp4 file. Pass an absolute output path; missing parent directories are created. Costs no credits. Fails if the video has not completed yet.

Return the authenticated user's credit balance and the live per-action credit costs (image, clip, clip_10s, scene_staged, motion_per_second, merge). Same as clipugc credits. Call it before any generation tool so you can tell the user the cost and stop early when the balance is too low. Costs no credits.

Get AI-suggested hook texts (the short attention-grabbing line burned over a UGC ad). Same as clipugc hooks suggest. Pass context describing the app for tailored hooks. Pick one (max 150 chars) and pass it as hook to merge_ad. Costs no credits.