Wizzo AI Streaming API

Streaming chat (Server-Sent Events)

Returns the AI answer token-by-token as an SSE stream. Use this when you want to render the answer live as it is generated.

• {"type":"chunk","content":"..."} - one or more, with the next text fragment
• {"type":"action","subtype":"tool_calls","calls":[...]} - emitted once if the model called a tool
• {"type":"done","input_tokens":N,"output_tokens":N,"wizzo_tokens":N} - terminal success event
• {"type":"error","message":"...","code":"..."} - terminal error event

Non-streaming chat (legacy PHP-compat)

Returns the full AI answer as a STRING in `data`, matching the legacy PHP m_ai::call() shape. When settings.json=true the string is cleaned (markdown fences/Hebrew quote escapes removed) and is safe to pass through json_decode() on the client. Use /api/ai/json when you want the response already parsed.

{
  "data": "The full answer as a string (raw text, or a JSON string when settings.json=true, or {type:\"tool_calls\",calls:[...]} when the model called a tool)"
}

Non-streaming chat - parsed JSON

Like /api/ai but forces settings.json=true and returns the answer ALREADY PARSED as an object/array in `data`. Use this when you want to skip the json_decode() step on the client.

{
  "data": {
    "example_field": "parsed object/array - depends on the model output"
  }
}

Image generation / editing

Generate an image (or edit one when settings.image_input is provided). Returns an array of public URLs hosted on stream.ai.wizzo.media (valid for 24 hours).

{
  "data": [
    "https://stream.ai.wizzo.media/uploads/ai_images/openai_173...png"
  ]
}

Text embedding vector

Returns an OpenAI embedding vector for the given text (defaults to text-embedding-3-small, 1536 dims).

{
  "data": [
    0.0123,
    -0.0456,
    "..."
  ]
}

List available models

Returns the active model catalog (id, name, provider, features, defaults) priced for YOUR account in wizzo tokens: tokens_input / tokens_output / tokens_cached_input per 1M tokens, tokens_per_call, tokens_per_minute, tokens_per_unit for media models.

{
  "data": {
    "models": [
      {
        "id": 1,
        "name": "gpt-5-mini",
        "provider": "openai",
        "tokens_input": 75000,
        "tokens_output": 600000,
        "features_images": false,
        "default_model": true
      }
    ],
    "price_unit": "wizzo tokens ..."
  }
}

OpenAI Realtime ephemeral session

Mints a short-lived OpenAI Realtime client secret (GA API) for browser WebRTC voice: client_secret.value, expires_at, model, sdp_url. Rate-limited to 5/minute per user.

{
  "voice": "shimmer (default) | alloy | echo | ..."
}

Report Realtime session usage (billing)

Called by the client when a voice session ends. Body: { duration_ms: number }.

Speech-to-text transcription

Transcribes an audio file. Send multipart/form-data with a `file` field (up to 64MB; OpenAI models cap at 25MB), or JSON with base64 `audio_input` + `mime`. Optional fields: model (default: the flagged transcription default), language (ISO-639-1 hint, e.g. "he"), prompt (vocabulary hint), response_format (json | text | srt | vtt | verbose_json | diarized_json), timestamps ("segment" | "word" | "both", whisper-1 only), diarize ("1" for speaker labels via a *-diarize model). Billed per audio minute (price_per_minute) or by tokens for token-billed models. API-key auth only. Rate-limited to 20/minute per user.

{
  "success": true,
  "data": {
    "text": "...",
    "language": "he",
    "duration": 12.4,
    "segments": null,
    "model": "gpt-transcribe",
    "provider": "openai",
    "wizzo_tokens": 5
  }
}

Health check

No auth. Returns { status: "ok", timestamp }.

MCP endpoint (JSON-RPC 2.0, Streamable HTTP, stateless)

The same account/usage tools as the WizzoCMS admin panel (ai_dashboard, ai_usage_logs, ai_log_detail, ai_models, ai_test_flight), for any MCP client — including the Wizzo Market gateway (mcp.wizzo.market). Auth: "Authorization: <wizzoai api_key>" (or "Bearer <api_key>"), OR a Wizzo Market MCP token ("Bearer wzm_…" / "Bearer wza_…"), resolved via the market's mcp_introspect and mapped to this account by market_id. Methods: initialize, tools/list, tools/call, notifications/* (202).

List prompts

{
  "data": {
    "prompts": [
      {
        "id": 1,
        "sysname": "headline_v2",
        "model": "gpt-5-mini",
        "version": 3,
        "comment": "",
        "updated_at": "2026-09-07 10:00:00",
        "preview": "first 120 chars"
      }
    ]
  }
}

Get a prompt by sysname

