Wizzo AI Streaming API

All endpoints (except /api/health) require:

Authorization: <API_KEY>

Send the raw wizzoai API key in the Authorization header, WITHOUT the "Bearer" prefix. "Bearer <jwt>" is reserved for short-lived public tokens you sign server-side (see public_jwt_mode). PHP CORE sites get the key via market_service::api_key("wizzoai").

{
  "model": "string (optional) - e.g. \"gpt-5\", \"gemini-2.5-pro\". Defaults to provider default.",
  "provider": "string (optional) - \"openai\" | \"gemini\" | \"anthropic\" | \"xai\". Defaults to \"openai\".",
  "prompt": "string (required) - the user message.",
  "prompt_ref": "string (optional) - sysname of a library prompt to use instead of prompt (rendered with vars).",
  "vars": "object (optional) - values for the {$var} placeholders of prompt_ref.",
  "settings": {
    "type": "string - log/billing tag (e.g. \"article_generation\").",
    "system_msg": "string - system prompt.",
    "history": "array - previous turns: [{role:\"user\"|\"assistant\"|\"tool\", content|name|tool_call_id|...}].",
    "max_tokens": "number - response length limit (default 15000).",
    "temperature": "number | null - sampling temperature.",
    "top_p": "number | null - nucleus sampling (0-1).",
    "presence_penalty": "number | null - penalize new tokens based on presence in text so far (-2 to 2). OpenAI/xAI only.",
    "frequency_penalty": "number | null - penalize new tokens based on frequency in text so far (-2 to 2). OpenAI/xAI only.",
    "json": "bool - if true, the answer is parsed as JSON before being returned.",
    "json_schema": "string|object - optional JSON schema for structured output.",
    "image_input": "string | string[] - URL / data-URI / base64 image(s) for vision or image editing. URLs are downloaded server-side with anti-bot fallbacks.",
    "tools": "array - tool/function definitions (OpenAI-style) for tool-calling.",
    "web_search": "bool - enable provider web-search tool when supported."
  }
}

1. Get your api key from the WizzoAI dashboard (or market_service::api_key("wizzoai") in a PHP CORE site).
2. Send it as-is in the Authorization header on every request: "Authorization: <API_KEY>" (no Bearer prefix).
3. POST /api/ai with { prompt } for a full answer, /api/ai/json for a parsed JSON answer, /api/ai/stream for SSE.
4. Every success is { data: ... } plus usage fields; every failure is { error, message } with a 4xx/5xx status.

curl -X POST https://stream.ai.wizzo.media/api/ai \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"כתוב כותרת לכתבה על מזג האוויר","model":"gpt-5-mini","settings":{"type":"headline"}}'

const res = await fetch('https://stream.ai.wizzo.media/api/ai/json', {
  method: 'POST',
  headers: { 'Authorization': 'YOUR_API_KEY', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    prompt_ref: 'headline_v2',          // a prompt from your library
    vars: { topic: 'מזג האוויר' },      // fills {$topic}
    settings: { json: true }
  })
});
const { data, wizzo_tokens } = await res.json();

$ch = curl_init('https://stream.ai.wizzo.media/api/ai');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: YOUR_API_KEY', 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode([
        'prompt' => 'סכם את הטקסט הבא בשלוש נקודות: ...',
        'settings' => ['type' => 'summary', 'max_tokens' => 800]
    ])
]);
$res = json_decode(curl_exec($ch), true);
echo $res['data'];

import requests
r = requests.post('https://stream.ai.wizzo.media/api/ai/json',
    headers={'Authorization': 'YOUR_API_KEY'},
    json={'prompt': 'Return {"ok":true}', 'settings': {'json': True}})
print(r.json()['data'])

const res = await fetch('https://stream.ai.wizzo.media/api/ai/stream', {
  method: 'POST',
  headers: { 'Authorization': 'YOUR_API_KEY', 'Content-Type': 'application/json' },
  body: JSON.stringify({ prompt: 'ספר לי בדיחה' })
});
const reader = res.body.getReader(); const dec = new TextDecoder(); let buf = '';
while (true) {
  const { done, value } = await reader.read(); if (done) break;
  buf += dec.decode(value, { stream: true });
  let i; while ((i = buf.indexOf('\n\n')) !== -1) {
    const line = buf.slice(0, i); buf = buf.slice(i + 2);
    if (line.startsWith('data:')) { const ev = JSON.parse(line.slice(5)); if (ev.type === 'chunk') process.stdout.write(ev.content); }
  }
}

