> ## Documentation Index
> Fetch the complete documentation index at: https://docs.domoai.app/llms.txt
> Use this file to discover all available pages before exploring further.

# File Uploads

> Upload large files using presigned URLs and domoai_uri

## Overview

For files that exceed the Base64 size limits or when you need better upload performance, DomoAI provides a file upload API. This allows you to:

* Upload files up to **80 MB**
* Reuse uploaded files across multiple API calls
* Reduce request payload size for better performance

## How It Works

The upload process uses **presigned URLs** - a secure, two-step upload flow:

<Steps>
  <Step title="Request Upload URL">
    Call `POST /v1/upload/file` with your filename to get a presigned URL and `domoai_uri`.
  </Step>

  <Step title="Upload File">
    Upload your file directly to the presigned URL using a `PUT` request with the provided headers.
  </Step>

  <Step title="Use domoai_uri">
    Use the `domoai_uri` in subsequent API calls (e.g., Talking Avatar, Image to Video) instead of Base64 data.
  </Step>
</Steps>

## Supported File Types

| Category   | Formats               | Use Cases                                         |
| ---------- | --------------------- | ------------------------------------------------- |
| **Images** | JPEG, PNG, WebP, AVIF | Image to Video, Template to Video, Talking Avatar |
| **Audio**  | MP3, WAV, M4A, AAC    | Talking Avatar                                    |
| **Video**  | MP4, WebM, MOV        | Talking Avatar, Video to Video                    |

## Step 1: Request Upload URL

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.domoai.com/v1/upload/file" \
    -H "Authorization: Bearer <YOUR_API_KEY>" \
    -H "Content-Type: application/json" \
    -d '{
      "filename": "audio.mp3"
    }'
  ```

  ```javascript JavaScript/Node.js theme={null}
  const response = await fetch('https://api.domoai.com/v1/upload/file', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer <YOUR_API_KEY>',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      filename: 'audio.mp3'
    })
  });

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import httpx

  response = httpx.post(
      'https://api.domoai.com/v1/upload/file',
      headers={
          'Authorization': 'Bearer <YOUR_API_KEY>',
          'Content-Type': 'application/json'
      },
      json={
          'filename': 'audio.mp3'
      }
  )

  data = response.json()
  print(data)
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "code": 0,
  "message": "success",
  "data": {
    "presigned_url": "https://storage.example.com/upload/...",
    "headers": {
      "Content-Type": "audio/mpeg",
      "x-amz-acl": "private"
    },
    "domoai_uri": "domoai://eyJhbGciOiJIUzI1NiIs..."
  }
}
```

| Field           | Description                                       |
| --------------- | ------------------------------------------------- |
| `presigned_url` | The URL to upload your file to                    |
| `headers`       | Required headers for the upload request           |
| `domoai_uri`    | Token to reference the uploaded file in API calls |

## Step 2: Upload File to Presigned URL

Use the `presigned_url` and `headers` from the previous response to upload your file:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PUT "<PRESIGNED_URL>" \
    -H "Content-Type: audio/mpeg" \
    -H "x-amz-acl: private" \
    --data-binary @audio.mp3
  ```

  ```javascript JavaScript/Node.js theme={null}
  const fs = require('fs');

  const fileBuffer = fs.readFileSync('audio.mp3');

  const uploadResponse = await fetch(data.data.presigned_url, {
    method: 'PUT',
    headers: data.data.headers,
    body: fileBuffer
  });

  if (uploadResponse.ok) {
    console.log('Upload successful!');
    console.log('domoai_uri:', data.data.domoai_uri);
  }
  ```

  ```python Python theme={null}
  with open('audio.mp3', 'rb') as f:
      file_content = f.read()

  upload_response = httpx.put(
      data['data']['presigned_url'],
      headers=data['data']['headers'],
      content=file_content
  )

  if upload_response.status_code == 200:
      print('Upload successful!')
      print('domoai_uri:', data['data']['domoai_uri'])
  ```
</CodeGroup>

## Step 3: Use domoai\_uri in API Calls

Once uploaded, use the `domoai_uri` in your API requests:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.domoai.com/v1/video/talking-avatar" \
    -H "Authorization: Bearer <YOUR_API_KEY>" \
    -H "Content-Type: application/json" \
    -d '{
      "image": {
        "domoai_uri": "domoai://eyJhbGciOiJIUzI1NiIs..."
      },
      "audio": {
        "domoai_uri": "domoai://eyJhbGciOiJIUzI1NiIs..."
      },
      "seconds": 10
    }'
  ```

  ```javascript JavaScript/Node.js theme={null}
  const response = await fetch('https://api.domoai.com/v1/video/talking-avatar', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer <YOUR_API_KEY>',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      image: {
        domoai_uri: 'domoai://eyJhbGciOiJIUzI1NiIs...'
      },
      audio: {
        domoai_uri: 'domoai://eyJhbGciOiJIUzI1NiIs...'
      },
      seconds: 10
    })
  });
  ```

  ```python Python theme={null}
  response = httpx.post(
      'https://api.domoai.com/v1/video/talking-avatar',
      headers={
          'Authorization': 'Bearer <YOUR_API_KEY>',
          'Content-Type': 'application/json'
      },
      json={
          'image': {
              'domoai_uri': 'domoai://eyJhbGciOiJIUzI1NiIs...'
          },
          'audio': {
              'domoai_uri': 'domoai://eyJhbGciOiJIUzI1NiIs...'
          },
          'seconds': 10
      }
  )
  ```
</CodeGroup>

## Limitations

| Limit                 | Value     |
| --------------------- | --------- |
| Maximum file size     | 80 MB     |
| Minimum file size     | 512 bytes |
| `domoai_uri` validity | 24 hours  |

<Warning>
  `domoai_uri` tokens expire after 24 hours. If you need to use the same file after expiration, you must upload it again.
</Warning>

## Input Format Reference

All media inputs support two methods:

```json theme={null}
{
  "image": {
    "domoai_uri": "domoai://eyJhbGci...",      // Uploaded file reference
    "bytes_base64_encoded": "iVBORw0KGgo..."   // Base64 encoded data
  }
}
```

<Note>
  You only need to provide **one** of these fields. If multiple are provided, `domoai_uri` takes priority, followed by `bytes_base64_encoded`.
</Note>

## Next Steps

<CardGroup cols={2}>
  <Card title="Talking Avatar API" icon="user" href="/api-reference/ai-video/talking-avatar">
    Create Talking Avatars from Audio, Images, or Videos
  </Card>

  <Card title="Upload API Reference" icon="upload" href="/api-reference/upload/upload-file">
    View the complete Upload API specification
  </Card>
</CardGroup>