Oppermind Lato 1 API

Oppermind Lato 1 reads text, images and documents, calls the developer's functions and built-in tools, and generates images and video. Each endpoint handles one kind of output: text endpoints return text and tool calls, /images returns images, /videos returns video.

Base URL

• Public: https://www.oppermind.com/api/v1
• Sites hosted on Oppermind are static and run in a sandbox: call the API from a server you control, never from page JavaScript.

Authentication

• Every request must include: Authorization: Bearer <api_key> (keys start with opmd_sk_)
• Content-Type: application/json
• Security: never expose API keys client-side. Proxy through a backend.

Models

Any "model" value is accepted. Responses always report the Oppermind model id.

Text endpoints

• POST {base}/messages (alias POST {base}/chat): Chat Completions style request, Oppermind native response.
• POST {base}/chat/completions: Chat Completions compatible request and response. Any Chat Completions client library works with baseURL https://www.oppermind.com/api/v1 and model oppermind-lato-1. Only n = 1. logprobs, logit_bias and legacy functions/function_call return 400.
• POST {base}/responses: Responses API compatible request and response. Stateless: previous_response_id, conversation, stored prompts, store: true and background: true return 400 OPMD_MODEL_001. Send the whole conversation in input.
• stream: true works on all three text endpoints. See Streaming.

Streaming

• Send "stream": true to /messages, /chat/completions or /responses for server-sent events.
• /chat/completions: chat.completion.chunk objects in data: lines, then data: [DONE]. The last chunk carries finish_reason, usage and billing. With stream_options: { "include_usage": true } usage also arrives in a final chunk with empty choices.
• /responses: response.created, response.output_text.delta, function call events, then response.completed (or response.incomplete) with the full response, usage and billing.
• /messages: message_start, content_block_start, content_block_delta (text_delta or input_json_delta), content_block_stop, message_delta (stop_reason, usage, billing), then message_stop.
• Text arrives about 100 tokens behind the model because every piece is checked before it is sent.
• Billing settles when the reply ends. A client that disconnects is charged for the text produced up to that point. A reply with no answer ends with its finish reason and a notice, and is not charged under the same rule as a non-streamed reply.
• An error after the stream starts arrives as an error event: an error object in a data line for /chat/completions, error then response.failed for /responses, an error event for /messages.

POST /api/v1/messages

Request body (Chat Completions format):

{
  "model": "oppermind-lato-1",
  "max_tokens": 1024,
  "messages": [
    { "role": "system", "content": "Answer briefly." },
    { "role": "user", "content": [
      { "type": "text", "text": "Summarise this report." },
      { "type": "file", "file": { "file_id": "file-0123456789abcdef0123456789abcdef" } }
    ] }
  ]
}

Roles: system, developer, user, assistant, tool. A tool message needs the tool_call_id of an earlier assistant tool call.

Response (Oppermind native):

{
  "id": "req_...",
  "model": "oppermind-lato-1",
  "type": "message",
  "content": [ { "type": "text", "text": "..." } ],
  "usage": { "input_tokens": 1830, "output_tokens": 256, "cache_read_input_tokens": 0, "cache_creation_input_tokens": 0, "reasoning_tokens": 0 },
  "stop_reason": "end_turn",
  "tool_usage": {},
  "billing": { "charged_aud": "0.001234" }
}

• Function calls arrive as content blocks { "type": "tool_use", "id", "name", "input" } with stop_reason "tool_use".
• stop_reason: end_turn | max_tokens | tool_use | refusal. Web search adds a "citations" array of { url, title }.

POST /api/v1/chat/completions

Response: { id, object: "chat.completion", created, model, choices: [ { index, message: { role, content, tool_calls?, annotations? }, finish_reason } ], usage: { prompt_tokens, completion_tokens, total_tokens, prompt_tokens_details: { cached_tokens }, completion_tokens_details: { reasoning_tokens } }, tool_usage? (only when built-in tools ran), billing: { charged_aud } } finish_reason: stop | length | tool_calls | content_filter.

POST /api/v1/responses

Request: { model, instructions?, input: string or array of items, tools?, tool_choice?, text?: { format }, max_output_tokens?, reasoning?: { effort }, temperature?, top_p?, prompt_cache_key?, user? } Input items: { role, content } messages (system, developer, user, assistant), { type: "function_call", call_id, name, arguments }, { type: "function_call_output", call_id, output }. Reasoning items are accepted and ignored. Content parts: input_text, input_image { image_url | file_id, detail }, input_file { file_id | file_data, filename }. Response: { id: "resp_...", object: "response", created_at, status: completed | incomplete, incomplete_details?, model, output: [ message with output_text content | function_call ], output_text, usage: { input_tokens, input_tokens_details: { cached_tokens }, output_tokens, output_tokens_details: { reasoning_tokens }, total_tokens }, tool_usage, billing: { charged_aud } } seed and stop are read on /messages and /chat/completions only.

