Ittybit

https://ittybit.com/docs
Admin
Ittybit provides powerful media APIs for developers, handling video, audio, and image processing...
Tokens:45,417
Snippets:246
Trust Score:6.8
Update:11 months ago
Show doc for...
Tokens:
Raw
### Example Chapters File (VTT Format)

Source: https://ittybit.com/docs/chapters

This is an example of a WebVTT (WebVTT) file format for video chapters. It includes timestamps for the start and end of each chapter segment, along with a title for each.

```vtt
WEBVTT

00:00:00.000 --> 00:01:00.200
Introduction

00:01:00.200 --> 00:03:00.500
Product Demo

00:03:00.500 --> 00:10:00.000
Conclusion and Q&A
```

--------------------------------

### Webhook Example for Speech Results

Source: https://ittybit.com/docs/speech

An example of how to set up a webhook endpoint to receive completed speech task results.

```APIDOC
## Webhook Endpoint

### Description
This is an example server-side endpoint designed to receive and process the results of a completed speech task from Ittybit.

### Method
POST

### Endpoint
`/speech-webhook` (or any custom URL provided during task creation)

### Parameters
#### Request Body
- **kind** (string) - The type of task that completed. Should be `"speech"`.
- **status** (string) - The final status of the task. Should be `"completed"`.
- **results** (object) - An object containing the detailed results of the speech task (structure matches the 'Speech Task Results' documentation).
  - **text** (array) - The transcribed text.
  - **speakers** (integer) - The number of detected speakers.
  - **language** (string) - The detected language.

### Request Example (Incoming Webhook Payload)
```json
{
  "kind": "speech",
  "status": "completed",
  "results": {
    "id": "file_qrstuvwx1234",
    "object": "intelligence",
    "kind": "speech",
    "detected": true,
    "speakers": 2,
    "language": "en",
    "text": [
      "Hello, and welcome to UkeTube. I'm Jesse Doe.",
      "And I'm John Doe. Today we're going to be learning Sandstorm by Darude."
    ],
    "confidence": 0.72,
    "timeline": [
      {
        "index": 0,
        "start": 12.00,
        "end": 14.50,
        "detected": true,
        "speaker": 0,
        "text": "Hello, and welcome to UkeTube. I'm Jesse Doe.",
        "confidence": 0.89
      },
      {
        "index": 1,
        "start": 14.80,
        "end": 18.28,
        "detected": true,
        "speaker": 1,
        "text": "And I'm John Doe. Today we're going to be learning Sandstorm by Darude.",
        "confidence": 0.91
      }
    ],
    "created": "2025-01-01T01:23:45Z",
    "updated": "2025-01-01T01:23:45Z"
  }
}
```

### Response
#### Success Response (200)
Acknowledge receipt of the webhook. Return a `200 OK` status.

#### Response Example
`Speech results received`
```

--------------------------------

### VTT Chapter Example

Source: https://ittybit.com/docs/tracks

Example of a WebVTT (VTT) formatted chapter file. Chapters help organize video or audio content into logical sections.

```txt
WEBVTT

1
00:00:00.000 --> 00:00:12.345
An intro to chapters

2
00:00:12.345 --> 00:00:23.456
A chapter about chapters

3
00:00:23.456 --> 00:00:34.567
Another chapter
```

--------------------------------

### Video Start Time

Source: https://ittybit.com/docs/video

Specifies the starting point in seconds from which to begin encoding the video.

```APIDOC
## Video Start Time

### Description
From where in the video to start encoding in seconds.

### Method
Not applicable (configuration option)

### Endpoint
Not applicable (configuration option)

### Parameters
#### Query Parameters
- **start** (number) - Optional - The time in seconds from the beginning of the video to start encoding. Defaults to `0.0` (beginning of the video).

*Note: If `start` is greater than the input file duration, the task will fail.*

### Request Example
```javascript
{
  "url": "https://example.com/video.mp4",
  "kind": "video",
  "start": 10.0
}
```

### Response
N/A (Configuration option for processing)
```

--------------------------------

### Example Chapters JSON Output

Source: https://ittybit.com/docs/chapters

This JSON object represents the structured chapter data generated for a media file. It includes metadata like ID, language, duration, and a list of chapters with their start and end times and titles.

```json
{
  "id": "file_789xyz",
  "object": "track",
  "kind": "chapters",
  "language": "en",
  "format": "json",
  "filename": "video-chapters.json",
  "duration": 600.0,
  "filesize": 1450,
  "url": "https://live.ittybit.net/video-chapters.json",
  "chapters": [
    {
      "index": 0,
      "start": 0.0,
      "end": 60.2,
      "title": "Introduction"
    },
    {
      "index": 1,
      "start": 60.2,
      "end": 180.5,
      "title": "Product Demo"
    },
    {
      "index": 2,
      "start": 180.5,
      "end": 600.0,
      "title": "Conclusion and Q&A"
    }
  ],
  "created": "2025-01-01T01:23:45Z",
  "updated": "2025-01-01T01:23:45Z"
}
```

