Skip to content

AI Query

Utilize Wickson's AI inferencing endpoint to obtain insights, answers, and creative content tailored to your needs. This endpoint is designed to provide high-quality responses (optionally) grounded in your uploaded media for maximum relevance and accuracy.

Endpoint

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

Request

Headers

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

Body (JSON)

  • query: Required. String. Your question or instruction for the AI. Be specific to get the most relevant results.
  • media_id: Optional. String. ID of a previously uploaded media file to use as context (must start with 'vec-'). This grounds the AI's response in your specific content.
  • temperature: Optional. Float. Controls response creativity and randomness, from 0.0 (focused/deterministic) to 1.0 (creative/varied). Default: 0.7
  • max_tokens: Optional. Integer. Maximum number of tokens in the response. Range: 1-4096. Default: 1024
  • system_prompt: Optional. String. Special instructions to guide how the AI approaches your query (e.g., "Act as a legal advisor" or "Explain concepts simply").
  • context: Optional. String. Additional information to consider alongside your query, such as previous conversation history or supplementary details.

Example Request

curl -X POST \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What are the main points in the quarterly report?",
    "media_id": "vec-38fn4098fn3049rj09jj9409jjjkdd",
    "temperature": 0.5,
    "max_tokens": 2048,
    "system_prompt": "Analyze this from a financial perspective"
  }' \
  https://api.wickson.ai/v1/ai/query

Python Example

import requests
import json

# Configuration
api_key = "YOUR_API_KEY"
endpoint = "https://api.wickson.ai/v1/ai/query"

# Basic query with media context
def query_with_media(question, media_id=None, temperature=0.7):
    payload = {
        "query": question,
        "temperature": temperature,
        "max_tokens": 1500
    }

    # Add media context if provided
    if media_id:
        payload["media_id"] = media_id

    # Send request
    response = requests.post(
        endpoint,
        headers={
            "X-Api-Key": api_key,
            "Content-Type": "application/json"
        },
        json=payload
    )

    # Process response
    if response.status_code == 200:
        result = response.json()

        print(f"AI Response: {result['data']['response']}")
        print(f"\nToken Usage: {result['data']['billing']['usage']['total_tokens']} tokens")
        print(f"Cost: ${result['data']['billing']['total_cost']}")

        return result
    else:
        print(f"Error {response.status_code}: {response.text}")
        return None

# Example: Query about a specific document
result = query_with_media(
    "What are the key revenue drivers mentioned in our latest financial report?",
    media_id="vec-38fn4098fn3049rj09jj9409jjjkdd"
)

Multi-turn Conversation Example

import requests

# Configuration 
api_key = "YOUR_API_KEY"
endpoint = "https://api.wickson.ai/v1/ai/query"

# Maintain conversation history
conversation = []

def chat_with_ai(user_message, media_id=None):
    global conversation

    # Add the new user message to conversation history
    conversation.append(f"User: {user_message}")

    # Format conversation history as context
    conversation_context = "\n".join(conversation)

    # Prepare request
    payload = {
        "query": user_message,
        "context": conversation_context,
        "temperature": 0.7
    }

    # Add media context if provided
    if media_id:
        payload["media_id"] = media_id

    # Send request
    response = requests.post(
        endpoint,
        headers={
            "X-Api-Key": api_key,
            "Content-Type": "application/json"
        },
        json=payload
    )

    # Process response
    if response.status_code == 200:
        ai_response = response.json()['data']['response']

        # Add AI response to conversation history
        conversation.append(f"AI: {ai_response}")

        return ai_response
    else:
        return f"Error {response.status_code}: {response.text}"

# Example conversation
print(chat_with_ai("Hello, I'd like to discuss our Q1 financial results.", 
                  media_id="vec-38fn4098fn3049rj09jj9409jjjkdd"))
print(chat_with_ai("What were our biggest expenses?"))
print(chat_with_ai("How does that compare to last year?"))

Response

Success Response (200 OK)

