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.

Prefer the `v2` upload endpoints. They return a presigned POST form with a 100 MB file-size limit and allowed MIME types. The older `v1` endpoints return a presigned PUT URL.

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

| Endpoint | Method | Use |
| --- | --- | --- |
| `/v2/image/uploadUrl` | `GET` | Create a presigned POST for image reference upload. |
| `/v2/image/downloadUrl` | `GET` | Create a presigned download URL for an uploaded image reference. |
| `/v2/media/uploadUrl` | `GET` | Create a presigned POST for audio or video reference upload. |
| `/v2/media/downloadUrl` | `GET` | Create a presigned download URL for an uploaded audio or video reference. |
| `/v1/image/uploadUrl` | `GET` | Legacy presigned PUT image upload URL. |
| `/v1/image/downloadUrl` | `GET` | Legacy image download URL. |
| `/v1/media/uploadUrl` | `GET` | Legacy presigned PUT media upload URL. |
| `/v1/media/downloadUrl` | `GET` | Legacy media download URL. |

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/#image-references)Image References

Use `/v2/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` | Optional image MIME type. Allowed values are `image/png`, `image/jpeg`, `image/jpg`, `image/webp`, and `image/gif`. |
| `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/v2/image/uploadUrl?jobId=agent-upload-001&type=referenceImage&contentType=image/png" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Representative response:

```
{
  "status": "success",
  "data": {
    "url": "https://...",
    "fields": {
      "Content-Type": "image/png",
      "key": "..."
    },
    "maxSizeBytes": 104857600,
    "allowedContentTypes": ["image/png", "image/jpeg", "image/jpg", "image/webp", "image/gif"]
  }
}
```

Upload the file as `multipart/form-data` to `data.url` with every returned `fields` entry plus the file part:

```
curl -X POST "$UPLOAD_URL" \
  -F "key=$KEY" \
  -F "Content-Type=image/png" \
  -F "policy=$POLICY" \
  -F "x-amz-algorithm=$ALGORITHM" \
  -F "x-amz-credential=$CREDENTIAL" \
  -F "x-amz-date=$DATE" \
  -F "x-amz-signature=$SIGNATURE" \
  -F "file=@reference.png;type=image/png"
```

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

```
curl "https://api.sogni.ai/v2/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 `/v2/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` | Optional MIME type. Video allows `video/mp4`, `video/quicktime`, and `video/webm`. Audio allows `audio/mp4`, `audio/mpeg`, `audio/flac`, `audio/wav`, `audio/x-wav`, and `audio/wave`. |
| `id` | Required only for worker output types such as `complete` or `preview`; not required for `referenceAudio` or `referenceVideo`. |

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

After uploading the file to the returned POST form URL, create a download URL:

```
curl "https://api.sogni.ai/v2/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/#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.