> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reactor.inc/llms.txt
> Use this file to discover all available pages before exploring further.

# File Uploads

> How to upload files and pass them to model commands

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.

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

***

## Uploading a file

Call `uploadFile()` with a `File` or `Blob`. It returns a [`FileRef`](/sdk-reference/types#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](/model-api-reference/overview) for what it expects.

<Frame>
  <img src="https://mintcdn.com/reactortechnologiesinc/oCeFlbp0H3XO2l0l/diagrams/file-upload-flow.svg?fit=max&auto=format&n=oCeFlbp0H3XO2l0l&q=85&s=82b20b926e024bec2c51f253d6155501" alt="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." width="982" height="224" data-path="diagrams/file-upload-flow.svg" />
</Frame>

<CodeGroup>
  ```typescript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
  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 });
  ```

  ```tsx React theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
  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}
      />
    );
  }
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
  ref = await reactor.upload_file("scene.jpg")
  await reactor.send_command("set_image", {"image": ref})
  ```
</CodeGroup>

<Note>
  `uploadFile()` can only be called when the connection status is `"ready"`. Upload URLs expire
  after 15 minutes. For more information, see [Rate Limits](/resources/rate-limits#file-uploads).
</Note>

***

## The FileRef type

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

<CodeGroup>
  ```typescript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
  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
  }
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
  @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
  ```
</CodeGroup>

***

## 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](/model-api-reference/helios/schema#complete-example-image-to-video).