API ReferenceMedia and Image URLs

Media and Image URLs

Surface · Asset transport

#Media Upload URLs

Presigned S3-style URLs for uploading reference media (audio, video) and downloading generated artifacts. The latest revision returns a presigned POST with form fields and a server-enforced max file size, replacing the previous PUT-style flow.

GET /v2/media/uploadUrl Auth required

Request a presigned POST URL plus form fields for uploading a single media object up to maxSizeBytes.

#Query parameters

Name	Type	In	Description
type*	string	query	Asset type. Artist-side: `referenceAudio`, `referenceVideo`. Worker-side: `complete`, `preview`.
jobId*	string	query	Job identifier the asset belongs to.
id	string	query	Artifact identifier. Required for worker uploads; omit for artist pre-uploads.
contentType	string	query	Optional MIME type. Pinned so downloads sign the same S3 object key.

#Response

{
  "status": "success",
  "data": {
    "url": "https://sogni-uploads.s3-accelerate.amazonaws.com/",
    "fields": {
      "Content-Type": "video/mp4",
      "bucket": "sogni-uploads",
      "key": "video/2026-05-18/<jobId>/reference.mp4",
      "X-Amz-Algorithm": "AWS4-HMAC-SHA256",
      "X-Amz-Credential": "…",
      "X-Amz-Date": "…",
      "Policy": "<base64-encoded-policy>",
      "X-Amz-Signature": "<hex-signature>"
    },
    "maxSizeBytes": 104857600,
    "allowedContentTypes": [ /* see below — varies by `type` */ ]
  }
}

allowedContentTypes depends on the asset type:

Video uploads (e.g. referenceVideo): video/mp4, video/quicktime, video/webm
Audio uploads (e.g. referenceAudio): audio/mp4, audio/mpeg, audio/flac, audio/wav, audio/x-wav, audio/wave
Preview frames: image/jpeg, image/jpg, image/png, image/webp

How to upload. POST to url as multipart/form-data, including every key/value from fields, then your file field last. The server returns 204 on success.

GET /v2/media/downloadUrl Auth required

Get a presigned download URL for a previously uploaded asset or a completed job artifact.

#Query parameters

Name	Type	In	Description
type*	string	query	Asset type — same values as upload.
jobId*	string	query	Job identifier.
id	string	query	Artifact id.
contentType	string	query	Optional MIME hint. The server uses the stored upload contentType when available.

#Response

{
  "status": "success",
  "data": { "downloadUrl": "https://s3.amazonaws.com/sogni-…" }
}

Surface · Asset transport

#Image Upload URLs

Image-specific counterpart to the media endpoints. Same presigned-POST flow with image-aware validation and content-type pinning.

GET /v2/image/uploadUrl Auth required

Presigned POST URL plus form fields for image uploads (PNG, JPEG, WEBP, GIF).

#Query parameters

Name	Type	In	Description
type*	string	query	Asset type. Artist-side: `startingImage`, `referenceImage`, `referenceImageEnd`, `contextImage*`. Worker-side: `complete`, `preview`.
jobId*	string	query	Job identifier.
imageId	string	query	Artifact id. Required for worker uploads.
contentType	string	query	Optional MIME type — pinned for download.
startContentType	string	query	Optional content type for the starting image (used by paired image+ref flows).

#Response

{
  "status": "success",
  "data": {
    "url": "https://sogni-uploads.s3-accelerate.amazonaws.com/",
    "fields": {
      "Content-Type": "image/png",
      "bucket": "sogni-uploads",
      "key": "2026-05-18/<jobId>/startingImage.png",
      "X-Amz-Algorithm": "AWS4-HMAC-SHA256",
      "X-Amz-Credential": "…",
      "X-Amz-Date": "…",
      "Policy": "<base64-encoded-policy>",
      "X-Amz-Signature": "<hex-signature>"
    },
    "maxSizeBytes": 104857600,
    "allowedContentTypes": ["image/png", "image/jpeg", "image/jpg", "image/webp", "image/gif"]
  }
}

GET /v2/image/downloadUrl Auth required

Get a presigned download URL for an image artifact.

#Response

{
  "status": "success",
  "data": {
    "downloadUrl": "https://s3.amazonaws.com/sogni-…"
  }
}