Skip to main content
POST
Describe what happens in a video
Describe visible events and scene boundaries in a video. Returns a request_id for status polling.
Prerequisite: Consult the Model Selection endpoint to identify a valid model slug and check supported presets and duration limits.

Authorizations

Authorization
string
header
required

Sanctum personal access token, sent as Authorization: Bearer <token>. The token is opaque — it carries no claims and no embedded expiry, so do not attempt to decode it. Issue and revoke tokens from your account dashboard.

Headers

Accept
enum<string>
default:application/json
required
Available options:
application/json

Body

multipart/form-data

Video description parameters. Provide exactly one of video_url or video_file.

A source is MANDATORY and comes in exactly one of two shapes — video_url for a hosted video, or video_file for an upload. Sending neither is a 422, and sending both is a 422 as well; the oneOf below is that choice, not a pair of optional fields. Everything else applies to both. The /price twin of this endpoint accepts a third shape, duration_seconds, which this one does not.

video_url
string
required

URL of the video to describe (YouTube, Twitter/X, Twitch, Kick, TikTok — the same platforms as transcription). Audio-only sources such as Twitter Spaces are rejected. Live streams are rejected. Mutually exclusive with video_file.

Example:

"https://www.youtube.com/watch?v=jNQXAC9IVRw"

model
string
required

The model to use. Available models can be retrieved via the GET /api/v2/models endpoint; a model lists video2desc (URL sources) and/or video_file2desc (uploads) in its inference_types. Its info.limits.max_video_duration_seconds, when present, is the longest source it accepts.

Example:

"Marlin_2B"

video_file
file

Video file to describe. Supported: mp4, mpeg, quicktime, avi, wmv, ogg, webm, mkv. Must contain a video stream. Mutually exclusive with video_url.

preset
enum<string> | null

Detail level. A preset is the per-frame pixel budget the model reads the video at: fast reads a small frame over long windows, detail a large frame over short windows, so higher presets read more of what is on screen (small text, brand names) and cost more — roughly ×1 / ×3 / ×7 machine time for fast / balanced / detail (×0.75 / ×1 / ×1.5 on the TikTok card). Omit for the default (balanced, or the cheapest preset the model offers if it does not offer balanced). Only honoured on a model whose info.features.supports_presets is true; such a model publishes the presets it offers as info.limits.available_presets and rejects any other. On a model without the flag the field is ignored.

Available options:
fast,
balanced,
detail,
null
Example:

"balanced"

include_metadata
boolean | null
default:false

If true, the job-status response carries a metadata object describing the source — title, channel, uploader, upload date and engagement counts such as views, likes and comments — exactly as on POST /api/v2/audio/transcriptions. Only URL sources have any; an uploaded file returns null and is never charged for the flag. Carries the same flat surcharge as transcription metadata.

Example:

false

return_result_in_response
boolean | null
default:false

If true, the completed job-status response includes the description as a serialized JSON string in data.result, in addition to data.result_url. Parse the string as JSON to read events, scenes and meta.

Example:

false

webhook_url
string<uri> | null

Optional HTTPS URL to receive webhook notifications for job status changes (processing, completed, failed). Must be HTTPS. Max 2048 characters. A per-request URL is self-contained: it is delivered even when the account has no webhook configuration, or the account webhook is disabled. See the webhooks block at the top level of this document for the event payloads and the headers each delivery carries.

Maximum string length: 2048
Example:

"https://your-server.com/webhooks/deapi"

webhook_secret
string | null

Optional per-request HMAC secret (min. 32 chars) used to sign the webhook callback. Overrides the account-default secret for this job only. If omitted, the account-default secret signs the callback; if no secret exists at all, the callback is still delivered but UNSIGNED (empty X-DeAPI-Signature header). Requires webhook_url to also be set.

Required string length: 32 - 255
Example:

"a1b2c3d4e5f60708091a2b3c4d5e6f7081920a1b2c3d4e5f60708091a2b3c4d5"

Response

ID of the inference request.

data
object
required

Information from success endpoint