---
title: "Generate"
method: POST
path: "/v1/generate/{model}"
tags: ["generate"]
---

# Generate

`POST /v1/generate/{model}`

Generate text from a prompt using the named model.

The ``model`` path segment uses the **SIE-safe** id (double-underscore
separator, e.g. ``Qwen__Qwen3-4B-Instruct``). HuggingFace-style slashes
are rejected with 400 to keep parity with the gateway contract.

## Path parameters

- `model` string, required

## Headers

- `X-SIE-MACHINE-PROFILE` string, nullable

## Request body

- GenerateRequestModel — Request body for the SIE-native generate endpoint.
  - `prompt` string, required — Prompt text to generate from
  - `images` NativeGenerateImageModel[], nullable — Optional inline images paired with prompt. The worker renders one user turn through the model's native chat template; remote URLs are not accepted.
    - `data` string, required — Canonical standard-base64 image bytes, at most 16 MiB decoded
    - `format` string, nullable — Short media-format hint such as png or jpeg
  - `grammar` union — Optional structured-output grammar; exactly one of json_schema, regex, or ebnf
    - NativeJsonSchemaGrammarModel — JSON Schema structured-output constraint.
      - `json_schema` object, required
      - `label` string, nullable
      - `strict` boolean, nullable
    - NativeRegexGrammarModel — Regular-expression structured-output constraint.
      - `regex` string, required
      - `label` string, nullable
      - `strict` boolean, nullable
    - NativeEbnfGrammarModel — EBNF structured-output constraint.
      - `ebnf` string, required
      - `label` string, nullable
      - `strict` boolean, nullable
  - `max_new_tokens` integer, required — Maximum number of tokens to generate
  - `temperature` number, nullable — Sampling temperature override
  - `top_p` number, nullable — Nucleus-sampling probability override
  - `options` object, nullable — Governed generation runtime options; explicit top-level sampler fields override them
  - `stop` string[], nullable — Stop sequences
  - `stream` boolean, nullable — Return SIE-native Server-Sent Events when true
  - `frequency_penalty` number, nullable — Frequency penalty
  - `presence_penalty` number, nullable — Presence penalty
  - `seed` integer, nullable — Optional signed 64-bit per-request sampling seed. Reproducibility is best effort, not guaranteed, and depends on the active generation backend and deployment configuration. Non-integer or out-of-range values reject with 400 invalid_request.
  - `logit_bias` object, nullable — Token-id string to finite sampler bias in [-100, 100]
  - `logprobs` boolean, nullable — Return per-token log probabilities; supported only with stream true
  - `top_logprobs` integer, nullable — Alternative tokens per position; requires logprobs and stream true
  - `routing_key` string, nullable — Optional routing hint
  - `prompt_cache_key` string, nullable — Optional prompt-cache routing hint
  - `safety_identifier` string, nullable — Sensitive client identifier; validated and dropped without logging or forwarding

## Response `200`

Generated text, or a Server-Sent Event stream when stream is true

- GenerateResponseModel — Blocking response from the SIE-native generate endpoint.
  - `model` string, required — Model used for generation
  - `text` string, required — Generated text
  - `finish_reason` string, required — Reason generation stopped
  - `usage` GenerateUsageModel, required — Token usage for one generation request.
    - `prompt_tokens` integer, required — Number of prompt tokens
    - `completion_tokens` integer, required — Number of generated tokens
    - `total_tokens` integer, required — Total prompt and generated tokens

## Other responses

- `400` — Invalid request
- `404` — Model not found
- `413` — Prompt exceeds the configured UTF-8 size limit (INPUT_TOO_LONG)
- `422` — Validation Error
- `502` — Terminal model-load failure (MODEL_LOAD_FAILED). Carried in the detail envelope: {code, message, error_class, permanent, attempts}. No Retry-After header; clients must not auto-retry.
- `503` — Model loading or unavailable

---

[API](https://skmtc.dev/superlinked/apis/sie-server.md) · [All operations](https://skmtc.dev/superlinked/apis/sie-server/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/superlinked/sie-server/revisions/26ac644915a4/schema)