Ad creative testing workflow with an API: five calls to a winner

An ad creative test on Sume is five API calls in a fixed order: search hooks, generate the variants, trim or assemble them, burn captions, then read what each variant cost before you spend media budget on it. Sume does the production side. The platform side, where the ads actually run and get measured, stays in the ad platform, so this workflow ends with files and a cost per file, not a winner.

The five calls

Every call below is a documented route and every price is the number printed on the docs page for that surface. Generation prices vary by model, so that line says to read usage.cost from your own first job.

Step 1 and 2: hooks in, clips out

Trending video search returns public TikTok video metadata, not downloadable video, so you use it to write briefs, not to copy footage. In production the query field is required and limit is 1 to 50. One search at $0.10 is cheap enough to run once per theme.

Then turn each brief into a /v1/videos body. Keep every body identical except the hook sentence, so the only difference between arms is the thing you are testing. Pin a model id; do not let two arms run on different models.

curl -sS -X POST https://api.sume.com/v1/trending-videos/search \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"travel mug","window":"this-week","limit":10}'

Step 3 and 4: make the arms comparable

Arms are only comparable if they have the same length and the same captions treatment. Trim every clip to the same duration with video-trim, which takes video_url, start and one of end or duration, and burn the same caption style on each. Both routes need the clip to be a media.sume.com artifact, which a /v1/videos result already is.

A worked cost: one search at $0.10, plus three trims at $0.02 is $0.06, plus three caption jobs at $0.20 is $0.60. That is $0.76 of fixed-price work for a three-hook test, before the generation cost of the three clips.

Step 5: read cost, then decide what to buy

Each completed /v1/videos poll carries usage.cost, which is the Sume billable amount for that job. Write it into the same row as your hook text. When the ad platform reports results for your arms, you will have cost of production and cost of media side by side.

Our rule for sizing a first test: do not pay for finals until two or three hook drafts have been through the same trim and caption steps, because most differences between arms come from pacing and the first second, which cheap drafts already show.

• Name each variant once, and use that name as the Idempotency-Key.
• Store job id, hook text, model id and usage.cost in one row.
• Re-run only the variants that failed, never the whole set.

What this workflow does not do

It does not upload to Meta, TikTok or Google, and it does not pick a winner. Run the arms in the platform's own experiment tool, keep one variable per test, and only then spend on higher-quality finals of the arm that won.

A concrete first run

Start small. Pick one product, three hooks of one sentence each, one ending and one model. Submit three /v1/videos jobs with names hookA, hookB and hookC as idempotency keys. When they complete, trim each to the same length, burn the same caption style, and open the three files side by side before spending on anything else.

If the arms look the same, your hooks are too similar and the test will tell you nothing. If one arm is visibly broken, fix the prompt and rerun only that variant, using a new version suffix on its key. This is cheaper than finding out after you have paid for media.

When you move from three variants to dozens, swap step 2 for a bulk Format run. A bulk queue accepts 1 to 100 items with a concurrency window of 1 to 16, and you poll one status URL for counts. The queue completes when every item is terminal, which is not the same as every item succeeding, so branch on counts.failed before you move to the trim step.