Create Task

View Markdown 
POST /tasks

Creates a standalone task — a single operation without a parent job. Tasks give you granular control: probe a file to inspect it, then decide what to do next. This is how agents and custom workflows compose operations. For the CLI equivalent, see ittybit task.

Request body

FieldTypeRequiredDescription
kindstringyesprobe · import · video · audio · image · animation · adaptive_video · export
inputobjectyesShape depends on kind
optionsobjectnoProcessing options

Input by kind

probe / import — minimum is {"url": "..."}:

{ "kind": "probe", "input": { "url": "https://example.com/video.mp4" } }

video / audio / image / animation — requires a File object from a prior probe:

{
  "kind": "video",
  "input": {
    "object": "file",
    "url": "...",
    "kind": "video",
    "format": "mp4",
    "width": 1920,
    "height": 1080,
    "duration": 62.5,
    "codecs": { "video": "h264", "audio": "aac" }
  },
  "options": { "width": 720, "quality": "medium" }
}

export — push to S3:

{
  "kind": "export",
  "input": { "object": "file", "url": "...", "kind": "video", "format": "mp4" },
  "options": { "url": "s3://bucket/output.mp4", "connection_id": "conn_abc123" }
}

Response 201

{
  "id": "task_abc123",
  "object": "task",
  "kind": "probe",
  "input": { "object": "external_file", "url": "https://example.com/video.mp4" },
  "output": null,
  "options": {},
  "status": "waiting",
  "progress": null,
  "error": null,
  "created_at": 1711900000000,
  "started_at": null,
  "finished_at": null,
  "updated_at": 1711900000000
}

Composing tasks

Output of one task feeds into the next. Probe a file, then encode:

# 1. Probe
ittybit task probe \
  -i '{"url": "https://example.com/video.mp4"}' \

# 2. Encode using probe output as input

ittybit task video \
 -i '<probe_output>' \
 --width 720 \

// 1. Probe
const probeTask = {
  kind: "probe",
  input: { url: "https://example.com/video.mp4" },
};

const probe = await fetch("https://api.ittybit.com/tasks", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ITTYBIT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(probeTask),
});
const probeResult = await probe.json();

// 2. Encode using probe output as input
const encodeTask = {
  kind: "video",
  input: probeResult.output,
  options: {
    width: 720,
  },
};

const encode = await fetch("https://api.ittybit.com/tasks", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ITTYBIT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(encodeTask),
});
const encodeResult = await encode.json();
import requests

headers = {"Authorization": f"Bearer {api_key}"}

# 1. Probe
probe_task = {
    "kind": "probe",
    "input": {"url": "https://example.com/video.mp4"},
}

probe = requests.post(
    "https://api.ittybit.com/tasks",
    headers=headers,
    json=probe_task,
)
probe_result = probe.json()

# 2. Encode using probe output as input
encode_task = {
    "kind": "video",
    "input": probe_result["output"],
    "options": {
        "width": 720,
    },
}

encode = requests.post(
    "https://api.ittybit.com/tasks",
    headers=headers,
    json=encode_task,
)
encode_result = encode.json()
# 1. Probe
TASK='{
  "kind": "probe",
  "input": {"url": "https://example.com/video.mp4"}
}'

curl -s -X POST https://api.ittybit.com/tasks \
  -H "Authorization: Bearer $ITTYBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$TASK"

# 2. Encode using probe output as input
TASK='{
  "kind": "video",
  "input": <probe_output>,
  "options": {
    "width": 720
  }
}'

curl -X POST https://api.ittybit.com/tasks \
  -H "Authorization: Bearer $ITTYBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$TASK"

This is how agents can inspect a file before deciding what to do with it.

See also

  • Create Job — run a full pipeline (probe + import + encode + export) in one call
  • CLI task — run tasks locally from the command line
  • Get Job — jobs also contain tasks, viewable after creation