> ## Documentation Index > Fetch the complete documentation index at: https://magica.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Upload media > Import a URL, data URI, or raw base64 media source into permanent storage for the authenticated API key owner. Uploads a media source from a public URL, data URI, or raw base64 payload and returns its permanent Magica URL and detected media metadata. ## Authorization **Authorization** `string` *required* Bearer API key. Format: `Bearer gx_your_api_key`. ## Request Provide exactly one source: * `url`: a public HTTPS media URL or a base64 data URI. Remote URLs must be reachable without interactive authentication. * `data_uri`: a base64 data URI. * `base64`: raw base64 bytes; `content_type` is required with this form. Optional fields include `media_type`, `filename`, and `folder`. `folder` defaults to `mcp-uploads`; setting it to `media-library` only changes the storage folder and does not create a media-library catalog record. ## Examples > [tab] URL > > ```bash theme={null} > curl -X POST https://inference.magica.com/v1/uploads \ > -H "Authorization: Bearer $MAGICA_API_KEY" \ > -H "Content-Type: application/json" \ > --data '{ > "url": "https://example.com/image.png", > "filename": "reference-image.png" > }' > ``` > [tab] Data URI > > ```bash theme={null} > curl -X POST https://inference.magica.com/v1/uploads \ > -H "Authorization: Bearer $MAGICA_API_KEY" \ > -H "Content-Type: application/json" \ > --data '{ > "data_uri": "data:image/png;base64,iVBORw0KGgoAAA...", > "filename": "inline-data-uri.png" > }' > ``` > [tab] Raw base64 > > ```bash theme={null} > curl -X POST https://inference.magica.com/v1/uploads \ > -H "Authorization: Bearer $MAGICA_API_KEY" \ > -H "Content-Type: application/json" \ > --data '{ > "base64": "iVBORw0KGgoAAA...", > "content_type": "image/png", > "filename": "inline-image.png" > }' > ``` ## Response **url** `string` Permanent URL for the uploaded media. **media\_type** `string` Detected media type: `image`, `video`, `audio`, or `file`. **filename** `string | null` Detected source filename when available. **metadata** `object` Additional media metadata discovered during import. ## Errors | Status | Reason | | - | - | | `400` | The source URL or upload request is invalid or inaccessible | | `401` | Missing or invalid API key | | `402` | Insufficient credits | | `403` | The API key is not allowed to upload media | | `413` | The source exceeds the upload size limit | | `429` | Upload rate limit exceeded | | `500` | The source could not be fetched or stored | | `503` | Upload service temporarily unavailable | ## OpenAPI ````yaml POST /v1/uploads openapi: 3.1.0 info: title: Magica REST API version: 1.0.0 description: >- REST API for managing Magica resources. Authenticate public endpoints with your Magica API key: Authorization: Bearer gx_xxx. servers: - url: https://inference.magica.com security: - bearerAuth: [] paths: /v1/uploads: post: tags: - Public REST summary: Upload a media source description: >- Upload a media source from a public URL, data URI, or base64 payload. Source-access failures include stable optional code and retryable fields so callers can distinguish user action from transient provider failures. requestBody: required: true content: application/json: schema: type: object additionalProperties: false example: url: https://example.invalid/conformance description: >- Provide exactly one of url, data_uri, or base64. URL sources may be public HTTPS media URLs or base64 data URIs; explicitly enabled non-production localhost fixtures may use HTTP. Raw base64 also requires content_type. oneOf: - required: - url properties: url: type: string minLength: 1 data_uri: type: string maxLength: 0 base64: type: string maxLength: 0 - required: - data_uri properties: url: type: string maxLength: 0 data_uri: type: string minLength: 1 base64: type: string maxLength: 0 - required: - base64 - content_type properties: url: type: string maxLength: 0 data_uri: type: string maxLength: 0 base64: type: string minLength: 1 content_type: type: string minLength: 1 properties: url: type: string description: >- Public HTTPS media source or a base64 data URI. HTTP is accepted only for explicitly enabled localhost development fixtures. anyOf: - type: string maxLength: 0 - type: string minLength: 1 format: uri pattern: ^https:// - type: string minLength: 1 pattern: ^data:[^;,]+;base64, data_uri: type: string description: Base64 data URI source. base64: type: string description: Raw base64 source bytes. media_type: type: string enum: - image - video - audio - file filename: type: string content_type: type: string folder: type: string enum: - mcp-uploads - media-library responses: '200': description: The source was uploaded to permanent storage. content: application/json: schema: type: object additionalProperties: false required: - url - media_type - filename - metadata properties: url: type: string format: uri media_type: type: string enum: - image - video - audio - file filename: type: - string - 'null' metadata: type: object additionalProperties: true '400': description: Invalid upload source or request. content: application/json: schema: type: object additionalProperties: false required: - error properties: error: type: string description: Safe validation guidance. code: type: string enum: - source_invalid_url - source_authentication_required - source_not_found - source_rejected - source_rate_limited - source_provider_unavailable - source_not_accessible retryable: type: boolean details: type: array items: type: object '401': description: Missing or invalid API key. content: application/json: schema: type: object additionalProperties: false required: - error properties: error: type: string description: Safe validation guidance. code: type: string retryable: type: boolean details: type: array items: type: object '402': description: Insufficient credits for this upload. content: application/json: schema: type: object additionalProperties: false required: - error properties: error: type: string description: Safe validation guidance. code: type: string retryable: type: boolean details: type: array items: type: object '403': description: The API key is not allowed to upload media. content: application/json: schema: type: object additionalProperties: false required: - error properties: error: type: string description: Safe validation guidance. code: type: string retryable: type: boolean details: type: array items: type: object '413': description: The upload source exceeds the media size limit. content: application/json: schema: type: object additionalProperties: false required: - error properties: error: type: string description: Safe validation guidance. code: type: string retryable: type: boolean details: type: array items: type: object '429': description: Upload rate limit exceeded. content: application/json: schema: type: object additionalProperties: false required: - error properties: error: type: string description: Safe validation guidance. code: type: string retryable: type: boolean details: type: array items: type: object '500': description: The upload source could not be fetched or stored. content: application/json: schema: type: object additionalProperties: false required: - error properties: error: type: string description: Safe explanation of why the upload failed. code: type: string enum: - source_invalid_url - source_authentication_required - source_not_found - source_rejected - source_rate_limited - source_provider_unavailable - source_not_accessible description: >- Stable source-access failure code, present only for classified remote-source failures. retryable: type: boolean description: Whether retrying the same remote source may succeed. details: type: array items: type: object '503': description: Upload service temporarily unavailable. content: application/json: schema: type: object additionalProperties: false required: - error properties: error: type: string description: Safe validation guidance. code: type: string retryable: type: boolean details: type: array items: type: object components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: Magica API key ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.