Quickads

Generate one ad per Quickads ad-template preset. Returns a task_id to poll. 'template_image_ids' must be existing Quickads ad-template UUIDs, not raw image URLs — these come from list_ad_templates(query, stage, has_product_image); call it first to browse/search the catalog and show the gallery widget, then pass the 'template_id' of whichever the employee picks (can be more than one, to batch-generate across several templates in one call). Pass 'product_image_url' for the product to place into each template. If the employee gives a website/product URL instead of a ready image and details, call BOTH get_product_details_from_url AND scrape_product_images_from_url for that URL, then pass the former's 'product_details' object here, the latter's picked/rehosted URL as 'product_image_url', and the SAME url again as 'web_url' (do not ask for it twice — it's the one URL the employee already gave for this ad). IMPORTANT — logo/brand-color source: 'include_logo' and 'include_brand_colors' only have something to apply if 'product_details' carries a populated 'brand' object (dark_logo/light_logo/colors) — that ONLY comes from get_product_details_from_url's return value. 'web_url' is a SEPARATE input used purely for background text/copy enrichment — it does NOT feed the logo or brand colors. So whenever the employee gives a URL, you MUST still call get_product_details_from_url and pass its full, unmodified 'product_details' object here — never call this tool with only 'web_url'/'product_image_url' and no 'product_details', or the generated ad will silently come out with no logo/brand colors even though those flags are True. DO NOT RETYPE 'product_details' FROM MEMORY. Copy the exact JSON object get_product_details_from_url returned, verbatim, field-for-field — especially the nested 'brand' key (brand.colors.primary/secondary/ tertiary, brand.dark_logo, brand.light_logo, brand.logo). If you reconstruct or summarize it instead of passing the literal object, the 'brand' nested fields are the ones most likely to get dropped, and include_brand_colors/include_logo will then have nothing to apply even though you set them to True. ASK ONE THING PER TURN — this is the most important rule here. Never call a widget tool and ask a question in the same turn (the question card covers the widget), and never stack two questions together. Ask, stop, wait for the answer, then move to the next step. Use the structured multiple-choice UI for each one, not a paragraph. The order: 1. TEMPLATE — call list_ad_templates on its own and wait for their pick. Nothing else this turn. 2. PRODUCT — get_product_details_from_url, then scrape_product_images_from_url, then wait for their picked image (one tool-surface per turn). 3. include_logo — yes (default) / no 4. include_brand_colors — yes / no. Brand colours are filled in from the account's saved brand automatically, so "yes" is safe to offer even if you never fetched a brand object yourself. 5. ai_model_name — show the friendly names, pass the model_N string: "Nano Banana" -> "model_1", "Nano Banana Pro" -> "model_2", "Nano Banana 2" -> "model_3" 6. COPY — ask once for custom_heading / custom_subheading / custom_cta / additional_instructions together, leading with a "let AI write all the copy" option so they can clear all four in one tap. Only split into separate turns if they choose to write their own. 7. Then call this tool. Do NOT ask about 'has_product_image' — set it yourself from whether the employee picked a product or service-industry template in step 1 (True for product, False for service). Do NOT ask for 'web_url' separately — reuse the product/service URL from step 2. Poll get_task_status(task_id) until 'Completed', then call show_ad_result(task_id=...) to actually display the ad(s) inline — announcing them as ready without that call leaves the employee with text and no picture. The raw URLs are in response.data.image_urls. EXISTING accounts are credit-metered for this flow; brand-new (recently signed-up) accounts get a free pass — same billing behavior as the REST endpoint. Don't tell an existing account it's free. Generation can occasionally take up to ~5 minutes. Keep calling get_task_status every ~15s and do NOT stop or ask the user whether to keep waiting — only stop once status is 'Completed' or 'Error'. "In Progress" this long is expected, not stuck.

Generate a video from a catalog template (the template flow's final step). 'template_id' comes from recommend_templates. 'prompt' = the dialogue/script / ad copy for the video. 'reference_image_urls' MUST supply the template's required images (see recommend_templates 'image_roles' / 'required_image_count') in order — for Seedance 2 / Short clip templates this is enforced; ClaudeHTML templates work from the script alone (images optional). Returns the inline native player, which POLLS AUTOMATICALLY and updates to the finished video — do NOT poll get_task_status yourself unless the user says it isn't updating.

Generate one image, or a whole consistent set of them, on any supported model. ONE IMAGE — pass 'prompt' and nothing else: generate_image(prompt="a cat on a red sofa, golden hour") generate_image(prompt="this pack on marble", model="gpt_image_2", ratio="4x5", reference_image_urls=["https://…/pack.png"]) MANY IMAGES THAT MUST MATCH EACH OTHER — pass 'items'. This is the reason this tool exists: items can reference each other, so the same face and the same product carry across every frame. That only works INSIDE ONE CALL — separate calls produce visibly different people and packs. Send the whole set at once. Each entry in 'items': prompt (str) required. Name reference images inline as @image1, @image2 … — see the ordering rule below. model (str) "nanobanana" | "nanobanana_pro" | "nanobanana_2" | "seedream" | "gpt_image_2". Separator style is forgiving ("nano-banana-2", "gpt"). Unrecognised names are REJECTED, not silently swapped. Default gpt_image_2 (the house default). ratio (str) "9x16" | "16x9" | "1x1" | "4x5" | "3x4" | "2x3" … URL-safe, no colons. Default 9x16. references (list of str) keys/ids of OTHER items in THIS call, fed in as reference images. The backend topologically sorts these, so list order does not matter — but a cycle is rejected, and an item whose reference failed is skipped rather than generated wrong. reference_image_urls (list of str) hosted http(s) images from outside the call. No effect on ordering. …plus, optionally, ONE of these two ways to address the item: id (str) your own label, so other items can reference it. Use this to chain — frame 2 references frame 1 for continuity. angle/beat/slot storyboard addressing. 'angle' is the angle slug ("a1"), 'slot' is the image's role AND its filename ("char", "product", "first_frame", "end_frame"), 'beat' is the beat id ("b01") or null for angle-level images (character and product sheets). angle + slot must be given TOGETHER; sending one without the other is an error. Omit all three and an id is assigned automatically. Typical storyboard shape: the char and product items have references=[]; each first_frame references ["a1/char", "a1/product"] so the same face and pack appear; each end_frame references the char, the product AND its own first_frame so the shot stays continuous. REFERENCE ORDER IS A CONTRACT: 'references' resolve first, in the order you listed them, then 'reference_image_urls'. @image1 is the first reference and the numbering runs continuously into the URLs. Tool-level 'model' and 'ratio' act as DEFAULTS for items that don't set their own (same convention as generate_frames). Tool-level 'reference_image_urls' is single-image only — with 'items' it has to go on the item that needs it, because reference order is per-item. Returns task_id, accepted (item count) and status. Poll get_image_status(task_id) for the URLs — results stream in level by level, so partial output is visible before the run finishes, and the response body is the only authoritative source of both the URL and the per-item outcome.

Create a PRODUCT turnaround sheet (all angles + detail shots) from product photo(s) (GPT Image 2). Use when the user wants their product shown consistently in the video. Pass one or more product photos. Returns IMMEDIATELY with an auto-polling widget (the sheet takes ~1-3 minutes and generates in the background — do NOT poll get_task_status in a loop). When it finishes, use the sheet's URL as a reference_image_urls entry for generation.

Generate the final video. Returns a task_id to poll. 'model' must be the one the user already chose (if they never picked one, call list_video_models and ask first). For Seedance 2 models pass 'prompt' = the (optionally user-edited) storyboard text from build_storyboard. EVERY other registry model (veo-3-1, veo-3-1-fast, kling-3, kling-3-turbo, gemini-omni, seedance-1-5-pro) generates a SINGLE clip directly from 'prompt' — same as generate_clip — honoring that model's input rules (see list_video_models 'input_rules'); no project_id needed. Before generating, OFFER open_image_uploader so the user can OPTIONALLY upload reference image(s) to steer the look — pass any returned URLs as reference_image_urls (skip the offer if references were already provided). If the user wants to lock the opening shot first, offer generate_frame (a first-frame/scene image) or generate_character (a consistent character) and pass the resulting URL as a reference_image_urls entry. Poll get_task_status(task_id) until 'Completed'; the video URL is in 'response'.

List every avatar in the avatars_lib catalogue, paginated -- the whole library, not a persona match. Use this when the ask is about the library itself rather than about filling a role: "what avatars do we have", "how many South Asian women are in the library", "show me everything added recently", an audit of inactive rows, or any time you need a stable page-by-page walk through the catalogue. For "find someone who fits this character" use search_avatar_references instead -- it ranks by persona fit and hides rows that would wreck a generation; this tool ranks nothing and hides nothing. Filters are the coarse dashboard set and are all exact-match except search_keyword, which is a case-insensitive substring across display_name, file_name, person_id and image_id. 'active' is tri-state: leave it unset for every row, true for live rows only, false to audit what has been retired. There is deliberately no usable_as_reference or face_clear filter here -- a catalogue listing is supposed to show the flawed rows too, which is exactly why you should not feed a row straight from this tool into a generator without checking its usable_as_reference and face_clear values. Rows come back newest-first (createdAt desc) as full avatar records: id, image_id, person_id, display_name, gender, age, age_range, ethnicity, vibe_expression, wardrobe, setting, apparent_class_context, tags, hosted_url, shot_type, angle, face_clear, resolution, resolution_band, orientation, usable_as_reference, review_notes, active, created_at, updated_at. Paging: 'page' is 1-based and 'page_size' is capped at 100. The response carries 'total' (rows matching the filters), 'pages', 'page' and 'page_size' -- read 'pages' rather than guessing when the library ends, and note that rows are one IMAGE each, so one person with six shots occupies six rows. An empty library or a filter that matches nothing returns data: [] with total 0 and a 'message' field; that is a real answer, not an error, so do not retry it.

Poll a generate_image run and get the image URLs back. Returns: status "pending" | "done" | "error" total / completed / failed images one entry per requested item, each with key, id, angle, beat, slot, ratio, model, path, image_url and a per-item status of "done", "failed" or "skipped". "skipped" means one of its references never generated, so it was not attempted — fix that reference and re-run. Results land level by level, so calling this while status is still 'pending' returns the images finished so far. Wait a few seconds between polls; a single image is quick, a full storyboard takes a couple of minutes. This response is the authoritative source for both the URL and the outcome. Do not construct URLs from the path and assume they exist — a failed item has a path and no image.

Get every reference shot on file for one avatars_lib person, by their person_id. Use this once search_avatar_references has picked a person and the storyboard needs more of their shots as references than the search result carried -- e.g. a specific angle or shot_type wasn't in the first batch. Default limit is 3 (matches the dashboard's "top 3" view); raise it if you genuinely need this person's full set. Returns the person's identity fields once (gender, age, ethnicity, vibe_expression, wardrobe, setting, apparent_class_context, tags) plus 'total_images' (their full count, which may exceed what 'images' contains if limit/offset paged it down) and 'images[]' -- each with hosted_url, shot_type, angle, face_clear, resolution_band. Same reference-safety defaults as search_avatar_references (active/usable_as_reference/face_clear/hosted_url), with the same two override flags. Raises an error if person_id doesn't match anyone -- double check it came from a prior search_avatar_references result rather than being guessed.

Extract product/brand details from a website URL (scrape + LLM extraction). ASKING FOR THE URL: when you need a URL and don't have one yet, ask with your structured multiple-choice question UI (a free-text/"other" option plus ~3 suggested URLs), never a plain paragraph. Pick the suggestions yourself, fresh each time rather than reusing a fixed trio, and match them to what's being advertised — real product-brand sites for a product template, real service-business sites for a service-industry template, ideally from the brand/industry the employee already mentioned. Use when the employee gives a product/brand URL instead of typing details by hand. Returns a 'product_details' object — pass it (as JSON, e.g. json.dumps(product_details)) straight into generate_ad_to_ad's, generate_from_ad_template's, or generate_ad_variations' 'product_details'-style inputs where applicable; it already carries product_name, product_description, price, other_information, summery, caption, ideal_customer, industry, product_category, stage, and brand (logo/colors) — no reshaping needed. Pair with scrape_product_images_from_url to also get a product photo from the same site.

Fetch the hosted URLs of images the user recently uploaded in the widget. Call this whenever the user says they uploaded / attached an image (e.g. via the 'Upload your own' tile from open_image_uploader) but you don't yet have its hosted URL — the widget hosts the file on Quickads storage but the URL may not reach you automatically. This returns the most recent uploads (newest first); use the returned http(s) URL(s) as reference_image_urls (or image_url for generate_character) when generating. If it returns nothing, ask the user to click 'Upload your own' again and wait for the ✓. Every entry carries a 'purpose'. MATCH ON IT rather than just taking the newest: a reference AD to clone (for generate_ad_to_ad's template_image_url, uploaded via open_reference_ad_uploader) has purpose='template', while the product-image picker's uploads have purpose='product'. Taking the newest entry blindly grabs the wrong image whenever both widgets were used in the same session.