{
  "success": true,
  "message": "LLM query processed successfully",
  "data": {
    "response": "Based on the quarterly report, the main points are: 1) Revenue increased by 15% year-over-year to $42.3M, 2) Gross margin improved from 52% to 56%, 3) Customer acquisition costs decreased by 12%, 4) Churn rate improved from 3.2% to 2.7%, and 5) The company launched two new product features that contributed $3.8M in new revenue.",
    "billing": {
      "total_cost": 0.01,
      "base_fee": 0.01,
      "token_charges": 0.0,
      "usage": {
        "context_tokens": 8520,
        "response_tokens": 105,
        "total_tokens": 8625,
        "processing_time_ms": 850
      },
      "pricing_tier": "minimum"
    },
    "request": {
      "query": "What are the main points in the quarterly report?",
      "temperature": 0.5,
      "max_tokens": 2048,
      "disclaimer": "Note: This content was generated by AI and may not always be accurate or complete. Please verify the information before using it for important business, legal, health, financial, or similar matters."
    },
    "media_context": {
      "media_id": "vec-38fn4098fn3049rj09jj9409jjjkdd",
      "media_type": "document",
      "collection": "financial_reports",
      "created_at": "2025-03-15T14:30:22Z"
    }
  },
  "metadata": {
    "request_id": "llm_f8az93jd72kla",
    "model": "gemini-2.0-flash",
    "api_version": "1.0.0"
  }
}

Response Fields

Response Content

Field Description
response The AI's answer to your query

Billing Information

Field Description
billing.total_cost Total cost of the query in USD
billing.base_fee Base fee for each query ($0.01)
billing.token_charges Additional charges based on token usage
billing.usage.context_tokens Number of input tokens (query, context, and media)
billing.usage.response_tokens Number of output tokens generated
billing.usage.total_tokens Total tokens processed
billing.usage.processing_time_ms Processing time in milliseconds
billing.pricing_tier "minimum" (just base fee) or "standard" (base fee + token charges)

Request Information

Field Description
request.query Your original query
request.temperature Temperature value used
request.max_tokens Maximum tokens setting used
request.disclaimer Disclaimer about AI-generated content

Media Context (if media_id was provided)

Field Description
media_context.media_id ID of the media used for context
media_context.media_type Type of media (document, image, video, audio, model)
media_context.collection Collection the media belongs to
media_context.created_at Timestamp when the media was uploaded

Metadata

Field Description
metadata.request_id Unique identifier for the request
metadata.model AI model used (from the Gemini family)
metadata.api_version API version

Error Scenarios

Status Code Error Type Description
400 Missing Parameters Missing required query parameter
400 Invalid Parameter Invalid temperature (must be 0.0-1.0) or max_tokens (must be 1-4096)
400 Invalid Format Invalid media_id format (must start with 'vec-')
400 Token Limit Input token count exceeds maximum of 100,000 tokens
401 Unauthorized Invalid or missing API key
402 Insufficient Balance Account balance too low for the operation
404 Not Found Specified media_id not found
429 Too Many Requests Rate limit exceeded
500 Processing Error Error during query processing
503 Service Unavailable Service temporarily unavailable

Usage Limits

Token Limits

Category Limit
Maximum Input Tokens 100,000 (combined query, context, system prompt, and media)
Maximum Output Tokens 4,096

Costs and Pricing

  • Base Cost: $0.01 per query
  • Input Tokens: $0.10 per 1 million tokens
  • Output Tokens: $0.40 per 1 million tokens

Note: The current beta pricing is designed to be simple and affordable. For most queries, you'll pay just the base fee of $0.01. Additional token charges only apply when processing very large inputs or generating extensive outputs.

Best Practices

Using Media Context Effectively

  • When providing a media_id, be specific in your query about what information you need from the media.
  • Example: Instead of "Tell me about this document", ask "What are the financial projections for Q3 in this report?"
  • Media IDs always start with vec- followed by a unique identifier (e.g., vec-38fn4098fn3049rj09l2409jdfka9).

Managing Conversation History

  • Use the context parameter to provide conversation history for multi-turn interactions.
  • Format context as a clear back-and-forth dialogue (e.g., "User: [message]\nAI: [response]\nUser: [message]").
  • Only include relevant previous exchanges to maintain context without exceeding token limits.

Controlling Response Style

  • Use temperature to control response style:
  • Lower values (0.1-0.3): More deterministic, factual, concise responses
  • Medium values (0.4-0.7): Balanced responses with some creativity
  • Higher values (0.8-1.0): More creative, varied, and potentially unexpected responses

System Prompts

  • Use system_prompt to guide the AI's approach:
  • Role specification: "Act as a financial analyst reviewing this report"
  • Tone guidance: "Respond in a simple, educational manner"
  • Format instruction: "Structure your response as bullet points"

AI Disclaimer

Content generated by this endpoint is created by AI and may not always be accurate or complete. Please verify any important information before using it for business, legal, health, financial, or other critical matters.

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.