File Uploads - Reactor

Some models accept file inputs alongside regular parameters. The SDK handles file uploads in two steps: upload the file to get a reference, then pass that reference into a command.

Upload the file with uploadFile() to get a FileRef.
Pass the FileRef into sendCommand() as a regular parameter.

Uploading a file

Call uploadFile() with a File or Blob. It returns a FileRef you can pass into sendCommand(), alongside regular arguments. The example below uses Helios’s set_image command. The commands and file parameters a model accepts vary by model, so check your model’s reference for what it expects.

File upload flow: your app calls uploadFile() to get a presigned PUT URL and a FileRef from Reactor, PUTs the file bytes directly to object storage, then sends the FileRef in a command to the model, which fetches the bytes from storage itself.

const input = document.querySelector("input[type=file]") as HTMLInputElement;
const file = input.files![0];

const ref = await reactor.uploadFile(file);
await reactor.sendCommand("set_image", { image: ref });

import { useReactor } from "@reactor-team/js-sdk";

function ImageUpload() {
  const { uploadFile, sendCommand, status } = useReactor((s) => s);

  const handleFile = async (e: React.ChangeEvent<HTMLInputElement>) => {
    const file = e.target.files?.[0];
    if (!file) return;

    const ref = await uploadFile(file);
    await sendCommand("set_image", { image: ref });
  };

  return (
    <input
      type="file"
      accept="image/*"
      disabled={status !== "ready"}
      onChange={handleFile}
    />
  );
}

ref = await reactor.upload_file("scene.jpg")
await reactor.send_command("set_image", {"image": ref})

uploadFile() / upload_file() can only be called when the connection status is "ready" — Python raises InvalidStateError otherwise, the same guard request_clip() uses. Upload URLs expire after 15 minutes. For more information, see Rate Limits.

The FileRef type

uploadFile() returns a FileRef with metadata about the uploaded file. You never construct one directly.

class FileRef {
  readonly uploadId: string;   // Upload identifier
  readonly name: string;       // Filename
  readonly mimeType: string;   // MIME type (e.g. "image/jpeg")
  readonly size: number;       // File size in bytes
}

@dataclass(frozen=True)
class FileRef:
    upload_id: str   # Upload identifier
    name: str        # Filename
    mime_type: str   # MIME type (e.g. "image/jpeg")
    size: int        # File size in bytes

Complete example

For a full image-to-video walkthrough that uploads a reference image and conditions the first frame on it, see Helios’s image-to-video example.

⌘I