Create Task

POST /tasks

Creates a task that processes a media file through a pipeline: probe → ingest → encode → upload. This is the main way to process media — send a URL, pick a kind, and Ittybit handles the rest. For the CLI equivalent, see ittybit tasks create.

Request body

Field	Type	Required	Description
`input`	string	yes	Source URL (`http://`, `https://`, or `s3://`)
`kind`	string	yes	`video` · `audio` · `image` · `adaptive_video`
`options`	object	no	Processing options
`output`	string	no	S3 destination (`s3://bucket/key`)
`metadata`	object	no	Arbitrary key-value pairs

Options

video

Option	Type	Values
`format`	string	`mp4` · `webm` · `mov`
`codec`	string	`h264` · `h265` · `vp9` · `av1`
`quality`	string	`very_low` · `low` · `medium` · `high` · `very_high`
`width`	int or string	Pixels or `"50%"`
`height`	int or string	Pixels or `"50%"`
`fit`	string	`contain` · `cover` · `fill`
`position`	string	`center` · `top` · `bottom` · `left` · `right` etc.
`background`	string	Hex color (e.g. `"#000000"`) — only with `fit: contain`
`fps`	number	1–60
`bitrate`	integer	300,000–60,000,000 bps
`start`	number	Seconds
`end`	number	Seconds

audio

Option	Type	Values
`format`	string	`mp3` · `aac` · `ogg` · `opus` · `wav` · `flac`
`quality`	string	`very_low` · `low` · `medium` · `high` · `very_high`
`bitrate`	integer	32,000–320,000 bps
`start`	number	Seconds
`end`	number	Seconds

image

Option	Type	Values
`format`	string	`jpeg` · `png` · `webp` · `gif` · `avif`
`quality`	string	`very_low` · `low` · `medium` · `high` · `very_high`
`width`	int or string	Pixels or `"50%"`
`height`	int or string	Pixels or `"50%"`
`fit`	string	`contain` · `cover` · `fill`
`position`	string	`center` · `top` · `bottom` · `left` · `right` etc.
`background`	string	Hex color (e.g. `"#000000"`) — only with `fit: contain`
`start`	number	Frame time in seconds (video input)

adaptive_video

Option	Type	Values
`format`	string	`hls`
`quality`	string	`very_low` · `low` · `medium` · `high` · `very_high`
`width`	int or string	Pixels or `"50%"`
`height`	int or string	Pixels or `"50%"`
`fit`	string	`contain` · `cover` · `fill`
`position`	string	`center` · `top` · `bottom` · `left` · `right` etc.
`background`	string	Hex color (e.g. `"#000000"`) — only with `fit: contain`
`start`	number	Seconds
`end`	number	Seconds

Examples

Video

Convert and resize a video. Smaller files mean faster page loads and lower CDN costs.

curl -X POST https://api.ittybit.com/tasks \
  -H "Authorization: Bearer $ITTYBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "https://example.com/upload.mov",
    "kind": "video",
    "options": {"width": 1280, "height": 720, "format": "mp4", "quality": "high"}
  }'

const res = await fetch("https://api.ittybit.com/tasks", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.ITTYBIT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    input: "https://example.com/upload.mov",
    kind: "video",
    options: { width: 1280, height: 720, format: "mp4", quality: "high" },
  }),
});
const task = await res.json();

import requests

res = requests.post(
    "https://api.ittybit.com/tasks",
    headers={"Authorization": f"Bearer {api_key}"},
    json={
        "input": "https://example.com/upload.mov",
        "kind": "video",
        "options": {"width": 1280, "height": 720, "format": "mp4", "quality": "high"},
    },
)
task = res.json()

Audio

Extract an audio track from a video file.

curl -X POST https://api.ittybit.com/tasks \
  -H "Authorization: Bearer $ITTYBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "https://example.com/interview.mp4",
    "kind": "audio",
    "options": {"format": "mp3", "quality": "high"}
  }'

const res = await fetch("https://api.ittybit.com/tasks", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.ITTYBIT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    input: "https://example.com/interview.mp4",
    kind: "audio",
    options: { format: "mp3", quality: "high" },
  }),
});
const task = await res.json();

import requests

res = requests.post(
    "https://api.ittybit.com/tasks",
    headers={"Authorization": f"Bearer {api_key}"},
    json={
        "input": "https://example.com/interview.mp4",
        "kind": "audio",
        "options": {"format": "mp3", "quality": "high"},
    },
)
task = res.json()

