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

# Create Media from URLs

> Create media records from files already uploaded to blob storage

## Endpoint

```
POST https://api.ugc.inc/media/create
```

## Overview

Create media records from file URLs. Use this after uploading files directly to blob storage via the presigned URL endpoint, or to reference media from external URLs.

The API will:

1. Determine the media type from the URL extension (video, image, or audio)
2. Create a database record pointing to the provided URL

<Note>
  This endpoint does NOT re-upload files. It creates database records that reference the provided URLs directly. Make sure your URLs are publicly accessible and permanent.
</Note>

## Request Body

<ParamField body="urls" type="string[]" required>
  Array of file URLs to create media from. Always provide as an array, even for single files.
</ParamField>

<ParamField body="names" type="string[]">
  Optional array of original filenames, parallel to the `urls` array. If not provided, filenames are extracted from the URLs.
</ParamField>

<ParamField body="previewUrls" type="(string | null)[]">
  Optional array of preview/thumbnail URLs, parallel to the `urls` array. Useful for providing video thumbnails.
</ParamField>

<ParamField body="tag" type="string">
  Optional tag to apply to all created media
</ParamField>

## Response

<ResponseField name="data" type="object">
  Upload result object

  <Expandable title="Response properties">
    <ResponseField name="data" type="UserMedia[]">
      Array of created media objects
    </ResponseField>

    <ResponseField name="failed" type="array">
      Array of failed uploads with error details

      <Expandable title="Failed item properties">
        <ResponseField name="name" type="string">
          File name that failed
        </ResponseField>

        <ResponseField name="error" type="string">
          Error message
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="message" type="string">
      Summary message
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.ugc.inc/media/create \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "urls": [
        "https://example.com/video1.mp4",
        "https://example.com/image1.jpg"
      ],
      "tag": "imported"
    }'
  ```

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

  response = requests.post(
      'https://api.ugc.inc/media/create',
      headers={
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json'
      },
      json={
          'urls': [
              'https://example.com/video1.mp4',
              'https://example.com/image1.jpg'
          ],
          'tag': 'imported'
      }
  )

  data = response.json()

  if data['ok']:
      result = data['data']
      print(f"Created {len(result['data'])} media files")
      
      if result.get('failed'):
          print(f"Failed: {len(result['failed'])} files")
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.ugc.inc/media/create', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      urls: [
        'https://example.com/video1.mp4',
        'https://example.com/image1.jpg'
      ],
      tag: 'imported'
    })
  });

  const data = await response.json();

  if (data.ok) {
    console.log('Created:', data.data.data.length, 'files');
    data.data.data.forEach(media => {
      console.log(`  ${media.name}: ${media.url}`);
    });
  }
  ```

  ```typescript React theme={null}
  import { UGCClient } from 'ugcinc';

  const client = new UGCClient({
    apiKey: 'YOUR_API_KEY'
  });

  // Create from single URL (still pass as array)
  const single = await client.media.create({
    urls: ['https://example.com/video.mp4'],
    tag: 'videos'
  });

  // Create from multiple URLs
  const multiple = await client.media.create({
    urls: [
      'https://example.com/video1.mp4',
      'https://example.com/video2.mp4',
      'https://example.com/image1.jpg'
    ],
    tag: 'batch-import'
  });

  if (multiple.ok) {
    console.log(`Created ${multiple.data.data.length} files`);
  }
  ```
</RequestExample>

<ResponseExample>
  ```json Success Response theme={null}
  {
    "ok": true,
    "code": 200,
    "data": {
      "data": [
        {
          "id": "media_abc123",
          "org_id": "org_xyz789",
          "name": "video1.mp4",
          "tag": "imported",
          "type": "video",
          "url": "https://api.ugc.inc/media/file/media_abc123",
          "created_at": "2024-01-15T10:30:00.000Z",
          "media_type": "user_media"
        },
        {
          "id": "media_def456",
          "org_id": "org_xyz789",
          "name": "image1.jpg",
          "tag": "imported",
          "type": "image",
          "url": "https://api.ugc.inc/media/file/media_def456",
          "created_at": "2024-01-15T10:30:01.000Z",
          "media_type": "user_media"
        }
      ],
      "message": "Created 2 media files"
    }
  }
  ```

  ```json Partial Success Response theme={null}
  {
    "ok": true,
    "code": 200,
    "data": {
      "data": [
        {
          "id": "media_abc123",
          "org_id": "org_xyz789",
          "name": "video1.mp4",
          "tag": "imported",
          "type": "video",
          "url": "https://api.ugc.inc/media/file/media_abc123",
          "created_at": "2024-01-15T10:30:00.000Z",
          "media_type": "user_media"
        }
      ],
      "failed": [
        {
          "name": "invalid-url",
          "error": "Failed to fetch file"
        }
      ],
      "message": "Created 1 media files, 1 failed"
    }
  }
  ```
</ResponseExample>