Docs / Core Concepts / Upload Files

Upload Files

Reference media in video tasks is passed by URL. If your source file is local, upload it first: POST /v1/files returns a hosted URL you can drop into metadata.content[]. Files already on a public URL can be used directly without uploading.

#Endpoint

POST/v1/files

Send the file as multipart/form-data with the field name file.

#cURL

terminalbash

curl https://relaydance.com/v1/files \
  -H "Authorization: Bearer $RELAYDANCE_API_KEY" \
  -F "file=@image.png"

#Python

upload.pypython

import requests, os

response = requests.post(
    "https://relaydance.com/v1/files",
    headers={"Authorization": f"Bearer {os.environ['RELAYDANCE_API_KEY']}"},
    files={"file": open("photo.jpg", "rb")},
)
result = response.json()
print(result["id"], result["url"])

#Node.js

upload.tstypescript

import { readFileSync } from "fs";

const file = new Blob([readFileSync("photo.jpg")], { type: "image/jpeg" });
const form = new FormData();
form.append("file", file, "photo.jpg");

const res = await fetch("https://relaydance.com/v1/files", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.RELAYDANCE_API_KEY}` },
  body: form,
});
const { id, url } = await res.json();
console.log(id, url);

#Response

response.jsonjson

{
  "id": "file_abc123",
  "url": "https://..."
}

#Using the URL in a video task

Put the returned url into a metadata.content[] entry and cite it in the prompt as @image1:

img2video.pypython

import requests, os

HEADERS = {"Authorization": f"Bearer {os.environ['RELAYDANCE_API_KEY']}"}

# 1) Upload the source image
upload = requests.post(
    "https://relaydance.com/v1/files",
    headers=HEADERS,
    files={"file": open("product.jpg", "rb")},
)
image_url = upload.json()["url"]

# 2) Submit the video task with the image as a reference
resp = requests.post(
    "https://relaydance.com/v1/video/generations",
    headers={**HEADERS, "Content-Type": "application/json"},
    json={
        "model": "seedance-1-5-pro-with-audio",
        "prompt": "@image1 rotates slowly on a marble pedestal, studio lighting",
        "seconds": "5",
        "metadata": {
            "ratio": "16:9",
            "resolution": "720p",
            "content": [
                {
                    "type": "image_url",
                    "image_url": {"url": image_url},
                    "role": "reference_image",
                }
            ],
        },
    },
)
print(resp.json()["task_id"])

See Video Generation for the content[] schema and limits (up to 9 reference images, 3 videos, 3 audio tracks), and Image-to-Video for the end-to-end example.

←How It Works Image-to-Video→