> For the complete documentation index, see [llms.txt](https://bountyv.gitbook.io/vdocs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://bountyv.gitbook.io/vdocs/uploading-files.md).

# Uploading Files

Several endpoints accept binary uploads via `multipart/form-data` — an identity photo, a source image to transform, or a reference video by URL. This page explains each input and how to send it.

Endpoints that take **no** uploads (like [Text-to-Image](/vdocs/image-api/images-txt2img.md), which is pure JSON) are not covered here.

## Identity photo (`face`)

Used by [Reel Recreate](/vdocs/video-api/videos-generate.md) (`POST /api/v1/videos/generate`) and [Create a Soul](/vdocs/soul-api/identities-create.md) (`POST /api/v1/identities/create`). This is the photo of the person you want rendered into the output.

### Requirements

* **Format:** JPEG, PNG, or WebP
* **Minimum size:** 512×512 pixels (larger is better)
* **Face clearly visible:** front-facing, eyes open, no sunglasses
* **Lighting:** even, well-lit — avoid heavy shadows across the face
* **One person:** if the photo has multiple people, only the largest/centered face is used
* **Max file size:** 10 MB

### What makes a good identity photo

| Do                      | Don't                            |
| ----------------------- | -------------------------------- |
| Front-facing headshot   | Side profile or heavy angle      |
| Neutral or slight smile | Exaggerated expression           |
| Even lighting           | Backlit / harsh shadows          |
| Clean background        | Busy background with other faces |
| High resolution         | Blurry or low-res crops          |

## Source image (`image`)

Used by the image-transform endpoints — [Image Edit](/vdocs/image-api/images-edit.md), [Image-to-Image / Inpaint](/vdocs/image-api/images-i2i.md), and [Image-to-Video](/vdocs/image-api/images-img2video.md). This is the picture you want to change, re-render, or animate. Each of those endpoints also takes a text `prompt` describing the change.

### Requirements

* **Format:** JPEG, PNG, or WebP
* **Any size:** no minimum — higher resolution yields higher-quality output
* **Max file size:** 10 MB
* **Optional mask** (`mask`, Image-to-Image only): a same-size image where white marks the region to repaint. See [Image-to-Image / Inpaint](/vdocs/image-api/images-i2i.md).

## Reference video (`reference_video_url`)

Used by [Reel Recreate](/vdocs/video-api/videos-generate.md). URL only — no file upload. Video generation takes a public URL to an existing reel, which keeps requests fast and lets you reference social content directly.

### Supported sources

* TikTok (`https://www.tiktok.com/@user/video/...`)
* Instagram Reels (`https://www.instagram.com/reel/...`)
* YouTube Shorts (`https://www.youtube.com/shorts/...`)
* Direct MP4 URLs (your own CDN, S3, etc.)

### Requirements

* **Must be publicly accessible** — login-gated or private URLs fail
* **Recommended:** clear single-subject reels work best

### Hosting your own videos

If your reference isn't on a social platform, upload it somewhere public first (AWS S3 with public-read, Cloudflare R2, any static host) and pass the raw MP4 URL as `reference_video_url`.

## How to send files (`multipart/form-data`)

File uploads use `multipart/form-data` encoding. Most HTTP clients set this automatically when you use the right API.

### cURL

```bash
curl -X POST https://substance-api.com/api/v1/images/edit \
  -H "Authorization: Bearer sk_live_..." \
  -F "image=@/path/to/photo.jpg" \
  -F "prompt=change the jacket to red leather"
```

The `-F` flag with an `@` prefix uploads a file; plain `-F key=value` sends a text field in the same request.

### Python (requests)

```python
with open("photo.jpg", "rb") as image:
    r = requests.post(
        "https://substance-api.com/api/v1/images/edit",
        headers={"Authorization": f"Bearer {API_KEY}"},
        files={"image": image},
        data={"prompt": "change the jacket to red leather"},
    )
```

`files=` sets the correct `Content-Type` and encoding automatically; `data=` carries the text fields.

### Node.js (fetch / FormData)

```javascript
import { readFileSync } from "node:fs";

const form = new FormData();
form.append("image", new Blob([readFileSync("photo.jpg")]), "photo.jpg");
form.append("prompt", "change the jacket to red leather");

const r = await fetch("https://substance-api.com/api/v1/images/edit", {
  method: "POST",
  headers: { Authorization: `Bearer ${API_KEY}` },
  body: form,
});
```

**Do not** manually set `Content-Type` — the `FormData` object sets it with the correct boundary automatically.

### Mixing a file and text fields (video endpoint)

[Reel Recreate](/vdocs/video-api/videos-generate.md) accepts a file (`face`) and text fields (`reference_video_url`, `quality`, etc.) in the same multipart request:

```bash
curl -X POST https://substance-api.com/api/v1/videos/generate \
  -H "Authorization: Bearer sk_live_..." \
  -F "face=@face.jpg" \
  -F "reference_video_url=https://www.tiktok.com/@user/video/12345" \
  -F "quality=pro" \
  -F "add_captions=true"
```

## Storing uploaded files

Your files are held only as long as needed to produce the output:

* **Image uploads:** discarded after the response returns
* **Video face uploads:** kept temporarily so the async pipeline can access them; purged after the job completes or fails

We do not retain your inputs beyond this processing window.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://bountyv.gitbook.io/vdocs/uploading-files.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.