Media & files

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

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.

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, or configure the same inputs visually in its playground. Fields that are unsupported for a model are rejected rather than silently ignored.

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.

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.

{
  "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:

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.

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.

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.

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; these outputs have no file to download.