> ## Documentation Index > Fetch the complete documentation index at: https://docs.omniall.ai/llms.txt > Use this file to discover all available pages before exploring further. # Chat Completions > OpenAI Chat Completions API relayed by Omniall AI. **Base path:** `POST https://api.omniall.ai/v1/chat/completions` Compatible with the official OpenAI Chat Completions schema. Use model IDs from the [Model Square](https://omniall.ai/pricing). ### Common scenarios - **Vision**: multimodal `messages[].content` with `image_url` - **File analysis**: `type: file` content parts (when the upstream model supports it) - **Web search**: `web_search_options` / provider search fields when the model supports search - **Agent**: `tools` + `tool_choice` function calling loop - **Streaming**: `stream: true` (SSE) Official reference: https://platform.openai.com/docs/api-reference/chat ## OpenAPI ````yaml openapi/xgapi-public.yaml POST /v1/chat/completions openapi: 3.0.3 info: title: Omniall AI Public API description: >- Omniall AI public API. Website: https://omniall.ai — API host: https://api.omniall.ai — Model Square: https://omniall.ai/pricing version: 1.1.0 servers: - url: https://api.omniall.ai description: Production security: - bearerAuth: [] tags: - name: Models description: List models available to your API key. - name: ChatGPT Chat Completions x-group: ChatGPT description: OpenAI Chat Completions (`POST /v1/chat/completions`). - name: Responses description: OpenAI Responses API (`POST /v1/responses`). - name: Claude description: Anthropic Messages API (`POST /v1/messages`). - name: Gemini description: Google Gemini generateContent / streamGenerateContent. - name: Images description: >- Image generation (OpenAI Images), vendor guides, and Midjourney proxy APIs. - name: Video description: Async video tasks. - name: Audio description: Speech and related audio APIs. - name: Rerank description: Document reranking. paths: /v1/chat/completions: post: tags: - ChatGPT Chat Completions summary: Chat Completions description: > OpenAI Chat Completions API relayed by Omniall AI. **Base path:** `POST https://api.omniall.ai/v1/chat/completions` Compatible with the official OpenAI Chat Completions schema. Use model IDs from the [Model Square](https://omniall.ai/pricing). ### Common scenarios - **Vision**: multimodal `messages[].content` with `image_url` - **File analysis**: `type: file` content parts (when the upstream model supports it) - **Web search**: `web_search_options` / provider search fields when the model supports search - **Agent**: `tools` + `tool_choice` function calling loop - **Streaming**: `stream: true` (SSE) Official reference: https://platform.openai.com/docs/api-reference/chat operationId: createChatCompletion requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ChatCompletionRequest' examples: basic: summary: Basic chat value: model: gpt-4o-mini messages: - role: user content: Hello streaming: summary: Streaming value: model: gpt-4o-mini stream: true stream_options: include_usage: true messages: - role: user content: Write a short poem vision: summary: Image understanding (vision) value: model: gpt-4o messages: - role: user content: - type: text text: What is in this image? - type: image_url image_url: url: https://example.com/photo.jpg detail: auto file_analysis: summary: File / PDF analysis value: model: gpt-4o messages: - role: user content: - type: text text: Summarize this PDF - type: file file: filename: report.pdf file_data: data:application/pdf;base64,JVBERi0xLjQ... banana21_pdf_url: summary: Banana 2.1 · PDF URL reference image value: model: gemini-nano-banana-2.1 stream: true messages: - role: user content: - type: text text: >- Read the PDF. List labels, colors and shapes by page, then generate a reference-sheet image on a white background. - type: file file: filename: reference.pdf file_data: https://example.com/reference.pdf extra_body: google: image_config: aspect_ratio: '3:2' image_size: 1K banana21_video_url: summary: Banana 2.1 · video URL reference image value: model: gemini-nano-banana-2.1 stream: true messages: - role: user content: - type: text text: >- Watch the video. List scene elements in order, then generate a reference-sheet image. - type: video_url video_url: https://example.com/clip.mp4 extra_body: google: image_config: aspect_ratio: '3:2' image_size: 1K web_search: summary: Web search (when model supports it) value: model: gpt-4o-search-preview web_search_options: search_context_size: medium messages: - role: user content: What are today's top AI product launches? agent_tools: summary: Agent / function calling value: model: gpt-4o tools: - type: function function: name: get_weather description: Get weather by city parameters: type: object properties: city: type: string required: - city tool_choice: auto messages: - role: user content: Weather in Tokyo? json_schema: summary: Structured JSON output value: model: gpt-4o response_format: type: json_schema json_schema: name: movie strict: true schema: type: object properties: title: type: string year: type: integer required: - title - year additionalProperties: false messages: - role: user content: Return Inception as JSON responses: '200': description: Chat completion JSON, or SSE stream when `stream=true`. content: application/json: schema: $ref: '#/components/schemas/ChatCompletionResponse' example: id: chatcmpl-... object: chat.completion created: 1710000000 model: gpt-4o-mini choices: - index: 0 message: role: assistant content: Hello! finish_reason: stop usage: prompt_tokens: 10 completion_tokens: 4 total_tokens: 14 '400': description: Invalid request body or unsupported parameter for the model. content: application/json: schema: $ref: '#/components/schemas/OpenAIErrorResponse' '401': description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/OpenAIErrorResponse' example: error: message: '无效的令牌 (request id: ...)' type: new_api_error code: '' '403': description: Forbidden (banned user, IP allowlist, group access). content: application/json: schema: $ref: '#/components/schemas/OpenAIErrorResponse' '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/OpenAIErrorResponse' '500': description: Upstream or gateway internal error. content: application/json: schema: $ref: '#/components/schemas/OpenAIErrorResponse' components: schemas: ChatCompletionRequest: type: object required: - model - messages description: >- OpenAI Chat Completions request (`POST /v1/chat/completions`). Maps to Omniall gateway `GeneralOpenAIRequest`. properties: model: type: string description: >- Model id from Model Square / `GET /v1/models`. Must be a model your key can access. example: gpt-4o messages: type: array items: $ref: '#/components/schemas/ChatMessage' description: >- Full conversation so far, oldest first. Include system/user/assistant/tool turns as needed. stream: type: boolean description: >- If `true`, return Server-Sent Events (`chat.completion.chunk`) instead of a single JSON object. default: false stream_options: type: object properties: include_usage: type: boolean description: If `true`, include token `usage` on the final stream chunk. description: Streaming extras. temperature: type: number minimum: 0 maximum: 2 description: >- Sampling temperature (about 0–2). Higher = more random; `0` = more deterministic. top_p: type: number minimum: 0 maximum: 1 description: >- Nucleus sampling probability mass (0–1). Prefer tuning either temperature or top_p, not both aggressively. top_k: type: integer description: >- Top-K sampling when the upstream model supports it (ignored by some OpenAI models). 'n': type: integer minimum: 1 description: >- How many completions to generate for this prompt (cost scales with n). max_tokens: type: integer description: >- Legacy max tokens for the completion. Prefer `max_completion_tokens` on newer OpenAI models. max_completion_tokens: type: integer description: >- Maximum tokens the model may generate (preferred for newer OpenAI chat models). stop: oneOf: - type: string - type: array items: type: string description: Stop sequence(s). Generation ends when any sequence is produced. presence_penalty: type: number minimum: -2 maximum: 2 description: >- Penalize new tokens based on whether they appear in the text so far (−2 to 2). Positive values encourage new topics. frequency_penalty: type: number minimum: -2 maximum: 2 description: >- Penalize tokens by frequency (−2 to 2). Positive values reduce repetition. seed: type: number description: Best-effort deterministic seed when the provider supports it. user: type: string description: >- Stable end-user id for abuse monitoring (opaque string). Do not put secrets here. logit_bias: type: object additionalProperties: type: number description: >- Map of token-id → bias to ban/boost specific tokens (provider-specific). logprobs: type: boolean description: Whether to return log probabilities for output tokens. top_logprobs: type: integer description: >- Number of most likely tokens to return at each position when logprobs is enabled. response_format: type: object description: >- Force output shape. `json_object` asks for valid JSON; `json_schema` asks for JSON matching your schema (when supported). properties: type: type: string enum: - text - json_object - json_schema json_schema: type: object additionalProperties: true tools: type: array items: $ref: '#/components/schemas/ChatTool' description: Function tools available to the model for agent workflows. tool_choice: description: >- Controls tool use: `none` / `auto` / `required`, or force a specific function. oneOf: - type: string enum: - none - auto - required - type: object additionalProperties: true parallel_tool_calls: type: boolean description: Whether the model may call multiple tools in one turn. reasoning_effort: type: string enum: - low - medium - high description: >- Reasoning intensity for o-series / compatible models (`low` / `medium` / `high`). modalities: type: array items: type: string enum: - text - audio description: Requested output modalities, e.g. `text`, `audio`. audio: type: object additionalProperties: true description: Audio output settings when using audio modalities. web_search_options: type: object description: OpenAI-style web search options when the model supports search. properties: search_context_size: type: string enum: - low - medium - high description: >- How much search context to retrieve: `low` / `medium` / `high` (cost/latency tradeoff). user_location: type: object additionalProperties: true description: Optional user location hint to localize search results. enable_search: description: Qwen-style web search toggle (channel/model dependent). oneOf: - type: boolean - type: object web_search: description: Provider-specific web search object (e.g. Baidu). type: object additionalProperties: true search_parameters: description: xAI search parameters object. type: object additionalProperties: true thinking: description: Doubao / Zhipu thinking controls. type: object additionalProperties: true enable_thinking: description: Qwen thinking toggle. oneOf: - type: boolean - type: object extra_body: description: >- Extra provider fields (sometimes used for Gemini-related options on the OpenAI-compatible path). type: object additionalProperties: true metadata: type: object additionalProperties: true description: Arbitrary metadata passthrough when supported. prediction: type: object additionalProperties: true description: >- Predicted-output hint to reduce latency when you can anticipate part of the answer. ChatCompletionResponse: type: object properties: id: type: string description: Unique completion id. object: type: string example: chat.completion description: Always `chat.completion` for non-streaming. created: type: integer description: Unix timestamp (seconds) when the completion was created. model: type: string description: Model that produced the answer (may reflect routing). choices: type: array items: type: object properties: index: type: integer description: Choice index, starting at 0. message: $ref: '#/components/schemas/ChatMessage' description: Assistant message (`role`, `content`, optional `tool_calls`). finish_reason: type: string enum: - stop - length - tool_calls - content_filter description: >- Why generation stopped: `stop`, `length`, `tool_calls`, `content_filter`, etc. description: One choice. description: Generated choices (usually one). usage: type: object properties: prompt_tokens: type: integer description: Tokens in the input messages/tools. completion_tokens: type: integer description: Tokens in the generated answer. total_tokens: type: integer description: prompt_tokens + completion_tokens. description: Token usage when provided by upstream. system_fingerprint: type: string description: Upstream system fingerprint when available (reproducibility signal). description: Non-streaming Chat Completions response. OpenAIErrorResponse: type: object description: OpenAI-style error envelope returned on auth/request failures. required: - error properties: error: type: object required: - message - type properties: message: type: string description: >- Human-readable error. The gateway may append a request id for support. type: type: string description: Error type, commonly `new_api_error`. example: new_api_error code: type: string description: >- Optional machine-readable code (e.g. `access_denied`). May be an empty string. description: Error object. ChatMessage: type: object required: - role properties: role: type: string enum: - system - user - assistant - tool - developer description: >- Speaker role. `system` = global instructions; `user` = end-user / app input; `assistant` = prior model reply; `tool` = tool result for a previous tool call; `developer` = OpenAI developer role when used. content: description: >- Message body. Use a string for plain text, or an array of `MessageContent` parts for multimodal input (vision/files). oneOf: - type: string - type: array items: $ref: '#/components/schemas/MessageContent' name: type: string description: >- Optional speaker name (some providers prepend it for non-OpenAI models). tool_calls: type: array items: type: object description: >- Present on assistant messages when the model wants to call tools/functions. tool_call_id: type: string description: >- Required when `role` is `tool`: id of the tool call this message answers. reasoning_content: type: string description: >- Reasoning/thinking text when the model returns it separately from the final answer. description: One message in the Chat Completions `messages` array. ChatTool: type: object properties: type: type: string example: function description: Usually `function`. function: type: object properties: name: type: string description: >- Function name the model will call (stable identifier, no spaces). description: type: string description: >- Natural-language description of when/why to call this function. Better descriptions improve tool selection. parameters: type: object additionalProperties: true description: JSON Schema object describing function arguments. required: - name description: Function definition. description: A function tool the model can call (agent / tool-calling). MessageContent: type: object properties: type: type: string enum: - text - image_url - input_audio - file - video_url description: >- Part type selector. `text` = plain text; `image_url` = image for vision; `file` = document (PDF etc.); `input_audio` = audio input; `video_url` = video URL when supported. text: type: string description: Text for this part when `type` is `text`. image_url: type: object properties: url: type: string description: >- HTTPS image URL or a data URL (`data:image/png;base64,...`). Public URLs must be downloadable without auth. detail: type: string enum: - auto - low - high description: >- Vision detail level: `low` (faster/cheaper), `high` (more detail), `auto` (model default). required: - url description: Image payload when `type` is `image_url`. input_audio: type: object properties: data: type: string description: Base64-encoded audio bytes. format: type: string example: wav description: Audio format hint, e.g. `wav` or `mp3`. description: Audio payload when `type` is `input_audio`. file: type: object description: >- File/document payload when `type` is `file` (for document Q&A when the model supports it). properties: filename: type: string description: >- Original file name, e.g. `report.pdf` (helps the model and logs). file_data: type: string description: File content as Base64 or a `data:` URL. file_id: type: string description: >- Previously uploaded file id, if your flow uses file upload instead of inlining bytes. video_url: oneOf: - type: string - type: object properties: url: type: string description: >- Video URL (string or `{ "url": "..." }`) when `type` is `video_url` and the model supports video input. description: >- One multimodal content part inside a chat message. Set `type` and fill the matching field (`text`, `image_url`, `file`, `input_audio`, or `video_url`). securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API Key description: 'Use Authorization: Bearer sk-... from https://omniall.ai/dashboard' ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.