Get the status of a build_storyboard / generate_video / generate_clip / generate_ad_to_ad / generate_from_ad_template / generate_ad_variations task. Statuses: 'Queued' / 'Processing' -> still running (poll again in ~10s), 'Completed' -> result is in 'response', 'Failed' -> see 'error'. For video tasks the result renders an inline NATIVE video player widget: a status card (status badge + selected model/specs + prompt) while generating, and the playable <video> once Completed. Keep polling on the same task_id. For the image-ad tasks (generate_ad_to_ad / generate_from_ad_template / generate_ad_variations): as soon as the status is 'Completed', CALL show_ad_result(task_id=...) — that renders the finished creative(s) inline with a copy-URL button on each. Never announce the ad as "ready" without calling it, and never write the image as chat markdown (``) — this host shows remote markdown images as a grey "Show Image" placeholder instead of loading them, which is what show_ad_result exists to avoid. Mention the raw URL in text only if the user asks for it.

Browse the Quickads ad-template catalog to find a template_image_id. BEFORE YOUR FIRST CALL: ask the employee for everything you'll need, in ONE round, using your structured multiple-choice/quick-reply question UI (one question per pick, NOT a free-text paragraph). Collect the URL in this same round too — the gallery widget CANNOT ask you anything later (this host exposes no chat-injection API to widgets), so anything you skip here means a dead end after they pick a template. THEN CALL THIS ALONE, AS THE WHOLE TURN. Never ask a question in the same turn you render the gallery — the question card covers the widget and the employee can't browse and answer at once. Render it, add at most one short line ("pick the one you like"), then END YOUR TURN and wait for their pick. Set multi_select=True when you're collecting templates for ADVANCE ad variations. The grid then lets the employee add several and press Done, and it reports them together as "Use these N ad templates for the variations (variation_template_ids): id, id, …" — pass that list to generate_ad_variations' 'variation_template_ids'. The count of templates IS the number of variations, so do not ask "how many" afterwards. Leave multi_select at its default (False) for generate_from_ad_template, which takes one pick at a time. The questions to ask BEFORE that call are: Q1 (choice): which stage — Stage 0: Brand Awareness Stage 1: Customers UNAWARE of PAIN POINTS Stage 2: Aware of the problem but UNAWARE of PRODUCT Stage 3: Aware of product but UNAWARE of RELATIVE BENEFITS Stage 4: Aware of above but CREATE URGENCY to act Stage 5: Retargeting (or "All stages") Q2 (choice): product templates (default) or service-industry templates (no product placement — has_product_image=False) Q3 (choice, with a free-text option): how many to show — offer a few presets (e.g. 6 / 12 / 24) plus "other". Q4 (free text, with suggestions): the product/service URL the ad should be built from — always include an "other"/free-text option, plus ~3 real, currently-live example URLs that YOU pick fresh each time (don't reuse the same three every run — the employee should see different ideas on each visit). Derive them from context: if their message named a brand, industry, or vertical, suggest sites from that space; if they said nothing, offer a spread (some product-brand sites, some service-business sites, since Q2's answer isn't known yet when you ask). Only if you genuinely can't think of anything contextual, fall back to: nike.com / mamaearth.in (product), urbancompany.com / practo.com (service). Defaults to Stage 0 if you don't pass 'stage' at all — pass stage=None explicitly if the employee wants ALL stages mixed together. Skip asking (and don't show the question UI) for anything they already specified in their message (e.g. "show me 10 stage 2 service templates for nike.com"). AFTER results are shown: the employee clicks a template in the gallery and pastes a short prompt naming its template_id. At that point you ALREADY have their URL from Q4 — do NOT ask again; go straight to get_product_details_from_url + scrape_product_images_from_url on that URL, then generate_from_ad_template. The gallery's own stage dropdown re-calls this tool directly, so stage/product switches need no chat turn. This catalog is GLOBAL — shared across all accounts, not owned by the caller. It's organized into 6 numbered 'stage' buckets (0-5, ~170-200 templates each) representing customer-awareness-funnel stages (Brand Awareness -> Retargeting; see STAGE_LABELS) — pass 'stage' to browse one bucket at a time; the gallery widget also lets the employee switch stages directly, no need to re-call this yourself just to change stage. 'query' ranks templates by their 'concept_name' (a short design-pattern family name, e.g. "The Premium Variant Cluster") and 'core_idea' (a 1-2 sentence description) — these are the ONLY searchable text fields; do NOT ask for or filter by industry/vertical, the catalog has no real per-template industry data. 'has_product_image' mirrors the app's own filter: True (default) returns templates whose concept includes a product placement (or leaves it unspecified); False returns templates explicitly without one. Each result includes 'template_id' (pass this as one entry of generate_from_ad_template's template_image_ids — you can pass more than one to batch-generate across several templates in one call), a 'preview_url' mockup, and up to 6 'example_output_urls' — REAL past-generated ads made from that template (an empty list is normal; most templates have few or no linked generations yet). The result also lists 'available_concepts' (unique design families in the current stage/ has_product scope) so you can steer the employee. Show the gallery widget; when they click a card it sends you the template_id in a follow-up message — then call generate_from_ad_template.

