InstantClips

Create a new brand for a product that is waiting on `brand_decision_required`, and attach the product to it. Use this when the product belongs to a company the account has no brand for yet — the usual case when someone brings a new store. For a product imported from a URL the brand's name, voice, target market and keywords are taken from what the storefront scrape drafted; the user can rename it with `name`. For a product created from photos nothing was detected (`detected_brand_name` is null), so `name` is required and `voice`, `target_market` and `keywords` should come from the user — ask them how the brand sounds and who it sells to. Anything you pass overrides the detected value. Ask the user before calling this. It consumes one of the plan's brand slots, and on a plan that has run out this fails with a brand-limit error — at which point the choices are to attach the product to an existing brand with `set_product_brand`, to re-point an existing brand at this identity with `set_product_brand` and `replace_identity: true`, or to upgrade. Once this returns, the video direction starts drafting: poll `get_product` until `video_direction.drafting` is false. Direction drafting sends product facts, photos and brand context to an external AI service when the product is ready and its brand is settled. This does not spend credits.

Start a new InstantClips product from product photos, for a product that has no public page to scrape. Photos arrive one of two ways: `image_urls`, publicly reachable URLs, or `image_files`, the photos the user attached to the conversation, for clients that pass attachments to tools (ChatGPT fills it in from the attachments — do not build it by hand). Either or both, at least one photo. This endpoint cannot read files from the caller's machine. Images larger than 8MB are skipped; at most 9 are used in a render. With `image_urls` alone the downloads run in the background: poll `get_product` until `import_status` is "imported". Attached photos are downloaded before this call answers, so the product comes back imported — or failed, with the reason and the way on in `next_step`. Photos carry no brand identity, so nothing can detect the brand here. Without `brand_id` the product waits on a brand decision (`brand_decision_required` on the response and on `get_product`) and no video direction is drafted until it is settled with `set_product_brand` or `create_brand`. Ask the user which brand this is; do not pick for them. Prefer `import_product_from_url` when a product page exists — the scrape also collects the name, description, price and brand identity, which make for a far better direction draft than images alone. Direction drafting sends product facts, photos and brand context to an external AI service when the product is ready and its brand is settled. This does not spend credits. Only `generate_video` does. Through this adapter, `image_paths` (files on this machine) replaces `image_urls`; the files are uploaded directly. Send one or the other, not both.

Render the video. THIS SPENDS THE USER'S CREDITS. Product photos, brand identity and direction are sent to external generation services. Results have public share pages; generation can trigger account emails, including a first-generation welcome email. Ask the user before calling this, every time. Tell them the cost first — `get_product` reports it as `video_direction.credit_cost`, and the user's balance as `credits_remaining` — and pass that cost as `expected_credit_cost`: if it no longer matches (settings changed, a resolution was clamped), nothing is charged and the response says the current cost. Credits are charged at launch, not on completion; a failed render is refunded automatically. Show the user the creative direction and let them approve or edit it before you call this. Do not call it to "see what happens", to retry a render that is still in progress, or as part of a batch you decided on your own. Returns as soon as the render is queued — the video is not ready yet. Do not answer with a bare "generating" and start polling silently. Tell the user, in one reply: it is in the queue and takes 5 to 15 minutes depending on queue depth, length and resolution; `workbench_url` is where they can see what they directed; and `email_on_completion` (present unless the account takes no mail) gets a message the moment it is done, so they can go and work on something else. Say you will keep checking only if you actually can — if this client keeps you running long enough to poll, and your session survives the user walking away. This server is request/response and holds no monitoring of its own: nothing here will wake you up, and if your session ends mid-render the video still finishes and the email still goes. When you cannot promise it, say so, and leave them with the link and the email as the delivery. They are the reliable path; you are the convenience. While you can, poll `get_video` with the returned video_request_id every 30-60 seconds until its status is "done…