--------------------------------

### Description Task Example Output (JSON)

Source: https://ittybit.com/docs/description

This is an example of the JSON output received from an Ittybit Description task upon completion. It includes metadata such as a unique ID, object type, kind, generated title, description, tags, language, confidence score, and timestamps.

```json
{
  "id": "file_abcdef123456",
  "object": "intelligence",
  "kind": "description",
  "title": "Sunset over the Alps",
  "description": "A scenic photo of a mountain range with orange clouds and warm evening light. Ideal for travel or nature collections.",
  "tags": ["sunset", "mountains", "nature", "travel", "landscape"],
  "language": "en",
  "confidence": 0.94,
  "created": "2025-01-01T01:23:45Z",
  "updated": "2025-01-01T01:23:45Z"
}
```

--------------------------------

### Create Workflow via Ittybit API (JavaScript)

Source: https://ittybit.com/docs/workflows

A JavaScript example using the Ittybit SDK to create an automation with a defined workflow. This demonstrates how to programmatically define tasks for video processing.

```javascript
const automation = await ittybit.automations.create({
  name: "Video Processing Workflow",
  trigger: {
    kind: "event",
    event: "media.created"
  },
  workflow: [
    { kind: "video", format: "mp4", quality: 75 },
    { kind: "subtitles" },
    { kind: "thumbnails", count: 3 }
  ],
  status: "active"
});
```

--------------------------------

### VTT Thumbnail Example

Source: https://ittybit.com/docs/tracks

Example of a WebVTT (VTT) formatted thumbnail track. This format specifies URLs to sprite sheet images and their coordinates for preview frames.

```txt
WEBVTT

1
00:00:00.000 --> 00:00:02.345
https://you.ittybit.net/example/sprite.png#xywh=0,0,160,90

2
00:00:02.345 --> 00:00:04.567
https://you.ittybit.net/example/sprite.png#xywh=160,0,160,90

3
00:00:04.567 --> 00:00:06.789
https://you.ittybit.net/example/sprite.png#xywh=320,0,160,90
```

--------------------------------

### Create Media Task with cURL

Source: https://ittybit.com/docs/.md

This example demonstrates how to create a new media processing task using cURL. It requires an API key for authorization and specifies the media URL and task kind as input. The output is an AI-generated description and tags for the video.

```bash
curl -X POST "https://api.ittybit.com/tasks" \
-H "Authorization: Bearer ITTYBIT_API_KEY" \
-d '{"url": "https://ittyb.it/sample.mp4", "kind": "description"}'
```

--------------------------------

### Sequential Video Processing Workflow

Source: https://ittybit.com/docs/workflows

An example JSON workflow that defines a pipeline for processing video files. It sequentially compresses the video, generates subtitles, thumbnails, and chapters when a 'media.created' event is triggered.

```json
{
  "name": "Video Compression Pipeline",
  "description": "Convert videos to MP4, generate subtitles, thumbnails, and chapters.",
  "trigger": {
    "kind": "event",
    "event": "media.created"
  },
  "workflow": [
    {
      "kind": "video",
      "format": "mp4",
      "quality": 75,
      "ref": "compressed-video"
    },
    {
      "kind": "subtitles",
      "ref": "video-subtitles"
    },
    {
      "kind": "thumbnails",
      "count": 3,
      "ref": "video-thumbnails"
    },
    {
      "kind": "chapters",
      "ref": "video-chapters"
    }
  ],
  "status": "active"
}
```

--------------------------------

### VTT Subtitle Example

Source: https://ittybit.com/docs/tracks

Example of a WebVTT (VTT) formatted subtitle file. VTT is commonly used for web-based video and audio accessibility.

```txt
WEBVTT

1
00:00:00.000 --> 00:00:01.234
Hello, world!

2
00:00:01.234 --> 00:00:02.456
This is an example of

3
00:00:03.456 --> 00:00:05.678
a VTT formatted subtitle file.
```

--------------------------------

### Create Video Clips from Speech Segments (JavaScript)

Source: https://ittybit.com/docs/speech

This JavaScript example shows how to leverage speech transcription data to automatically create short video clips based on identified speech segments. It uses the `chapters` array (generated from the speech timeline) to initiate new video tasks via the Ittybit SDK. For each chapter, it creates a video task specifying the `sourceFileId`, `start` and `end` times from the chapter, and a descriptive `filename` and `ref`.

```javascript
// Example: create a short clip per speech segment
const clips = chapters.map(ch => ittybit.tasks.create({
  kind: "video",
  file_id: sourceFileId,
  start: ch.start,
  end: ch.end,
  filename: `clip-${ch.index}.mp4`,
  ref: `speech-segment-${ch.index}`
}));
```

--------------------------------

### Execute a Media Processing Workflow (TypeScript)

Source: https://ittybit.com/docs/about

This snippet shows how to define and execute a media processing workflow using the Ittybit API. Workflows allow for sequential or parallel execution of multiple tasks. The example defines a workflow to describe a video, resize it, and then create a thumbnail track. The request is a POST to '/workflows' with the media URL and workflow definition.