Show the employee's own recently generated ads so they can pick one to vary. CALL THIS ALONE, AS THE WHOLE TURN. Never ask a question in the same turn you render this grid — the question card covers it and they can't browse and answer at once. Render it, add at most one short line ("pick the ad you want to make variations of"), then END YOUR TURN and wait for their pick. Each card carries a numeric 'project_id'. That is what generate_ad_variations' 'project_id' takes — NOT a URL and NOT a UUID. When the employee picks one, the widget reports it back in chat as "Use this creative as the variations base (project_id): <id>". Pass that id and pass NOTHING for template_image_url: the pipeline pulls the base image, the product shot AND the brand (colours + logo) straight off that saved project, so there is nothing else to collect. Newest first, default 10 (max 24). Only finished image ads appear (rendered creatives with a stored output image). Note that several cards may share the same title — one variations run saves a set of sibling ads — so the images and timestamps are what tell them apart. The list spans ALL the brands on the account, not just the one currently being discussed. If the employee picks a creative from a different brand, say so, because its brand colours and logo come from that creative's own saved data.

List the AI video models and each model's per-model input rules. Every model here is generated as a single clip via generate_clip. They differ in what inputs they accept — read each model's 'input_rules': - text→video vs image-to-video (kling-3-turbo REQUIRES one input image); - whether it accepts first/last frames (Veo, Seedance); - how many reference images / videos / audios it takes (e.g. Gemini Omni up to 7 images + 1 video; Seedance 2 up to 9 images / 3 videos / 3 audios; Veo 3.1 Fast up to 3 reference images, always 8s; Veo 3.1 / Kling 3.0 / Seedance 1.5 accept frames only, no reference images). - Frames and references are mutually exclusive on every model. The Seedance 2 family ('storyboard_text': true) can ALSO drive the multi-scene build_storyboard → generate_video flow for longer stitched videos.

