Uploads and references

Models take input media through references. Each reference has a role, which says how the model uses it, and either an upload_id or a public url:

"references": [
  { "role": "first_frame", "upload_id": "upl_01jbx9w6k3f8..." },
  { "role": "reference_image", "url": "https://example.com/style.jpg" }
]

Each model accepts some roles, with a maximum count per role, listed on its model page. A role the model doesn't accept is rejected with invalid_parameters. When you leave out mode, it's inferred from the roles.

Uploading a fileCopy Anchor Link

Uploading is two steps: create an upload, which returns a signed URL, then PUT the bytes to that URL with the same Content-Type. The SDKs do both:

import { readFile } from "node:fs/promises";
import { RawFrame } from "@rawframe/sdk";

const rf = new RawFrame();

// Upload the first frame. Uploads are kept for 7 days and can be reused.
const frame = await rf.uploads.upload(await readFile("first-frame.png"), { contentType: "image/png" });

const video = await rf.generations.createAndWait({
  model: "bytedance/seedance-2.5",
  prompt: "The camera slowly pulls back as the scene comes to life",
  references: [{ role: "first_frame", upload_id: frame.id }],
  params: { duration_seconds: 5 },
});
console.log(video.mode, video.outputs?.[0]?.url);

• Accepted types: image/png, image/jpeg, image/webp, video/mp4, video/quicktime, audio/mpeg, audio/wav. Up to 200 MB.
• size_bytes must be the exact size. If the uploaded file is a different size, the upload becomes rejected. sha256 is optional.
• The upload_url works for 15 minutes and needs no API key. Don't send your key to it.
• An upload is pending until its bytes arrive, then ready. Referencing a pending upload fails with upload_incomplete.
• Uploads are kept for 7 days (expires_at) and can be used by any number of generations until then. After that, references to them fail with upload_expired.

Referencing a URLCopy Anchor Link

A url reference must be public HTTPS. We fetch it once when the generation starts and keep our own copy, so the URL only needs to work for a few minutes. Private and internal addresses are refused. Use an upload for anything that isn't publicly reachable, or that you'll reuse.