# Ingest

[View original](https://ittybit.com/docs/ingest)

## How to ingest media

There are two options for ingesting media:

1. Create a new file from a URL (synchronous)
2. Create an ingest task (asynchronous)

***

## 1. Create a new file from a URL

If you need immediate access to the file for delivery, or to access the file's metadata, you can create a new file from a URL synchronously.

### Request

<Tabs groupId="language" items={["typescript", "python", "ruby", "php", "go", "fetch", "curl" ]} persist>
  <Tab value="typescript">
    ```js
    const ittybit = require('ittybit')({
      apiKey: 'ITTYBIT_API_KEY'
    })

    const file = await ittybit.files.create({ url: 'https://example.com/video.mp4' })
    ```
  </Tab>

  <Tab value="python">
    ```python
    import ittybit

    file = ittybit.files.create(url='https://example.com/video.mp4')
    ```
  </Tab>

  <Tab value="ruby">
    ```ruby
    require 'ittybit'

    file = Ittybit::File.create(url: 'https://example.com/video.mp4')
    ```
  </Tab>

  <Tab value="php">
    ```php
    use Ittybit\IttybitClient;

    $client = new IttybitClient(
        token: "ITTYBIT_API_KEY"
    );

    $file = $client->files->create([
        'url' => 'https://example.com/video.mp4'
    ]);
    ```
  </Tab>

  <Tab value="go">
    ```go
    package main

    import (
    	"context"
    	"github.com/ittybit/sdk-go/client"
    	"github.com/ittybit/sdk-go/option"
    )

    func main() {
    	c := client.NewClient(
    		option.WithToken("ITTYBIT_API_KEY"),
    	)
    	
    	file, err := c.Files.Create(
    		context.Background(),
    		&client.FileCreateParams{
    			URL: "https://example.com/video.mp4",
    		},
    	)
    	if err != nil {
    		// Handle error
    		return
    	}
    	
    	// Use the file
    	_ = file
    }
    ```
  </Tab>

  <Tab value="fetch">
    ```js
    const response = await fetch('https://api.ittybit.com/files', {
      method: 'POST',
      headers: { 'Authorization': 'Bearer ITTYBIT_API_KEY' },
      body: JSON.stringify({ 
        url: 'https://example.com/video.mp4' 
      })
    })
    ```
  </Tab>

  <Tab value="curl">
    ```bash
    curl -X POST https://api.ittybit.com/files \
    -H "Authorization: Bearer ITTYBIT_API_KEY" \
    -d '{"url": "https://example.com/video.mp4"}'
    ```
  </Tab>
</Tabs>

Ittybit's server will download the file from the URL, analyse it, and store it in your project.

### Response

A successful response will include a [File object](/docs/file).

```json title="POST /files"
// 201 Created
// Content-Type: application/json
{
  "meta": { 
    "id": "req_abcdefgh12345678",
    "type": "object",
  },
  "data": {
    "id": "file_abcdefgh1234",
    "kind": "video",
    "type": "video/mp4",
    "width": 1024,
    "height": 768,
    "duration": 120.5,
    "filesize": 123456,
    "url": "https://you.ittybit.net/file_abcdefgh1234",
    "created": "2025-01-01T01:23:45Z",
    "updated": "2025-01-01T01:23:45Z"
  },
  "links": {
    "self": "https://api.ittybit.com/files/file_abcdefgh1234"
  }
}
```

***

## 2. Create an ingest task

You can also create an ingest task to ingest a file asynchronously. This will start the ingestion process and return a `task_id` immediately, without waiting for the file to be ingested.

This is the better option if you need to ingest a large number of files without waiting for each file to complete before moving on, or if you are ingesting files in a cron job, scheduled batch, etc.

### Request

<Tabs groupId="language" items={["typescript", "python", "ruby", "php", "go", "fetch", "curl" ]} persist>
  <Tab value="typescript">
    ```js
    const ittybit = require('ittybit')({
      apiKey: 'ITTYBIT_API_KEY'
    })

    const task = await ittybit.tasks.create({
      kind: 'ingest',
      url: 'https://example.com/video.mp4'
    })
    ```
  </Tab>

  <Tab value="python">
    ```python
    import ittybit

    task = ittybit.tasks.create(
      kind='ingest',
      url='https://example.com/video.mp4'
    )
    ```
  </Tab>

  <Tab value="ruby">
    ```ruby
    require 'ittybit'

    task = Ittybit::Task.create(
      kind: 'ingest',
      url: 'https://example.com/video.mp4'
    )
    ```
  </Tab>

  <Tab value="php">
    ```php
    use Ittybit\IttybitClient;

    $client = new IttybitClient(
        token: "ITTYBIT_API_KEY"
    );

    $task = $client->tasks->create([
        'kind' => 'ingest',
        'url' => 'https://example.com/video.mp4'
    ]);
    ```
  </Tab>

  <Tab value="go">
    ```go
    package main

    import (
    	"context"
    	"github.com/ittybit/sdk-go/client"
    	"github.com/ittybit/sdk-go/option"
    )

    func main() {
    	c := client.NewClient(
    		option.WithToken("ITTYBIT_API_KEY"),
    	) 

    	task, err := c.Tasks.Create(
    		context.Background(),
    		&client.TaskCreateParams{
    			Kind: "ingest",
    			URL: "https://example.com/video.mp4",
    		},
    	) 
    	if err != nil {
    		// Handle error
    		return
    	}
    	
    	// Use the task
    	_ = task  
    ```
  </Tab>

  <Tab value="curl">
    ```bash
    curl -X POST https://api.ittybit.com/tasks \
    -H "Authorization: Bearer ITTYBIT_API_KEY" \
    -d '{
      "kind": "ingest",
      "url": "https://example.com/video.mp4"
    }'
    ```
  </Tab>

  <Tab value="fetch">
    ```js
    const response = await fetch('https://api.ittybit.com/tasks', {
      method: 'POST',
      headers: { 'Authorization': 'Bearer ITTYBIT_API_KEY' },
      body: JSON.stringify({ 
        kind: 'ingest', 
        url: 'https://example.com/video.mp4' 
      })
    })
    ```
  </Tab>
</Tabs>

### Response

A successful response will include a [Task object](/docs/task).

```json title="POST /tasks"
// 201 Created
// Content-Type: application/json  
{
  "meta": { 
    "id": "req_abcdefgh12345678",
    "type": "object",
  },
  "data": {
    "id": "task_abcdefgh1234",
    "kind": "ingest",
    // ... other props
    "status": "pending",
    "created": "2025-01-01T01:23:45Z",
    "updated": "2025-01-01T01:23:45Z"
  },  
  "links": {  
    "self": "https://api.ittybit.com/tasks/task_abcdefgh1234"
  }
}
```

The file will be ingested in the background and you can either poll the task occasionally for updates, or set up a webhook to notify you when the file is ready.

### Poll for updates

<Tabs groupId="language" items={["typescript", "python", "ruby", "php", "go", "fetch", "curl" ]} persist>
  <Tab value="typescript">
    ```js
    const ittybit = require('ittybit')({
      apiKey: 'ITTYBIT_API_KEY'
    })

    const task = await ittybit.tasks.get('task_abcdefgh1234')
    ```
  </Tab>

  <Tab value="python">
    ```python
    import ittybit

    task = ittybit.tasks.get('task_abcdefgh1234')
    ```
  </Tab>

  <Tab value="ruby">
    ```ruby
    require 'ittybit'

    task = Ittybit::Task.get('task_abcdefgh1234')
    ```
  </Tab>

  <Tab value="php">
    ```php
    use Ittybit\IttybitClient;

    $client = new IttybitClient(
        token: "ITTYBIT_API_KEY"
    );

    $task = $client->tasks->get('task_abcdefgh1234');
    ```
  </Tab>

  <Tab value="go">
    ```go
    package main

    import (
    	"context"
    	"github.com/ittybit/sdk-go/client"
    	"github.com/ittybit/sdk-go/option"
    )

    func main() {
    	c := client.NewClient(
    		option.WithToken("ITTYBIT_API_KEY"),
    	) 

    	task, err := c.Tasks.Get(
    		context.Background(),
    		'task_abcdefgh1234',
    	) 
    	if err != nil {
    		// Handle error
    		return
    	}
    	
    	// Use the task
    	_ = task
    }
    ```
  </Tab>

  <Tab value="curl">
    ```bash
    curl https://api.ittybit.com/tasks/task_abcdefgh1234 \
    -H "Authorization: Bearer ITTYBIT_API_KEY"
    ```
  </Tab>

  <Tab value="fetch">
    ```js
    const response = await fetch('https://api.ittybit.com/tasks/task_abcdefgh1234', {
      headers: { 'Authorization': 'Bearer ITTYBIT_API_KEY' },
    })
    ```
  </Tab>
</Tabs>

When the task is complete, the task object will contain an `output` object with the file data.

```json title="GET /tasks/:id"
// 200 OK
// Content-Type: application/json
{
  "meta": { 
    "id": "req_abcdefgh56789012",
    "type": "object",
  },
  "data": {
    "id": "task_abcdefgh1234",
    "kind": "ingest",
    // ... other props
    "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",
    }
  }
}
```

***

## Additional props

Both [File](/api/files) and [Task](/api/tasks) approaches support additional properties, which can be included in the request's JSON body.

For example, you might set a specific `folder` or `filename` for the ingested file.

<Tabs items={["Files", "Tasks"]}>
  <Tab value="Files">
    ```json
    {
      "url": "https://example.com/video.mp4",
      "folder": "user_1234/uploads",
      "filename": "custom-filename.mp4"
    }
    ```
  </Tab>

  <Tab value="Tasks">
    ```json
    {
      "kind": "ingest",
      "url": "https://example.com/video.mp4",
      "folder": "user_1234/uploads",
      "filename": "custom-filename.mp4"
    }
    ```
  </Tab>
</Tabs>

<Cards>
  <Card title="Files API Reference" href="/api/files" icon={<Icon icon="files" className="w-6 h-6 text-brand-pink"/>} />

  <Card title="Tasks API Reference" href="/api/tasks" icon={<Icon icon="tasks" className="w-6 h-6 text-brand-green"/>} />
</Cards>

***

## Signed URLs

The examples above show a URL that is publicly accessible. If you need to ingest a file from a URL that is not publicly accessible, you can provide a signed URL to the API.

```js
url: "https://example.com/video.mp4?signature=s0Mes3cR3tS1gN4tUr3"
```