Show a colour picker so the employee can choose the variation colour. CALL THIS ALONE, AS THE WHOLE TURN. Never ask a question in the same turn — the question card covers the picker. Open it, add at most one short line ("pick the colour you want"), then END YOUR TURN and wait. Use it when the employee answered "use a specific colour" to the colour question in generate_ad_variations' flow. Do NOT open it when they chose their brand colours — the two are mutually exclusive and passing both is rejected. They can use the native colour wheel, tap a preset swatch, or type a hex. The widget previews the colour on a mock ad (background, headline and CTA) with automatic light/dark text, so they can see the contrast before spending credits. It reports the value back in chat as "Use this variation colour (variation_color): #DDB5FF" — pass exactly that hex as generate_ad_variations' 'variation_color'. Optionally pass 'base_image_url' — the ad they're making variations of — to show it beside the swatch for context, and 'current_color' to pre-select a hex they already mentioned. This tool only picks a value; it generates nothing and costs no credits.

Show an inline uploader so the user can pick a LOCAL image OR video to use as a reference. Use when the user wants to upload their own photo/artwork/clip from their device (rather than search stock or scrape a URL). Renders the picker widget with an upload drop zone: the user chooses a file (image ≤15 MB, or video mp4/mov/webm ≤50 MB), the widget hosts it and reports the hosted URL back to you — use an image URL as a reference_image_urls entry and a VIDEO URL as a reference_video_urls entry when generating. If you don't see the URL, call get_recent_uploads (each item is tagged image/video). (The user can also paste an http(s) image URL and you call add_reference_image.)