```typescript
const url = 'https://your.storage.bucket/video.mp4';

const workflow = [
  {
    kind: 'description'
  },
  {
    kind: 'video',
    height: 720,
    next: [
      {
        kind: 'thumbnails'
      }
    ]
  }
];

const response = await fetch('https://api.ittybit.com/workflows', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer ITTYBIT_API_KEY' },
  body: JSON.stringify({ url, workflow })
});
```

--------------------------------

### Create Video Task with Shared Options

Source: https://ittybit.com/docs/video

This example shows how to create a video task and includes optional shared properties like 'folder' and 'filename' for organizing the output video. These parameters help manage where and how the processed video is stored.

```javascript
const options = {
  url: 'https://example.com/video.mp4',
  kind: 'video',
  folder: "uploads/user123",
  filename: "intro-20250101.mp4"
}
```

--------------------------------

### Create Audio Task with Shared Options - JavaScript

Source: https://ittybit.com/docs/audio

This example demonstrates creating an audio task with additional shared options such as `folder` and `filename`. These options allow for organizing and naming the processed audio files, alongside the required `url` and `kind`.

```javascript
const options = {
  url: 'https://example.com/audio.mp3',
  kind: 'audio',
  folder: 'uploads/user123',
  filename: 'episode-01.mp3',
}
```

--------------------------------

### NSFW Workflow Automation Example (JSON)

Source: https://ittybit.com/docs/nsfw

A JSON configuration for an Ittybit workflow that automatically triggers an NSFW task for every new media file created. This demonstrates how to automate content moderation based on events.

```json
{
  "name": "Moderate new uploads",
  "trigger": {
    "kind": "event",
    "event": "media.created"
  },
  "workflow": [
    { "kind": "nsfw", "ref": "safety-check" }
  ],
  "status": "active"
}
```

--------------------------------

### File Object Type Example

Source: https://ittybit.com/docs/files

Illustrates the 'object' property, specifying the type of the file, such as 'source', 'track', or 'intelligence'.

```json
{
  "id": "file_abcdefgh1234",
  "object": "source",
  "//": "... other props"
}
```

--------------------------------

### Audio Task Example JSON Output

Source: https://ittybit.com/docs/audio

A sample JSON representation of a 'Media' object, specifically focusing on audio-relevant fields. This structure illustrates the data returned after an audio processing task, including file details, duration, and URLs.

```json
{
  "id": "med_598j8Q37dsM3zzRe",
  "object": "media",
  "kind": "audio",
  "title": null,
  "duration": 62.224,
  "files": [
    {
      "id": "file_598j8I0639G3VtMy",
      "object": "source",
      "kind": "audio",
      "type": "audio/mpeg",
      "duration": 62.224,
      "filesize": 2488947,
      "bitrate": 320000,
      "ref": null,
      "folder": null,
      "filename": "Dorian_Concept_1.mp3",
      "url": "https://jamal-tests.ittybit.net/Dorian_Concept_1.mp3",
      "metadata": {},
      "original": true,
      "created_by": null,
      "created": "2025-10-09T19:08:52.381Z",
      "updated": "2025-10-09T19:08:52.381Z"
    }
  ],
  "urls": {
    "original": "https://jamal-tests.ittybit.net/Dorian_Concept_1.mp3"
  },
  "metadata": {},
  "created": "2025-10-09T19:08:52.380Z",
  "updated": "2025-10-09T19:08:52.380Z"
}
```

--------------------------------

### Example Ittybit Webhook Payload JSON

Source: https://ittybit.com/docs/webhooks

This is an example of the JSON payload structure that Ittybit sends to your configured webhook URL when a task or automation step completes. It includes details about the event, status, and results.

```json
{
  "id": "task_123abc",
  "object": "task",
  "kind": "nsfw",
  "status": "completed",
  "results": {
    "is_nsfw": true,
    "confidence": 0.97
  },
  "project_id": "proj_xyz",
  "automation_id": "auto_456def",
  "created": "2025-01-10T12:34:56Z",
  "completed": "2025-01-10T12:35:22Z"
}
```

--------------------------------

### File Folder Property Example

Source: https://ittybit.com/docs/files

Illustrates the 'folder' property for organizing files into URLs, supporting nested folders for better structure.

```json
{
  "id": "file_abcdefgh1234",
  "object": "source",
  "kind": "video",
  "//": "... other props",
  "filename": "video.mp4",
  "folder": "example/videos",
  "url": "https://you.ittybit.net/example/videos/video.mp4"
}
```

--------------------------------

### File Kind Property Example

Source: https://ittybit.com/docs/files

Shows the 'kind' property, which categorizes files like 'video', 'image', 'audio' for source files, or 'subtitles', 'chapters' for track files.

```json
{
  "id": "file_abcdefgh1234",
  "object": "source",
  "kind": "video",
  "//": "... other props"
}
```

--------------------------------

### Example Chapters Workflow Integration

Source: https://ittybit.com/docs/chapters

