# Media & files

Bring your own images, video and audio. Reuse the outputs.

Use media URLs directly in a run, or import media once and reuse its ID. The [model playground](/api/models) shows which inputs a model accepts, their limits and the exact request to send.

## Generate from an existing image

```bash
curl 'https://fusara.ai/api/v3/run' \
  -H "Authorization: Bearer $FUSARA_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "model": "krea2-edit",
  "prompt": "Replace the background with pale lavender. Keep the product unchanged.",
  "images": [
    {
      "url": "https://your-app.example/product.png"
    }
  ]
}'
```

Replace the example URL with your image. Use a public HTTP(S) URL that Fusara can download without your browser cookies. HTTPS is recommended. Both the original and encoded URL must fit within 2,048 characters. Credentials, fragments, nondefault ports and private network targets are rejected. A signed storage URL works while it remains valid.

Each source must contain exactly one of `url` or `media_id`. Do not put a base64 data URL, a local file path or raw file bytes in these fields. Keep input URLs valid long enough for Fusara to import them.

## Images, video and audio

| Input | Shape | When to use it |
| --- | --- | --- |
| `images` | Array of media sources. | Image editing or models that accept image references. |
| `videos` | Array of media sources. | Models that accept source video. |
| `audio` | Array of media sources. | Models that accept source audio. |
| Named reference fields | As specified by the model schema. | Style, character or other model-specific references. |

Input names, accepted media kinds and maximum counts depend on the model. Array order matters: preserve the order shown in the model request. A model that creates images does not necessarily accept image inputs.

Check `request_schema` from [Get a model](/api/reference/get-model), or configure the same inputs visually in its playground. Fields that are unsupported for a model are rejected rather than silently ignored.

## Formats and size limits

The URL importer recognizes these file formats:

| Media kind | Formats |
| --- | --- |
| Image | JPEG, PNG, WebP, GIF, BMP, TIFF, SVG. |
| Video | MP4, MOV, WebM, AVI. |
| Audio | MP3, WAV, AAC, FLAC, OGG. |

The downloaded bytes must be a recognizable media file. An HTML sign-in or preview page is not an image, even if its URL ends in `.png`. The import service's configured ceiling is **10 GiB per file**; this is not a promise that every model accepts a file that large. Model constraints and media preparation apply separately.

To inspect the existing profile rules, call `GET /models/krea2-edit?include=presentation` relative to `/api/v3`, or add `include=presentation` to the model you use:

| Returned field | What it describes |
| --- | --- |
| `request_schema` | Public request fields, required inputs, counts and conditional settings. |
| `presentation.capabilities.inputConstraints` | The same input rules used by Workspace. Each entry identifies an `inputKey`. |
| `mediaRequirements` within an input constraint | Applicable admission requirements, such as duration, aspect ratio or file size. |
| `mediaPreparation` within an input constraint | Formats, dimensions or byte limits Fusara prepares for the model. These are not automatically limits on your original upload. |
| `presentation.capabilities.inputModes` | Rules for the selected combination of inputs; conditional rules can narrow the applicable limits. |

For example, a preparation rule with `maxPreparedBytes` limits the **prepared file**, while a requirement with `maxFileSizeBytes` is an admission constraint. Fusara can resize or convert media where the profile allows it; do not infer that it will shorten a video or change its meaning. Missing limits are not a guarantee of unlimited input. The server applies the selected profile's rules to the actual media.

Presentation retains Workspace's field names; use `request_schema` for the names you send to the API. These rules are read from the published profile, not a separate per-model format list in this guide.

## Import once and reuse

```bash
curl 'https://fusara.ai/api/v3/media' \
  -H "Authorization: Bearer $FUSARA_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "url": "https://your-app.example/product.png"
}'
```

`POST /media` accepts JSON containing a URL. It is not a multipart upload endpoint. It requires your API key and returns a media descriptor with `type`, `media_id`, `url` and `url_expires_at`.

```json
{
  "type": "image",
  "media_id": 901,
  "url": "https://media.example/imported-image.png",
  "url_expires_at": "2026-10-25T12:00:00Z"
}
```

The values above are illustrative. Imported API media has a 24-hour lifetime; use the actual returned expiration. You can then reference the imported media in a run:

```bash
curl 'https://fusara.ai/api/v3/run' \
  -H "Authorization: Bearer $FUSARA_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "model": "krea2-edit",
  "prompt": "Add soft studio lighting.",
  "images": [
    {
      "media_id": 901
    }
  ]
}'
```

Use media owned by, or otherwise accessible to, the authenticated account. An ID is not a public access token. Expired or incompatible media must be replaced with an available source.

`410 media_expired` from a submission or authenticated estimate means a referenced input has expired. Use available media or import the original file again; retrying the expired reference cannot restore it. If a keyed submission was rejected, send the corrected body with a new `Idempotency-Key`: the old key remains bound to its original body even after rejection.

## Reuse a generated result

File outputs include `media_id`. Pass that ID to a compatible input of your next run, exactly as with imported media. This avoids downloading and uploading the same file through your application.

Some named reference inputs support an `artifact`, such as `original`, `first_frame` or `last_frame`. Use these only where the selected model's schema allows them; they are not universal media options.

## Masks and LoRAs

For a model that supports masks, the mask belongs to an image source. Supply one of `mask_url` or `mask_media_id` alongside that image's source. Use `mask_feather_px` only when the model exposes it. Mask support, dimensions and count are model-specific.

Models with a `loras` field accept entries with one of `model_id` or `url`, plus the supported `strength` setting. A LoRA model ID is different from a media ID. Check the model's schema for compatible resources, count and strength limits. LoRA training is not part of API v3.

## Save your outputs

Download result files before `url_expires_at` if your application needs long-term storage. Store them in your own storage and retain the run ID for tracing. A run record can remain available after its media expires; its descriptor can then say `expired: true` without a download URL.

API-generated files also use a 24-hour retention deadline, assigned when the run is submitted. It is not a fresh 24 hours after completion. Always use the returned `url_expires_at`; reading a run or reusing a media ID does not renew that file's deadline.

For `text`, `json` and `boolean` outputs, save `value` directly, including `false`, `0`, empty strings or `null`. JSON results are already parsed JSON values. See the [inline result example](/api/runs#read-a-result); these outputs have no file to download.