Core APIs/Files

Upload Base64 File

POST

Overview

Upload a file by sending a base64 payload. Use this when your client already has an in-memory base64 image and you want a reusable hosted URL for subsequent generation requests.

Authentication

All API requests require a Bearer token in the request header.

Authorization: Bearer YOUR_API_KEY

Create and manage API keys from API Keys or use https://www.apimall.ai/api-keys.

Request

API Information

URL: POST https://gateway.apimall.ai/api/v1/files/base64
Content-Type: application/json

Request Parameters

Parameter	Type	Required	Description
`data`	string	Required	Base64 payload. Data URI prefixes are accepted. Uploaded file size must not exceed `104857600` bytes (100 MB).
`filename`	string	Optional	Optional filename used when storing the uploaded file.
`content_type`	string	Optional	Optional MIME type override. API Mall accepts public `image/`, `video/`, and `audio/*` uploads.

Request Example

{
  "data": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
  "filename": "frame.png"
}

Response Example

{
  "success": true,
  "data": {
    "url": "https://cdn.apimall.ai/uploads/2026/03/12/frame.png",
    "key": "uploads/2026/03/12/frame.png",
    "content_type": "image/png",
    "file_size": 412331
  },
  "request_id": "req_01HQ9M7J7X9P7Y8T6W5V4U3S2R"
}

cURL Example

curl --request POST 'https://gateway.apimall.ai/api/v1/files/base64' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "data": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
  "filename": "frame.png"
}'

JavaScript Example

const API_KEY = process.env.APIMALL_API_KEY;

const payload = {
  data: 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...',
  filename: 'frame.png',
};

const response = await fetch('https://gateway.apimall.ai/api/v1/files/base64', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(payload),
});

if (!response.ok) {
  throw new Error(`Base64 upload failed: ${response.status} ${response.statusText}`);
}

const data = await response.json();
console.log(data.data?.url);

Response Parameters

Parameter	Type	Description
`success`	boolean	Whether the request completed successfully.
`data.url`	string	URL associated with the returned resource, such as a hosted file URL or a webhook destination URL.
`data.key`	string	Storage object key assigned to the uploaded file.
`data.content_type`	string	Detected or required MIME type for the uploaded file.
`data.file_size`	integer	Uploaded file size in bytes.
`request_id`	string	Request identifier for debugging and support.

Error Response Example

{
  "success": false,
  "error": {
    "code": "invalid_request",
    "message": "Invalid base64 payload"
  },
  "request_id": "req_01HQ9M7J7X9P7Y8T6W5V4U3S2R"
}

Integration Notes

Store your API key on the server side only.

Error Codes

Common Error Codes

Status Code	Description
200	Request successful
400	Invalid request parameters
401	API key required or invalid API key
403	API access not approved or request made on a non-gateway host
429	Rate limit exceeded or too many concurrent jobs
500	Internal server error

Request

curl --location --request POST 'https://gateway.apimall.ai/api/v1/files/base64' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "data": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
  "filename": "frame.png"
}'

{
  "success": true,
  "data": {
    "url": "https://cdn.apimall.ai/uploads/2026/03/12/frame.png",
    "key": "uploads/2026/03/12/frame.png",
    "content_type": "image/png",
    "file_size": 412331
  },
  "request_id": "req_01HQ9M7J7X9P7Y8T6W5V4U3S2R"
}