This JSON configuration illustrates how to integrate Chapters task generation into an Ittybit workflow. It's defined as part of a sequence of tasks triggered by a media creation event, alongside other track generations like subtitles and thumbnails.

```json
{
  "name": "Auto-generate video tracks",
  "trigger": {
    "kind": "event",
    "event": "media.created"
  },
  "workflow": [
    { "kind": "video", "format": "mp4" },
    { "kind": "subtitles", "ref": "video-subtitles" },
    { "kind": "thumbnails", "count": 3 },
    { "kind": "chapters", "ref": "video-chapters" }
  ],
  "status": "active"
}
```

--------------------------------

### File URL Property Example

Source: https://ittybit.com/docs/files

Shows the 'url' property, providing the accessible URL for the file, typically formed from the project's domain and the file's ID.

```json
{
  "id": "file_abcdefgh1234",
  "object": "source",
  "kind": "video",
  "//": "... other props",
  "url": "https://you.ittybit.net/file_abcdefgh1234"
}
```

--------------------------------

### SRT Subtitle Example

Source: https://ittybit.com/docs/tracks

Example of a SubRip Text (SRT) formatted subtitle file. SRT is a widely supported subtitle format for video players.

```txt
1
00:00:00,000 --> 00:00:01,234
Hello, world!

2
00:00:01,234 --> 00:00:02,456
This is an example of

3
00:00:03,456 --> 00:00:05,678
a SRT formatted subtitle file.
```

--------------------------------

### File Filename Property Example

Source: https://ittybit.com/docs/files

Demonstrates how the 'filename' property can customize the file's URL, allowing for more user-friendly or descriptive names.

```json
{
  "id": "file_abcdefgh1234",
  "object": "source",
  "kind": "video",
  "//": "... other props",
  "filename": "video.mp4",
  "url": "https://you.ittybit.net/video.mp4"
}
```

--------------------------------

### Example File Object with Metadata (JSON)

Source: https://ittybit.com/docs/metadata

This JSON snippet demonstrates the structure of a file object, including the 'metadata' property which holds custom key-value pairs. This data is returned in file or media responses.

```json
{
  "id": "file_abcdefgh1234",
  "object": "file",
  // ... other props
  "metadata": {
    "user_id": "abcd-1234-efgh-5678",
    "username": "@totallyrealperson"
  }
}
```

--------------------------------

### Example Automation Workflow (JSON)

Source: https://ittybit.com/docs/subtitles

This JSON defines an Ittybit automation workflow. When a new media file is created, it triggers a sequence that first encodes the video to MP4 and then generates subtitles. This showcases integrating subtitles generation into automated media processing.

```json
{
  "name": "Generate subtitles for uploaded videos",
  "trigger": {
    "kind": "event",
    "event": "media.created"
  },
  "workflow": [
    { "kind": "video", "format": "mp4" },
    { "kind": "subtitles", "ref": "video-subtitles" }
  ],
  "status": "active"
}
```

--------------------------------

### Example VTT Subtitle Output

Source: https://ittybit.com/docs/subtitles

This is a sample of the WebVTT (Video Text Tracks) format for subtitles. It includes timestamps indicating when each caption line should appear and disappear, synchronized with the audio or video content.

```text
WEBVTT

00:00:12.000 --> 00:00:14.500
Hello, and welcome to UkeTube. I'm Jesse Doe.

00:00:14.800 --> 00:00:18.280
And I'm John Doe. Today we're going to be learning Sandstorm by Darude.
```

--------------------------------

### Example Subtitles Task Output (JSON)

Source: https://ittybit.com/docs/subtitles

This JSON object represents the structure of a completed subtitles track. It includes metadata like ID, language, format, duration, and the URL to the generated subtitle file.

```json
{
  "id": "file_abc123xyz",
  "object": "track",
  "kind": "subtitles",
  "language": "en",
  "format": "vtt",
  "filename": "video-subtitles.vtt",
  "duration": 63.2,
  "filesize": 2048,
  "url": "https://live.ittybit.net/video-subtitles.vtt",
  "metadata": {},
  "created": "2025-01-01T01:23:45Z",
  "updated": "2025-01-01T01:23:45Z"
}
```

--------------------------------

### Output File with 'folder' Property (JSON)

Source: https://ittybit.com/docs/tasks

This JSON example shows a file object that has been processed and saved into a specified folder. The 'folder' property is included in the file's metadata, and the 'url' reflects this folder structure.

```json
{
  "id": "file_abcdefgh1234",
  // ... other file props
  "folder": "uploads/user123",
  "url": "https://you.ittybit.net/uploads/user123/file_abcdefgh1234.mp4"
}
```

--------------------------------

### Output File with 'ref' Property (JSON)

Source: https://ittybit.com/docs/tasks

This JSON example illustrates how an output file is structured when a 'ref' property is used during task creation. The 'ref' acts as a key in the 'urls' object of the associated Media Object, providing a named alias for the file's URL.