Inputs: images and documents

• Images: { "type": "image_url", "image_url": { "url": "https://... or data:image/png;base64,...", "detail": "auto|low|high" } }. JPEG, PNG, GIF or WebP as a base64 data URL (GIF and WebP are converted to PNG; an animation keeps its first frame), or JPEG or PNG as an https URL.
• Documents: { "type": "file", "file": { "file_id": "file-..." } } or { "type": "file", "file": { "file_data": "data:application/pdf;base64,...", "filename": "report.pdf" } }. PDF (including scanned PDFs, read page by page up to 20 pages), Word, Excel, PowerPoint (including macro-enabled and legacy files), OpenDocument, project schedules (MPP, MS Project XML, Primavera XER/XML, MPX), CSV, TXT, MD, JSON, code. A PDF sent as an image_url data URL is also read as a document.
• Text beyond 1,000,000 characters per document is cut off with a note. A file that cannot be read returns 422 OPMD_FILE_002. Every file is checked for malware before it is stored or read; a file that fails returns 422 OPMD_FILE_003.
• Request bodies up to 31 MB. Up to 2000 messages per request.

Files API

• POST {base}/files: raw bytes with header X-Filename (URL-encoded) or ?filename=, or JSON { "filename", "data": base64 or data URL, "mime_type"?, "purpose"? }. Or multipart/form-data with the file in a field named file and an optional purpose field. Up to 31 MB per request, one file per request.
• GET {base}/files (?limit=1..1000, default 100, ?after=<file id>) returns { object: "list", data, has_more, first_id, last_id }.
• GET {base}/files/{id} returns { id, object: "file", bytes, created_at, filename, purpose, mime_type }.
• GET {base}/files/{id}/content returns the bytes.
• DELETE {base}/files/{id} returns { id, object: "file", deleted: true }.
• Per account: up to 1,000 files and 10 GiB. File ids look like file-<32 hex>.

Tools

• Function calling: tools: [ { "type": "function", "function": { "name", "description", "parameters" } } ] (the flat Responses shape works too), tool_choice: auto | none | required | { "type": "function", "function": { "name" } }, parallel_tool_calls.
• Built-in: { "type": "web_search", "filters": { "allowed_domains": [...] } or { "excluded_domains": [...] }, "max_uses"? (400 OPMD_CAPABILITY_001 where a cap cannot be enforced) }, { "type": "x_search", "allowed_x_handles"?, "excluded_x_handles"?, "from_date"?, "to_date"? }, { "type": "code_interpreter" }, { "type": "mcp", "server_url": "https://...", "server_label", "allowed_tools"?, "authorization"?, "headers"? }.
• Some built-in tools or options may not be available on every model version: those return 400 OPMD_CAPABILITY_001 with a clear message.

Request options

• max_tokens / max_completion_tokens / max_output_tokens: default 16384, up to 128000. Reasoning tokens count as output.
• response_format: { "type": "json_object" } or { "type": "json_schema", "json_schema": { "name", "schema", "strict" } } (text.format on /responses).
• reasoning_effort (or reasoning.effort): none | minimal | low | medium | high | xhigh.
• temperature 0 to 2 and top_p 0 to 1 (model default when omitted), seed, stop (some model versions do not support stop), user.
• Caching is automatic: a repeated opening (system text, tools, documents) is served from cache, billed at the lower cached input rate and reported as cached tokens in usage. prompt_cache_key (optional) groups related requests to raise the cache hit rate. cache_control markers on content parts are accepted and used where the model version supports them. Only input is cached.

POST /api/v1/images

Endpoint: POST {base}/images 1 to 4 images per request (n outside that range is clamped), prompt up to 8 KB. Some options may not apply on every model version.

Request body:

{
  "model": "oppermind-lato-1-vision",
  "prompt": "A futuristic city at dusk",
  "n": 1,
  "aspect_ratio": "16:9",
  "response_format": "url"
}

Response: { "model": "oppermind-lato-1-vision", "data": [ { "url": "/api/v1/images/proxy?token=..." } ], "usage": { "images_generated": 1 } }. Fetch each url with the same bearer key.

POST /api/v1/videos

