Documentation

Mortera Cloud accepts OpenAI-style chat completions and Anthropic-style messages. The gateway resolves the requested catalog model, reserves one eligible billing mode, selects a healthy provider source, and settles against reported usage after delivery.

1. 01

   Create a Key

   Create your key in Panel > API Keys and copy it anytime from the key list.

2. 02

   Read the Catalog

   Call /v1/models and use an exact visible model id. Catalog availability is dynamic.

3. 03

   Generate a Unique Key

   Optionally send a unique Idempotency-Key per logical request to protect retries from duplicate settlement; one is generated automatically when absent.

curl https://mortera.cloud/v1/chat/completions \  -H "Authorization: Bearer $MORTERA_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "model": "YOUR_MODEL_ID",    "messages": [{"role": "user", "content": "Hello from Mortera Cloud"}],    "stream": false  }'

Keys are scoped to allowed billing modes and can also restrict models. Authentication accepts either a Bearer token or x-api-key. Do not send both.

Mortera Cloud is served over HTTPS at mortera.cloud, which is the only host that exposes the API. OpenAI clients usually include /v1 in baseURL; Anthropic clients append /v1/messages themselves and therefore use the origin. Requests addressed to panel.mortera.cloud never reach the gateway.

Every Endpoint Mortera Cloud Serves

All five API endpoints require authentication. The two generation routes also accept an optional unique Idempotency-Key - when absent, one is generated automatically. Header names are case-insensitive.

POST /v1/chat/completions accepts the common chat shape: model, messages (text and images), system messages, temperature, top_p, stop, max_tokens or max_completion_tokens, stream, tools, tool_choice, and parallel_tool_calls. All of these bridge correctly to an Anthropic-protocol source, multi-turn tool-call history included. response_format/structured_outputs, n, logprobs/top_logprobs, and provider-specific sampling extras (frequency_penalty, presence_penalty, seed, logit_bias) have no Anthropic equivalent and are only honored on a native OpenAI route - bridged to Anthropic, they are dropped rather than mistranslated.

curl https://mortera.cloud/v1/chat/completions \  -H "Authorization: Bearer $MORTERA_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "model": "YOUR_MODEL_ID",    "messages": [      {"role": "system", "content": "Answer concisely."},      {"role": "user", "content": "What is idempotency?"}    ],    "max_tokens": 300,    "stream": false  }'

POST /v1/messages accepts model, system, messages (text and images), max_tokens, temperature, top_p, stop_sequences, stream, tools, and tool_choice (including disable_parallel_tool_use). All of these bridge correctly to an OpenAI-protocol source, multi-turn tool-call history included. Extended thinking content and provider-specific tool types (for example built-in web search) have no OpenAI equivalent and are only honored on a native Anthropic route.

curl https://mortera.cloud/v1/messages \  -H "x-api-key: $MORTERA_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "model": "YOUR_MODEL_ID",    "max_tokens": 300,    "system": "Answer concisely.",    "messages": [{"role": "user", "content": "What is idempotency?"}],    "stream": false  }'

GET /v1/models returns active models that are visible in the picker, permitted by the key, and backed by at least one provider route that can serve them right now. Anything the catalog lists is dispatchable, so a listed id never fails with 422 model_unavailable for want of a route. It requires authentication but does not require Idempotency-Key.

curl https://mortera.cloud/v1/models \  -H "Authorization: Bearer $MORTERA_API_KEY"

Catalog Response

Each item includes its canonical id, provider label, context window, capabilities, and current Pay As You Go and Token pricing metadata.

{  "object": "list",  "data": [{    "id": "MODEL_ID",    "object": "model",    "owned_by": "provider",    "created": 1786900000,    "context_window": 128000,    "capabilities": {},    "pricing": {      "payg_per_1m_idr": { "in": 0, "out": 0, "cache": 0 },      "credit_per_1m": 2.5    }  }]}

Non-streaming success responses preserve the requested inbound protocol. Mortera Cloud normalizes usage and appends a mortera object describing the selected billing mode and the applicable settled amount.

{  "id": "chatcmpl_...",  "object": "chat.completion",  "model": "YOUR_MODEL_ID",  "choices": [{    "index": 0,    "message": { "role": "assistant", "content": "..." },    "finish_reason": "stop"  }],  "usage": {    "prompt_tokens": 42,    "completion_tokens": 18,    "prompt_tokens_details": { "cached_tokens": 0 }  }}# response header: mortera-billing: {"mode":"payg","charge_idr":125.5}