```json
{
  "id": "med_abcdefgh1234",
  // ... other media props
  "urls": {
    "original": "https://you.ittybit.net/file_abcdefgh1234.mp4",
    "avatar": "https://you.ittybit.net/file_abcdefgh5678.jpg"
  }
}
```

--------------------------------

### Ingestion Request with Additional Properties (Files and Tasks)

Source: https://ittybit.com/docs/ingest

These JSON examples illustrate how to include optional parameters like 'folder' and 'filename' when ingesting files, applicable to both the Files and Tasks API endpoints. This allows for organized storage and custom naming of ingested assets.

```json
{
  "url": "https://example.com/video.mp4",
  "folder": "user_1234/uploads",
  "filename": "custom-filename.mp4"
}
```

```json
{
  "kind": "ingest",
  "url": "https://example.com/video.mp4",
  "folder": "user_1234/uploads",
  "filename": "custom-filename.mp4"
}
```

--------------------------------

### Access Files by 'ref' in Code

Source: https://ittybit.com/docs/files

Demonstrates how to find a specific file source from a Media object's sources array using its 'ref' property. Examples are provided for JavaScript, Python, Ruby, PHP, and Go.

```javascript
const poster = media.sources.find(source => source.ref === 'poster') || null;
```

```python
poster = next((source for source in media.sources if source.ref == 'poster'), None)
```

```ruby
poster = media.sources.find { |source| source.ref == 'poster' } || nil
```

```php
$poster = array_filter($media->sources, function($source) {
    return $source->ref === 'poster';
})[0] ?? null;
```

```go
poster := media.Sources.Find(func(source *Source) bool {
    return source.Ref == "poster"
})
```

--------------------------------

### Set Video Encoding Start Time (JavaScript)

Source: https://ittybit.com/docs/video

Specifies the starting point for video encoding in seconds from the beginning of the input file. If omitted, encoding starts from the beginning. Exceeding the file duration will result in task failure.

```javascript
const options = {
  url: 'https://example.com/video.mp4',
  kind: 'video',
  start: 10.0,
}
```

--------------------------------

### Create Chapters Task using Ittybit SDK

Source: https://ittybit.com/docs/chapters

This JavaScript code demonstrates how to create a Chapters task using the Ittybit SDK. It requires an API key and specifies the media URL, a description, and a webhook URL for notifications.

```javascript
import { IttybitClient } from "@ittybit/sdk";

const ittybit = new IttybitClient({
  apiKey: process.env.ITTYBIT_API_KEY!
});

const task = await ittybit.tasks.create({
  kind: "chapters",
  url: "https://example.com/video.mp4",
  description: "Generate structured chapters for a video",
  webhook_url: "https://your-app.com/chapters-webhook"
});

console.log("Task created:", task.id);
console.log("Status:", task.status);
```

--------------------------------

### Video Processing Automation Workflow with Thumbnails

Source: https://ittybit.com/docs/thumbnails

This JSON configuration defines an automation workflow that includes generating video, subtitles, thumbnails, and chapters. When a 'media.created' event is triggered, this workflow automatically processes the media, ensuring thumbnails are created as part of the pipeline. The 'ref' property links the thumbnail generation to a specific output.

```json
{
  "name": "Video Processing Pipeline",
  "trigger": {
    "kind": "event",
    "event": "media.created"
  },
  "workflow": [
    { "kind": "video", "format": "mp4", "quality": 75 },
    { "kind": "subtitles", "ref": "video-subtitles" },
    { "kind": "thumbnails", "count": 3, "ref": "video-thumbnails" },
    { "kind": "chapters", "ref": "video-chapters" }
  ],
  "status": "active"
}
```

--------------------------------

### File Original Property Example

Source: https://ittybit.com/docs/files

Shows the 'original' property, a boolean indicating if the file is the primary uploaded or ingested version.

```json
{
  "id": "file_abcdefgh1234",
  "object": "source",
  "kind": "video",
  "//": "... other props",
  "url": "https://you.ittybit.net/example/videos/video.mp4",
  "original": true
}
```

--------------------------------

### File Size Property Example

Source: https://ittybit.com/docs/files

Displays the 'filesize' property, indicating the file size in bytes, used for calculating storage usage.

```json
{
  "id": "file_abcdefgh1234",
  "object": "source",
  "kind": "video",
  "type": "video/mp4",
  "filesize": 12345678,
  "//": "... other props"
}
```

--------------------------------

### File ID Property Example

Source: https://ittybit.com/docs/files

Demonstrates the 'id' property of a file object, which serves as a unique and immutable identifier assigned by the API.

```json
{
  "id": "file_abcdefgh1234",
  "//": "... other props"
}
```

--------------------------------

### POST /tasks

Source: https://ittybit.com/docs/ingest

Initiates a background ingestion task for a file. The response includes metadata and the initial task status.

