Submit a job with the raw `query` JSON.
The `query` dict can be either the wrapped form `{"query": {...inner...}}`
or the inner object directly — the underlying client auto-wraps if needed.
The inner query MUST have shape:
{
"source": "<url>",
"encoder_version": 2,
"format": [ # ARRAY of output specs
{
"output": "mp4", # STRING type field. NOT "format".
... # encoding params per the recipe
}
]
}
Common composition mistakes this tool catches up front:
- `"format": "mp4"` inside an entry instead of `"output": "mp4"`.
- Missing `output` field.
- Unknown `output` value.
- `format` as a string at the top level (must be an array).
- `vmaf` without `distorted` (`source` = reference, `distorted` = encoded).
- `video_intelligence` without `mode` (use `mode: "description"`, not
`features`). Source must be https://; `description` modes need ≥10s
clip, `search` ≥4s — check duration before submit (metadata job).
Example vmaf query (encoder v1 — set explicitly here):
{
"source": "https://example.com/original.mp4",
"encoder_version": 1,
"format": [{
"output": "vmaf",
"distorted": "https://example.com/encoded.mp4",
"destination": {"url": "s3://.../vmaf.json"}
}]
}
Example video_intelligence query (encoder v2):
{
"source": "https://example.com/input.mp4",
"encoder_version": 2,
"format": [{
"output": "video_intelligence",
"mode": "description",
"destination": {"url": "s3://.../vi/"}
}]
}
Unlike `transcode_video`, this tool does **not** auto-inject
`encoder_version`. Set `"encoder_version": 2` at the top of the inner
query for all v2 outputs (`smart_thumbnail`, `ai_detection`,
`video_intelligence`, `m4a`, …). Use `1` for VMAF and stitching per
their recipes.
Stitching: a stitch job uses a top-level `stitch` array *instead of*
`source` — the two are mutually exclusive, so do NOT also set `source`
(setting both makes the API reject the job). Each `stitch[]` entry is a
URL string or a `{"url": ..., "start_time": ..., "duration": ...}`
object, and stitch jobs require `encoder_version: 1`. Example:
{
"encoder_version": 1,
"stitch": [
{"url": "https://example.com/in.mp4", "start_time": 0, "duration": 5},
{"url": "https://example.com/in.mp4", "start_time": 148, "duration": 5}
],
"format": [{
"output": "mp4", "video_codec": "libx264",
"audio_codec": "libfdk_aac", "bitrate": 2800,
"framerate": "30", "keyframe": "60", "audio_bitrate": 128
}]
}
For complex queries — ABR ladders, DRM, stitching, callbacks — call
`search_qencode_docs(...)` then `fetch_qencode_doc(...)` to read the
matching recipe before composing.