Image

Extract a poster frame from a video at the 5-second mark.

curl -X POST https://api.ittybit.com/tasks \
  -H "Authorization: Bearer $ITTYBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "https://example.com/video.mp4",
    "kind": "image",
    "options": {"start": 5, "format": "webp", "width": 640}
  }'

const res = await fetch("https://api.ittybit.com/tasks", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.ITTYBIT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    input: "https://example.com/video.mp4",
    kind: "image",
    options: { start: 5, format: "webp", width: 640 },
  }),
});
const task = await res.json();

import requests

res = requests.post(
    "https://api.ittybit.com/tasks",
    headers={"Authorization": f"Bearer {api_key}"},
    json={
        "input": "https://example.com/video.mp4",
        "kind": "image",
        "options": {"start": 5, "format": "webp", "width": 640},
    },
)
task = res.json()

Adaptive video

Create an HLS stream so players can switch quality based on viewer bandwidth. Adaptive streams prevent buffering for users on slow connections.

curl -X POST https://api.ittybit.com/tasks \
  -H "Authorization: Bearer $ITTYBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "https://example.com/video.mp4",
    "kind": "adaptive_video",
    "options": {"format": "hls", "quality": "high"}
  }'

const res = await fetch("https://api.ittybit.com/tasks", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.ITTYBIT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    input: "https://example.com/video.mp4",
    kind: "adaptive_video",
    options: { format: "hls", quality: "high" },
  }),
});
const task = await res.json();

import requests

res = requests.post(
    "https://api.ittybit.com/tasks",
    headers={"Authorization": f"Bearer {api_key}"},
    json={
        "input": "https://example.com/video.mp4",
        "kind": "adaptive_video",
        "options": {"format": "hls", "quality": "high"},
    },
)
task = res.json()

Output to S3

Send processed media to your own storage instead of Ittybit-managed storage. Requires a connection.

curl -X POST https://api.ittybit.com/tasks \
  -H "Authorization: Bearer $ITTYBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "https://example.com/upload.mov",
    "kind": "video",
    "output": "s3://my-bucket/processed/video.mp4"
  }'

const res = await fetch("https://api.ittybit.com/tasks", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.ITTYBIT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    input: "https://example.com/upload.mov",
    kind: "video",
    output: "s3://my-bucket/processed/video.mp4",
  }),
});
const task = await res.json();

import requests

res = requests.post(
    "https://api.ittybit.com/tasks",
    headers={"Authorization": f"Bearer {api_key}"},
    json={
        "input": "https://example.com/upload.mov",
        "kind": "video",
        "output": "s3://my-bucket/processed/video.mp4",
    },
)
task = res.json()

Response `201`

{
  "id": "task_abc123",
  "object": "task",
  "kind": "video",
  "input": "https://example.com/upload.mov",
  "output": null,
  "options": {"width": 1280, "height": 720, "format": "mp4", "quality": "high"},
  "metadata": {},
  "status": "queued",
  "error": null,
  "steps": [
    {"id": "step_001", "object": "step", "kind": "probe", "input": null, "options": {}, "output": null, "status": "waiting", "progress": null, "error": null, "created_at": 1711900000000, "started_at": null, "finished_at": null, "updated_at": 1711900000000},
    {"id": "step_002", "object": "step", "kind": "ingest", "input": null, "options": {}, "output": null, "status": "waiting", "progress": null, "error": null, "created_at": 1711900000000, "started_at": null, "finished_at": null, "updated_at": 1711900000000},
    {"id": "step_003", "object": "step", "kind": "video", "input": null, "options": {}, "output": null, "status": "waiting", "progress": null, "error": null, "created_at": 1711900000000, "started_at": null, "finished_at": null, "updated_at": 1711900000000},
    {"id": "step_004", "object": "step", "kind": "upload", "input": null, "options": {}, "output": null, "status": "waiting", "progress": null, "error": null, "created_at": 1711900000000, "started_at": null, "finished_at": null, "updated_at": 1711900000000}
  ],
  "created_at": 1711900000000,
  "started_at": null,
  "finished_at": null,
  "updated_at": 1711900000000
}

Errors

Status	Kind	Cause
`400`	`input_required`	Missing `input`
`400`	`invalid_input`	Bad URL scheme
`400`	`invalid_format`	Unknown format for kind
`400`	`invalid_codec`	Codec incompatible with container
`401`	`token_missing`	No Authorization header
`401`	`token_invalid`	Bad API key