Import from URL

POST/api/v1/media/files/import-url

Import files directly from URLs without downloading them first. The server fetches the file(s) and stores them in your bucket. This is the easiest method for automation tools.

info

Best for automation: This endpoint is designed for Xano, N8N, Make, and similar automation platforms where you have image/file URLs and want to store them in SpiderMedia.

Two Modes

This endpoint supports both single file and batch imports:

Mode	Payload	Response
Single	{"url": "..."}	FileUploadResponse
Batch	{"urls": [...]}	FileImportBatchResponse

The API automatically detects which mode based on the payload structure.

---

Single File Import

Use the url field to import a single file.

Request

urlstringrequired

URL of the file to import

filenamestring

Custom filename (auto-detected from URL if not provided)

folderstring

Optional folder path within your bucket (e.g., "logos", "ads/banners")

Response

successboolean

Whether the upload succeeded

urlstring

Public URL to access the uploaded file

keystring

File key within the bucket

content_typestring

MIME type of the uploaded file

sizeinteger

File size in bytes

Example

cURL

curl -X POST "https://spideriq.ai/api/v1/media/files/import-url" \
  -H "Authorization: Bearer cli_abc123:sk_xxx:secret_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/images/product.jpg",
    "folder": "products"
  }'

Python

import requests

url = "https://spideriq.ai/api/v1/media/files/import-url"
headers = {
    "Authorization": "Bearer cli_abc123:sk_xxx:secret_xxx",
    "Content-Type": "application/json"
}
payload = {
    "url": "https://example.com/images/product.jpg",
    "folder": "products"
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

JavaScript (Xano)

// In Xano External API Request
{
  "method": "POST",
  "url": "https://spideriq.ai/api/v1/media/files/import-url",
  "headers": {
    "Authorization": "Bearer cli_abc123:sk_xxx:secret_xxx",
    "Content-Type": "application/json"
  },
  "body": {
    "url": "https://example.com/images/product.jpg",
    "folder": "products"
  }
}

Response Example

{
  "success": true,
  "file_id": "products/20260111_product.jpg",
  "bucket": "client-cli-abc123",
  "key": "products/20260111_product.jpg",
  "url": "https://media.spideriq.ai/client-cli-abc123/products/20260111_product.jpg",
  "size": 45231,
  "content_type": "image/jpeg"
}

---

Batch Import

Use the urls array to import multiple files in a single request. Each file is processed independently - if one fails, others continue.

Request

urlsarrayrequired

Array of file objects to import. Each object contains:

• url (required): URL of the file to import
• filename (optional): Custom filename for this specific file

folderstring

Folder path for ALL files in this batch (e.g., "ads", "campaign-123")

Response

successboolean

true only if ALL files uploaded successfully

totalinteger

Total number of files in the request

successfulinteger

Number of files successfully uploaded

failedinteger

Number of files that failed

resultsarray

Array of per-file results, each containing:

• success: Whether this file succeeded
• url: Source URL that was imported
• file_url: Public URL of uploaded file (if successful)
• filename: Final filename used
• size: File size in bytes
• error: Error message (if failed)

Example

cURL

curl -X POST "https://spideriq.ai/api/v1/media/files/import-url" \
  -H "Authorization: Bearer cli_abc123:sk_xxx:secret_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": [
      {"url": "https://example.com/img/logo.png"},
      {"url": "https://example.com/banner.jpg", "filename": "main-banner.jpg"},
      {"url": "https://example.com/icon.svg"}
    ],
    "folder": "campaign-assets"
  }'

Python

import requests

url = "https://spideriq.ai/api/v1/media/files/import-url"
headers = {
    "Authorization": "Bearer cli_abc123:sk_xxx:secret_xxx",
    "Content-Type": "application/json"
}
payload = {
    "urls": [
        {"url": "https://example.com/img/logo.png"},
        {"url": "https://example.com/banner.jpg", "filename": "main-banner.jpg"},
        {"url": "https://example.com/icon.svg"}
    ],
    "folder": "campaign-assets"
}

response = requests.post(url, headers=headers, json=payload)
result = response.json()

