Oppermind Lato 1 API
Oppermind Lato 1 reads text, images and documents, calls the developer's functions and built-in tools, and generates and edits 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
| Model ID | Modality | Endpoints | Billed per |
|---|---|---|---|
| oppermind-lato-1 | Text, images and documents in, text out | /messages, /chat/completions, /responses | Million input, cached input and output tokens, plus built-in tool calls |
| oppermind-lato-1-vision | Image generation | /images | Image |
| oppermind-lato-1-video | Video generation | /videos | Second of video |
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. If you leave it out and the model uses all 16384 before answering, the request runs once more with up to 65536 (not when built-in tools are in the request); the empty first attempt is not charged.
- 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.
To clean up, retouch, restore or otherwise edit an existing photo, add image (one source) or images (1 to 3 sources). Each source is a base64 data URL, a public HTTPS URL, { "url": "..." }, or { "file_id": "file-..." } from POST /files. JPEG, PNG, WebP and GIF are accepted. The original pixels are sent to image editing; a source is never silently discarded. Existing /api/v1/images/proxy?token=... paths can be reused by their owning account. Inputs are limited to 24 MB combined decoded bytes and 31 MB per JSON request. Unsupported editing configurations return OPMD_CAPABILITY_001 before charging. Some model versions deliver one image per call even if n is higher; billing uses the delivered count.
Photo cleanup request:
{
"prompt": "Remove the clutter and correct the lighting, keeping the person unchanged",
"image": { "file_id": "file-your-upload-id" },
"n": 1
}
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.
To animate a photo, add image. To guide a video with subjects from photos, add reference_images (1 to 3 sources). To edit a clip, add video and optionally video_mode: "edit" (the default with video). To continue a clip, use video_mode: "extend"; duration_seconds is the new portion, clamped to 2 to 10 seconds, and only that portion is billed. Use exactly one of image, reference_images or video. Sources use the same URL, base64 data URL or { "file_id": "file-..." } format as /images; uploaded videos must be MP4. Returned /api/v1/videos/proxy?token=... paths can be reused by their owning account. Inputs are limited to 24 MB combined decoded bytes and 31 MB per JSON request. Some model versions edit MP4 clips up to 8.7 seconds, retaining the source duration and aspect ratio at up to 720p. Other versions accept source clips up to 10 seconds and produce video in whole seconds from 3 to 10. The API adapts to the selected version. duration_seconds, resolution and aspect_ratio do not resize or shorten an edit on versions that inherit the source geometry. Limits and accepted options depend on the current model version; rejected requests return an error. Billing and reservations use the duration actually submitted to that version. Media uses the first capable configured provider in the admin primary and fallback slots, with its own key, model and endpoints. If neither slot supports the feature, OPMD_CAPABILITY_001 is returned before charging. For image-to-video and reference-to-video, aspect_ratio may be 16:9, 9:16, 1:1, 4:3, 3:4, 3:2 or 2:3. Generation and editing return the finished video synchronously.
Video editing request:
{
"prompt": "Change the jacket to blue, preserving the scene and movement",
"video": { "file_id": "file-your-upload-id" },
"video_mode": "edit"
}
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.
| Code | HTTP | Meaning |
|---|---|---|
| OPMD_MODEL_001 | 400 | Invalid request (409 when the request was already processed) |
| OPMD_MODEL_002 | 400 | More than 2000 messages or input items |
| OPMD_MODEL_003 | 413 / 400 | Body over 31 MB, or image prompt over 8 KB |
| OPMD_MODEL_005 | 400 | Streaming is not available for this request |
| OPMD_CAPABILITY_001 | 400 | The current model version cannot use this tool, option or content type |
| OPMD_UPSTREAM_400 | 400 / 413 / 415 / 422 | The model rejected the request (for example an unreadable image). Reason in the message. Not charged. |
| OPMD_EMPTY_001 | 502 | The model returned no answer (for example it ran out of output tokens; the message says which limit ran out). Not charged, unless built-in tools already ran during the request or more than 20 requests in the past hour returned no answer; the error message says when a request was charged. |
| OPMD_FILE_001 | 404 | No file with that id |
| OPMD_FILE_002 | 400 / 409 / 413 / 415 / 422 | File empty, too large, unreadable, unsupported file type, or over the account limit |
| OPMD_FILE_003 | 422 | File did not pass our file safety checks and was not accepted. Not charged |
| OPMD_AUTH_001 | 401 | Invalid or missing API key |
| OPMD_AUTH_002 | 403 | Key lacks permission for this endpoint, or account suspended |
| OPMD_AUTH_003 | 403 | Caller IP not in the key's allowlist |
| OPMD_BILLING_001 | 402 | Not enough credit |
| OPMD_BILLING_002 | 402 | Monthly spend limit reached. Requests resume next month, or when the limit is raised or removed |
| OPMD_POLICY_001 | 403 | Request breaks the usage policy |
| OPMD_MODERATION_001 | 403 | Image or video prompt blocked by content moderation |
| OPMD_RATE_001 | 429 | Per-key request limit reached |
| OPMD_RATE_002 | 429 | Model busy, retry shortly |
| OPMD_IDEMP_001 | 400 | Malformed Idempotency-Key |
| OPMD_IDEMP_002 | 409 | Same Idempotency-Key still running |
| OPMD_PROVIDER_001 | 503 | Capability not available right now |
| OPMD_GW_001 | 500 / 502 / 503 | Gateway error, retry with backoff |
| OPMD_GW_002 | 503 | IP allowlist or spend limit check unavailable, retry |
| OPMD_ROUTE_404 | 404 | Unknown endpoint |
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
- Optional monthly spend limit, set on the dashboard Usage page. In stop mode, new requests are refused with OPMD_BILLING_002 once the month's spend reaches it. Requests already running finish, so spend can go slightly past it
- 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)
- billing.spend_limit: data { percent, month_spend_aud, monthly_limit_aud, mode, requests_stopped } (once per spend limit alert per month, and again if the limit is saved, for alerts set to send a webhook)
- 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!"}]}'
