For developers

A brief in, a finished thumbnail out

Describe the video, say the words, and get back a YouTube thumbnail with the headline painted in. No canvas to build, no fonts to pick, no text to place. Sign in, create a key in the console, and call it from your own product.

The brief

Everything POST /v1/thumbnails takes is about the picture, never about the canvas.

• topic — what the video is about. The one required field.
• headline, tagline — the words. Leave the headline out and HitCanvas writes one from the topic (counts as an idea).
• style — the picture’s look; lettering — the words’ finish, kind of face and slant, if you care.
• role, subject, featured — who is in it: the story’s subject, or a host at the edge with the story behind them. A saved person by personaId (with one of their looks as lookId), whose consent was recorded when they were saved; or photos sent along (one to three of the same face, with permission: true); and how they look. expression, intensity, pose — the face and the body, in words.
• kitId — a brand kit from GET /v1/kits. Wherever the brief is silent the kit speaks: style, lettering, colours, tagline, role. Its person becomes the subject when none is named — or send subject: { anyone: true } to have the model draw someone instead — and its logo is set in its corner of the finished picture.
• niche from POST /v1/study, concept from POST /v1/direct — the picture steered by what wins in the niche and by a chosen idea. Neither is required.
• x-hitcanvas-space header — which client it is for. Idempotency-Key header — so a retry never pays twice. Or POST /v1/jobs with kind: "thumbnails" to get a 202 now and poll for the picture.

Routes marked Studio need a signed-in browser session and are not reachable with an API key. The scope beside a route is what a key needs to call it.

What is Studio-only

HitCanvas Studio has a second way of working: AI-plus-text, where the model paints a background composed around a headline the Studio then sets in real type, on its own canvas, with its own fonts, layers, arrows, logos and export. That is a product of the Studio’s typography and canvas, and it is not the API’s. An integration should not have to reproduce a canvas, choose fonts, read clearance measurements, manage layered designs or render a file to get a thumbnail — so the public API does not ask it to. Studio-only: AI-plus-text creation, layered editing, canvas controls, font choice, and the Studio’s render and export.

Keys and limits

• Keys belong to your workspace, not to a person, so they keep working when someone leaves.
• A key is shown once and stored hashed. Revoke it in the console at any time.
• Send it as a bearer token. Keys are limited to 60 calls a minute.
• A key holds scopes — generate, library:read, library:write, kits:read, kits:write, personas:read, personas:write, videos:read, videos:write — and may be limited to certain client spaces. Set both when you make a key in the console or with POST /v1/keys; change them with PATCH /v1/keys/<id>; GET /v1/keys shows them. A call the key may not make is a 403 key_scope_denied or key_space_denied. A key made before scopes existed is unrestricted and stays so until you narrow it.
• API calls count against the same monthly allowance as the studio, and a call that fails is not counted.
• Agencies: send an x-hitcanvas-space header with a client space’s id to work in that client’s library and brand kits. GET /v1/spaces lists them, and marks one isDefault: that is where a call works when you send no header, an empty one, or general. A header naming anything else — a malformed id, another workspace’s space, or one that has since been removed — is a 404 and nothing is written. It is never swapped silently for the default space.
• Reference photos in a request are passed to the image model and not stored. Photos are kept only when someone saves a person with POST /v1/personas, which needs an explicit consent field and the kitId of the brand the persona belongs to. A brand holds up to three.
• YouTube: you never connect a YouTube account to use the API. Your HitCanvas key is the only credential; every piece of public YouTube data that research and generation need (POST /v1/study, GET /v1/videos) HitCanvas fetches itself, with its own YouTube Data API credentials. Google OAuth exists only inside the Studio, where a signed-in person may connect their own channel for things only their account can do — picking one of their existing thumbnails to review, say. That connection is not part of the public API and is never required for making thumbnails; the /v1/youtube operations that expose it are session-only, and a key calling them is refused with session_required.
• Every response carries an x-request-id header; include it if you write to support about a specific call.
• Send an Idempotency-Key header (any string up to 255 characters, unique to the attempt) on any POST, PUT or PATCH, and the same request again returns the same answer without doing the work or charging again, marked Idempotency-Replayed: true. The same key with a different body is a 422 idempotency_key_reused; the same key while the first is still running is a 409 idempotency_in_progress. A 5xx is never kept, so a failed generation can be retried with its key. Keys are yours for 24 hours.
• Or do not wait at all: POST /v1/jobs answers 202 with an id and does the work after answering, and GET /v1/jobs/<id> tells you when it is done and hands you the result. A job still running when its route’s time limit passes is marked failed with job_timed_out, and nothing is charged for work that did not finish. Jobs take an Idempotency-Key like any other POST.
• Every error, 4xx or 5xx, is one shape: { error: { code, message, type, param?, requestId } }. code is stable and specific (invalid_request, not_found, usage_limit_exceeded); type is the class to branch on without knowing every code (validation, authentication, authorization, not_found, conflict, rate_limit, provider, unavailable, internal); param names the field when one is at fault; requestId matches the x-request-id header. A 429 usage_limit_exceeded means your workspace used its monthly allowance; a 503 service_capacity_exceeded means HitCanvas itself is out of room and was never yours to fix by upgrading.
• The API path is versioned (/v1) and additive changes within it are tracked by the contract version above; a breaking change gets a new path version and a deprecation notice first, never a silent removal.