Show an uploader so the employee can supply the REFERENCE AD to clone. CALL THIS ALONE, AS THE WHOLE TURN. Do not ask the employee any question in the same turn you call this — a question card renders on top of the uploader and they cannot use both at once. Call it, add at most one short line telling them to drop the ad or paste its URL, then END YOUR TURN and wait for the hosted URL. Only after it arrives do you ask about the product, the model, the stage, or anything else. Two flows need this, and both take the hosted URL as 'template_image_url': - generate_ad_to_ad — the ad whose style/layout gets CLONED onto the employee's product. - generate_ad_variations — the ad they want VARIATIONS of, when they'd rather upload one than pick from list_my_recent_creatives. (If they pick a saved creative instead, skip this tool entirely and pass that project_id — no upload needed.) Neither flow can run without a base image, so call this whenever you don't already have a hosted URL. Never ask the employee to type a URL blind; open this instead. The widget has TWO lanes, both hosting the result on Quickads storage: a drag-and-drop / file-pick zone (for a screenshot or a saved ad file), and a "paste the image URL" field (for an ad already online — it gets re-hosted, which is required for the thumbnail to render at all). Optionally pass 'template_image_url' to pre-populate: if the employee already pasted a reference-ad URL in chat, hand it over here and the widget shows it already re-hosted and pre-selected — which also proves the URL is fetchable before you spend a generation on it. An unreachable URL is not an error; the uploader still opens so they can drop the file instead. This tool does NOT generate anything and costs no credits.

