Caption design colors: hex, rgb, rgba, transparent only, else 400

The colour fields

The Video captions page lists six colour fields under design.colors: base, active, stroke, accent, accent_deep and card. Setting card to null draws no card. Each field is optional and merges over the style's own value, so one key changes one thing.

A colour is a hex string, an rgb() or rgba() value, or transparent. Other CSS syntax is rejected rather than drawn into the render document.

What is accepted and what is not

A value outside the documented range returns 400 at request time, before a render is billed, and the docs say that is deliberate: a look should fail up front rather than render wrong and charge.

A minimal request

The docs example sets only the active colour on black-outline, which gives a cyan emphasis and leaves everything else as the style defines it.

{
  "video_url": "https://example.com/clean.mp4",
  "style": "black-outline",
  "design": {
    "colors": { "active": "#22D3EE", "card": null }
  }
}

Validate before you send

Add a small client-side check so brand tokens do not reach the API in an unsupported form. A regular expression for hex and rgb/rgba with a fallback list is enough.

• Convert named or HSL colours to hex in your own code.
• Remember design is not supported on punch or tiktok-green.
• Keep the same design object for a series so captions match across videos.
• Use source_caption_id to restyle an earlier caption without paying for a second speech-to-text pass.

Contrast checks

Pick colours for legibility first. Test the base and stroke against both a bright and a dark frame from your footage, since captions sit on moving video. A thick stroke in a contrasting colour, or a card behind the text, carries legibility when the footage varies.

transparent is useful for strokes or accents you want to switch off while keeping the field set.

Price

A caption job is $0.20 for videos up to 60 seconds, restyles included under the current fixed estimate, so testing three colour sets costs $0.60. The API pricing page has the book.