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.

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

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

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

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.

#Audio And Video References

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

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"

#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 for the full response.

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