# Check results
print(f"Uploaded: {result['successful']}/{result['total']}")
for item in result['results']:
    if item['success']:
        print(f"  ✓ {item['filename']} -> {item['file_url']}")
    else:
        print(f"  ✗ {item['url']} - {item['error']}")

JavaScript (N8N/Xano)

// Batch import from a list of image URLs
{
  "method": "POST",
  "url": "https://spideriq.ai/api/v1/media/files/import-url",
  "headers": {
    "Authorization": "Bearer cli_abc123:sk_xxx:secret_xxx",
    "Content-Type": "application/json"
  },
  "body": {
    "urls": [
      {"url": "https://example.com/img/logo.png"},
      {"url": "https://example.com/banner.jpg", "filename": "main-banner.jpg"}
    ],
    "folder": "campaign-assets"
  }
}

Response Example

{
  "success": true,
  "total": 3,
  "successful": 3,
  "failed": 0,
  "results": [
    {
      "success": true,
      "url": "https://example.com/img/logo.png",
      "file_url": "https://media.spideriq.ai/client-cli-abc123/campaign-assets/20260111_logo.png",
      "filename": "logo.png",
      "size": 15234,
      "error": null
    },
    {
      "success": true,
      "url": "https://example.com/banner.jpg",
      "file_url": "https://media.spideriq.ai/client-cli-abc123/campaign-assets/20260111_main-banner.jpg",
      "filename": "main-banner.jpg",
      "size": 89012,
      "error": null
    },
    {
      "success": true,
      "url": "https://example.com/icon.svg",
      "file_url": "https://media.spideriq.ai/client-cli-abc123/campaign-assets/20260111_icon.svg",
      "filename": "icon.svg",
      "size": 2048,
      "error": null
    }
  ]
}

{
  "success": false,
  "total": 3,
  "successful": 2,
  "failed": 1,
  "results": [
    {
      "success": true,
      "url": "https://example.com/img/logo.png",
      "file_url": "https://media.spideriq.ai/client-cli-abc123/assets/img/logo.png",
      "filename": "logo.png",
      "size": 15234,
      "error": null
    },
    {
      "success": false,
      "url": "https://example.com/missing.jpg",
      "file_url": null,
      "filename": null,
      "size": null,
      "error": "Client error '404 NOT FOUND' for url 'https://example.com/missing.jpg'"
    },
    {
      "success": true,
      "url": "https://example.com/icon.svg",
      "file_url": "https://media.spideriq.ai/client-cli-abc123/assets/icon.svg",
      "filename": "icon.svg",
      "size": 2048,
      "error": null
    }
  ]
}

---

Use Cases

Xano: Import Product Images

When scraping product data, import all images to your media storage:

// After SpiderSite returns product data with image URLs
{
  "urls": product_images.map(img => ({ "url": img.src })),
  "folder": "products/" + product_id
}

N8N: Campaign Asset Upload

Import multiple ad creatives from a Google Drive folder or external source:

// Batch import campaign assets
{
  "urls": [
    {"url": drive_url_1, "filename": "ad-variant-a.jpg"},
    {"url": drive_url_2, "filename": "ad-variant-b.jpg"},
    {"url": drive_url_3, "filename": "ad-variant-c.jpg"}
  ],
  "folder": "campaigns/q1-2026"
}

Dynamic Filename from Variable

// Single file with dynamic naming
{
  "url": scraped_logo_url,
  "filename": company_name.toLowerCase().replace(/\s+/g, '-') + "-logo.png",
  "folder": "logos"
}

---

Error Handling

warning

Single mode vs Batch mode errors:

• Single file: Returns HTTP 400 error if import fails
• Batch: Always returns HTTP 200, with per-file success/error in results

Common Errors

Error	Cause	Solution
404 NOT FOUND	Source URL doesn't exist	Verify the URL is accessible
Timeout downloading file	Source server too slow	Try again or use a different URL
Downloaded file is empty	URL returned no content	Check if URL requires authentication
Must provide either 'url' or 'urls'	Neither field provided	Include url or urls in payload