# Uploading assets

## Upload a local file

Pass existing public URLs directly in `inputs.uploadedUrls`. For a local file, ask i2v.ai for a signed storage ticket, PUT the bytes to storage, then use the public URL from the ticket. Both types of URL can appear in the same array.

```bash
API=https://api.i2v.ai
TICKET=$(curl --fail-with-body -sS "$API/api/v1/uploads" \
  -H "Authorization: Bearer $I2V_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"fileName":"reference.png"}')

curl --fail-with-body -sS -X PUT "$(jq -r .uploadUrl <<< "$TICKET")" \
  -H "Content-Type: $(jq -r .contentType <<< "$TICKET")" \
  --data-binary @reference.png
```

The ticket returns `uploadUrl`, `url`, `path`, `method`, `contentType`, `expiresIn`, `confirmUrl`, and `assetTtlSeconds`. Send the API key to the API origin only. The signed URL authorizes the raw PUT. The returned media URL can be opened by anyone who has the link.

The API infers MIME type from common image, video, and audio extensions. Pass `contentType` explicitly for a file with a missing or incorrect extension. You can supply `fileSize` in bytes to bind the ticket to an exact size.

## Inspect the upload

```bash
curl --fail-with-body -sS "$API$(jq -r .confirmUrl <<< "$TICKET")" \
  -H "Authorization: Bearer $I2V_API_KEY"
```

`GET /api/v1/uploads?path=…` returns `size`, `contentType`, `uploadedAt`, `expiresAt` and `media`, along with the original path and URL. `media` can contain the kind, display dimensions, rotation, and duration in milliseconds. It is `null` when the container cannot be read within the probe budget. Confirmation is optional. After a successful PUT, pass `url` to [createTask](/docs/api), for example:

```json
{
  "model": "gpt-image-2",
  "inputs": {
    "prompt": "Restyle the reference as a watercolor.",
    "uploadedUrls": ["https://your-upload-url"]
  }
}
```

For video models, known filename extensions in `uploadedUrls` select the image, video, or audio reference slot. For videos or audio at URLs without an extension, use the model’s explicit `referenceVideoUrls` or `referenceAudioUrls` field.

## Lifetime and limits

- Upload tickets are valid for 15 minutes. Submit new tasks within 24 hours of the PUT. Expired files are cleaned up automatically. Tasks that already reference a file can keep it until they finish.
- File limits are 10 MiB for images, 50 MiB for video, and 15 MiB for audio. When size is omitted, the API checks the stored size at confirmation or submission. Model-specific reference limits also apply.
- Invalid paths, unsupported MIME types, or size mismatches return HTTP 400. A path owned by another account returns HTTP 403. Missing or expired files return HTTP 404.
- For the size-bound ticket and explicit completion workflow, see [Media workflow and recovery](/docs/media-workflow).