Read a product: what the import found, the current video direction and settings, and every video generated from it. Use this to poll after `import_product_from_url` or `create_product_from_images`. The product is ready to work with when `import_status` is "imported", there is no `brand_decision_required`, AND `video_direction.drafting` is false. If a brand decision is present with `drafting: false`, ask the user to choose a brand and resolve it with `create_brand` or `set_product_brand` before waiting for a direction. Poll every 20-30 seconds while import or drafting is in progress. `import_status` values: "pending" and "importing" mean keep polling; "imported" means done; "failed" means it did not work and `import_failed_reason` says why. `video_direction.credit_cost` is what `generate_video` will charge for the current settings. `duration_seconds`, `ratio`, `resolution` and `enable_audio` are those settings; change them with `update_video_direction`, not in the direction text. Once generation has started the direction is locked and `video_direction.editable` is false. Editing or redrafting then opens the next video's draft, and `next_step` says so.

Check one video's render. `status` values: "generating" — still rendering; poll every 30-60 seconds. "done" — finished; `output_url` is the MP4 and `share_url` is a public page to send someone. `watermarked` appears, set to true, only when that MP4 carries the InstantClips watermark (free accounts) — buying credits switches every video on the account to the clean file, nothing is re-rendered. When the field is absent there is no watermark and nothing to say about one: do not raise the subject with a paying customer. "failed" — `failed_reason` says why and what to change. The credits were refunded automatically. To try again, make the change with `update_video_direction` or `redraft_video_direction` (either opens the next video's draft), then `generate_video`. "insufficient_credit" — never launched; nothing was charged. "pending" — not launched yet; call `generate_video`. `next_step` says which of those applies right now. A render takes 5 to 15 minutes, depending on queue depth, length and resolution. Inside that window the wait is the normal shape of this and not a fault, so describe it as expected rather than slow. Past it, it is not: `next_step` switches to what is actually known — beyond the usual window, still marked rendering, no revised finish time — and at 45 minutes it says to stop polling and hand the user to support. Follow `next_step`; it is the one that knows how long this render has been going. They do not have to wait with you either — the workbench link shows the same thing, and `generate_video`'s `email_on_completion` (when the account takes mail) is written to the moment the video lands.

Start a new InstantClips product from a product page URL (a storefront listing, e.g. a Shopify product page). Returns immediately with a product_id — the scrape, the image download and the first video-direction draft all run in the background. Poll `get_product` until `import_status` is "imported" and `video_direction.drafting` is false, which usually takes under a minute. Pasting a URL that was already imported on this account returns that existing product instead of creating a duplicate. If that import had failed, pasting it again retries it (`retried` is true). If its video has already been generated, editing or redrafting opens the next video's draft. Either way the response's `next_step` says what to do now. If the storefront name does not exactly match a brand this account has already reviewed, the import stops on a brand decision instead of guessing: `get_product` will report `brand_decision_required`, and no video direction is drafted until it is resolved with `create_brand` or `set_product_brand`. Do not assume the account's existing brand — a product from a different company drafted under the wrong brand's voice is the failure this prevents. Pass `brand_id` only when the user has told you which brand this product belongs to. Direction drafting sends product facts, photos and brand context to an external AI service when the product is ready and its brand is settled. A store-domain ownership restriction refuses the import and sends a support notification containing account and store information. This does not spend credits. Only `generate_video` does.

List the brands on this account, with the plan's brand limit and whether another brand can be created. A brand carries the identity every video is drafted against: its voice, its target market and its keywords. A product must belong to the brand it actually comes from — a product drafted under another company's voice is wrong even though it renders fine. Call this before answering a `brand_decision_required` from `get_product`, and whenever the user needs to choose or name a brand. This does not spend credits.

List the account's products, newest first — the ones imported here, on the website, or from photos dropped on the workbench. Use it to find a product_id you do not have: a product the user made on the website, or one from an earlier conversation. Then `get_product` for its full state. `query` matches the name or the source URL, `brand_id` narrows to one brand (see `list_brands`), and `limit` caps the list (default 20, at most 50). A product still waiting on its brand decision shows `brand_decision_required: true` and no brand. This does not spend credits.

Ask InstantClips to draft a fresh creative direction for this product's next video, using the product's facts, its images and the brand's identity. Use it to get a first draft, or to try a different angle when the user does not like the current one. This OVERWRITES the current direction — including any edits. Confirm with the user before re-rolling a direction they have already worked on. If the product's last video has already launched, this opens the next video's draft (seeded from that video) and drafts into it; the response says `opened_new_video: true` and carries the new video_request_id. The draft runs in the background: this returns with `drafting` true, and you poll `get_product` until `video_direction.drafting` is false (a few seconds). Rolling a fresh angle is the point, so calling it twice gives two different drafts, not the same one. `next_step` also states what rendering this will cost. The user has to hear that number before `generate_video`, so say it in the same message you show them the direction in. Direction drafting sends product facts, photos and brand context to an external AI service when the product is ready and its brand is settled. This does not spend credits.