Recommend suitable video templates from the Quickads catalog. This is the DEFAULT when the user wants a video but has NOT provided their own storyboard/script. Searches only the supported families (Seedance 2 / Short clip / ClaudeHTML). CONSIDER THE USER'S INDUSTRY/CATEGORY: pass 'category' = their industry (e.g. "Skincare", "Fashion", "SaaS", "Real Estate" — partial, case-insensitive) whenever you can infer it, and 'query' = the topic/brief (e.g. "skincare ugc"); results are ranked with category/industry as the strongest signal. The result also lists 'available_categories' so you can steer the user by industry. Each returned template includes its 'template_id', 'category', a preview, duration, and its REQUIREMENTS — 'required_image_count' + 'image_roles' (what each reference image should be) and 'input_fields' (text inputs like dialogue). Suggest the best-fit template, tell them exactly which reference images and script it needs, help them gather those (search_stock_images / open_image_uploader), then call generate_from_template(template_id, prompt=the script, reference_image_urls=[...]).

Pull candidate product photos from a website URL. CALL THIS ALONE, AS THE WHOLE TURN. Never ask the employee a question in the same turn you render this picker — the question card covers the grid and they can't pick and answer at once. Render it, add at most one short line ("click the product photo you want"), then END YOUR TURN and wait for their pick. Use when the employee gives a product/brand URL and needs a product image. Every candidate is already re-hosted onto Quickads storage before you see it (so thumbnails always render regardless of the source site's domain). Returns candidates in a CLICKABLE picker grid — tell the employee to click the image they want; the widget reports the (already-hosted) URL back to you via chat — no further rehosting needed, just use that URL directly as 'product_image_url'. The widget ALSO has an "upload your own product photo" drop zone, for when nothing scraped from the site is usable — those uploads go to Quickads storage too and behave identically, so never tell the employee to go elsewhere to upload. Capped at 30 scraped candidates (fewer if some fail to rehost). Pair with get_product_details_from_url to also get product text from the same site.

