Source: https://docs.sogni.ai/sogni-intelligence/media-upload-urls/

# Media Upload URLs

Durable chat runs and creative-agent workflows need HTTP(S) media URLs when the backend must retrieve user-supplied images, video, or audio after the initial request. Use the upload URL helpers when your app has a local file and needs a Sogni-hosted presigned download URL to pass through `media_references`, `media_context`, workflow dependencies, or hosted tool arguments.

Use the `v1` upload endpoints. Each returns a signed `PUT` URL: send the file bytes to it with the `Content-Type` you requested. The `v2` upload endpoints, which return an HTML form `POST` policy instead, still work but are legacy.

## [#](https://docs.sogni.ai/sogni-intelligence/media-upload-urls/#endpoints)Endpoints

| Endpoint | Method | Use |
| --- | --- | --- |
| `/v1/image/uploadUrl` | `GET` | Create a signed `PUT` URL for an image reference. |
| `/v1/image/downloadUrl` | `GET` | Create a signed download URL for an uploaded image reference. |
| `/v1/media/uploadUrl` | `GET` | Create a signed `PUT` URL for an audio or video reference. |
| `/v1/media/downloadUrl` | `GET` | Create a signed download URL for an uploaded audio or video reference. |
| `/v2/image/uploadUrl` | `GET` | Legacy: form `POST` policy for an image upload, 100 MB limit. |
| `/v2/media/uploadUrl` | `GET` | Legacy: form `POST` policy for an audio or video upload, 100 MB limit. |
| `/v2/image/downloadUrl`, `/v2/media/downloadUrl` | `GET` | Same as the `v1` download endpoints. |

All public upload URL routes require authentication. Send parameters as query string values. The API accepts a JSON body too, but query strings are easier to use with `GET`.

## [#](https://docs.sogni.ai/sogni-intelligence/media-upload-urls/#link-lifetime)Link Lifetime

Upload and download links last 48 hours, and Sogni keeps uploaded and generated media for about two days. Request a fresh download URL when one expires, and copy anything you want to keep to your own storage.

Treat every link as opaque. Use `uploadUrl` and `downloadUrl` exactly as returned: don't parse, rebuild, or allowlist the host, and don't strip the query string. The signature lives in the query string, storage refuses unsigned requests, and the storage host behind these links can change without notice.

## [#](https://docs.sogni.ai/sogni-intelligence/media-upload-urls/#image-references)Image References

Use `/v1/image/uploadUrl` for image files used as starting images, ControlNet inputs, image-edit context images, first/last video frames, or general references.

| Query field | Use |
| --- | --- |
| `jobId` | Caller-chosen stable upload group ID. Use the same value for upload and download. |
| `type` | Image asset type. For agent references use `startingImage`, `cnImage`, `contextImage1` through `contextImage16`, `referenceImage`, or `referenceImageEnd`. |
| `contentType` | Image MIME type: `image/png`, `image/jpeg`, `image/jpg`, `image/webp`, or `image/gif`. Defaults to `image/png`. Send the same value as the upload's `Content-Type` header. |
| `imageId` | Required only for worker output types such as `complete` or `preview`; not required for the agent reference types above. |

```
curl "https://api.sogni.ai/v1/image/uploadUrl?jobId=agent-upload-001&type=referenceImage&contentType=image/png" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Representative response:

```
{
  "status": "success",
  "data": {
    "uploadUrl": "https://..."
  }
}
```

`PUT` the raw file bytes to `data.uploadUrl` with the same `Content-Type`:

```
curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: image/png" \
  --data-binary @reference.png
```

Then request a download URL for the same `jobId` and `type`:

```
curl "https://api.sogni.ai/v1/image/downloadUrl?jobId=agent-upload-001&type=referenceImage&contentType=image/png" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Use `data.downloadUrl` in Sogni Intelligence requests.

## [#](https://docs.sogni.ai/sogni-intelligence/media-upload-urls/#audio-and-video-references)Audio And Video References

Use `/v1/media/uploadUrl` for audio and video files.

| Query field | Use |
| --- | --- |
| `jobId` | Caller-chosen stable upload group ID. Use the same value for upload and download. |
| `type` | For agent references use `referenceAudio` or `referenceVideo`. |
| `contentType` | MIME type. Video: `video/mp4`, `video/quicktime`, or `video/webm`. Audio: `audio/mp4`, `audio/mpeg`, `audio/flac`, `audio/wav`, `audio/x-wav`, or `audio/wave`. Send the same value as the upload's `Content-Type` header. |
| `id` | Required only for worker output types such as `complete` or `preview`; not required for `referenceAudio` or `referenceVideo`. |

```
curl "https://api.sogni.ai/v1/media/uploadUrl?jobId=agent-upload-002&type=referenceAudio&contentType=audio/mpeg" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: audio/mpeg" \
  --data-binary @reference.mp3
```

After the upload, create a download URL:

```
curl "https://api.sogni.ai/v1/media/downloadUrl?jobId=agent-upload-002&type=referenceAudio&contentType=audio/mpeg" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## [#](https://docs.sogni.ai/sogni-intelligence/media-upload-urls/#legacy-form-uploads)Legacy Form Uploads

`/v2/image/uploadUrl` and `/v2/media/uploadUrl` take the same query fields and return `data.url`, `data.fields`, `data.maxSizeBytes` (100 MB), and `data.allowedContentTypes`. Post the file as `multipart/form-data` to `data.url` with every `fields` entry unchanged and the file part last; the form expires after one hour. Existing integrations keep working, but new code should use the `v1` `PUT` flow above. See [Media and Image URLs](https://docs.sogni.ai/api-reference/media/#form-uploads) for the full response.

## [#](https://docs.sogni.ai/sogni-intelligence/media-upload-urls/#use-uploaded-urls)Use Uploaded URLs

For `/v1/chat/runs`, pass uploaded URLs in `media_references`, `media_context`, or OpenAI-style message content:

```
{
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "Animate this image with the uploaded audio." },
        { "type": "image_url", "image_url": { "url": "https://...download-url..." } }
      ]
    }
  ],
  "media_references": [
    { "kind": "audio", "url": "https://...download-url..." }
  ]
}
```

For `/v1/creative-agent/workflows`, pass uploaded URLs in `media_references` and bind them with negative media indices or `$input_media` dependencies. See [Creative-Agent Workflows](https://docs.sogni.ai/sogni-intelligence/creative-agent-workflows/) for step examples.