Help guides

Create a model response for a chat conversation. Request and response shapes follow OpenAI Chat Completions. Unlisted top-level fields are passed through when safe.

POST https://ai.win10030.com/v1/chat/completions

Authentication

Authorization: Bearer YOUR_API_KEY — required.

Recommended headers

Header	Description
`Content-Type`	`application/json`
`Accept`	`application/json`, or `text/event-stream` when `stream: true`
`x-trace-id`	Optional correlation id (max 256 chars)
`x-user-id`	Optional end-user id in your system
`x-agent-name`	Optional agent name (recorded in usage)

Request body

Field	Required	Description
`model`	yes	Catalog `id` from `GET /models`
`messages`	yes	Array, min length 1
`stream`	no	`true` → SSE (`chat.completion.chunk`)
`max_tokens`	no	Max output tokens
`temperature`, `top_p`	no	Sampling
`stop`	no	String or string array
`frequency_penalty`, `presence_penalty`	no	OpenAI-compatible
`seed`	no	Integer seed when upstream supports
`tools`	no	Up to 64 function tools
`tool_choice`	no	`none` / `auto` / `required` or named function
`pdf_preprocess`	no	Gateway PDF extension (below)
`extra_body`	no	JSON object merged into upstream (OpenAI-compatible routes)
`stream_options`	no	Gateway always enables `include_usage` on streams

Limit: JSON body up to 32 MB.

`messages[]`

`role`	Notes
`system`, `user`, `assistant`, `developer`	Standard
`tool`	Non-empty `tool_call_id` required
`assistant`	May include `tool_calls`; `content` may be `null` when only tools

content may be a string, null (treated as empty), or an array of parts for multimodal user messages.

User content parts

`type`	Description
`text`	Plain text
`image_url`	`{ "url": "...", "detail": "auto" }`
`input_audio`	Audio input (OpenAI wire)
`file`	File input with nested `file` object: `{ "file": { "file_data": "...", "filename": "..." } }`

`pdf_preprocess` (gateway)

{ "engine": "native" }

`engine`	Behavior
`native`	Default — forward unchanged
`ocr`	OCR then send upstream
`markdown`	Extract as Markdown

Optional: max_pages (≤ 50), merge_pages.

Non-streaming example

curl -sS "https://ai.win10030.com/v1/chat/completions" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL_ID",
    "messages": [{"role": "user", "content": "Summarize edge gateways in one sentence."}]
  }'

Streaming

Set "stream": true and Accept: text/event-stream. See Streaming and Streaming quickstart.

Tools example

curl -sS "https://ai.win10030.com/v1/chat/completions" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL_ID",
    "messages": [{"role": "user", "content": "What is the weather in Paris?"}],
    "tools": [{
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get weather for a city",
        "parameters": {
          "type": "object",
          "properties": { "city": { "type": "string" } },
          "required": ["city"]
        }
      }
    }],
    "tool_choice": "auto"
  }'

After tool_calls, append the assistant message with calls, then role: "tool" results, and call again.

Multimodal (files)

Send files in user content arrays via file parts with nested file object:

`file` field	Description
`file_data`	Inline base64 data, supports `data:<mime>;base64,...` format
`filename`	File name for MIME type inference (e.g. `spec.pdf`)

Inline file example

curl -sS "https://ai.win10030.com/v1/chat/completions" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"YOUR_MODEL_ID\",
    \"messages\": [{
      \"role\": \"user\",
      \"content\": [
        { \"type\": \"text\", \"text\": \"List key requirements\" },
        { \"type\": \"file\", \"file\": { \"filename\": \"spec.pdf\", \"file_data\": \"data:application/pdf;base64,$(base64 spec.pdf | tr -d '\n')\" } }
      ]
    }]
  }"

Image examples

image_url (OpenAI-compatible):

{ "type": "image_url", "image_url": { "url": "https://example.com/photo.jpg" } }

Or file with inline base64:

{ "type": "file", "file": { "filename": "photo.jpg", "file_data": "data:image/jpeg;base64,..." } }

See Files and context.

Response (non-streaming)

OpenAI-shaped chat.completion with choices[].message, usage, and id.

Errors

{
  "error": {
    "message": "...",
    "type": "invalid_request_error",
    "param": "messages[0].content",
    "code": null
  }
}

Status	Typical cause
400	Validation (messages, parts, size)
401	Invalid or expired API key
403	Model denied, balance, IP, upstream keys
429	Rate limit
502/503	Upstream failure

See Errors · OpenAI differences.