Pull images (logo, hero/og image, product photos) from a brand/product URL. Use when the user references their website, a product page, or a brand link. Returns candidates in a CLICKABLE picker grid — the user clicks the image(s) they want; the widget re-hosts each pick and reports its reference URL back to you via context (do NOT call add_reference_image yourself for grid picks). For product catalogs the logo + hero + on-page images are surfaced.

Search the avatars_lib reference library for real people matching a persona, ranked by fit. Call this BEFORE generating a brand-new character sheet whenever the storyboard needs a person: an existing hosted reference is cheaper and holds up better across frames than a freshly generated one. Pass the persona in 'q' as prose exactly as you'd describe it internally (e.g. "warm Indian woman, early 30s, home kitchen") -- structured filters alone miss what prose catches. Add structured filters (gender, age_range, ethnicity, ...) whenever the persona pins those down; they narrow the search, 'q' just biases the ranking. Results are grouped by person, not by image -- pick a person, then use ALL of their 'images[].hosted_url' as the reference set for that character (multiple angles/shots of the same person is the point). Sorted by 'match_score' (0..1, highest first); a near-miss with a lower score still beats falling through to generation, so don't discard a result just because it isn't a perfect match. If 'relaxed' comes back true, nothing matched every soft attribute (vibe_expression/setting/apparent_class_context/wardrobe) exactly, so those were dropped and the returned people are the closest available -- identity (gender/age/ethnicity) and per-image quality filters were NOT relaxed, so everything returned still satisfies those exactly. Defaults exclude unusable/inactive/unclear-face/no-URL rows -- the most likely source of character drift if fed to a generator. Only override include_unusable/include_inactive if you deliberately need to inspect flagged rows (e.g. an admin/QA request); there's no override for a blurry face or a dead URL. If 'count' comes back 0, there's genuinely nobody in this account's library matching the identity/quality filters given -- move on to generating a character rather than retrying. Once you've picked a person, call get_person_avatar_shots(person_id) if you need more of their shots than this returned (search doesn't cap images per person, but get_person_avatar_shots is the one built for "give me everything for this person").

