Chat & text

Implementation target. This guide specifies the intended product surface. The current frontend uses local samples; it does not call an inference service or collect funds. An endpoint is enabled only after its adapter, ownership, usage, and payment behavior are qualified.

Planned API origin. Examples use https://noemad.dev/v1, the intended product API path. The API is not connected in this frontend preview. MODEL_ID_FROM_DISCOVERY and NOEMAD_API_KEY are placeholders, not published credentials or model IDs. A product API key identifies an account; a separate payment-aware transport must handle spending authorization.

Choose the right request format

All three retain their native success and error contracts. Payment authorization wraps the transport lifecycle; it does not require changing the model’s prompt into a proprietary single-input format.

Chat Completions example

{
  "model": "MODEL_ID_FROM_DISCOVERY",
  "messages": [
    {
      "role": "system",
      "content": "Return a concise, useful answer."
    },
    {
      "role": "user",
      "content": "Summarize the design and list next steps."
    }
  ],
  "max_tokens": 1024,
  "thinking": "medium",
  "stream": true
}

Send only controls advertised by the chosen model. The example reasoning level is a placeholder choice, not a universal supported value. The service must quote and enforce the actual output limit before dispatch.

Responses example

{
  "model": "MODEL_ID_FROM_DISCOVERY",
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "Explain this design in three points."
        }
      ]
    }
  ],
  "max_output_tokens": 1024,
  "reasoning": {
    "effort": "medium"
  },
  "stream": true
}

Preserve response event ordering, content item IDs, final usage, and failure events. A client should not treat the first output delta as a completed response.

Messages example

{
  "model": "MODEL_ID_FROM_DISCOVERY",
  "system": "Be concise and state uncertainty.",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Review this proposal."
        }
      ]
    }
  ],
  "max_tokens": 1024,
  "stream": true
}

Messages content blocks and stop semantics must remain compatible. The server may accept the Messages authentication header where the final contract declares it. A separate token-count operation must be qualified before clients depend on it.

Read capabilities instead of guessing

Use input_modalities, context_length, max_output, and thinking from authenticated discovery. Text, image, video, and file input support vary even within one model family. Model-specific attachment limits and MIME requirements must also be enforced.

The complete archived capability table and searchable model library preserve the source records. Their published maximums do not override Noemad’s admitted request limits.

Reasoning controls

auto delegates the choice only when supported. none disables reasoning only on models that advertise it. Levels such as minimal, low, medium, high, xhigh, and max are model-specific. A model with only auto should not show a runtime effort selector.

The adapter maps product-compatible fields such as reasoning.effort or a thinking value into the native provider contract. Hidden reasoning tokens may affect usage differently from visible output; the quote must state the relevant limit and billing behavior.

Tool definitions and complete history

{
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "lookup_note",
        "description": "Read a note the user has allowed this app to access.",
        "parameters": {
          "type": "object",
          "properties": {
            "note_id": {
              "type": "string"
            }
          },
          "required": [
            "note_id"
          ],
          "additionalProperties": false
        }
      }
    }
  ],
  "tool_choice": "auto"
}

Tool declarations must match the endpoint format and selected model. A returned call must name a declared tool and contain complete schema-valid arguments. Match every tool result to its original call ID; preserve the original order and content blocks when continuing the conversation.

The application, not the model, authorizes tool execution. Model output cannot increase a spending budget, change a payment recipient, or expand a tool’s data access. Parallel tool calls are permitted only when both model and application support them.

Structured output and validation

Where supported, schema-constrained text output can request a specific object shape. It is distinct from the dedicated typed evaluation endpoint. Pin the schema and model configuration, then validate the entire output.

{
  "title": "An illustrative summary",
  "summary": "A brief explanation of the proposal.",
  "actions": [
    "Resolve the main open decision.",
    "Assign the next task."
  ]
}

Reject empty content, unrecognized error envelopes, truncated JSON, invalid tool arguments, and forbidden finish reasons. A response succeeds only after its complete protocol and output contract are satisfied.

Usage and payment outcome

Record ordinary input, cached input, output, reasoning, or cache-write fields according to the model’s documented accounting. Do not double-count cached input already included in total input. Missing usage is unknown, not zero or the approved maximum.

Inference completion and collection are separate. A usable partial stream can be billable under the pinned delivery policy, but it must have reliable attributable usage. An uncertain dispatch or usage outcome enters reconciliation rather than triggering a duplicate inference request.