Analyze Media¶

This endpoint allows you to perform deep AI-powered analysis on your media files, extracting insights and answering specific queries about the content. The Wickson API supports analysis of various media types, including documents, images, video, audio, and 3D models.

Endpoint¶

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

Request¶

Headers¶

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

Body (Multipart/form-data)¶

file: Required. The media file to analyze. Supported file types are the same as for the upload media endpoint. Ensure the file type is compatible with the chosen analysis features. See the Limits section for file size and content restrictions.
query: Required. The question or query you want to ask about the media content. Be as specific as possible to get the most relevant results.
system_prompt (Optional): String. Provides context or instructions to the AI model on how to approach the analysis. This can steer the analysis towards specific aspects or perspectives (e.g., legal guidelines, industry-specific knowledge, desired tone).
response_format (Optional): String. Specifies the desired format for the analysis response. Possible values: "text" (default), "json". The "json" format provides a structured response with separate fields for analysis components.
media_type (Optional): String. Overrides automatic media type detection. Useful for ambiguous file extensions. Possible values: "document", "image", "video", "audio", "model". If omitted, the Wickson API attempts to auto-detect the media type.

Example Request¶

curl -X POST \
  -H "X-Api-Key: YOUR_API_KEY" \
  -F "file=@/path/to/your/file.pdf" \
  -F "query=What are the key takeaways from this document?" \
  -F "system_prompt=Analyze this document from a legal perspective, focusing on potential liabilities." \
  -F "response_format=json" \
  https://api.wickson.ai/v1/ai/analyze

Python Example¶

import requests

# Configuration
api_key = "YOUR_API_KEY"
file_path = "contract.pdf"
query = "What are the key takeaways from this document?"

# Send analysis request
with open(file_path, "rb") as file:
    response = requests.post(
        "https://api.wickson.ai/v1/ai/analyze",
        headers={"X-Api-Key": api_key},
        files={"file": file},
        data={
            "query": query,
            "response_format": "json",
            "system_prompt": "Analyze this from a legal perspective"
        }
    )

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

    # Print key information
    print(f"Analysis of: {result['media_info']['filename']}")
    print(f"Summary: {result['analysis']['summary']}")
    print(f"Answer: {result['answer']['main_response']}")

    # Print insights if available
    if "insights" in result["answer"]:
        print("\nKey Insights:")
        for insight in result["answer"]["insights"]:
            print(f"- {insight['observation']}")
else:
    print(f"Error {response.status_code}: {response.text}")

Response¶

Body (JSON - when response_format=json)¶

{
  "success": true,
  "message": "Media analysis completed successfully",
  "data": {
    "media_info": {
      "filename": "contract.pdf",
      "format": ".pdf",
      "media_type": "document",
      "processed_at": "2024-12-19T15:30:00Z",
      "size": 1234567,
      "type": "document"
    },
    "processing_info": {
      "api_version": "1.0.0",
      "context_id": "req_98765",
      "model": "gemini",
      "processing_time_ms": 1200,
      "status": "success",
      "cost": 0.10,
      "balance": 9.50
    },
    "query_info": {
      "query": "What are the key takeaways from this document?",
      "response_format": "json",
      "system_prompt": "Analyze this document from a legal perspective..."
    },
    "response": {
      "content": {
        "analysis": {
          "summary": "This contract outlines...",
          "key_elements": ["Clause 1...", "Clause 2..."],
          "relevant_details": "..."
        },
        "answer": {
          "main_response": "The key takeaways are...",
          "insights": [
            {"observation": "...", "analysis": "...", "implication": "..."},
            {"observation": "...", "analysis": "...", "implication": "..."}
          ],
          "additional_considerations": "..."
        }
      },
      "format": "json",
      "generated_at": "2024-12-19T15:30:00Z"
    }
  },
  "metadata": {
    "request_id": "req_98765",
    "processing_time_ms": 1200,
    "summary": "Key takeaways: ..."
  }
}

Response Details¶

Body Format¶

When response_format=text (default), the response will be a plain text string containing the analysis results, including summary, key elements, query answers, insights, and additional considerations.

Response Fields¶

Media Information¶

Field	Description
`media_info.filename`	Original filename of the media
`media_info.format`	File extension of the media
`media_info.media_type`	Detected or specified media type
`media_info.processed_at`	Timestamp of the analysis
`media_info.size`	Size of the file in bytes

Processing Details¶

Field	Description
`processing_info.api_version`	Version of the API used
`processing_info.context_id`	Unique identifier for the analysis request
`processing_info.model`	AI model used for analysis (e.g., "gemini")
`processing_info.processing_time_ms`	Time taken for analysis in milliseconds
`processing_info.status`	Status of the analysis ("success" or "failed")
`processing_info.cost`	Cost of the analysis operation
`processing_info.balance`	Remaining account balance after operation

Query Information¶

Field	Description
`query_info.query`	The original query text
`query_info.response_format`	The requested response format
`query_info.system_prompt`	The provided system prompt (if any)

Response Content¶

Field	Description
`response.content.analysis`	Objective analysis of the media content
`response.content.summary`	Concise summary of the content
`response.content.key_elements`	Important elements/features identified
`response.content.relevant_details`	Specific details relevant to query
`response.content.answer`	Direct response to submitted query
`response.content.main_response`	Primary answer to the query

Insights¶

Field	Description
`insights.observation`	Specific observation from content
`insights.analysis`	Interpretation of the observation
`insights.implication`	Potential implications of observation
`insights.additional_considerations`	Further points to consider

Error Scenarios¶

Status Code	Error Type	Description
400	Missing Parameters	Missing file or query parameter
400	Unsupported File	Unsupported file type for analysis
400	Invalid Format	Invalid response_format
400	Size Limit	File size exceeds limits
401	Unauthorized	Invalid or missing API key
429	Too Many Requests	Rate limit exceeded. Retry after the specified time
500	Processing Error	Error during media analysis
503	Service Down	Service temporarily unavailable

Usage Limits¶

File Size Limits (Subject to change)¶

Media Type	Maximum Size	Duration Limit
Video	100MB	10 minutes
Audio	50MB	10 minutes
Images/Models	50MB	N/A
Documents	20MB	~75k tokens

Costs and Rate Limiting¶

Cost per Query: $0.03 (deducted from account balance)
Rate Limiting: Enforced with 429 status code when exceeded
Retry Strategy: Check Retry-After header for next attempt timing