---
title: "Upload File"
method: POST
path: "/files"
tags: ["Access"]
---

# Upload File

`POST /files`

## Request

- Base URL: `https://api.hedra.com/v3`
- URL: `https://api.hedra.com/v3/files`
- Auth: one of:
  - API key in header `Authorization`
  - HTTP bearer

Store a file and return a short-lived URL to pass in a model's `input`.

Free, and available on an empty API wallet — funding is enforced when you
submit a generation, not when you upload its inputs. `GET /v3/balance`
reports what the wallet holds.

Returns 402 while uploads are paused, which happens when your recent
requests were all refused for insufficient funds. Adding funds to the API
wallet resumes them.

## Request body `multipart/form-data`

- object
  - `file` string, binary, required: The file to upload.

## Response `201`

Successful Response

- FileUploadResponse: ``POST /v3/files`` result. The presigned ``url`` *is* the file handle: pass it as ``{"source": "url", "url": <url>}`` in any media input the model's schema advertises (``image`` / ``end_image`` / ``images`` / ``audio`` / ``video``) on submit.
  - `url` string, required: Presigned GET URL for the stored bytes — the handle itself. Pass it back verbatim, query string included: a modified URL is not recognised as your handle and is rejected as an external URL.
  - `content_type` string, required: MIME type sniffed from the uploaded bytes; the request's own Content-Type and filename are never trusted. Decides which media inputs will accept this handle.
  - `expires_at` string, date-time, required: ISO-8601 instant after which `url` is rejected. Submitting with a lapsed handle is a 400 with `reason: "expired"`, not a fetch failure; upload the file again for a fresh handle.

## Other responses

- `400`: Invalid or failed-validation request.
- `401`: Authentication failed: missing, malformed, or invalid credentials.
- `402`: New requests are paused because this user's recent requests were all refused for insufficient funds. Adding funds resumes them.
- `403`: Insufficient scope or plan.
- `404`: Resource not found.
- `429`: Rate limit exceeded.
- `500`: Internal error.

## Changes

- **2026-10-16** `06692d16e78a`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/hedra-labs/apis/hedra-api/changes/files/post.md)

---

[API](https://skmtc.dev/hedra-labs/apis/hedra-api.md) - [All operations](https://skmtc.dev/hedra-labs/apis/hedra-api/llms.txt) - [OpenAPI document](https://skmtc.dev/hedra-labs/apis/hedra-api/revisions/6ef35a11cefe?raw)