{
  "data": {
    "id": 1,
    "sysname": "headline_v2",
    "content": "...",
    "model": "gpt-5-mini",
    "version": 3,
    "comment": "",
    "updated_at": "..."
  }
}

Create

{
  "sysname": "headline_v2",
  "content": "כתוב כותרת על {$topic}",
  "model": "gpt-5-mini",
  "comment": "optional"
}

{
  "data": {
    "id": 1,
    "version": 1
  }
}

Update (partial)

{
  "content": "?",
  "model": "?",
  "comment": "?",
  "sysname": "?"
}

{
  "data": {
    "id": 1,
    "version": 4,
    "changed": true
  }
}

Delete (cascades versions)

{
  "data": true
}

Version history, newest first

{
  "data": {
    "versions": [
      {
        "id": 9,
        "version_number": 3,
        "model": "",
        "comment": "",
        "is_current": true,
        "created_at": "...",
        "content": "..."
      }
    ]
  }
}

Restore a version (creates a new version with the old content)

{
  "version_number": 2
}

{
  "data": {
    "version": 4
  }
}

Render with vars

{
  "vars": {
    "topic": "חורף"
  }
}

{
  "data": {
    "content": "כתוב כותרת על חורף",
    "model": "gpt-5-mini"
  }
}

Shortcut: prompt_ref + vars

Send prompt_ref: "<sysname>" and vars: {} instead of prompt. The stored model is used when the request has none and settings.type defaults to "prompt:<sysname>". 404 prompt_not_found.

{
  "prompt_ref": "headline_v2",
  "vars": {
    "topic": "חורף"
  }
}

List with weekly stats, plus templates, the tool catalog (builtin + the Wizzo services of the site as <service>:*) and global_active

{
  "data": {
    "agents": [
      {
        "id": 1,
        "slug": "daily_report",
        "title": "",
        "trigger_type": "schedule",
        "crontime": "0 8 * * *",
        "next_run": "...",
        "last_run": "...",
        "status": "scheduled",
        "runs_week_ok": 5,
        "runs_week_failed": 0
      }
    ]
  }
}

Get definition

Create

{
  "title": "דוח יומי",
  "slug": "daily_report",
  "description": "",
  "goal": "אסוף את החדשות של אתמול וסכם",
  "system_prompt": "...",
  "tools": [
    "builtin:fetch_url",
    "builtin:web_search"
  ],
  "model": "gpt-5",
  "trigger_type": "schedule",
  "crontime": "0 8 * * *",
  "limits": {
    "max_steps": 30,
    "max_tokens": 300000
  },
  "webhook_url": "https://example.com/hooks/agent",
  "is_active": 1
}

{
  "data": {
    "id": 1
  }
}

Update (partial)

Delete (runs and memory too)

Run now

{
  "prompt": "optional extra instruction",
  "dry_run": false
}

{
  "data": {
    "run_id": 12,
    "job_id": 340,
    "status": "queued"
  }
}

Test run (dry_run: tools get __dry_run: true). body.clean = run without the previous run summary

Switch on/off. A dashboard draft (created with require_test) needs one successful test run first (409 need_test)

{
  "on": true
}

Answer a finished run: opens a continuation run that resumes the conversation (fresh: true = same instruction, clean head)

{
  "message": "הסיכום ארוך מדי, תן רק 3 סיפורים",
  "fresh": false
}

{
  "data": {
    "ok": true,
    "run_id": 13
  }
}

The recruiter: free text in, draft_updates out (title, goal, trigger, crontime, tools, approval_mode)

{
  "messages": [
    {
      "role": "user",
      "content": "סוכן שמסכם לי כל בוקר חדשות טכנולוגיה"
    }
  ],
  "draft": {}
}

Global switch for every agent of the account

{
  "on": false
}

Runs, newest first (status synced from the runtime)

{
  "data": {
    "runs": [
      {
        "id": 12,
        "job_id": 340,
        "trigger_src": "manual",
        "dry_run": 0,
        "status": "done",
        "summary": "...",
        "error": null,
        "steps_count": 4,
        "tokens_in": 0,
        "tokens_out": 0,
        "wizzo_tokens": 0,
        "created_at": "...",
        "started_at": "...",
        "finished_at": "..."
      }
    ]
  }
}

Run detail with the step timeline (?narrate=1 adds a Hebrew one-liner per tool step, billed to the account)

{
  "data": {
    "run": {},
    "steps": [
      {
        "step_num": 1,
        "type": "tool",
        "tool_name": "builtin:fetch_url",
        "tool_args": "{...}",
        "tool_result": "{...}",
        "duration_ms": 120
      }
    ]
  }
}

Cancel

{
  "data": {
    "status": "cancelled"
  }
}