Search stock images for a topic and show them in a grid for the user to pick. Use when the user wants a video "about" something and you need real reference imagery. 'orientation' is portrait (9:16, default), landscape (16:9), or square. Returns candidates in a CLICKABLE picker grid — the user clicks the image(s) they want; the widget re-hosts each pick and reports its reference URL back to you via context. Do NOT call add_reference_image yourself for grid picks — just use the reference URLs you receive when generating.

Display finished ad creative(s) inline, each with a copy-URL button. Call this the moment an image-ad task reaches 'Completed' — pass the 'task_id' you were polling and it pulls the creative(s) out itself. Do NOT describe the ad as "ready" without calling this, or the employee gets text with no picture. Do NOT write the image as chat markdown (``) either: this host renders remote markdown images as a grey "Show Image" placeholder instead of loading them, which is exactly what this widget exists to avoid. Also use it to re-display an earlier ad, or to show arbitrary hosted ad images by passing 'image_urls' instead of a task_id. Several images (e.g. from generate_ad_variations) page 3-at-a-time behind arrows. This tool only renders — it generates nothing and costs no credits.

Show MULTIPLE finished clips together in ONE native player (a grid). Use this whenever you have more than one clip to display — several generate_clip results, the clips of a multi-scene / 30s+ video, etc. Showing each clip with its own show_video (one widget per clip) makes the host render duplicate widgets that collapse to a single clip; show_clips renders them all as a grid in a SINGLE widget so every clip appears, each with its own player + per-clip download. 'clips' is a JSON array (newest→oldest or scene order) of objects: [{"video_url": "https://…", "duration_seconds": 15, "title": "Scene 1", "thumbnail_url": "https://…"}]. Only 'video_url' is required per clip. width/height are the clips' pixel dimensions (from 'video_dimensions').

Show a completed video in the inline NATIVE video player (not Remotion). Call this to let the user WATCH a finished clip instead of clicking a URL — pass the 'video_url' from a completed generation task (get_task_status), 'duration_seconds' = its duration, and width/height = its 'video_dimensions'. ALWAYS pass 'prompt' = the video's generation prompt / storyboard text and 'model' / 'resolution' / 'aspect_ratio' — the card shows the prompt (clamped, with Show more) + spec chips above the player, so omitting them leaves it blank. get_task_status already renders this player (with the prompt from the task) while polling and on completion; use show_video to (re)display any completed or user-provided URL. The Remotion player is for EDITING only (create_edit_project -> preview_video).

Transcribe a video's speech and get ready-to-use captions (Whisper). Pass the clip's URL (e.g. 'response.video_url' from a completed generate_clip / generate_video task) and the spoken language as an ISO 639-1 code ('en', 'hi', 'es', ...) or a plain name ('English', 'Hindi'). Returns the full transcript text, word-level timestamps ('words'), and caption lines grouped for on-screen display ('captions', each with text/ start/end in seconds). Call it once per clip to caption each video.

Host a LOCAL image OR video on Quickads storage and return an http(s) URL. Use this when the image is NOT already a public URL — a chat attachment, an extracted video frame on disk, a screenshot, a real person's photo you must not send to a third-party host. Every other tool (generate_character, generate_product_sheet, and the reference_image_urls / first_frame_url / last_frame_url params) needs an http(s) URL; upload_asset is how a local image becomes one. Pass the image as base64 (raw, or a 'data:image/...;base64,' URI). It is stored on Quickads' OWN bucket (never a third party); the returned 'asset_url' can be fed straight into those tools. 'purpose' can be 'reference', 'character', 'product', or 'template' — use 'template' for a reference/competitor AD whose style will be cloned via generate_ad_to_ad's template_image_url.