API reference

Drop-in for the OpenAI SDK: change base_url and api_key. model can be auto or a catalog slug from GET /v1/models. Extra fields: optimize (auto | cheap | fast | quality), max_cost (USD), allow_model_fallback. Supports streaming, tools, JSON schema, temperature, max_tokens (default 4096).

from openai import OpenAI
client = OpenAI(api_key="mk_live_...", base_url="https://app.monokey.ai/v1")
r = client.chat.completions.create(model="auto", messages=[{"role": "user", "content": "Explain duration risk."}])
print(r.choices[0].message.content, r.usage)   # usage includes billed_amount

curl https://app.monokey.ai/v1/generate -H "Authorization: Bearer mk_live_..." -H "Content-Type: application/json" -d '{
  "messages": [{"role": "user", "content": "Summarize this in one line: ..."}],
  "optimize": "quality", "max_cost": 0.03
}'
# → { id, model, content, finish_reason, usage: { input_tokens, output_tokens, billed_amount, currency }, route: { provider, model, reason, fallback_count, task_type }, latency_ms }
# stream: true → Server-Sent Events: start, delta, tool_call_delta, done, error (recoverable), end

{ "query": "latest NVIDIA AI chip announcement", "num_results": 10, "optimize": "auto" }
# → { id, results: [{ title, url, snippet, published_at, source }], route, usage: { billed_amount }, latency_ms }

Multipart file (PDF or image, ≤ 50 MB / 300 pages) or JSON { url | file_id }. Options: output = markdown | text | json, optimize, max_cost, async. Small digital documents return immediately; larger ones return 202 { id: "job_…", status: "queued" } — poll GET /v1/jobs/:id.

curl https://app.monokey.ai/v1/parse -H "Authorization: Bearer mk_live_..." -F file=@report.pdf -F output=markdown
# → { id, status: "completed", markdown, metadata: { page_count, kind, is_digital, task_type }, route, usage: { pages, billed_amount }, latency_ms }

Prerecorded MP3 / WAV / M4A / MP4 (≤ 250 MB / 4 h). Options: language, diarization, optimize, max_cost. Clips over 60 s return a job.

curl https://app.monokey.ai/v1/transcribe -H "Authorization: Bearer mk_live_..." -F file=@meeting.mp3 -F diarization=true
# → { id, status, text, segments: [{ start, end, speaker, text }], language, route, usage: { minutes, billed_amount }, latency_ms }

GET  /v1/jobs/:id        → { id, status: queued|processing|completed|failed, result?, error? }
POST /v1/files           (multipart file) → { id: "file_…", expires_at }   # reuse with file_id
POST /v1/feedback        { "request_id": "req_…", "success": true, "score": 0.9 }
GET  /v1/models          OpenAI-style list of models you can pin
GET  /v1/me              org, mode, trial, wallet balance

• Requests are classified by rules (never by another model call), incompatible routes are removed before any scoring.
• Presets: auto (quality 40 / cost 30 / reliability 20 / latency 10), cheap (cost 70), fast (latency 60), quality (quality 70). Heuristics, not guarantees.
• A specific model may fail over to the same model on another provider, never to a different model unless allow_model_fallback: true.
• Streaming: failover only before the first token; afterwards you receive a recoverable error event, never spliced output.
• Credit is reserved at an upper bound before execution and settled to the actual retail price afterwards. Test keys (mk_test_) use a mock provider and are free.