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.

#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.

#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 "[email protected];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.

#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"

#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 for step examples.