Skip to content

Upload Media

This endpoint allows you to upload media files to the Wickson API for processing, analysis, and storage. Uploaded files are processed to generate vector embeddings, detailed content analysis, and structured metadata, enabling efficient search and retrieval.

Endpoint

POST https://api.wickson.ai/v1/media

Request

Headers

  • X-Api-Key: Required. Your Wickson API key.

Body (Multipart/form-data)

  • file: Required. The media file to upload. Supported file types include documents (PDF, DOCX, TXT), images (JPG, PNG, GIF), audio (MP3, WAV), video (MP4, MOV), and 3D models (GLB, OBJ).
  • force_overwrite (optional): Boolean. If true, existing media with the same checksum will be overwritten. Defaults to false.
  • collection_id (optional): String. An identifier for grouping related media items. If not provided, media will be added to the default collection.
  • include_vectors (optional): Boolean. If true, includes vector embeddings in the response. Defaults to false.

URL Parameters

Example Request

curl -X POST \
  -H "X-Api-Key: YOUR_API_KEY" \
  -F "file=@/path/to/your/file.pdf" \
  -F "force_overwrite=true" \
  -F "collection_id=my_collection" \
  https://api.wickson.ai/v1/media?include_vectors=true

Python Example

import requests

# Configuration
api_key = "YOUR_API_KEY"
file_path = "research_paper.pdf"

# Upload media file
with open(file_path, "rb") as file:
    response = requests.post(
        "https://api.wickson.ai/v1/media",
        headers={"X-Api-Key": api_key},
        files={"file": file},
        data={
            "collection_id": "research",
            "force_overwrite": "false"
        }
    )

# Process response
if response.status_code == 200:
    result = response.json()["data"]

    print(f"Uploaded: {result['file_details']['filename']}")
    print(f"Media ID: {result['media_id']}")
    print(f"Type: {result['media_type']}")
    print(f"Collection: {result['storage_info']['collection']}")
    print(f"Cost: ${result['balance_info']['cost']}")

    if "content_summary" in result and "summary" in result["content_summary"]:
        print(f"Summary: {result['content_summary']['summary'][:100]}...")
elif response.status_code == 409:
    print("File already exists. Use force_overwrite=true to replace it.")
else:
    print(f"Error {response.status_code}: {response.text}")

File Storage Notice

When you upload media files to this endpoint, the Wickson API: * Uses your files to generate vector embeddings and extract metadata * Securely deletes the original files after processing * Stores only the derived vectors and metadata for searching * Does not provide a way to retrieve the original uploaded files later

Plan accordingly and maintain your own copies of important files!

Response

Status Codes

Status Code Description
200 OK Media processed successfully.
400 Bad Request Invalid request parameters.
401 Unauthorized Invalid or missing API key.
403 Forbidden Insufficient API key permissions.
409 Conflict File already exists (when force_overwrite=false).
429 Too Many Requests Rate limit exceeded.
500 Internal Server Error An unexpected error occurred.
503 Service Unavailable Service temporarily unavailable.

Body (JSON)

{
  "success": true,
  "message": "Media processed successfully",
  "data": {
    "media_id": "doc_b1e01882-a58c-5010-a13c-ceff0c564f15",
    "media_type": "document",
    "status": "completed",
    "processing_info": {
      "started_at": "2025-03-09T04:47:54.784841",
      "completed_at": "2025-03-09T04:47:54.784841",
      "job_id": "job_2f3a1379-35ab-596a-8d6c-aa83cc3df7cc"
    },
    "content_summary": {
      "summary": "This document, titled \"Fertilizing Apples\"...",
      "description": "This document is a comprehensive guide on fertilizing apple trees...",
      "topics": ["Apple Fertilization", "Soil Nutrition", "Plant Nutrition"],
      "keywords": ["apples", "fertilizing", "soil pH", "nitrogen"],
      "categories": ["Agriculture", "Horticulture", "Fruit Production"],
      "emotions": ["Informative", "Instructive", "Cautionary", "Advisory"],
      "entities": {
        "people": ["Garth Cahoon", "Eric Hanson"],
        "organizations": ["Spectrum Analytic Inc.", "Ohio State University"],
        "locations": ["Washington C.H., Ohio", "Columbus, Ohio"],
        "objects": ["apples", "soil", "fertilizer", "leaves"],
        "concepts": ["fertilization", "soil analysis", "plant analysis"]
      },
      "quality": {
        "clarity": 0.9,
        "completeness": 0.95,
        "relevance": 0.9,
        "technical": 0.85
      }
    },
    "file_details": {
      "filename": "fertilizing_apple_trees.pdf",
      "size_bytes": 538064,
      "checksum": "3fbcec1c16cecd8166ae7a6f8a00b240db995bd5df1d8aced124acc91959c019",
      "media_type": "document",
      "page_count": 23
    },
    "storage_info": {
      "collection": "default",
      "vectors_stored": 1,
      "stored_at": "2025-03-09T04:47:54.783840"
    },
    "balance_info": {
      "previous_balance": 999999.99,
      "cost": 0.04,
      "new_balance": 999999.99
    },
    "vectors": {
      "combined": [0.123, 0.456, ... ] // Only included when include_vectors=true
    }
  },
  "metadata": {
    "cost": 0.04,
    "collection": "default",
    "request_id": "req_67890",
    "processing_time_ms": 2543
  },
  "timestamp": "2025-03-09T04:47:54.784841"
}