wizzo_tokens

The billing unit. Every call returns wizzo_tokens: the provider price of the call (input, cached input, output) converted at the account token rate. The dashboard shows monthly usage in wizzo tokens.

budget

Each account has a monthly wizzo-token budget (change_budget). When it is exhausted the API answers 403 { error: "monthly_limit" } until the next month or a budget change. Listing/dashboard endpoints keep working.

types

settings.type is a free tag stored on every log row (e.g. "headline", "summary"). Use it to break usage down per feature in the dashboard. prompt_ref sets it to "prompt:<sysname>", agents to "agent:<slug>".

models

GET /api/models lists the catalog with prices and features. Omit model to get the provider default. The server falls back to another provider automatically on outages unless settings.allowed_providers fences it.

prompts

A prompt library with {$var} templating and versions. Call any endpoint with prompt_ref + vars instead of prompt.

agents

Long-running server-side loops (model + builtin tools) with a step budget, a token budget, persisted steps, optional cron schedule and a finish webhook.

sysname ^[a-z0-9_]{2,64}$. A new version is created only when the content (whitespace-normalised) or the model changes.

tools: ["builtin:fetch_url", "builtin:web_search"] (only builtin:<name> references are accepted; anything else -> 400 invalid_tools). trigger_type schedule needs a 5-field crontime (Asia/Jerusalem); invalid -> 400 bad_cron. limits {max_steps 1..120, max_tokens 1000..2000000}. When a run finishes and webhook_url is set, it receives POST {agent, run_id, status, summary, error, tokens}.

Lower-level API used by the CMS: you send the whole run definition, including MCP tool servers, and reconcile by polling.

Never ship your api key to a browser. Sign a short-lived HS256 token server-side with the shared WIZZO_PUBLIC_JWT_SECRET and send it as "Authorization: Bearer <token>". Claims: site_id (your account id), feature ("public_chat"), optional origin (must equal the browser Origin header), optional grants {model, provider, settings:{...}, client_keys:[...]}, exp. JWT calls are clamped: max_tokens <= 2000 unless granted, no system_msg, no image input, no dashboard endpoints, no image generation, no transcription. Errors: 401 token_expired / invalid_token, 403 origin_mismatch.

realtime_session 5 per minute per account (GET /api/realtime/session), 429 rate_limit

realtime_max_session 45 minutes billed per session (POST /api/realtime/usage caps duration_ms)

transcribe 300 per minute per account (POST /api/transcribe), 429 rate_limit

monthly_budget When the monthly wizzo-token budget is reached every billable call returns 403 monthly_limit (limit_reached from the auth layer) until the next month or a budget change

agent_steps agents are bounded by limits.max_steps and limits.max_tokens

agent_concurrency 3 running agent jobs per account, 8 globally; extra jobs wait in the queue

image_urls Generated image URLs expire after 24 hours

payload JSON bodies up to 50MB; transcription files up to 64MB (OpenAI models 25MB)

4xx for client errors (prompt_not_set, monthly_limit, INVALID_TOOL_CALL, ...), 5xx for provider/server errors

{
  "error": "short_code",
  "message": "human readable Hebrew message"
}

auth error 401: missing/invalid api key, or inactive account

token_expired 401: JWT expired

invalid_token 401: JWT malformed or missing claims

forbidden 403: endpoint needs an api key (JWT not allowed)

origin_mismatch 403: JWT origin claim differs from the Origin header

limit_reached 403: monthly budget reached (auth layer)

monthly_limit 403: monthly budget reached (during a call)

rate_limit 429: too many requests for this endpoint

prompt_not_set 400: prompt missing

prompt_not_found 404: prompt_ref does not exist

INVALID_TOOL_SCHEMA 400: settings.tools definition invalid

INVALID_TOOL_CALL 400: the model produced a tool call that failed validation

provider_not_allowed 400: the model resolved to a provider outside settings.allowed_providers

not_found 404: row not found

exists 409: unique name/slug/key already used

invalid_sysname 400: sysname/slug must match ^[a-z0-9_]{2,64}$

invalid_tools 400: agent tools must be builtin:<name> references

invalid_webhook 400: agent webhook_url must be https and public

bad_cron 400: crontime is not a valid 5-field cron expression

content_required 400: content missing

INVALID_RUN_REQUEST 400: agent run body invalid

transcribe_not_supported 400: model cannot transcribe

file_too_large 400: audio exceeds the limit

server_error 500: unexpected server error