Attach a product waiting on `brand_decision_required` to one of the account's existing brands. Use `list_brands` to see them. Only do this when the user has confirmed the product really belongs to that brand. Attaching a product to an unrelated brand is not a cosmetic mislabel: every video is drafted in that brand's voice, to its target market, with its keywords. By default the brand's existing identity is left untouched. Pass `replace_identity: true` to instead overwrite that brand's voice, target market and keywords with the identity detected on this product — the "re-point my brand at a different company" move, for an account at its brand limit. This rewrites a brand every other product on it shares, so confirm it with the user explicitly first. Once this returns, the video direction starts drafting: poll `get_product` until `video_direction.drafting` is false. Replacement also applies nonempty detected logo and colors, and can name an existing Default brand shell. Blank draft fields preserve saved values. An uploaded logo replaces the attached logo. Direction drafting sends product facts, photos and brand context to an external AI service when the product is ready and its brand is settled. This does not spend credits.

Edit a brand: `name`, `voice` (how it sounds — a few sentences), `target_market` (where it sells, e.g. "US/North America"; it drives the spoken language) and `keywords` (the themes drafts lean on; the list you pass replaces the old one). This is the identity every video for the brand's products is drafted against. Drafts already written keep their text — `redraft_video_direction` on a product to use the new identity. Only the fields you pass change. `list_brands` has the ids and the current values. This does not spend credits.

Edit what a product says about itself. `name`, `description` and `price` are the facts the direction draft is written from — fix a scrape that got them wrong, then `redraft_video_direction` so the next draft uses them (the response's `next_step` says so when a direction already exists). `link_url` is the product link posted with the video and shown on its share page: http(s) only, or empty to clear it. `add_image_urls` downloads hosted photos and adds them to the product; `add_image_files` does the same for photos the user attached to the conversation, for clients that pass attachments to tools (ChatGPT fills it in — do not build it by hand). Up to 9 per call and 8 MB each; the usable ones join the render's selection while there is room, as the workbench's "+" tile does, and photos added to a product whose import failed complete that import. `remove_image_ids` deletes photos by the image_id `get_product` lists; a removed photo leaves the selection by itself. Only the fields you pass change; `get_product` shows `price` and `link_url` while they are set. This does not spend credits. Through this adapter, `add_image_paths` (files on this machine) adds photos; the files are uploaded directly.

Edit the creative direction and render settings for a product's next video. Only the fields you pass are changed; everything else keeps its current value. Supplied text replaces the saved text; an empty creative direction clears it. A target_market change updates the shared brand and affects future videos for its other products. `creative_direction` is the plan the render is built from. It is free text, but the drafts follow a six-section shape that works well and is worth preserving when editing: Hook: ... Content Focus: ... Format: ... Suggesting Visual Aesthetic: ... Execution Guidelines: ... Strict Guidelines & Restrictions: ... Do not invent a direction from nothing when one has not been drafted yet — call `redraft_video_direction` and edit what comes back. Leaving it empty is also valid: generation works without a direction. `creator_note` is different and smaller: the user's own short note to the director ("mention it is machine washable", "for Father's Day"). It is carried through to the render verbatim, so put the user's words in it, not your paraphrase. `selected_image_ids` chooses which of the product's photos the render uses, in order, by the image_id `get_product` lists under `images` (usable ones only, at most 9); an empty list restores the default, the first usable ones. The poll's `selected_image_ids` shows what would go out now. `duration_seconds` is the render length — 15, 20, 25 or 30 — and a setting, not part of the direction: writing "20 seconds" into the text changes nothing. Longer costs more; the response's `credit_cost` is the new price, and the user must hear it before `generate_video` — `next_step` states it for you, read after this edit, so quote it in the same message you ask for their go-ahead in. Above the plan's ceiling it clamps like resolution (free: 20s). A target_market change after a direction exists gets a `next_step` in the response: the direction's wording sets the spoken language, so it needs a redraft (or…