Submit a transcoding job.
Args:
source: URL of the input video (https://, s3://, or `tus:<uuid>`).
outputs: list of format-spec dicts. Each MUST have an `output` field
whose value is one of: mp4, webm, advanced_hls, advanced_dash,
webm_dash, repack, mp3, m4a, hls_audio, flac, gif, thumbnail,
thumbnails, smart_thumbnail, metadata, speech_to_text, vmaf,
video_intelligence, ai_detection, waveform.
The OUTER array is named `format` in the Qencode schema (this
tool wraps it for you). The INNER STRING field naming the type
is `output` — NOT `format`. This is the most common composition
mistake. Example of a valid entry:
{
"output": "mp4",
"video_codec": "libx264",
"audio_codec": "libfdk_aac",
"resolution": 720,
"optimize_bitrate": 1,
"audio_bitrate": 128,
"destination": {
"url": "<destination_prefix>/<new filename or folder>"
}
}
Media Storage `destination.url` is `{destination_prefix}/{new key}`
— a NEW file or folder, never a listed object's `destination_url`
(that is the existing file, for reading as `source`). Folder
outputs (HLS / STT / VI / thumbnails) take `{destination_prefix}/folder`
with no trailing slash. Do not assemble the host.
`s3://<bucket>/…` is rejected here (the API would demand
`key`/`secret`). Inputs the encoder fetches (`source`, `distorted`,
subtitle files, `logo.source`) use `cdn_url` when public and
`destination_url` when private. Video Intelligence `source` must
be https — `cdn_url` only; a private object cannot be a VI source.
For HLS/DASH ABR, put per-rendition params on each entry of an
inner `stream[]` array (not on the format object directly).
Output-specific required fields (see matching recipe):
advanced_hls / advanced_dash / webm_dash / hls_audio —
non-empty `stream[]` of objects. A bare
`{"output": "advanced_hls"}` is rejected. Fetch
`qencode://recipe/hls_abr` (or `audio_outputs` for
`hls_audio`) before composing.
vmaf — `distorted` URL of the encoded video; `source` is the
reference original (encoder v1 is auto-selected).
video_intelligence — `mode` one of description, categorization,
moderation, search, custom (NOT `features`). Source must be
https:// and meet duration minimums (description etc. ≥10s,
search ≥4s) — check via metadata or tell user if too short.
Example vmaf entry:
{
"output": "vmaf",
"distorted": "https://example.com/encoded.mp4",
"destination": {"url": "<destination_prefix>/vmaf.json"}
}
Example HLS entry (params on `stream[]`, not on the format object):
{
"output": "advanced_hls",
"segment_duration": 6,
"stream": [{
"video_codec": "libx264",
"audio_codec": "libfdk_aac",
"resolution": 720,
"framerate": "30",
"keyframe": "60",
"optimize_bitrate": 1,
"audio_bitrate": 128
}]
}
Example video_intelligence entry:
{
"output": "video_intelligence",
"mode": "description",
"destination": {"url": "<destination_prefix>/vi"}
}
payload: optional opaque callback tag echoed by Qencode. Must be a
string (or omitted). A JSON object is not submitted — the tool
returns `{"error": "..."}` asking you to retry with a string.
It is not the job body (`outputs` is). Do not put `source` or
`format` in `payload`.
`encoder_version` is injected automatically when omitted: `2` by default,
`1` when any output is `vmaf`. Stitch jobs (multi-source `stitch` array)
are not supported here — use `start_encode2_raw` with `encoder_version: 2`
per `qencode://recipe/stitching`.
Other composition defaults in this server's instructions (libfdk_aac,
optimize_bitrate, per-stream ABR params, etc.) still belong in each
`outputs[]` entry — consult the matching recipe via
`search_qencode_docs` + `fetch_qencode_doc` before submitting.
After this returns a `task_token`, in the SAME reply call `list_jobs`
with that token. If the job is already Done with a playable video URL,
also `open_player`. If the deliverable is a json/txt/srt/vtt file, call
`fetch_job_result` and give the user both the URL and the extracted
content.