cURL and shell

Every endpoint as a command you can paste. Set your key once:

export VT_API_KEY="spk_your_key_here"
export VT_BASE="https://videotranscode.cloud/api/v1"

Presets

The only endpoint where the key is optional. Without one you see the free plan's view.

curl -s "$VT_BASE/presets" \
  -H "Authorization: Bearer $VT_API_KEY" | jq '.meta'

List just the ones you can actually submit:

curl -s "$VT_BASE/presets" \
  -H "Authorization: Bearer $VT_API_KEY" \
  | jq -r '.presets[] | select(.available) | "\(.id)\t\(.name)"'

Create a job

curl -s -X POST "$VT_BASE/jobs" \
  -H "Authorization: Bearer $VT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputUrl": "https://cdn.example.com/master.mov",
    "preset": "mp4_264_720p"
  }' | jq

Capture the identifier for the commands that follow:

JOB_ID=$(curl -s -X POST "$VT_BASE/jobs" \
  -H "Authorization: Bearer $VT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"inputUrl":"https://cdn.example.com/master.mov","preset":"mp4_264_720p"}' \
  | jq -r '.id')
 
echo "$JOB_ID"

Read a job

curl -s "$VT_BASE/jobs/$JOB_ID" \
  -H "Authorization: Bearer $VT_API_KEY" | jq

Just the status:

curl -s "$VT_BASE/jobs/$JOB_ID" \
  -H "Authorization: Bearer $VT_API_KEY" | jq -r '.status'

List jobs

curl -s "$VT_BASE/jobs?limit=20&status=completed" \
  -H "Authorization: Bearer $VT_API_KEY" \
  | jq -r '.jobs[] | "\(.createdAt)  \(.status)  \(.preset)  \(.id)"'

Cancel a job

Works only while the job is queued or processing.

curl -s -X DELETE "$VT_BASE/jobs/$JOB_ID" \
  -H "Authorization: Bearer $VT_API_KEY" | jq

Download the output

OUTPUT_URL=$(curl -s "$VT_BASE/jobs/$JOB_ID" \
  -H "Authorization: Bearer $VT_API_KEY" | jq -r '.outputUrl')
 
# The signature is in the query string, so no auth header here.
curl -L -o output.mp4 "$OUTPUT_URL"

Or ask for a link on its own:

curl -s "$VT_BASE/jobs/$JOB_ID/download-url" \
  -H "Authorization: Bearer $VT_API_KEY" | jq

Validate a timeline

Costs nothing and does not touch your quota.

curl -s -X PUT "$VT_BASE/edl" \
  -H "Authorization: Bearer $VT_API_KEY" \
  -H "Content-Type: application/json" \
  -d @timeline.json | jq

Wait for a job from the shell

#!/usr/bin/env bash
set -euo pipefail
 
wait_for_job() {
  local job_id=$1
  local interval=${2:-12}
  local deadline=$(( SECONDS + 45 * 60 ))
 
  while (( SECONDS < deadline )); do
    local status
    status=$(curl -sf "$VT_BASE/jobs/$job_id" \
      -H "Authorization: Bearer $VT_API_KEY" | jq -r '.status')
 
    case "$status" in
      completed|failed|cancelled)
        echo "$status"
        return 0
        ;;
    esac
 
    sleep "$interval"
  done
 
  echo "timeout" >&2
  return 1
}

Full script that encodes and downloads:

#!/usr/bin/env bash
set -euo pipefail
 
: "${VT_API_KEY:?set VT_API_KEY}"
VT_BASE="https://videotranscode.cloud/api/v1"
 
SOURCE=$1
PRESET=${2:-mp4_264_720p}
 
job=$(curl -sf -X POST "$VT_BASE/jobs" \
  -H "Authorization: Bearer $VT_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg u "$SOURCE" --arg p "$PRESET" '{inputUrl:$u,preset:$p}')")
 
job_id=$(jq -r '.id' <<<"$job")
echo "Created $job_id"
 
status=$(wait_for_job "$job_id")
 
detail=$(curl -sf "$VT_BASE/jobs/$job_id" -H "Authorization: Bearer $VT_API_KEY")
 
if [[ "$status" != completed ]]; then
  echo "Job $status: $(jq -r '.errorMessage' <<<"$detail")" >&2
  exit 1
fi
 
curl -L -o "${job_id}.out" "$(jq -r '.outputUrl' <<<"$detail")"
echo "Saved ${job_id}.out"

Note that curl -sf returns a non-zero exit code on HTTP errors but discards the body, so you lose the message explaining the refusal. Drop -f and inspect the JSON when you want to know why a request was rejected.

Python Preset catalogue