```APIDOC
## POST /tasks

### Description
Initiates a background ingestion task for a file. The response includes metadata and the initial task status. The file will be ingested in the background, and you can poll the task for updates or set up webhooks.

### Method
POST

### Endpoint
/tasks

### Request Body
- **url** (string) - Required - The URL of the file to ingest.
- **kind** (string) - Optional - The type of task, e.g., "ingest".
- **folder** (string) - Optional - The destination folder for the ingested file.
- **filename** (string) - Optional - A custom filename for the ingested file.

### Request Example
```json
{
  "url": "https://example.com/video.mp4",
  "folder": "user_1234/uploads",
  "filename": "custom-filename.mp4"
}
```

### Response
#### Success Response (201 Created)
- **meta** (object) - Metadata about the request.
- **data** (object) - The created task object.
- **links** (object) - Links related to the task.

#### Response Example
```json
{
  "meta": {
    "id": "req_abcdefgh12345678",
    "type": "object"
  },
  "data": {
    "id": "task_abcdefgh1234",
    "kind": "ingest",
    "status": "pending",
    "created": "2025-01-01T01:23:45Z",
    "updated": "2025-01-01T01:23:45Z"
  },
  "links": {
    "self": "https://api.ittybit.com/tasks/task_abcdefgh1234"
  }
}
```
```

--------------------------------

### File Management - GET /files/{fileId}

Source: https://ittybit.com/docs/tasks

Retrieves information about a specific file, including its ID, filename, and URL. The filename can be customized.

```APIDOC
## GET /files/{fileId}

### Description
Retrieves information about a specific file, including its ID, filename, and URL. The `filename` property in the response can be used to specify a custom filename for the saved file, and when combined with the `folder` option, it allows saving to a specific path.

### Method
GET

### Endpoint
/files/{fileId}

### Parameters
#### Path Parameters
- **fileId** (string) - Required - The unique identifier of the file.

### Request Example
(No request body for GET request)

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the file.
- **filename** (string) - The custom filename of the file.
- **folder** (string) - The folder path where the file is saved (optional).
- **url** (string) - The delivery URL of the file.

#### Response Example
```json
{
  "id": "file_abcdefgh1234",
  "filename": "user123-profile-20250101.jpg",
  "url": "https://you.ittybit.net/user123-profile-20250101.jpg"
}
```

#### Response Example with Folder
```json
{
  "id": "file_abcdefgh1234",
  "filename": "profile-20250101.jpg",
  "folder": "uploads/user123",
  "url": "https://you.ittybit.net/uploads/user123/profile-20250101.jpg"
}
```
```

--------------------------------

### Create Advanced Video Task with Customization and Overlays

Source: https://ittybit.com/docs/video

This comprehensive snippet illustrates creating a video task with extensive customization options. It includes setting dimensions (width, height), fit, position, background color, frame rate, format, quality, and duration. It also demonstrates adding image and text overlays with their respective properties.

```javascript
const options = {
  url: 'https://example.com/video.mp4',
  kind: 'video',
  width: 720,
  height: 1280,
  fit: 'contain',
  position: 'center',
  background: '#20B075',
  fps: 30,
  format: 'mp4',
  quality: 80,
  start: 0,
  end: 10,
  layers: [
    {
      kind: 'image',
      url: 'https://example.com/image.png',
      position: 'bottom right',
      width: 100,
      height: 100,
    },
    {
      kind: 'text',
      text: 'Hello, world!',
      font: 'Inter',
      font_size: 32,
      color: '#FFFFFF',
      position: 'bottom left',
    },
  ],
}
const task = await ittybit.tasks.create(options);
```

--------------------------------

### Create Speech Task with Ittybit SDK (TypeScript)

Source: https://ittybit.com/docs/speech

This TypeScript code snippet demonstrates how to create a new speech processing task using the Ittybit client SDK. It initializes the client with an API key and then calls the `create` method, specifying the task `kind` as 'speech', providing a media `url`, a descriptive `description`, and an optional `webhook_url` for notifications. The output logs the newly created task's ID and status.

```typescript
import { IttybitClient } from "@ittybit/sdk";

const ittybit = new IttybitClient({
  apiKey: process.env.ITTYBIT_API_KEY!
});

const task = await ittybit.tasks.create({
  kind: "speech",
  url: "https://example.com/video.mp4",
  description: "Transcribe spoken audio to text",
  webhook_url: "https://your-app.com/speech-webhook"
});

console.log("Task created:", task.id);
console.log("Status:", task.status);
```

--------------------------------

### GET /tasks/{id}

Source: https://ittybit.com/docs/tasks

Retrieves the status and details of a specific task using its ID. This endpoint is used to poll for task completion.