Response Fields

Core Information

Field Description
media_id Unique identifier for the processed media item. Use this ID for subsequent operations.
media_type The detected media type (e.g., "document", "image", "video", "audio", "model").
status Processing status: "completed", "processing", or "failed".

Content Summary

Field Description
summary Concise summary of the media content.
description Detailed description of the media content.
topics Main topics covered in the media.
keywords Key terms extracted from the content.
categories Broad categories the content belongs to.
emotions Emotional tone analysis of the content.
entities Structured extraction of named entities by type.
quality Quality assessment metrics for the content.

File Details

Field Description
filename Original filename of the uploaded file.
size_bytes File size in bytes.
checksum SHA-256 checksum of the file for verification.
media_type Specific media type.
page_count Number of pages (for documents).
duration Length in seconds (for audio/video).
dimensions Width x height (for images).
resolution Resolution details (for video).

Processing & Storage

Field Description
processing_info Details about the processing operation.
job_id Unique identifier for the processing job.
storage_info Information about where and how the media is stored.
collection The collection containing this media item.
vectors_stored Number of vector embeddings stored.
balance_info Cost information and account balance details.
vectors Vector embeddings (only when include_vectors=true).

Media Type Specific Fields

Different media types will include specialized fields in their file_details:

Document Files

  • page_count: Number of pages
  • word_count: Estimated number of words (when available)

Image Files

  • dimensions: Width and height in pixels
  • color_mode: RGB, CMYK, etc.

Video Files

  • duration: Length in seconds
  • resolution: Width x height
  • frame_rate: Frames per second

Audio Files

  • duration: Length in seconds
  • sample_rate: Audio sample rate
  • channels: Mono, stereo, etc.

3D Model Files

  • vertex_count: Number of vertices
  • material_count: Number of materials
  • dimensions: 3D dimensions

Costs

The total cost of uploading media consists of:

Processing Cost (by media type):

  • Document processing: $0.03 per file
  • Image processing: $0.03 per file
  • Video processing: $0.03 per file
  • Audio processing: $0.03 per file
  • Model (3D) processing: $0.03 per file

Storage Cost:

  • Database operations: $0.01 per operation

Total for standard upload: $0.04

Note: Costs are automatically deducted from your account balance upon successful processing.

Error Responses

In case of error, the response will follow this structure:

{
  "success": false,
  "message": "Error message describing what went wrong",
  "error": {
    "code": "ERROR_CODE",
    "details": {
      "specific": "error details",
      "request_id": "req_12345"
    }
  }
}

Common Error Scenarios

HTTP Status Error Code Description
400 MISSING_FILE Required file upload is missing
400 UNSUPPORTED_FILE_TYPE File format not supported
400 FILE_SIZE_EXCEEDED File larger than allowed limit
400 INVALID_PARAMETER Invalid parameter format
401 INVALID_API_KEY Invalid or missing API key
403 INSUFFICIENT_PERMISSIONS API key lacks required capabilities
409 DUPLICATE_FILE File already exists (use force_overwrite=true to replace)
429 RATE_LIMIT_EXCEEDED Too many requests in time period
500 PROCESSING_ERROR Error during media processing
503 SERVICE_UNAVAILABLE Service temporarily unavailable
This site uses cookies to help us improve the overall documentation and browsing experience. By continuing to use this site, you agree to our Privacy Policy.