Endpoint: POST {base}/videos Video generation is synchronous - the response returns the finished video url directly. No polling is required. duration_seconds is 1 to 15 (clamped, default 10). resolution 720p or 1080p (default). Requires a key with full permission.

Request body:

{
  "model": "oppermind-lato-1-video",
  "prompt": "Ocean waves at sunset",
  "duration_seconds": 10,
  "resolution": "1080p"
}

Response:

{
  "id": "req_01abc123",
  "model": "oppermind-lato-1-video",
  "status": "succeeded",
  "url": "{base}/videos/proxy?token=...",
  "duration_seconds": 10,
  "resolution": "1080p"
}

GET /api/v1/videos/{id}

Endpoint: GET {base}/videos/{id} You probably do not need this. Video generation is synchronous, so POST {base}/videos already returns the finished url. This returns a confirmation only, and exists so clients written against a polling-style API do not break.

GET /api/v1/openapi.json

Endpoint: GET {base}/openapi.json The machine-readable OpenAPI 3.1 description of this API - point an SDK generator or Postman at it to scaffold a typed client. Public: no API key needed.

GET /api/v1/changelog

Endpoint: GET {base}/changelog Machine-readable changelog and deprecation policy. Poll this to learn about breaking changes before they reach you. Requires a valid API key.

GET /api/v1/pricing

Endpoint: GET {base}/pricing Current AUD rates: text per million input, cached input and output tokens, tools per built-in tool call, image.per_image, video.per_second_720p / per_second_1080p. image or video is null when that capability is not available. Rates can change, so read them from here instead of hardcoding them.

Error codes

/messages, /images and /videos return { "error": { "type", "code", "message" } }. /chat/completions, /responses and /files return { "error": { "message", "type", "code", "param" } }. Authentication and rate-limit errors use the first shape everywhere. Branch on error.code.

Response headers (useful for debugging)

• X-Request-ID: unique request ID
• X-Model: oppermind-lato-1
• X-Route-Type: text | image | video
• X-Powered-By: Oppermind Lato 1
• X-API-Version: dated contract build
• RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset
• Idempotent-Replay: true when a response is replayed for a repeated Idempotency-Key

Limits

• 120 requests per minute per API key unless the key has a different limit
• Request body: 31 MB. Messages or input items: 2000 per request
• Output tokens: default 16384, up to 128000
• Files: 31 MB per upload, 1,000 files and 10 GiB per account
• Images: prompt up to 8 KB, 1 to 4 per request. Video: 1 to 15 seconds

Webhooks

• Add endpoints in the developer dashboard (Settings, Webhooks). https on port 443 or 8443, public internet only. The signing secret (whsec_...) is shown once; it can be rolled.
• Events (JSON POST body { id: "evt_...", type, created, data }):
  • request.completed: data { request_id, endpoint, route_type, status, input_tokens?, output_tokens?, units?, charged_aud, latency_ms }
  • request.error: data { request_id, endpoint, route_type, status, error_code, latency_ms }
  • billing.threshold: data { credit_balance_aud, alert_threshold_aud } (once per drop below the alert threshold)
  • key.created / key.deleted: data { key_id, name, key_prefix, permissions }
  • webhook.test: sent by the dashboard's Send test button
• Headers: Oppermind-Event, Oppermind-Delivery (event id, same on every retry; use it to ignore repeats), Oppermind-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>" with the signing secret>. Verify against the raw body and reject timestamps more than 5 minutes old; compare with a constant-time comparison.
• Reply 2xx within 10 seconds. Other replies are retried after 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours; 50 failures in a row pause the endpoint. Events never contain prompts or responses.

Pricing

Prepaid credit at Oppermind's AUD rates: per million input tokens, per million cached input tokens, per million output tokens (reasoning tokens count as output), per built-in tool call, per image and per second of video. Rates can change. Current rates are on the developer dashboard Billing page and at GET {base}/pricing. Every text response reports its exact charge in billing.charged_aud. Requests the model rejects are not charged. Replies with no answer (OPMD_EMPTY_001) are not charged unless built-in tools already ran or more than 20 requests in the past hour returned no answer.

Client libraries

• There is no official SDK yet. Use any HTTP client, or any Chat Completions client library with baseURL https://www.oppermind.com/api/v1, apiKey opmd_sk_... and model oppermind-lato-1.
• cURL example (text):
  BASH

  curl {base}/messages -H "Authorization: Bearer opmd_sk_..." -H "Content-Type: application/json" -d '{"model":"oppermind-lato-1","max_tokens":1024,"messages":[{"role":"user","content":"Hello!"}]}'