> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nomask.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a chat completion

> Generate text using the OpenAI Chat Completions format. Set stream=true for SSE. Model-specific capabilities govern tools, vision, video and reasoning. Select a current text model ID. This API does not support Responses, structured JSON output, file uploads or built-in web access. Paid requests debit your NoMask balance.



## OpenAPI

````yaml /openapi.json post /chat/completions
openapi: 3.0.3
info:
  title: NoMask API
  version: 1.0.0
  description: >-
    OpenAI-compatible text and image APIs with prepaid USD billing. Use a NoMask
    Bearer key and a current public model ID. Request examples contain
    placeholders; replace them before using Try it.


    The documentation playground sends requests through Mintlify's proxy. curl
    and SDK examples call NoMask directly. Only enter your own key and prompts
    you intend to send. Generation requests can incur charges; GET endpoints
    inspect account metadata without generating content.
  contact:
    name: NoMask Support
    email: support@nomask.ai
    url: https://docs.nomask.ai/support
servers:
  - url: https://api.nomask.ai/v1
    description: NoMask API
security:
  - bearerAuth: []
tags:
  - name: Chat
    description: Chat Completions with optional streaming, tools and multimodal inputs.
  - name: Images
    description: Synchronous image generation and editing.
  - name: Models
    description: Current model IDs, capabilities, limits and pricing.
  - name: Account
    description: Balance, usage and calling-key metadata.
