TikTok Ads

INTERNAL widget-only poll for asynchronous storyboard sketch generation. Scene sketches can take over a minute, so generate_storyboard_scene_images returns still-running scenes as status "generating" with a sceneKey; the storyboard_preview widget polls THIS tool with those keys until each job is terminal. Long-polls server-side (returns as soon as any scene's status changes). Renders no card. The model must NEVER call this; it is invoked automatically by the widget.

INTERNAL widget-only probe. Returns superseded=true when a newer widget card has rendered in this session than the caller's card_uid, so a previous widget can disable its own buttons. Makes no external call and renders no card. The model must NEVER call this; it is invoked automatically by widgets.

Read-only readiness check for a generated video — THE allowed way to confirm the video's status yourself. Renders NO card, starts NO generation, returns no URLs: just {status, ready, review_guidance} for the given video_task_id (the generate_id). Use this whenever you want to verify the video is ready before preview_smartplus_campaign or create_smartplus_campaign_draft, or to re-confirm after a refresh — instead of generate_video_and_wait (starts/dedups a generation AND renders another card) or wait_for_generated_video (widget-only, renders a card). Safe to call repeatedly; near-instant.

INTERNAL widget-only long-poll: ONE held connection a card uses to watch every signal it is waiting on — supersession (card_uid), async storyboard sketch jobs (scene_keys), and video generation (video_task_id). The widget attaches only signals it still believes are pending; the server holds the request and returns the moment anything watched is no longer pending, with the full current state of all watched signals. Renders no card, makes no mutations. The model must NEVER call this; it is invoked automatically by widgets.

Render the connect-identity card so the user can pick the TikTok identity (TT_USER, BC_AUTH_TT, or AUTH_CODE) to publish the Smart+ ad under. The identity is the user's choice ON THE CARD: this tool renders the options, and the user's click carries identity_type / identity_id (and identity_authorized_bc_id when present) plus advertiser_id forward to create_smartplus_campaign_draft. Returns status=connected with identities[] (each: identity_type, identity_id, optional identity_authorized_bc_id, plus display_name/username/profile_image), or status=needs_authorization with a QR code for connecting a new account — follow that result's own next_step guidance. advertiser_id: the account chosen via select_tiktok_advertiser, or the single auto-resolved account; never invent a placeholder — if it is omitted while several accounts are authorized, call select_tiktok_advertiser first.

Create a disabled native Smart+ campaign draft (Campaign → Ad Group → Ad, all operation_status=DISABLE) from an approved preview payload. Internally resolves missing advertiser_id, identity, and CTA portfolio, and uploads video / cover image as needed. Recoverable: on partial failure returns artifacts and resume_hint so the next call can resume without duplicating resources. TERMINAL RENDER — call ONCE per draft: a draft_created result is final; do NOT re-call to re-acknowledge or re-show it (a redundant re-call is refused). Re-call ONLY to retry a failed/partial_failed draft or apply a genuine user edit.

Build a storyboard prompt for a TikTok ad video from confirmed product data. Returns a prompt the client uses to draft scene-by-scene storyboard JSON. This is the MANDATORY entry point for the storyboard/creative phase: whenever you are about to propose an ad concept, scenes, or a storyboard, first call this tool, then call present_storyboard to render the widget

Generate optional per-scene STORYBOARD SKETCHES (deliberately not photorealistic) conditioned on the user-confirmed product reference images. Sketches are for the user's approval of the storyboard only — they never feed video generation and do not block storyboard approval.

Submit a TikTok ad video generation and render the video_status card. This is the SINGLE entry point for video generation — call it ONCE after the storyboard is approved (Phase 3, BEFORE the campaign preview); never call create_video / generate_video directly. It submits the generation, captures generate_id, does a brief status check, and returns within a few seconds. TikTok videos take 5–10 minutes, so the call almost always returns status=processing — that is normal and NOT an error: the video_status card shows progress and a Refresh chip the user clicks to poll to completion. Do NOT call this tool again and do NOT call wait_for_generated_video yourself — that starts a duplicate generation. The video model, aspect ratio, and duration are fixed by the server — supply only user_input_text and materials.image_urls. The finished video is announced to YOUR CONTEXT by the video_status card when it completes — look for {widget:"video_status", status:"ready"|"selected", video_task_id}. After the user clicks Use this video, pass that video_task_id (the generate_id) as preview_smartplus_campaign.video_task_id — you never need a video URL for any later phase (any video_url is a watermarked preview for display only; never pass it to an upload field); the server resolves the publishable file from the video_task_id at draft-create. To CONFIRM status without a card, call check_video_ready (read-only). Calls are IDEMPOTENT per session+arguments: identical re-calls return the SAME generation instead of starting a new one; force_new_generation: true (an explicit user Regenerate / Try again) produces a genuinely new video.

Get details for one of the user's authorized TikTok Ads advertiser accounts — such as account name, status, currency, and timezone — from the TikTok Ads platform. Read-only lookup; select which fields to return via the fields parameter.