Create a chat completion

Send a conversation to a model and get its reply, whole or streamed.

POSThttps://inference.trymorse.ai/v1/chat/completions

Sends a conversation to a model and returns the model's reply, whole or as a stream. The request and the reply follow OpenAI's chat completions format. Each field below notes where Morse differs.

Before the call, the account must hold enough credit for the most the request could cost, which is the prompt plus the output limit at the model's prices. After the call, the account pays for the tokens the provider reports. If a stream stops early, the account pays for what the stream delivered. A retried request that reached the model costs again. Each reply's X-Request-Id identifies the request.

curl -X POST https://inference.trymorse.ai/v1/chat/completions \
  -H "Authorization: Bearer $MORSE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kimi-k3",
    "messages": [
      {
        "role": "system",
        "content": "Answer in one sentence."
      },
      {
        "role": "user",
        "content": "What does a TEE attest?"
      }
    ],
    "max_completion_tokens": 200
  }'
Response
{
  "id": "chatcmpl-YYOKD77FV2J75JOVRH6T77B4GZ",
  "object": "chat.completion",
  "created": 1792187800,
  "model": "kimi-k3",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "A TEE attests which code runs inside it, signed by keys the hardware vendor vouches for."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 24,
    "completion_tokens": 19,
    "total_tokens": 43
  }
}

Request body