```APIDOC
## GET /tasks/{id}

### Description
Retrieves the status and details of a specific task using its ID. This endpoint is used to poll for task completion.

### Method
GET

### Endpoint
/tasks/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique ID of the task to retrieve.

### Response
#### Success Response (200 OK)
- **task** (object) - A task object containing the latest information about the task's status and output. If the task is completed, the `output` field will contain the details of the created file.

#### Response Example (Pending)
```json
{
  "id": "task_abcdefgh12345678",
  "object": "task",
  "kind": "speech",
  "input": {
    "url": "https://example.com/video.mp4",
    "kind": "video",
    "type": "video/mp4",
    "filesize": 123456789,
    "duration": 123.45,
    "created": "2025-01-01T01:23:45.678Z"
  },
  "options": {},
  "output": null,
  "status": "pending",
  "created": "2025-01-01T01:23:45.678Z",
  "updated": "2025-01-01T01:23:45.678Z"
}
```

#### Response Example (Completed)
```json
{
  "id": "task_abcdefgh12345678",
  "object": "task",
  "kind": "speech",
  "input": {
    "url": "https://example.com/video.mp4",
    "kind": "video",
    "type": "video/mp4",
    "filesize": 123456789,
    "duration": 123.45,
    "created": "2025-01-01T01:23:45.678Z"
  },
  "options": {
    "speakers": true
  },
  "output": {
    "id": "file_abcdefgh90123456",
    "kind": "speech",
    "type": "application/json",
    "filesize": 123456,
    "url": "https://you.ittybit.net/file_abcdefgh90123456.json",
    "metadata": {},
    "created": "2025-01-01T01:23:46.789Z",
    "updated": "2025-01-01T01:23:46.789Z"
  },
  "status": "completed",
  "created": "2025-01-01T01:23:45.678Z",
  "updated": "2025-01-01T01:23:46.789Z"
}
```
```

--------------------------------

### HTML Video with Poster Image

Source: https://ittybit.com/docs/sources

Illustrates how to set a poster image for a video element. This image is displayed before the video starts playing or while it's buffering.

```html
<video poster="https://you.ittybit.net/example/poster.png">
  <source src="https://you.ittybit.net/example/video.mp4" type="video/mp4">
</video>

```

--------------------------------

### List Files using Ittybit API (Multiple Languages)

Source: https://ittybit.com/docs/keys

This snippet demonstrates how to authenticate with the Ittybit API using an API key and list files for a project. It supports TypeScript, Python, Ruby, PHP, Go, Fetch (JavaScript), and cURL. Ensure you replace 'ITTYBIT_API_KEY' with your actual key. The output is typically a list of files or an error.

```typescript
import { Ittybit } from '@ittybit/sdk'

const ittybit = new Ittybit({
  apiKey: 'ITTYBIT_API_KEY'
})

const files = await ittybit.files.list()
```

```python
import Ittybit from ittybit

itybit = Ittybit(api_key="ITTYBIT_API_KEY")

files = ittybit.files.list()
```

```ruby
require 'ittybit'

itybit = Ittybit::Client.new(
    api_key: "ITTYBIT_API_KEY"
)

files = ittybit.files.list()
```

```php
use Ittybit\IttybitClient;

$ittybit = new IttybitClient(
    apiKey: "ITTYBIT_API_KEY"
);

$files = $ittybit->files->list();
```

```go
ittybit := client.NewClient(
	option.WithAPIKey("ITTYBIT_API_KEY"),
)

files, err := ittybit.Files.List(
	context.TODO(),
	ittybit.Files.ListParams{},
)
```

```javascript
const response = await fetch('https://api.ittybit.com/files', {
  headers: { 'Authorization': 'Bearer ITTYBIT_API_KEY' }
})

const { data: files, error } = await response.json()
```

```bash
curl https://api.ittybit.com/files \
-H "Authorization: Bearer ITTYBIT_API_KEY"
```

--------------------------------

### GET /tasks/:id

Source: https://ittybit.com/docs/ingest

Retrieves the status and details of a specific ingestion task. If the task is complete, it will contain an 'output' object with file data.

```APIDOC
## GET /tasks/:id

### Description
Retrieves the status and details of a specific ingestion task. When the task is complete, the task object will contain an `output` object with the file data.

### Method
GET

### Endpoint
/tasks/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the task to retrieve.

### Response
#### Success Response (200 OK)
- **meta** (object) - Metadata about the request.
- **data** (object) - The task object, which may include an `output` field if completed.

#### Response Example
```json
{
  "meta": {
    "id": "req_abcdefgh56789012",
    "type": "object"
  },
  "data": {
    "id": "task_abcdefgh1234",
    "kind": "ingest",
    "output": {
      "id": "file_abcdefgh1234",
      "kind": "video",
      "type": "video/mp4",
      "width": 1024,
      "height": 768,
      "duration": 120.5,
      "filesize": 123456,
      "url": "https://you.ittybit.net/file_abcdefgh1234",
      "status": "complete"
    }
  }
}
```
```

--------------------------------

### File MIME Type Example

Source: https://ittybit.com/docs/files

Defines the 'type' property, representing the MIME type of the file (e.g., 'video/mp4'), used by browsers and players to handle the file.

```json
{
  "id": "file_abcdefgh1234",
  "object": "source",
  "kind": "video",
  "type": "video/mp4",
  "//": "... other props"
}
```

--------------------------------

### Simple Uploads

Source: https://ittybit.com/docs/uploads

Use simple uploads for most use cases, starting with basic file uploads. Make an authenticated PUT request with the file bytes in the request body.

