API
On this section

Reframe

Submit a reframe job

video
produces
video
$0.50per minute

Start an asynchronous job that turns a landscape video into a vertical 9:16 video. For each shot, the model picks a layout from the frames, the faces, who is speaking and the transcript: it follows the speaker, tracks a moving subject, fits a wide view, or stacks two panels (two people talking, or a speaker and their slides). Captions can be burned in.

Inputs

  • video_url — public URL of a landscape video with both a video and an audio track, up to 10 minutes and 4 GB. The active speaker is found by voice
  • captions — optional; the style of burned-in captions, or none (the default). Captions are transcribed from the speech, with the language detected automatically
  • accent_color — optional; the colour of the spoken word, as #rrggbb. Only highlight (default #ffd43b) and pill (default #7b61ff) use it

Caption styles

  • clean — white text with a thin outline and a soft shadow
  • boxed — black text on a white box behind each line
  • highlight — short cues; the spoken word is in the accent colour and each cue pops in
  • pill — all caps, two or three words per cue; the spoken word sits on a pill in the accent colour

Captions are centred and placed where the layout leaves room: on the seam between stacked panels, in the bands around a fitted view, or at about 60% of the height away from faces. They stay clear of the top 15% and the bottom 35% of the frame, where platforms draw their controls.

Output

An H.264 MP4 at the source height, capped at 1920 and never upscaled (1080p gives 606×1080, 4K gives 1080×1920). It keeps the source audio and timing, so it is as long as the input. The same video can be framed differently on different runs.

What happens next

The job is accepted immediately — you get 202 Accepted with a job_id and status PROCESSING. Processing takes minutes. Poll GET /v1/reframe/{job_id} until the job is COMPLETED or FAILED.

POST
/v1/reframe
Try it ▷

Headers

X-Veed-Store-IOenumoptional

Set to 0 to not store this request's and response's bodies. They are then not available in your request logs for debugging.

Accepts01Defaults to "1".
X-Veed-Media-Expiration-Secondsintegeroptional

Number of seconds before the media URLs returned for this request expire. A value above the maximum is capped rather than rejected.

At most 2592000.Defaults to 86400.

Request body ReframeInput ↗

accent_colorstringoptional

Colour of the spoken word, as #rrggbb. Only the highlight and pill styles use it. Omit it for the style default.

captionsenumoptional

Style of the burned-in captions, or none for no captions.

AcceptsnonecleanboxedhighlightpillDefaults to "none".
video_urlurlrequired

URL of a landscape video with both a video and an audio track, up to 10 minutes and 4 GB.

Must be an http(s) URL.

Responses

dataobjectrequiredReframeJob ↗
Show 6 nested fields
credits_chargedintegeroptional

Credits charged for the job. Present once the job is COMPLETED and the final charge is known.

credits_estimatedintegeroptional

Credits quoted before the job ran. Present only on the response that created the job. This is an estimate, not the price: the charged amount can be higher or lower.

errorobjectoptionalJobErrorReframeErrorCode ↗

Failure information. Present once the job has FAILED.

Show 3 nested fields
codeenumrequired

Stable, machine-readable failure code for this job type.

Acceptsinput_validationcontent_moderationinvalid_fileaudio_too_longtransload_failedgeneration_failedtimeoutinsufficient_credits
detailsarray of objectoptionalJobErrorDetail ↗

Optional structured failure details.

Show 3 nested fields
fieldstringoptional

Dotted path to the offending input, when applicable.

messagestringrequired

Human-readable explanation of this detail.

typestringrequired

The category of this detail entry.

messagestringrequired

Human-readable failure message.

job_iduuidrequired

Stable identifier of the job and of the resource it produces.

resultobjectoptionalReframe ↗

The produced resource. Present once the job is COMPLETED.

Show 1 nested field
videoobjectrequiredFile ↗

The input video reframed to 9:16, with any captions burned in. It keeps the source audio and length.

Show 4 nested fields
content_typestringoptional

The mime type of the file.

file_namestringoptional

The name of the file.

file_sizeintegeroptional

The size of the file in bytes.

urlstringrequired

The URL where the file can be downloaded from.

statusenumrequired

Current lifecycle state of the job.

