Change one caption color: design.colors.active and what it accepts

To change the emphasis color of a Sume caption style for one request, send design.colors.active with a hex value, for example #22D3EE. Sume merges each field you send over the style's own token, so one key changes one thing and everything else stays. Colors may be hex, rgb(), rgba() or transparent; any other CSS syntax is rejected and never reaches the render document.

Five token groups

design has five optional groups. Numbers outside a documented range return 400, which means a bad look fails at request time and you are not charged for an incorrect render.

The default render has no tint

If you send no style, Sume resolves by text: Korean text goes to black-outline, Latin text to slam. In their original design both have a gold tint on the spoken word, but Sume does not add a tint to a look you did not select. A default render therefore keeps the fill color on the spoken word.

If you select black-outline or slam yourself, that style keeps its own gold tint, and design.colors.active sets the tint in both cases. So the same key either adds a tint (default render) or replaces one (selected style).

Request

This burns black-outline with a cyan emphasis. Every other value stays the style's own.

curl -X POST https://api.sume.com/v1/video-captions \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: caption-cyan-001" \
  -d '{
    "video_url": "https://media.sume.com/artifacts/example/clean.mp4",
    "style": "black-outline",
    "design": { "colors": { "active": "#22D3EE" } }
  }'

Practical advice

Change one token at a time and compare the results. Put a safe-area limit in typography.safe_width_ratio if captions touch the edge of a vertical frame, and move the line with placement.anchor_ratio when platform UI covers the lower third. A restyle with source_caption_id lets you test those without a second transcription.

What fails and what does not

The documented failure mode is a number outside its range, which returns 400. A CSS value that is not hex, rgb(), rgba() or transparent is not placed into the render document; the docs say Sume rejects it. In both cases the point is the same: you find out before a render is paid for.

Keep a small table of approved brand colors in your own code and pass them as hex. That avoids ambiguity such as named colors or gradients, which are not in the accepted list.

• card: null removes the card behind the text.
• stroke and stroke_width_px control outline weight on styles that have an outline.
• Two styles, punch and tiktok-green, ignore design; see the related post.