```APIDOC
## PUT /:filename

### Description
Uploads a file using a simple PUT request. The filename and folder are inferred from the URL.

### Method
PUT

### Endpoint
`https://your-domain.ittybit.net/:filename`

### Parameters
#### Path Parameters
- **filename** (string) - Required - The name of the file to upload.

#### Headers
- **Authorization** (string) - Required - Bearer token with your API Key (e.g., `Bearer ITTYBIT_API_KEY`).

### Request Body
- **file** (binary) - Required - The file content (bytes).

### Request Example
```js
const response = await fetch('https://you.ittybit.net/image.png', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer ITTYBIT_API_KEY',
  },
  body: file,
});
```

### Response
#### Success Response (200 OK)
Returns a File object containing metadata about the uploaded file.

#### Response Example
```json
{
  "id": "file_abcdefgh1234",
  "kind": "image",
  "type": "image/png",
  "width": 3000,
  "height": 2000,
  "filesize": 12345678,
  "url": "https://you.ittybit.net/image.png",
  "created": "2025-01-01T01:23:45Z",
  "updated": "2025-01-01T01:23:45Z"
}
```
```

--------------------------------

### Workflows API

Source: https://ittybit.com/docs/index

Build and manage media processing workflows. Workflows allow you to chain multiple tasks together to create complex media processing pipelines.

```APIDOC
## Workflows API

### Description
Workflows enable you to orchestrate multiple media processing tasks into a scalable pipeline. You can trigger workflows based on events in your application.

### Resources
- **Workflows**: `/docs/workflows`
- **Conditions**: `/docs/conditions`
- **Webhooks**: `/docs/webhooks`
```

--------------------------------

### Automations API

Source: https://ittybit.com/docs/index

Set up automated media processing. Automations allow you to automatically run workflows on files as they are added or updated.

```APIDOC
## Automations API

### Description
Automations provide a way to automatically process media files at scale. You can configure automations to trigger workflows based on file events.

### Resources
- **Automations**: `/docs/automations`
```

--------------------------------

### Create Audio Task with URL - JavaScript

Source: https://ittybit.com/docs/audio

This snippet shows how to create an audio processing task using a direct URL to the audio file. It requires a `url` and the `kind` set to 'audio'. The created task object can then be passed to an SDK or API request.

```javascript
const options = {
  url: 'https://example.com/audio.mp3',
  kind: 'audio',
}
// Pass options to an SDK or API request, e.g.:
const task = await ittybit.tasks.create(options)
```

--------------------------------

### Resize Image to Specific Height

Source: https://ittybit.com/docs/image

Shows how to resize an image to a specified height, with the width automatically adjusted to preserve the aspect ratio. This example sets the height to 1200 pixels.

```javascript
const options = {
  url: 'https://example.com/image.jpg',
  kind: 'image',
  height: 1200, // or height: "50%"
}
const task = await ittybit.tasks.create(options)
```

--------------------------------

### Create Description Task with Ittybit SDK (TypeScript)

Source: https://ittybit.com/docs/description

This snippet demonstrates how to use the Ittybit SDK to create a 'description' task. It requires an API key for authentication and takes a URL, a task description, and an optional webhook URL as input. The output includes the task ID and its status.

```typescript
import { IttybitClient } from "@ittybit/sdk";

const ittybit = new IttybitClient({
  apiKey: process.env.ITTYBIT_API_KEY!
});

const task = await ittybit.tasks.create({
  kind: "description",
  url: "https://example.com/photo.jpg",
  description: "Generate title and tags for an image",
  webhook_url: "https://your-app.com/description-webhook"
});

console.log("Task created:", task.id);
console.log("Status:", task.status);
```

--------------------------------

### Resize Image to Specific Width

Source: https://ittybit.com/docs/image

Demonstrates resizing an image to a specified width while maintaining the original aspect ratio. The height is automatically calculated. This example sets the width to 1200 pixels.

```javascript
const options = {
  url: 'https://example.com/image.jpg',
  kind: 'image',
  width: 1200,
}
const task = await ittybit.tasks.create(options)
```

--------------------------------

### Create a New Media Processing Task (TypeScript)

Source: https://ittybit.com/docs/about

This snippet demonstrates how to create a new media processing task using the Ittybit API. It requires a valid media URL, the type of task (e.g., 'speech'), and optional parameters like 'speakers'. The request is sent as a POST request to the '/tasks' endpoint with an Authorization header.

```typescript
const task = {
  url: 'https://your.storage.bucket/video.mp4',
  kind: 'speech',
  speakers: true,
};

const response = await fetch('https://api.ittybit.com/tasks', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer ITTYBIT_API_KEY' },
  body: JSON.stringify(task)
});
```

--------------------------------

### File Status Property Example

Source: https://ittybit.com/docs/files

The 'status' property indicates the current state of the file. Possible values include 'waiting', 'processing', 'ready', and 'failed'. Only files with a 'ready' status are publicly accessible.

```json
{
  "id": "file_abcdefgh1234",
  "status": "ready"
}
```
Tokens:
Raw