AcceptsPROCESSINGCOMPLETEDFAILEDCANCELLED
X-Request-IDCorrelation id for this request, adopted from the request or minted at the edge.
401UnauthorizedErrorResponse ↗
errorobjectrequiredErrorBody ↗
Show 4 nested fields
codeenumrequired
Acceptsinvalid_requestunauthenticatedinsufficient_tokenspermission_deniednot_foundconflictrate_limitedunavailableinternal
detailsarray of objectoptionalErrorDetail ↗
Show 6 nested fields
fieldstringoptional
messagestringoptional
reasonenumoptional
Acceptsapi_key_expiredapi_key_inactiveapi_key_invalidapi_key_revokedapi_key_workspace_unavailableinsufficient_creditsjob_not_foundmodel_access_requiredoauth_token_invalid
retry_after_msintegeroptional
typestringrequired
valueobjectoptional
messagestringrequired
request_idstringrequired
X-Request-IDCorrelation id for this request, adopted from the request or minted at the edge.
402Payment RequiredErrorResponse ↗
errorobjectrequiredErrorBody ↗
Show 4 nested fields
codeenumrequired
Acceptsinvalid_requestunauthenticatedinsufficient_tokenspermission_deniednot_foundconflictrate_limitedunavailableinternal
detailsarray of objectoptionalErrorDetail ↗
Show 6 nested fields
fieldstringoptional
messagestringoptional
reasonenumoptional
Acceptsapi_key_expiredapi_key_inactiveapi_key_invalidapi_key_revokedapi_key_workspace_unavailableinsufficient_creditsjob_not_foundmodel_access_requiredoauth_token_invalid
retry_after_msintegeroptional
typestringrequired
valueobjectoptional
messagestringrequired
request_idstringrequired
X-Request-IDCorrelation id for this request, adopted from the request or minted at the edge.
422Unprocessable EntityErrorResponse ↗
errorobjectrequiredErrorBody ↗
Show 4 nested fields
codeenumrequired
Acceptsinvalid_requestunauthenticatedinsufficient_tokenspermission_deniednot_foundconflictrate_limitedunavailableinternal
detailsarray of objectoptionalErrorDetail ↗
Show 6 nested fields
fieldstringoptional
messagestringoptional
reasonenumoptional
Acceptsapi_key_expiredapi_key_inactiveapi_key_invalidapi_key_revokedapi_key_workspace_unavailableinsufficient_creditsjob_not_foundmodel_access_requiredoauth_token_invalid
retry_after_msintegeroptional
typestringrequired
valueobjectoptional
messagestringrequired
request_idstringrequired
X-Request-IDCorrelation id for this request, adopted from the request or minted at the edge.
429Rate limit exceededErrorResponse ↗
errorobjectrequiredErrorBody ↗
Show 4 nested fields
codeenumrequired
Acceptsinvalid_requestunauthenticatedinsufficient_tokenspermission_deniednot_foundconflictrate_limitedunavailableinternal
detailsarray of objectoptionalErrorDetail ↗
Show 6 nested fields
fieldstringoptional
messagestringoptional
reasonenumoptional
Acceptsapi_key_expiredapi_key_inactiveapi_key_invalidapi_key_revokedapi_key_workspace_unavailableinsufficient_creditsjob_not_foundmodel_access_requiredoauth_token_invalid
retry_after_msintegeroptional
typestringrequired
valueobjectoptional
messagestringrequired
request_idstringrequired
Retry-AfterSeconds until the rate limit resets.
X-RateLimit-ClassThe rate-limit class that was hit (read, mutation, ai-generation).
X-RateLimit-LimitRequest budget for the matched class.
X-RateLimit-RemainingRemaining requests in the current window.
X-RateLimit-ResetUnix time (seconds) when the budget resets.
X-Request-IDCorrelation id for this request, adopted from the request or minted at the edge.
500Internal Server ErrorErrorResponse ↗
errorobjectrequiredErrorBody ↗
Show 4 nested fields
codeenumrequired
Acceptsinvalid_requestunauthenticatedinsufficient_tokenspermission_deniednot_foundconflictrate_limitedunavailableinternal
detailsarray of objectoptionalErrorDetail ↗
Show 6 nested fields
fieldstringoptional
messagestringoptional
reasonenumoptional
Acceptsapi_key_expiredapi_key_inactiveapi_key_invalidapi_key_revokedapi_key_workspace_unavailableinsufficient_creditsjob_not_foundmodel_access_requiredoauth_token_invalid
retry_after_msintegeroptional
typestringrequired
valueobjectoptional
messagestringrequired
request_idstringrequired
X-Request-IDCorrelation id for this request, adopted from the request or minted at the edge.

Example request

terminal
curl -X POST "https://api.veed.io/v1/reframe" \
  -H "Authorization: Bearer $VEED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "video_url": "https://static-assets.veed.io/api-examples/reframe-input.mp4"
}'

Example response

HTTP 202
{
  "data": {
    "job_id": "123e4567-e89b-12d3-a456-426614174000",
    "status": "PROCESSING",
    "credits_estimated": 50
  }
}