Upload local media

1. Send file metadata to POST /api/v1/files/upload. Name the capability and the parameter that will receive the file.
2. Upload the exact file bytes to the returned uploadUrl with every returned header, or run the provided uploadCommand.
3. After the upload completes, use fileUrl in the capability submission.

The upload URL is temporary and bound to a file size. Bytes travel directly to storage. VidMage checks the upload before charging generation credits.

This Python example prepares an image for face-swap.targetImageUrl. It requests an upload but does not submit a generation task. Install requests in your chosen environment first.

import os
from pathlib import Path
import requests

media = Path("./input.jpg")
response = requests.post(
    "https://vidmage.ai/api/v1/files/upload",
    headers={"Authorization": f"Bearer {os.environ['VIDMAGE_API_KEY']}"},
    json={
        "capability": "face-swap",
        "parameter": "targetImageUrl",
        "fileName": media.name,
        "localPath": str(media.resolve()),
        "contentType": "image/jpeg",
        "fileSize": media.stat().st_size,
    },
    timeout=60,
)
response.raise_for_status()
print(response.json())

Match contentType to the file bytes, not just a renamed extension. Use the exact byte count, including for large videos. Do not supply duration in upload metadata. The server measures the uploaded media before billing; the upload contract accepts file metadata only.

Use the upload details returned by the service. Use HTTP PUT for the exact bytes and every returned upload header. Do not add your VidMage Bearer key to this storage request or replace the file with another file of a different size. The storage upload URL and the task input URL have different jobs: upload bytes with uploadUrl, then submit fileUrl.

Each returned fileUrl belongs to the capability parameter named when creating that upload. Do not reuse it for an unrelated input. In MCP, prepare one to five local files in a single upload_files call, then complete all returned storage transfers.

Temporary files are cleared automatically. No fixed retention interval is specified here. For bulk local media in an AI client, use the batch upload flow in the MCP guide.