Skip to main content
POST
Thumbnail

Authorizations

Authorization
string
header
required

A workspace API key.

Headers

idempotency-key
string

Stable retry key for this logical paid call. Reuse it after a timeout to receive the original result without duplicate work or spend.

Required string length: 1 - 255
x-sigmora-quote-only
string

Send 1 to get the price, balance and budget verdict without running anything.

Allowed value: "1"
x-sigmora-max-credits
string

The approved price; a call that would cost more is refused and nothing is charged.

Pattern: ^\d+$

Body

application/json
title
string
required

Video or article title. This is the only required field.

Required string length: 1 - 200
projectId
string
required

The existing project to file this work under. Create it with POST /v1/projects, then reuse its id across related calls. A project this workspace does not own answers not_found; the work is never silently filed somewhere else.

Required string length: 1 - 200
subject
string

Who or what should be visibly present; the strongest visual-quality input.

Maximum string length: 300
transcript
string

Up to 3,000 characters from the content. Helps the image reflect the actual material instead of guessing from the title.

Maximum string length: 3000
assetId
string

Id of an asset this workspace has already transcribed. Use it instead of pasting transcript; if both are sent, transcript wins. Asset ids come from GET /v1/assets.

Required string length: 1 - 200
description
string

Additional visual direction that is not already in the title or subject.

Maximum string length: 500
mood
string

Emotional tone, e.g. urgent, calm, or hopeful.

Maximum string length: 80
colors
string

Preferred palette in plain language or hex colors.

Maximum string length: 100
composition
enum<string>

Where the main subject sits. Defaults to subject_left; accepted values are listed below.

Available options:
subject_left,
subject_right,
centered
style
enum<string>

Visual treatment. Defaults to viral; accepted values are listed below.

Available options:
viral,
cinematic,
bold-text,
dramatic,
educational,
minimal
platform
enum<string>

Target platform, which determines aspect ratio: 16:9 for youtube, 9:16 for the others. Defaults to youtube.

Available options:
youtube,
youtube_shorts,
instagram_reels,
tiktok
headline
string

Words to lay on the thumbnail, in heavy capitals on the side the composition leaves open. Omit it for a clean image with no text (the default).

Required string length: 1 - 120
variants
integer

How many different images to make, 1 to 4. Each is priced as one thumbnail. Defaults to 1.

Required range: 1 <= x <= 4
palette
object

Brand colours for the headline panel and accents. Used only with headline.

fontFamily
string

Brand heading font for the headline; one Sigmora cannot draw falls back to Anton.

Maximum string length: 60
source
object

Make the thumbnail from a frame of your own video instead of generating an image. The headline (or the title) is laid on the frame. One image per call.

Response

Success.

success
boolean
required
credits
number
required

What this call actually cost, which is not always what was quoted.

Example:

300

thumbnail
object
required
projectId
string

The existing project this work was filed under. It matches the projectId supplied by the caller after workspace ownership was verified.

Example:

"prj_9x2a4c"

creditBalance
number

Your balance after the charge. Absent when billing is disabled for the workspace.

Example:

3900

reused
object

Present only when assetId was sent: the indexed transcript the image was written from.

{key}
any