Parameters

Replace <BASE_URL> using values from Endpoints.

Request parameters for POST /v1/chat/completions.

Required

Parameter	Type	Description
`model`	string	Model id from `GET /v1/models`
`messages`	array	OpenAI chat messages; `content` may be a string or a content-part array (text + images / video, etc.)

Common optional parameters

SupaNexus passes through standard OpenAI parameters when the model supports them. Check supported_parameters on the model object.

Parameter	Type	Description	Example
`stream`	boolean	Stream tokens as they are generated; use `true` for chat UIs, `false` for batch jobs	`"stream": true`
`temperature`	number	Randomness: higher = more creative; lower = more stable and repeatable. Try `0.7` for chat, `0`–`0.3` for factual Q&A	`"temperature": 0.7`
`top_p`	number	Another randomness control (nucleus sampling); usually tune either this or `temperature`, not both aggressively	`"top_p": 0.9`
`max_tokens`	integer	Cap reply length in tokens — avoids overly long answers or runaway cost	`"max_tokens": 1024`
`frequency_penalty`	number	Discourage repeating the same words — higher values reduce “looping” phrasing	`"frequency_penalty": 0.5`
`presence_penalty`	number	Encourage new topics — higher values reduce staying stuck on one point	`"presence_penalty": 0.3`
`stop`	string or array	Generation stops when the model outputs these strings — useful for sections or lists	`"stop": ["\n\n", "END"]`
`tools`	array	Declare functions the model may call (weather, orders, etc.); requires Function Calling support	See example below
`tool_choice`	string or object	Tool policy: `"auto"` (model decides), `"none"` (disable), `"required"` (must call a tool)	`"tool_choice": "auto"`
`response_format`	object	Force a structured output shape, e.g. valid JSON only	`"response_format": {"type": "json_object"}`
`user`	string	End-user id in your app — helps abuse tracking; on OpenAI models can also improve Prompt Cache hit rate	`"user": "user-42"`

tools example (simplified):

"tools": [
  {
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "Get current weather for a city",
      "parameters": {
        "type": "object",
        "properties": {
          "city": { "type": "string", "description": "City name, e.g. Shanghai" }
        },
        "required": ["city"]
      }
    }
  }
]

Multimodal input

When the model supports vision or video, messages[].content may be a content-part array (OpenAI-compatible format).

Confirm via GET /v1/models that architecture.input_modalities includes "image" for images and/or "video" for video. Text-only models (["text"] only) reject media.

Images (`image_url`)

Image URL example

{
  "model": "google/gemini-2.5-flash",
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "text", "text": "Describe this image"},
        {
          "type": "image_url",
          "image_url": {
            "url": "https://example.com/photo.jpg"
          }
        }
      ]
    }
  ]
}

Base64 image example

Set image_url.url to a data URI:

{
  "type": "image_url",
  "image_url": {
    "url": "data:image/jpeg;base64,/9j/4AAQSkZJRg..."
  }
}

Base64 inflates the body by about 33%. The default body limit is 64 MB; exceeding it returns 413 with error.code request_too_large. Prefer a publicly reachable URL for large images.

Video (`video_url`)

When input_modalities includes "video" (e.g. minimax/minimax-m3, moonshot/kimi-k2.6), use a video_url content part.

Whale v1 policy:

Allowed	Not allowed
Public `http://` / `https://` video URLs (upstream fetches the media)	`data:` (base64), `file://`, `blob:`, vendor file refs (e.g. `mm_file://`, `ms://`)

Invalid video_url values are rejected with 400 and are not forwarded. Do not send video as a data URI through the gateway — that would consume platform bandwidth.

Public video URL example

{
  "model": "minimax/minimax-m3",
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "text", "text": "Summarize this video"},
        {
          "type": "video_url",
          "video_url": {
            "url": "https://example.com/demo.mp4",
            "detail": "default"
          }
        }
      ]
    }
  ]
}

Some upstreams also accept fields such as fps for frame sampling; they are passed through when supported.

Limitation: Anthropic upstream models

When an OpenAI client (POST /v1/chat/completions) calls anthropic/*, the gateway translates the request and flattens messages to plain text — images are dropped silently. For images use POST /v1/messages.

Rule of thumb: for images, align client protocol with upstream — /v1/messages for anthropic/*, /v1/chat/completions otherwise.

Request handling

Recognized fields

model — model id for this call
stream — SSE streaming vs JSON response

Streaming usage

When stream: true, the response may include a usage object at the end (model-dependent).

Other parameters

Remaining JSON fields are handled in an OpenAI-compatible way within body size limits.

Body size limit

Default maximum request body: 64 MB (GATEWAY_OPENAPI_MAX_REQUEST_BODY_BYTES).

Exceeding the limit returns 413 with error.code request_too_large. Large images may use data URIs; large videos must use a public URL — do not base64-encode video into the request body.

Model-specific defaults

Each model may expose default_parameters in GET /v1/models. These are suggested defaults; the client may override them in the request.