Core APIs/Files

Upload File From URL

POST

Overview

Fetch a publicly accessible file and store it in API Mall managed storage. Use this when you have a remote image or media URL and want a stable hosted asset URL before submitting a generation task.

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/from-url
Content-Type: application/json

Request Parameters

Parameter	Type	Required	Description
`url`	string	Required	Publicly reachable source file URL. Only `http://` and `https://` URLs are allowed, and private network targets are rejected.
`filename`	string	Optional	Optional filename override for the uploaded object.
`content_type`	string	Optional	Optional MIME type override. API Mall accepts public `image/`, `video/`, and `audio/*` uploads.

Request Example

{
  "url": "https://example.com/assets/reference-image.png",
  "filename": "reference-image.png"
}

Response Example

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

cURL Example

curl --request POST 'https://gateway.apimall.ai/api/v1/files/from-url' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "url": "https://example.com/assets/reference-image.png",
  "filename": "reference-image.png"
}'

JavaScript Example

const API_KEY = process.env.APIMALL_API_KEY;

const payload = {
  url: 'https://example.com/assets/reference-image.png',
  filename: 'reference-image.png',
};

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

if (!response.ok) {
  throw new Error(`Remote 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": "Failed to fetch source url",
    "details": {
      "status": 404
    }
  },
  "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/from-url' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "url": "https://example.com/assets/reference-image.png",
  "filename": "reference-image.png"
}'

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