paths:
  /chat/completions:
    post:
      tags:
        - Chat
      summary: Create a chat completion
      description: >-
        Generate text using the OpenAI Chat Completions format. Set stream=true
        for SSE. Model-specific capabilities govern tools, vision, video and
        reasoning. Select a current text model ID. This API does not support
        Responses, structured JSON output, file uploads or built-in web access.
        Paid requests debit your NoMask balance.
      operationId: createChatCompletion
      parameters:
        - name: Idempotency-Key
          in: header
          required: false
          description: >-
            For non-streaming requests, identical key and body can replay a
            successful response for 24 hours. Streaming requests do not use this
            replay cache.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatCompletionRequest'
            example:
              model: your-text-model-id
              messages:
                - role: user
                  content: Explain a database index in one sentence.
      responses:
        '200':
          description: Successful response. Example values are illustrative.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            X-RateLimit-Profile:
              $ref: '#/components/headers/XRateLimitProfile'
            X-RateLimit-Limit-Requests:
              $ref: '#/components/headers/XRateLimitLimitRequests'
            X-RateLimit-Remaining-Requests:
              $ref: '#/components/headers/XRateLimitRemainingRequests'
            X-RateLimit-Reset:
              $ref: '#/components/headers/XRateLimitReset'
            X-RateLimit-Limit-Tokens:
              $ref: '#/components/headers/XRateLimitLimitTokens'
            X-RateLimit-Remaining-Tokens:
              $ref: '#/components/headers/XRateLimitRemainingTokens'
            Idempotency-Replayed:
              $ref: '#/components/headers/IdempotencyReplayed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatCompletionResponse'
              example:
                id: chatcmpl_example
                object: chat.completion
                created: 1793617200
                model: your-text-model-id
                choices:
                  - index: 0
                    message:
                      role: assistant
                      content: >-
                        A database index helps a database find matching rows
                        without scanning the entire table.
                    finish_reason: stop
                usage:
                  prompt_tokens: 14
                  completion_tokens: 19
                  total_tokens: 33
                nomask:
                  cost_usd: 0.0001
                  model_cost_usd: 0.0001
                  prompt_cache:
                    enabled: false
                    usage_status: unreported
                    read_tokens: null
                    write_tokens: null
                    usd_per_1m_cached_input: null
                    savings_usd: null
            text/event-stream:
              schema:
                type: string
                description: >-
                  SSE chat.completion.chunk events carrying
                  role/content/reasoning/tool-call deltas; optional final usage
                  chunk. Ends with data: [DONE]. Mid-stream failures emit an
                  error event.
              example: >+
                data:
                {"id":"chatcmpl_example","object":"chat.completion.chunk","created":1793617200,"model":"your-text-model-id","choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}]}


                data:
                {"id":"chatcmpl_example","object":"chat.completion.chunk","created":1793617200,"model":"your-text-model-id","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}


                data: [DONE]

        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '402':
          $ref: '#/components/responses/Error402'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '413':
          $ref: '#/components/responses/Error413'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '502':
          $ref: '#/components/responses/Error502'
        '503':
          $ref: '#/components/responses/Error503'
        '504':
          $ref: '#/components/responses/Error504'
components:
  schemas:
    ChatCompletionRequest:
      type: object
      properties:
        model:
          type: string
          description: >-
            Current public text model ID from GET /models. No automatic OpenAI
            model-name mapping.
          minLength: 1
          example: your-text-model-id
        messages:
          type: array
          items:
            $ref: '#/components/schemas/ChatMessage'
          description: Conversation history.
          minItems: 1
        stream:
          type: boolean
          description: Return server-sent events rather than a completed JSON response.
          default: false
        stream_options:
          type: object
          properties:
            include_usage:
              type: boolean
              description: >-
                Include a final usage/cost chunk with empty choices before
                [DONE].
              default: false
        temperature:
          type: number
          description: Sampling temperature, subject to model support.
          minimum: 0
          maximum: 2
        top_p:
          type: number
          description: Nucleus sampling probability, subject to model support.
          minimum: 0
          maximum: 1
        frequency_penalty:
          type: number
          description: Frequency penalty, subject to model support.
          minimum: -2
          maximum: 2
        presence_penalty:
          type: number
          description: Presence penalty, subject to model support.
          minimum: -2
          maximum: 2
        max_tokens:
          type: integer
          description: >-
            Output token ceiling including reasoning. Defaults to model
            max_output_tokens; larger values are clamped to that ceiling.
          minimum: 1
        max_completion_tokens:
          type: integer
          description: Alias for max_tokens. Takes precedence when both are supplied.
          minimum: 1
        stop:
          oneOf:
            - type: string
            - type: array
              items:
                type: string
              maxItems: 4
          description: One stop sequence, or up to four.
        'n':
          type: integer
          description: One completion per request.
          enum:
            - 1
          default: 1
        tools:
          type: array
          items:
            $ref: '#/components/schemas/FunctionTool'
          description: >-
            Client-defined functions. Requires the model's function_calling
            capability. Your application executes returned tool calls.
          minItems: 1
          maxItems: 64
        tool_choice:
          oneOf:
            - type: string
              enum:
                - auto
                - none
                - required
            - type: object
              properties:
                type:
                  type: string
                  enum:
                    - function
                function:
                  type: object
                  properties:
                    name:
                      type: string
                  required:
                    - name
              required:
                - type
                - function
          description: >-
            Requires tools. Select automatically, prohibit tool calls, require a
            tool call, or name a function.
        parallel_tool_calls:
          type: boolean
          description: Allow multiple tool calls in one assistant turn. Used with tools.
        reasoning:
          type: object
          properties:
            enabled:
              type: boolean
              description: Request reasoning on/off. Always-on models may override off.
            effort:
              type: string
              description: >-
                Requested effort; resolved against the selected model's
                supported levels.
              enum:
                - none
                - minimal
                - low
                - medium
                - high
                - xhigh
                - max
        reasoning_effort:
          type: string
          description: >-
            Shorthand for reasoning effort; takes precedence over
            reasoning.effort. none requests Off.
          enum:
            - none
            - minimal
            - low
            - medium
            - high
            - xhigh
            - max
        nomask_system_prompt:
          type: boolean
          description: >-
            Prepend NoMask's model persona before your messages. Your own system
            messages are preserved.
          default: false
        response_format:
          type: object
          properties:
            type:
              type: string
              enum:
                - text
          required:
            - type
          nullable: true
          description: >-
            Only text output is supported. Omit this field or set type=text.
            json_object and json_schema return unsupported_parameter.
      required:
        - model
        - messages
      description: >-
        OpenAI-compatible Chat Completions. Legacy functions/function_call,
        logprobs, audio, modalities, prediction, file inputs and web access
        fields are unsupported.
    ChatCompletionResponse:
      type: object
      properties:
        id:
          type: string
          description: Completion identifier.
        object:
          type: string
          enum:
            - chat.completion
        created:
          type: integer
          description: Unix timestamp.
          format: int64
        model:
          type: string
          description: Selected public model ID.
        choices:
          type: array
          items:
            type: object
            properties:
              index:
                type: integer
                enum:
                  - 0
              message:
                type: object
                properties:
                  role:
                    type: string
                    enum:
                      - assistant
                  content:
                    type: string
                    description: Assistant text; null on pure tool-call turns.
                    nullable: true
                  reasoning_content:
                    type: string
                    description: Reasoning text when available.
                  tool_calls:
                    type: array
                    items:
                      $ref: '#/components/schemas/ToolCall'
                required:
                  - role
                  - content
              finish_reason:
                type: string
                description: >-
                  Current API responses normalize completion reasons to stop or
                  tool_calls.
                enum:
                  - stop
                  - tool_calls
            required:
              - index
              - message
              - finish_reason
          minItems: 1
          maxItems: 1
        usage:
          $ref: '#/components/schemas/TokenUsage'
        nomask:
          $ref: '#/components/schemas/ChatNoMask'
      required:
        - id
        - object
        - created
        - model
        - choices
        - usage
        - nomask
    ChatMessage:
      type: object
      properties:
        role:
          type: string
          description: Message role.
          enum:
            - system
            - user
            - assistant
            - tool
        content:
          oneOf:
            - type: string
              nullable: true
            - type: array
              items:
                oneOf:
                  - $ref: '#/components/schemas/TextPart'
                  - $ref: '#/components/schemas/ImagePart'
                  - $ref: '#/components/schemas/VideoPart'
              minItems: 1
          description: >-
            Required string or nonempty content-part array. Assistant tool-call
            messages may omit content or set it to null. Tool result messages
            require string content.
        tool_call_id:
          type: string
          description: >-
            Required for tool messages; identifies the assistant tool call being
            answered.
        tool_calls:
          type: array
          items:
            $ref: '#/components/schemas/ToolCall'
          description: Assistant tool calls from the preceding response.
          minItems: 1
      required:
        - role
      description: >-
        Each message requires content, except an assistant message with nonempty
        tool_calls. Video parts are valid only in user messages. File/input_file
        parts and developer roles are not supported.
    FunctionTool:
      type: object
      properties:
        type:
          type: string
          enum:
            - function
        function:
          type: object
          properties:
            name:
              type: string
              description: Function name.
              minLength: 1
              maxLength: 64
              pattern: ^[a-zA-Z0-9_-]+$
            description:
              type: string
              description: Purpose of this function.
            parameters:
              type: object
              properties: {}
              additionalProperties: true
              description: JSON Schema describing function arguments.
          required:
            - name
      required:
        - type
        - function
    ToolCall:
      type: object
      properties:
        id:
          type: string
          description: Tool call identifier.
        type:
          type: string
          enum:
            - function
        function:
          type: object
          properties:
            name:
              type: string
              description: Function name.
            arguments:
              type: string
              description: JSON-encoded argument string. Validate before executing.
          required:
            - name
            - arguments
      required:
        - id
        - type
        - function
    TokenUsage:
      type: object
      properties:
        prompt_tokens:
          type: integer
          description: Input tokens, including supported media and injected instructions.
          minimum: 0
        completion_tokens:
          type: integer
          description: Output tokens, including reasoning.
          minimum: 0
        total_tokens:
          type: integer
          description: Input plus output tokens.
          minimum: 0
        prompt_tokens_details:
          type: object
          properties:
            cached_tokens:
              type: integer
              description: Confirmed cache-read tokens.
              minimum: 0
            cache_write_tokens:
              type: integer
              description: Reported cache-write tokens.
              minimum: 0
          description: Included when cache counters are available.
      required:
        - prompt_tokens
        - completion_tokens
        - total_tokens
    ChatNoMask:
      type: object
      properties:
        model_cost_usd:
          type: number
          description: Model charge in USD.
        cost_usd:
          type: number
          description: Settled debit in USD.
        prompt_cache:
          $ref: '#/components/schemas/PromptCache'
        warnings:
          type: array
          items:
            type: string
          description: Options that were adjusted or ignored for this model.
      required:
        - model_cost_usd
        - cost_usd
        - prompt_cache
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              description: Human-readable error.
            type:
              type: string
              description: Error category.
            code:
              type: string
              description: Machine-readable NoMask error code.
            param:
              type: string
              description: The invalid parameter, if applicable.
              nullable: true
          required:
            - message
            - type
            - code
            - param
      required:
        - error
    TextPart:
      type: object
      properties:
        type:
          type: string
          enum:
            - text
        text:
          type: string
          description: Text sent to the model.
      required:
        - type
        - text
    ImagePart:
      type: object
      properties:
        type:
          type: string
          enum:
            - image_url
        image_url:
          type: object
          properties:
            url:
              type: string
              description: >-
                An HTTP(S) image URL or a data:image/... URI. Requires a
                vision-capable model.
          required:
            - url
      required:
        - type
        - image_url
    VideoPart:
      type: object
      properties:
        type:
          type: string
          enum:
            - video_url
        video_url:
          type: object
          properties:
            url:
              type: string
              description: >-
                A public HTTPS video file URL or a base64 data:video/... URI.
                One video per request, in a user message. The model must
                advertise video_input and its current limits.
          required:
            - url
      required:
        - type
        - video_url
    PromptCache:
      type: object
      properties:
        enabled:
          type: boolean
        usage_status:
          type: string
          enum:
            - reported
            - unreported
            - invalid
            - estimated
        read_tokens:
          type: integer
          minimum: 0
          nullable: true
        write_tokens:
          type: integer
          minimum: 0
          nullable: true
        usd_per_1m_cached_input:
          type: number
          nullable: true
        savings_usd:
          type: number
          nullable: true
      required:
        - enabled
        - usage_status
        - read_tokens
        - write_tokens
        - usd_per_1m_cached_input
        - savings_usd
  headers:
    XRequestId:
      description: Request identifier for support and diagnostics.
      schema:
        type: string
    XRateLimitProfile:
      description: Applied public rate-limit profile.
      schema:
        type: string
    XRateLimitLimitRequests:
      description: Maximum requests in the minute window.
      schema:
        type: string
    XRateLimitRemainingRequests:
      description: Remaining requests in the minute window.
      schema:
        type: string
    XRateLimitReset:
      description: Seconds until the relevant allowance resets.
      schema:
        type: string
    XRateLimitLimitTokens:
      description: Maximum text tokens in the minute window.
      schema:
        type: string
    XRateLimitRemainingTokens:
      description: Remaining text tokens in the minute window.
      schema:
        type: string
    IdempotencyReplayed:
      description: true when returning a previously cached non-streaming response.
      schema:
        type: string
        enum:
          - 'true'
    RetryAfter:
      description: Seconds to wait before retrying a rate-limited request, when supplied.
      schema:
        type: integer
  responses:
    Error400:
      description: Invalid input or unsupported parameter.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/XRequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Error401:
      description: Missing, invalid, expired or revoked API key.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/XRequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Error402:
      description: Insufficient prepaid balance.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/XRequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Error403:
      description: Account restricted from API access.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/XRequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Error404:
      description: Unknown or inaccessible model.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/XRequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Error413:
      description: Request or input media too large.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/XRequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Error429:
      description: >-
        Account rate limit or key monthly spending limit exceeded. Observe
        Retry-After when supplied.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/XRequestId'
        X-RateLimit-Profile:
          $ref: '#/components/headers/XRateLimitProfile'
        X-RateLimit-Limit-Requests:
          $ref: '#/components/headers/XRateLimitLimitRequests'
        X-RateLimit-Remaining-Requests:
          $ref: '#/components/headers/XRateLimitRemainingRequests'
        X-RateLimit-Reset:
          $ref: '#/components/headers/XRateLimitReset'
        X-RateLimit-Limit-Tokens:
          $ref: '#/components/headers/XRateLimitLimitTokens'
        X-RateLimit-Remaining-Tokens:
          $ref: '#/components/headers/XRateLimitRemainingTokens'
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Error500:
      description: Internal server error.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/XRequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Error502:
      description: Model service returned an invalid result or could not be reached.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/XRequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Error503:
      description: Service unavailable or model at capacity.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/XRequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Error504:
      description: Model request timed out.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/XRequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: NoMask API key
      description: >-
        Create a NoMask API key at https://nomask.ai/api/keys. Keep it private;
        enter only your own key when sending a request.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.