---
title: "Generate a nonstreaming managed model message"
method: POST
path: "/v1/managed-models/messages"
tags: ["Managed models"]
---

# Generate a nonstreaming managed model message

`POST /v1/managed-models/messages`

## Request

- Base URL: `/` (relative, and the document was published on a file host, not at the API’s origin)
- URL: `/v1/managed-models/messages`
- Auth: HTTP bearer

Requires a Nodus API key or console session and an account-qualified catalog model. No customer model-provider key is required. Send JSON without query parameters or Content-Encoding. New requests reserve prepaid Nodus credits under account spending limits before dispatch. The reservation covers the full qualified input window and requested output limit, so it can exceed the final charge. Unused credit is released after settlement. Model usage is billed separately from compute and saved storage. Every logical call requires a stable Idempotency-Key. Preserve the key and body after an uncertain response. An accepted replay returns 409 with the existing billing receipt and never executes again or replays the answer. A different body using the same key returns an idempotency conflict. Persist received answers in your application. Unknown outcomes retain reserved funds and do not authorize a new-key retry. This endpoint does not install agent harnesses or inject credentials into hosted workers.

## Headers

- `Idempotency-Key` string, required

## Request body

- ManagedModelMessagesRequest: Bounded native Messages request for a catalog model using messages. The JSON body is limited to 1 MiB. An omitted max_tokens uses the catalog output limit. Unsupported top-level fields, streaming, media and provider-hosted tools are refused. Native model-specific validation also applies.
  - `model` string, required: Model ID returned by this account’s managed model catalog.
  - `messages` ManagedModelMessagesMessage[], required
    - `role` 'user' | 'assistant', required
    - `content` union, required: Text or native text/function/reasoning blocks. Media and provider-hosted tool blocks are not supported.
      - string
      - object[]
        - `type` 'text' | 'tool_use' | 'tool_result' | 'thinking' | 'redacted_thinking', required
        - `text` string
        - `id` string
        - `name` string
        - `input` object
        - `tool_use_id` string
        - `content` ManagedModelMessagesContent (recursive)
        - `is_error` boolean
        - `thinking` string
        - `signature` string
        - `data` string
        - `cache_control` object: Native cache settings for eligible blocks. Cache usage must have qualified catalog prices.
  - `max_tokens` integer: Must not exceed max_output_tokens from the model catalog. Omission uses that catalog limit.
  - `stream` false: Only nonstreaming requests are admitted.
  - `temperature` number: Native model sampling setting. Model-specific validation still applies.
  - `top_p` number
  - `tools` ManagedModelMessagesTool[]
    - `type` 'custom'
    - `name` string, required
    - `description` string
    - `input_schema` object, required
    - `cache_control` object
  - `tool_choice` union: Native selection of a customer-defined function tool. Provider-hosted tools are not supported.
    - string
    - object
  - `system` union: Text or native text/function/reasoning blocks. Media and provider-hosted tool blocks are not supported.
    - string
    - object[]
      - `type` 'text' | 'tool_use' | 'tool_result' | 'thinking' | 'redacted_thinking', required
      - `text` string
      - `id` string
      - `name` string
      - `input` object
      - `tool_use_id` string
      - `content` ManagedModelMessagesContent (recursive)
      - `is_error` boolean
      - `thinking` string
      - `signature` string
      - `data` string
      - `cache_control` object: Native cache settings for eligible blocks. Cache usage must have qualified catalog prices.
  - `stop_sequences` string[]
  - `thinking` object: Native reasoning configuration within the catalog output limit. Reasoning tokens count toward billed output.
  - `metadata` object

## Response `200`

Model response received and its verified usage charge committed.

- ManagedModelCompletionResponse: Nonstreaming native response with its model field replaced by the Nodus catalog ID. Other fields follow the selected protocol, such as content or choices. The caller must save the answer. It is not retained or replayed by the billing ledger.
  - `model` string, required: Model ID returned by this account’s managed model catalog.
  - `usage` object, required: Verified usage in the selected model’s native response format. Read the billing receipt for normalized counters and the settled charge.

## Other responses

- `400`: Missing or invalid stable idempotency key, unsupported request format, or request outside the bounded nonstreaming text/function-tool contract.
- `401`: A valid Nodus API key or console session is required.
- `402`: Insufficient unreserved prepaid credits or account spending allowance. No new model request is dispatched.
- `403`: The authenticated user no longer has account write access.
- `404`: Model is not in this account’s qualified catalog or uses a different protocol.
- `409`: Previously accepted request returns its durable receipt without another model call or answer replay. A conflicting key, request or price version returns an ordinary error.
- `413`: The model request exceeds the supported body size.
- `429`: Nodus account request rate limit reached.
- `502`: Definitive rejection posts no model charge and releases the reservation. A missing response or uncertain usage returns model_outcome_unknown and keeps its reservation. Inspect the receipt and preserve the request identity.
- `503`: Model access or accounting admission is unavailable, or model_accounting_pending means a received response could not be durably settled. Inspect an accepted request receipt before retrying.
- `default`: Authentication, accounting and transient failures use the standard error shape.

## Changes

- **2026-10-01** `ba84c74aeec8`: 1 info
  - endpoint added
- **2026-10-01** `544fef290a54`: 1 breaking
  - api path removed without deprecation
- **2026-09-27** `c27e8c7c4e1f`: 1 info
  - endpoint added
- **2026-09-27** `90c4cb8514af`: 1 breaking
  - api path removed without deprecation
- **2026-09-25** `808adc26fb17`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/nodus-compute/apis/nodus-infrastructure-execution-api/changes/v1/managed-models/messages/post.md)

---

[API](https://skmtc.dev/nodus-compute/apis/nodus-infrastructure-execution-api.md) - [All operations](https://skmtc.dev/nodus-compute/apis/nodus-infrastructure-execution-api/llms.txt) - [OpenAPI document](https://skmtc.dev/nodus-compute/apis/nodus-infrastructure-execution-api/revisions/a59210899d95?raw)