{  "id": "msg_...",  "type": "message",  "role": "assistant",  "model": "YOUR_MODEL_ID",  "content": [{ "type": "text", "text": "..." }],  "stop_reason": "end_turn",  "usage": {    "input_tokens": 42,    "output_tokens": 18  }}# response header: mortera-billing: {"mode":"token","credits_used":0.52}

Set stream: true on either generation endpoint. Mortera Cloud responds with text/event-stream, relays chunks as they arrive, and settles asynchronously from usage found in the stream.

If a stream omits final usage, Mortera Cloud still bills the output already delivered - from the provider's mid-stream counts when they arrived, otherwise from the streamed characters. A completed stream idempotency record replays as a small non-stream JSON marker, so do not reconnect a completed stream with the same key.

Native protocol requests pass tool definitions through. The bridge converts function/tool definitions, tool_choice, and tool results in both directions, and reconstructs tool calls in the target protocol's own shape - OpenAI tool_calls become Anthropic tool_use blocks and back, including every prior turn in multi-turn history, single or parallel calls, and both non-streaming responses and live streams.

{  "model": "YOUR_MODEL_ID",  "messages": [{"role": "user", "content": "Weather in Jakarta?"}],  "tools": [{    "type": "function",    "function": {      "name": "get_weather",      "description": "Get the current weather",      "parameters": {        "type": "object",        "properties": { "city": { "type": "string" } },        "required": ["city"]      }    }  ]}

One key covers every modality, and every request names the canonical Mortera Cloud model id. Responses carry normalized usage and never reveal which source served the request - the catalog's output modalities tell you which surface a model speaks.

Text Embeddings

Send a string or an array of strings; the response carries one vector per input plus prompt and total token usage.

curl https://mortera.cloud/v1/embeddings \  -H "Authorization: Bearer $MORTERA_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "model": "text-embedding-3-large",    "input": "Mortera Cloud, one key for every modality"  }'

{  "object": "list",  "data": [{ "object": "embedding", "index": 0, "embedding": [-0.08142313, -0.01452982, ...] }],  "model": "text-embedding-3-large",  "usage": { "prompt_tokens": 9, "total_tokens": 9 }}

Image Generation

Images return inline as base64 PNG data (or a hosted url). Size, quality, and count are optional; usage is normalized into the same token model as chat.

curl https://mortera.cloud/v1/images/generations \  -H "Authorization: Bearer $MORTERA_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "model": "gpt-image-2",    "prompt": "a red circle on white",    "n": 1,    "size": "1024x1024",    "quality": "low"  }'

Video Generation

Video generation is asynchronous: create a task, poll its status until completed, then stream the finished mp4 from the content endpoint. The id Mortera Cloud returns is the only one you ever see - the upstream task id stays internal. Billing settles on the first completed poll; an abandoned task's reserve is released automatically.

# 1. Create the task - the id Mortera Cloud mints is the only id you ever see.curl https://mortera.cloud/v1/videos \  -H "Authorization: Bearer $MORTERA_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "model": "seedance-2.0",    "prompt": "a cat walks across a sunny room",    "seconds": 5,    "size": "480p"  }'# -> {"id":"vid_...","object":"video","model":"seedance-2.0","status":"queued","created_at":...} # 2. Poll until completed.curl https://mortera.cloud/v1/videos/vid_... \  -H "Authorization: Bearer $MORTERA_API_KEY" # 3. Stream the finished mp4.curl https://mortera.cloud/v1/videos/vid_.../content \  -H "Authorization: Bearer $MORTERA_API_KEY" \  -o video.mp4

Every admitted request uses exactly one billing mode. Mortera Cloud walks the modes allowed by the API key, ordered by the account's mode preference. Modes the key still allows are always tried, even if they are missing from the account preference.

Admission Reserves Before Provider Dispatch

Input is estimated from request content and output from max_tokens or configured defaults. That estimate sizes the hold; it does not reject a request that still has leftover funds. A remaining Pay As You Go balance or Token credit of any amount greater than zero still admits. The hold is the smaller of the estimate and what remains. The request is rejected with insufficient_quota only when remaining funds are actually zero. On success the actual amount settles and unused reserve is released. Provider 4xx responses and all-source failures release the hold with no customer debit.

Billing Fallback Is Ordered, Not Split

If the first allowed mode cannot reserve the request, because the wallet is empty or a per-key spend ceiling is reached, Mortera Cloud tries the next mode allowed on that API key. One request never splits across modes or Token packages. Lock a key to one wallet by disabling the other mode on the key.

The public model id stays constant while Mortera Cloud chooses among configured sources for that model.

• Only active, enabled, priced, credentialed, margin-safe, and circuit-healthy sources are eligible.
• Subscription-first sources with allowance lead when configured; remaining candidates are ordered by estimated provider cost.
• Network errors, provider 5xx, and provider 429 responses advance to the next candidate in the same request.
• Provider 4xx responses other than 429 do not fail over; they return as invalid_request with upstreamStatus details.
• Optional cacheAffinityKey or cache_affinity_key can prefer the last healthy source for the same user and model for up to one hour when its estimated cost remains within the configured delta. Mortera Cloud strips this field before dispatch.
• Send a stable cacheAffinityKey (or cache_affinity_key) per conversation: it keeps prompt-cache-affine traffic on the same source, so follow-up turns skip cold caches and first tokens arrive markedly faster.
• Reasoning models think before the first token. When speed matters more than depth, send a lower reasoning_effort (or the provider's equivalent) - Mortera Cloud forwards it untouched.

Idempotency is scoped by user, API key, endpoint, and key value. The gateway hashes the complete JSON body and retains records for the configured security window.

A request is admitted when the account has Pay As You Go balance or Token credits that cover the reserved estimate. There is no requests-per-minute ceiling, no concurrent-stream slot, no burst throttle, and no daily spend quota.

Gateway failures use a stable error.code and localized message. Some errors add details. Retry-After is sent only when the gateway has a concrete reset delay.

{  "error": {    "code": "insufficient_quota",    "message": "This account has no remaining Pay As You Go balance or Token credits.",    "details": {}  }}

A provider-side customer error can retain its HTTP status while using code invalid_request and details.upstreamStatus. Do not retry it unchanged.

invalid_host is an edge guard that fires before authentication when a request's Host header isn't mortera.cloud. A correctly configured client pointed at https://mortera.cloud should never see it.

• Keep keys on trusted servers. Never expose them in browser bundles, mobile binaries, screenshots, or public repositories.
• Redact Authorization, x-api-key, and full mrt- key values from logs and support reports.
• Use separate keys per environment or integration. Rotate immediately after suspected exposure and revoke the old key.
• Limit each key to only the models and billing modes it needs.
• Use only https://mortera.cloud in production and reject invalid TLS certificates.
• Prompt content and required request metadata are sent to the selected third-party AI provider. Do not submit data you are not authorized to process.

Any coding tool that speaks the OpenAI Chat Completions or Anthropic Messages protocol works against Mortera Cloud directly: point it at the Mortera Cloud base URL, paste a Mortera Cloud key, and pick a model id from /v1/models. No proxy or shim is required.

# ~/.zshrc or ~/.bashrc - Mortera Cloud keys come from the panelexport ANTHROPIC_BASE_URL="https://mortera.cloud"export ANTHROPIC_AUTH_TOKEN="mrt-..."export ANTHROPIC_MODEL="claude-opus-5"export ANTHROPIC_SMALL_FAST_MODEL="deepseek-v4-flash" claude

# ~/.continue/config.yamlname: Mortera Cloud Assistantversion: 1.0.0models:  - name: Mortera Cloud Chat    provider: openai    model: claude-opus-5    apiBase: https://mortera.cloud/v1    apiKey: ${{ secrets.MORTERA_API_KEY }}    roles: [chat, edit, apply]  - name: Mortera Cloud Autocomplete    provider: openai    model: deepseek-v4-flash    apiBase: https://mortera.cloud/v1    apiKey: ${{ secrets.MORTERA_API_KEY }}    roles: [autocomplete]

# ~/.codex/config.tomlmodel = "gpt-5.6-sol"model_provider = "mortera" [model_providers.mortera]name = "Mortera Cloud"base_url = "https://mortera.cloud/v1"env_key = "MORTERA_API_KEY"wire_api = "chat"

// opencode.json (project root){  "$schema": "https://opencode.ai/config.json",  "provider": {    "mortera": {      "npm": "@ai-sdk/openai-compatible",      "name": "Mortera Cloud",      "options": {        "baseURL": "https://mortera.cloud/v1",        "apiKey": "{env:MORTERA_API_KEY}"      },      "models": {        "claude-opus-5": { "name": "Claude Opus 5 (Mortera Cloud)" },        "gpt-5.6-sol": { "name": "GPT-5.6 Sol (Mortera Cloud)" }      }    }  }}

Every message code the API can answer with, and what each one means - the complete reference for decoding any error response.

Use the API Key Checker at /checker to verify a key authenticates and see its allowed models, without spending a request or touching your prompt content.

For account, billing, or gateway incidents, contact Mortera Cloud support.

Include the incident time, endpoint, model id, HTTP status, error code, and Idempotency-Key. Never include your full API key or sensitive prompt content.