Run an LLM completion
Runs a single LLM completion: one prompt in, one text (or schema-constrained JSON) result out. No tools and no agent loop. The completion runs under your API key’s organization and its rate limits.
Accepted requests respond with 200 text/event-stream. Each frame is a data-only data: {json} line. Every frame includes operation. content and metadata are omitted when empty. Metal sends a HEARTBEAT frame every 10 seconds while the completion runs, then exactly one terminal frame:
HEARTBEAT:{"operation":"HEARTBEAT"}.COMPLETE:contentis a JSON string containing{"data":{"text":"..."}}.metadatais omitted.ERROR:contentis the error message andmetadata.errorCodeclassifies the failure:deadline_exceeded,canceled,completion_failed,internal_runtime_state,no_choices, orpanic.
Read the stream until the terminal frame and ignore HEARTBEAT frames. Validation failures that happen before the stream starts (missing prompt, malformed jsonSchema, unlisted model, or timeoutSeconds outside 0 to 180) return a plain JSON 400. Omit timeoutSeconds or send 0 to use the 60-second default.
Authorizations
The Client ID of your API key.
The secret value of your API key.
Body
The user prompt.
Optional system prompt, sent before the user prompt.
Optional model ID. Metal rejects IDs that are not in its registered model list. Omit to use the platform default.
Maximum number of tokens the model can generate.
x >= 1Reasoning effort for models that support it.
JSON Schema for structured output. The model is constrained to emit JSON matching the schema. The returned text is that JSON as a string, so parse and validate it yourself.
Sampling temperature.
Completion deadline in seconds. Omit or send 0 to use the 60-second default. Otherwise the value must be from 1 to 180.
0 <= x <= 180Response
Server-sent event stream. HEARTBEAT frames every 10 seconds, followed by one terminal COMPLETE or ERROR frame. content and metadata are omitted when empty.
One server-sent event frame, sent as data: {json}. content and metadata are omitted when empty.
Frame type. COMPLETE and ERROR are terminal.
HEARTBEAT, COMPLETE, ERROR Omitted on HEARTBEAT. For COMPLETE, a JSON string containing {"data":{"text":"..."}}. For ERROR, the error message.
Omitted when empty, including on HEARTBEAT and COMPLETE frames.