Of the fields below, all but provider reach the model, and temperature, top_p, stop, seed, n, and response_format reach it only from an API key whose forward_settings is on ("Let my settings reach the model host" on the key in the developer console, https://console.trymorse.ai/keys). A new key has it on unless POST /v1/keys sends forward_settings false or null, and the console or PATCH /v1/keys/{id} turns it off or on. A key with forward_settings off is refused any of those fields with 400 setting_not_forwarded, which names the field, before Morse calls the model or holds any credit; a null value counts as absent. A response_format of {"type":"text"} or null counts as absent. A response_format of type json_object or json_schema reaches only the hosts of the model whose Morse endpoint records that it honours that type, and Morse picks one of them; when none of the model's endpoints does, it is refused with 400 unsupported_parameter, which names response_format and the type. A field that changes the reply and that Morse sends to no model, such as logprobs, top_logprobs, logit_bias, frequency_penalty, presence_penalty, top_k, min_p, repetition_penalty, modalities, audio, prediction, verbosity, or web_search_options, is refused with 400 unsupported_parameter, which names it, unless its value changes nothing (false, 0, null, an empty object, or modalities ["text"]). Morse drops every other field without an error, such as user, metadata, store, service_tier, safety_identifier, or prompt_cache_key. A chat from the Morse app is sent none of these fields and is refused none of them. An E2EE model is sent the body as it was encrypted, under its own rules.

modelstringRequired

A chat model's id from GET /v1/models.

messagesarray of ChatMessageRequired

The conversation, at least one message. An empty or missing messages is refused with 400 invalid_parameter naming messages, before Morse calls the model or holds any credit.

Show 4 fields
rolestringRequired

system, developer, user, assistant, or tool.

contentstring | array of ContentPart | null

Text, or an array of content parts. Media must be inline. If an image_url, video_url, audio_url, or file_url part has a URL that does not start with data:, Morse refuses the request with remote_media. A file part may carry only file_data and filename.

tool_callsarray of object

The tool calls an assistant message made, as the model returned them.

tool_call_idstring

On a tool message, the id of the tool call it answers.

streambooleanDefaults to false

Send the reply as server-sent events.

stream_optionsobject
Show 1 field
include_usagebooleanDefaults to false

Send a last chunk with usage and an empty choices array before [DONE]. Without it, the stream carries no usage.

max_completion_tokensinteger | null

The most output tokens the model may produce. The limit is the max_output_tokens of the tier that serves the request, as GET /v1/models lists it under tiers, and a model's tiers can differ: Kimi K3.1 Pro allows 1,048,576 at private and 262,144 at e2ee. Below e2ee, Morse lowers a value above that tier's max_output_tokens to it. An E2EE request's body is forwarded as sent, so one above the e2ee tier's max_output_tokens, or with max_tokens and max_completion_tokens both set and unequal, is refused with 400 e2ee_output_limit_refused. Below e2ee, when neither limit is set, the model's default applies; an E2EE request that sets neither is refused with 400 e2ee_output_limit_required. The account must hold credit for the most the request could cost, so a lower limit holds less credit.

max_tokensinteger | null

The same as max_completion_tokens. Below e2ee, when both are set, max_completion_tokens wins; at e2ee they must be equal.

reasoning_effortstring

How much a reasoning model reasons, such as low, medium, or high. Morse sends the nearest effort the model takes, listed as the model's reasoning_efforts in GET /v1/models: the lowest listed effort at or above the one asked for, or the highest listed. A model whose reasoning_efforts is empty is sent no reasoning_effort. Any value other than none, minimal, low, medium, high, xhigh, or max is refused with 400 invalid_parameter. When reasoning_effort is absent, the model's default applies. An E2EE model is sent the body as it was encrypted, so on one the client picks from reasoning_efforts itself.

One of none, minimal, low, medium, high, xhigh, or max.

toolsarray of Tool
Show 2 fields
type"function"Required
functionobjectRequired
tool_choicestring | object

auto, none, required, or one named function.

Show 2 fields
type"function"Required
functionobjectRequired
parallel_tool_callsboolean
temperaturenumber | null

Sent to the model only from an API key whose forward_settings is on. Any other key is refused with 400 setting_not_forwarded.

top_pnumber | null

Sent to the model only from an API key whose forward_settings is on. Any other key is refused with 400 setting_not_forwarded.

stopstring | array of string | null

Up to 4 strings the model stops before. Sent to the model only from an API key whose forward_settings is on. Any other key is refused with 400 setting_not_forwarded.

seedinteger | null

Sent to the model only from an API key whose forward_settings is on. Any other key is refused with 400 setting_not_forwarded. Whether the same seed gives the same reply is up to the model's host.

ninteger | null

1 only: Morse returns one choice. Any other value is refused with 400 invalid_parameter. 1 is sent to the model only from an API key whose forward_settings is on, and any other key is refused it with 400 setting_not_forwarded.

One of 1 or null.

response_formatobject | null

JSON mode: {"type":"json_object"} or {"type":"json_schema","json_schema":{...}}, sent to the model as given. {"type":"text"} or null counts as absent, and any other type is refused with 400 invalid_parameter. Sent only from an API key whose forward_settings is on, and any other key is refused it with 400 setting_not_forwarded. Morse sends it only to an endpoint that records that it honours the type, picking one among the model's endpoints, and refuses it with 400 unsupported_parameter when the model has none, such as a Claude, Gemini, or GPT model, or an E2EE model reached in plaintext. How closely the reply follows a schema is up to the model's host.

providerobject

Conditions on the model that serves the request. Morse checks them itself and never sends this object to the model's provider, except in an E2EE request body, which Morse forwards as sent. Morse chooses the provider within a privacy tier, and a reply does not name it. order, sort, preferred_min_throughput, preferred_max_latency, and require_parameters are accepted after a check of their shape and have no effect. quantizations chooses among the providers by the precision each serves. only, ignore, and enforce_distillable_text are refused with 400 provider_choice_unsupported. Any other field is refused with 400 invalid_parameter, which names the field.

Show 11 fields
min_privacystring

The lowest privacy tier the request may run at, from lowest to highest anon, private, tee, and e2ee. TEE is opt-in: without min_privacy, or with anon or private, a request on a model id runs at private or anon, at or above the floor, where the model has an endpoint there, so set tee to require attested hardware. A model whose tier, as GET /v1/models lists it, is below it is refused with 400 privacy_floor_unmet before Morse calls it or holds any credit. Any other value is refused with 400 invalid_parameter. An E2EE model meets every floor, and its encrypted body is forwarded as sent, so an E2EE request leaves min_privacy out.

One of anon, private, tee, or e2ee.

zdrboolean

true raises the floor to private and keeps only the endpoints that retain no data. An endpoint whose retention Morse has not confirmed, such as a tee endpoint today, is left out, so a model served only by those is refused with 400 privacy_floor_unmet. false does nothing.

data_collectionstring

deny is the same as zdr true. allow does nothing.

One of allow or deny.

allow_fallbacksboolean

false keeps only the endpoints at the privacy tier of the first one the request can reach, so the request is served at that tier or fails. Retries among that tier's endpoints stay. true does nothing.

max_priceobject

The most the request may cost per million tokens, in dollars, as a number or a string holding one. Morse drops every tier whose price to you, which is list for an API key, is above a cap, and refuses with 400 max_price_unmet when none is left. image, audio, and request are refused with 400 unsupported_parameter.

quantizationsarray | null

The precisions a provider may serve the model at, in OpenRouter's names (https://openrouter.ai/docs/guides/routing/provider-selection, "Quantization Levels"). Morse keeps only the providers whose published precision the list admits, at the tiers the request already reaches, and every retry and failover stays among them. fp4 also admits mxfp4 and nvfp4, and fp8 also admits mxfp8. A provider that publishes no precision, as no host of a closed model does, is unknown, and qualifies only when the list names unknown. The filter never moves a request to another tier: when no provider qualifies, the request is refused with 400 quantization_unmet. GET /v1/models lists each tier's quantizations. An empty list, or a name not in the enum, is refused with 400 invalid_parameter, and null does nothing. An E2EE request sealed to a Phala or NEAR endpoint that names quantizations is refused with 400 quantization_unsupported before the provider's body check: a Phala body's provider must be exactly {"aci_verified":true,"zdr":true}, and a NEAR body is forwarded verbatim and may carry no provider field. A Tinfoil body is encrypted whole, so Morse cannot read the field there: it neither filters nor refuses on it, and the body reaches the Tinfoil endpoint it is sealed to as sent.

orderarray of string

Accepted and ignored. Morse chooses the provider.

sortstring | object

Accepted and ignored. A string, or an object with by and partition.

preferred_min_throughputnumber | object

Accepted and ignored.

preferred_max_latencynumber | object

Accepted and ignored.

require_parametersboolean

Accepted and ignored. Morse refuses or drops a field by the model's own rules and does not route around it.

Response

The reply. When stream is true, the body is server-sent events. Each data line is a ChatCompletionChunk, and the stream ends with data: [DONE]. If the provider fails after the first event, the stream ends with one error event in the Error shape and no [DONE]. Some reasoning models send a : keepalive comment every 25 seconds while they reason.

idstringRequired
object"chat.completion"Required
createdinteger

Unix seconds.

modelstringRequired
choicesarray of objectRequired
Show 3 fields
indexintegerRequired
messageobjectRequired
finish_reasonstring | nullRequired

stop, length, tool_calls, or content_filter.

usageUsage
Show 6 fields
prompt_tokensintegerRequired
completion_tokensintegerRequired
total_tokensintegerRequired
prompt_tokens_detailsobject
completion_tokens_detailsobject
unansweredboolean

Present, and true, only when the reply reached its output limit (finish_reason length) having shown nothing: no text, refusal, tool call, or visible reasoning. A reasoning model thought through the whole limit. The account paid for the prompt alone, and completion_tokens still counts what the provider reported. Absent on every other reply.

Response headers

HeaderWhat it says
X-Morse-VersionThe running build. Every reply carries it.
X-FundingWhat pays for the request. With a key, the value is always credits. A request that Morse refuses before it bills anything has no X-Funding.
X-Request-IdAn id for this request. Quote it when you contact support about the request. An error that arrives after the request starts carries it too. A request that Morse refuses before it bills anything has no X-Request-Id.
X-Output-LimitedSet when Morse lowered the output limit so that the request fits: balance for the account's credits, key_limit for what the key's spend limit has left.
X-TierThe privacy tier of the endpoint that served the reply. TEE is opt-in: a request on a model id is served at private or anon, at or above its provider.min_privacy and the key's minimum tier, and at tee only when either of those is tee or the model has no private or anon endpoint at or above them. This header says which tier served it. It is at least the request's floor. No header names the provider or the endpoint.

Errors

Every error has the same shape. Errors explains it and when to retry.

400The request is malformed, or the model or its provider refused it.24 codes
invalid_request_body
The body is not a JSON object, a field has the wrong JSON type, or model is missing.
invalid_parameter
A field has a value the endpoint refuses. The message names the field.
duplicate_json_key
A JSON object in the body repeats a key.
too_many_messages
messages holds more than 4,096 entries.
request_too_complex
The body holds more than 262,144 JSON values.
invalid_output_limit
max_tokens or max_completion_tokens is not a positive integer.
e2ee_output_limit_required
An E2EE request sets neither max_tokens nor max_completion_tokens, or sets both to null. Morse forwards the encrypted body as sent and cannot add a limit.
e2ee_output_limit_refused
An E2EE request sets max_tokens or max_completion_tokens above the e2ee tier's max_output_tokens, or sets both to different values. Morse forwards the encrypted body as sent and cannot lower them.
e2ee_field_refused
An E2EE request carries a field or value outside the e2ee client contract, such as tools on a model sealed to Phala, or provider.min_privacy, which every e2ee model already meets. Morse forwards the encrypted body as sent and cannot remove it. The message names the field.
unsealable_request
A plaintext request to an e2ee model carries a field Morse cannot seal for you, such as tools, and no other endpoint of the model at the tiers the request may run at takes it. Send only system, user, and assistant messages with string content, or seal the request yourself. The message names the field.
privacy_floor_unmet
The model's tier is below provider.min_privacy, or below the API key's min_privacy, when param is key.min_privacy, or no endpoint at the tiers the request may run at keeps no data when the request sets provider.zdr or provider.data_collection deny. The message names both tiers. GET /v1/models lists only the models the key may call. Morse refuses before it calls the model or holds any credit.
unsupported_parameter
provider.max_price names image, audio, or request, which no chat price has; the request sets a field that changes the reply and that Morse sends to no model, such as logprobs or frequency_penalty; or an API key whose forward_settings is on sets temperature, top_p, stop, seed, n, or response_format on a model none of whose hosts Morse sends them, such as a Claude model, or a response_format of type json_object or json_schema that no endpoint of the model honours, when the message names the type; or an API key's request lets a model that GET /v1/models lists with tools false call a tool, with tools or a tool_choice other than none, when the field named is tools. The message names the field.
setting_not_forwarded
An API key whose forward_settings was turned off set temperature, top_p, stop, seed, n, or a response_format other than {"type":"text"}, which Morse sends to no model for it. A new key has forward_settings on unless it is created with forward_settings false or null. The message names the field and the key setting, "Let my settings reach the model host", that sends them, and the developer console's keys page, https://console.trymorse.ai/keys, where it is turned back on.
provider_choice_unsupported
provider names only, ignore, or enforce_distillable_text. Morse chooses the provider within a privacy tier and refuses a request that would ignore the choice. The message points to the Pricing page, which lists the providers, and to provider.min_privacy, which requires a tier.
max_price_unmet
Every tier of the model costs you more than provider.max_price allows, at your price: list for an API key. The message names the cheapest tier's price.
quantization_unmet
No host of the model at the tiers the request may run at serves a precision that provider.quantizations admits. param is provider.quantizations, and the message names the precisions those hosts do serve. Morse never moves a request to another tier to find one, so a precision that only a tee host serves needs min_privacy tee. Morse refuses before it calls the model or holds any credit.
quantization_unsupported
An E2EE request sealed to a Phala or NEAR endpoint names provider.quantizations. A body sealed to Phala must carry provider exactly {"aci_verified":true,"zdr":true}, and a body sealed to NEAR is forwarded verbatim and may carry no provider field, so neither route can take quantizations. param is provider.quantizations, and the message names the model and the vendor. Morse refuses before the vendor's body check, before it calls the model or holds any credit.
invalid_request
A message, part, or tool has a shape the model does not take, or the provider refused the request.
remote_media
A media part links a URL instead of a data: URL.
unsupported_input
An API key's messages carry an image part for a model whose input_modalities in GET /v1/models do not include image. The message names what the model reads. Morse refuses before it calls the model or holds any credit.
message_too_long
In a chat with a character, the last user message holds more than 8,000 bytes of text.
model_unsupported_for_characters
A chat that plays a character, one that sends X-Character or a character's prompt, names a model that GET /v1/models lists with characters false. param is model. Morse refuses before it calls the model or holds any credit.
context_length_exceeded
The conversation is too long for the model.
content_filter
The model provider declined the request.
401The key is missing or wrong.3 codes
invalid_api_key
The Authorization header is missing or not Bearer, the key is unknown or revoked, a token that starts with sk_ is not a whole sk_morse_ key, or the bearer is no Morse key or login token at all, such as another service's API key (sk-proj-...).
api_key_expired
The key is past the expiry set on it. Make a new key, or set a later expiry before a key expires.
invalid_token
The bearer is shaped as a Morse login token (a JWT) but its signature fails or it has expired. An API key sends the whole sk_morse_ key.
402The account's credits, or what the key's spend limit has left, do not cover the request.2 codes
insufficient_balance
The balance is below the amount the request must hold. While the balance is negative, the API refuses every metered request. With no credit left, a balance of zero or below, the message says only to add credit, since no lower max_tokens would help.
key_spend_limit_reached
What the key's spend limit has left in its window is below the amount the request must hold. A limit that resets daily, weekly, or monthly sends Retry-After, the seconds until it resets. A limit that never resets sends none. Raise or remove the limit in the dashboard, and the next request is served.
403The key's account may not make this request.6 codes
account_disabled
Morse has disabled the key's account.
account_deleted
The key's account has been deleted.
account_under_18
The account's owner said they are under 18.
characters_app_only
The first system message opens with the prompt of a Morse character, or the request names one in X-Character-Content or sends X-Writer-Examples. Morse characters are available only in the Morse app, not through an API key.
ip_not_allowed
The key allows requests only from its allowed IPs, and the request came from another address. The message names the address the proxy saw.
sealed_required
The key is sealed_only, and the request came unsealed. Send it inside POST /v1/sealed, as the Morse app does.
404The model does not exist, or it is not a model for this endpoint.1 code
model_not_found
No model of this endpoint's type has that name.
408The request body arrived too slowly.1 code
request_timeout
The request body did not arrive within one minute.
413The request body is too large.1 code
request_too_large
The body is over 32 MiB, or too large for the provider.
429The account is over its rate limit or its concurrency limit. Wait the number of seconds in Retry-After, then retry.2 codes
rate_limit_exceeded
The account used up its requests per minute. All of the account's keys and its owner's use of the Morse app share one budget.
concurrency_limit_exceeded
The account already has its maximum number of requests in flight. Retry-After is 1.
502The model provider failed or refused the request.4 codes
upstream_error
The provider failed or did not answer.
upstream_unavailable
The provider is unavailable right now. Retry later, or choose another model.
upstream_retention
A zero-retention model's provider did not confirm zero data retention.
upstream_refused
The provider refused the request, such as when it does not serve the model to Morse right now. Retry later, or choose another model.
503Morse or the provider is busy or unavailable. Retry the request later.4 codes
service_unavailable
Morse could not start the request. Retry it.
server_busy
Morse is busy. Retry-After is 1.
upstream_busy
The provider is overloaded. Try again shortly.
upstream_unattested
Morse could not verify the attested endpoint. Try again shortly.