Memory rows (playbook + insight rows are appended to the system prompt on every run)

Add memory

{
  "kind": "playbook",
  "mem_key": "style",
  "mem_value": "כתוב קצר"
}

Delete memory row

Enqueue a run

{
  "system_prompt": "...",
  "prompt": "?",
  "model": "?",
  "limits": {
    "max_steps": 30,
    "max_tokens": 300000
  },
  "idempotency_key": "?",
  "tool_servers": [
    {
      "name": "cms",
      "url": "https://.../mcp",
      "token": "..."
    }
  ],
  "allowed_tools": [
    "cms:save_record",
    "builtin:fetch_url"
  ],
  "report_url": "?",
  "run_secret": "?",
  "dry_run": false,
  "type": "agent"
}

{
  "data": {
    "run_id": 340,
    "status": "queued"
  }
}

Run status

{
  "data": {
    "run_id": 340,
    "status": "done",
    "steps_count": 4,
    "tokens_in": 0,
    "tokens_out": 0,
    "wizzo_tokens": 0,
    "summary": "...",
    "error": null
  }
}

Cancel a run

Speech-to-text

multipart/form-data `file` (up to 64MB) or JSON {audio_input (base64/data URL), mime}. Fields: model, language ("he"), prompt, response_format (json|text|srt|vtt|verbose_json|diarized_json), timestamps, diarize. API key only. 300 requests/minute per account.

{
  "success": true,
  "data": {
    "text": "...",
    "language": "he",
    "duration": 12.4,
    "wizzo_tokens": 5
  }
}

Image generation / editing

Returns public URLs under /uploads/ai_images that EXPIRE AFTER 24 HOURS. Copy the file if you need it longer.

{
  "data": [
    "https://stream.ai.wizzo.media/uploads/ai_images/....png"
  ]
}

Video, speech, talking avatar (a job)

Body: {model, prompt (video: the scene; speech: the text; avatar: the script), settings, webhook_url?}. Video (fal.ai: fal-ai/veo3.1, fal-ai/veo3.1/fast, fal-ai/kling-video/v3/pro/...): settings.duration (seconds), aspect_ratio, resolution, generate_audio (default true), image_url for image-to-video. Speech (ElevenLabs: eleven_v3, eleven_v4, eleven_v4_turbo, Hebrew included): settings.voice_id, language_code, output_format; finished inside the call. Avatar (HeyGen: heygen/avatar-iii|iv|v with settings.avatar_id, heygen/photo-avatar-iv with settings.image_url and voice_id). Answers 202 with the job; read it with GET /api/media/jobs/{id} until status is done or failed. Billed per the model unit (second of video, 1,000 characters, minute of avatar); a failed job costs nothing. A prepaid account must hold the estimate (402 otherwise). Files are ours, kept 7 days (expires_at). webhook_url (https) gets one POST {event: "media.job.finished", job} when it ends.

{
  "data": {
    "id": 12,
    "kind": "video",
    "model": "fal-ai/veo3.1/fast",
    "status": "running",
    "result_url": null,
    "unit": "second",
    "units": 0,
    "estimated_units": 4,
    "wizzo_tokens": 0
  }
}

A media job

status queued|running|done|failed; when done: result_url (our copy), mime, units billed, wizzo_tokens, expires_at. GET /api/media/jobs?status=&limit= lists the account's recent jobs.

{
  "data": {
    "id": 12,
    "status": "done",
    "result_url": "https://stream.ai.wizzo.media/uploads/ai_media/video_....mp4",
    "unit": "second",
    "units": 4,
    "wizzo_tokens": 60000
  }
}

Cancel a media job

Lets a video still waiting in the provider queue go: it ends failed with error "cancelled" and costs nothing (cancelled: true). A render the provider already started cannot be stopped: it ends done and is billed as usual, and the answer is the job as it is with cancelled: false. Avatars and speech are never cancelled.

{
  "data": {
    "id": 12,
    "status": "failed",
    "error": "cancelled",
    "units": 0,
    "cost_usd": 0
  },
  "cancelled": true
}

Embedding vector

{
  "text": "...",
  "type": "article_embedding",
  "model": "text-embedding-3-small"
}

{
  "data": [
    0.01,
    -0.02
  ],
  "input_tokens": 12,
  "wizzo_tokens": 1
}

OpenAI Realtime ephemeral session (voice)

5 sessions/minute per account. Report usage with POST /api/realtime/usage {duration_ms}; a session is billed up to 45 minutes.

Account info + monthly usage

Stats for a date_range (month_offset_0 ...)

Paginated prompt history (page, per_page, search, type, model)

One log row with its settings

{
  "log_id": 1
}

Set the monthly budget

{
  "budget": 100000
}

Model catalog