> ## 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.

# Generate an image

> Generate one image from a prompt, optionally with references supported by the model. Use a current image model ID and its advertised prompt, reference-count, resolution and aspect-ratio limits. Accepts JSON base64 data URLs or multipart PNG/JPEG/WebP files. Remote image URLs, masks, quality controls and streaming are unsupported. Reference bytes total at most 25 MiB; JSON bodies are limited to 40 MiB. Paid requests debit your NoMask balance.



## OpenAPI

````yaml /openapi.json post /images/generations
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:
  /images/generations:
    post:
      tags:
        - Images
      summary: Generate an image
      description: >-
        Generate one image from a prompt, optionally with references supported
        by the model. Use a current image model ID and its advertised prompt,
        reference-count, resolution and aspect-ratio limits. Accepts JSON base64
        data URLs or multipart PNG/JPEG/WebP files. Remote image URLs, masks,
        quality controls and streaming are unsupported. Reference bytes total at
        most 25 MiB; JSON bodies are limited to 40 MiB. Paid requests debit your
        NoMask balance.
      operationId: generateImage
      parameters:
        - name: Idempotency-Key
          in: header
          description: >-
            Optional duplicate protection for 24 hours. A reused accepted key
            returns 409; image bytes are not cached for replay.
          schema:
            type: string
            minLength: 1
            maxLength: 255
            pattern: ^[!-~]+$
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImageRequestJson'
            example:
              model: your-image-model-id
              prompt: A quiet mountain lake at sunrise
              'n': 1
              response_format: b64_json
              output_format: png
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/ImageRequestMultipart'
      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-Requests-Day:
              $ref: '#/components/headers/XRateLimitLimitRequestsDay'
            X-RateLimit-Remaining-Requests-Day:
              $ref: '#/components/headers/XRateLimitRemainingRequestsDay'
            X-RateLimit-Reset-Day:
              $ref: '#/components/headers/XRateLimitResetDay'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImageResponse'
              example:
                created: 1793617200
                request_id: req_example
                model: your-image-model-id
                data:
                  - b64_json: BASE64_IMAGE_BYTES
                    mime_type: image/png
                    width: 1024
                    height: 1024
                usage:
                  input_tokens: 0
                  output_tokens: 0
                  prompt_tokens: 0
                  completion_tokens: 0
                  total_tokens: 0
                  images: 1
                  tokens_reported: false
                nomask:
                  cost_usd: 0.04
                  model_cost_usd: 0.04
                  resolution: 1K
                  aspect_ratio: auto
                  output_format: png
                  reference_images: 0
                  pricing_type: resolution
        '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'
        '409':
          $ref: '#/components/responses/Error409'
        '413':
          $ref: '#/components/responses/Error413'
        '415':
          $ref: '#/components/responses/Error415'
        '429':
          $ref: '#/components/responses/Error429Images'
        '500':
          $ref: '#/components/responses/Error500'
        '502':
          $ref: '#/components/responses/Error502'
        '503':
          $ref: '#/components/responses/Error503'
        '504':
          $ref: '#/components/responses/Error504'
components:
  schemas:
    ImageRequestJson:
      type: object
      properties:
        model:
          type: string
          description: Current public image model ID from GET /models.
          minLength: 1
          maxLength: 150
          example: your-image-model-id
        prompt:
          type: string
          description: >-
            Nonempty UTF-8 prompt, within this model's
            limits.max_prompt_characters.
          minLength: 1
          example: A quiet mountain lake at sunrise
        'n':
          type: integer
          description: One output image.
          enum:
            - 1
          default: 1
        response_format:
          type: string
          description: Images are returned inline; hosted URL responses are unavailable.
          enum:
            - b64_json
          default: b64_json
        resolution:
          type: string
          description: >-
            An advertised tier from limits.supported_resolutions. Omit to use
            the model default.
        aspect_ratio:
          type: string
          description: >-
            An advertised value from limits.supported_aspect_ratios. Omit to use
            the model default.
        size:
          type: string
          description: >-
            Alias accepting auto, an advertised resolution tier, or WIDTHxHEIGHT
            that maps to a supported tier and aspect ratio. Conflicting explicit
            options are rejected; exact pixel dimensions are not guaranteed.
          default: auto
        output_format:
          type: string
          description: Output format. jpeg is normalized to jpg.
          enum:
            - png
            - jpg
            - jpeg
            - webp
          default: png
        format:
          type: string
          description: Alias used when output_format is absent.
          enum:
            - png
            - jpg
            - jpeg
            - webp
        stream:
          type: boolean
          description: Images return completed JSON only.
          enum:
            - false
          default: false
        user:
          type: string
          description: >-
            Accepted for client compatibility; it does not affect image
            generation.
        image:
          oneOf:
            - type: string
              description: Base64 PNG, JPEG or WebP data URL. Remote URLs are not accepted.
              pattern: ^data:image/(png|jpeg|webp);base64,
              example: data:image/png;base64,BASE64_IMAGE_BYTES
            - type: array
              items:
                type: string
                description: >-
                  Base64 PNG, JPEG or WebP data URL. Remote URLs are not
                  accepted.
                pattern: ^data:image/(png|jpeg|webp);base64,
                example: data:image/png;base64,BASE64_IMAGE_BYTES
          description: >-
            Single reference data URL or a list. Use either image or images,
            never both.
        images:
          oneOf:
            - type: string
              description: Base64 PNG, JPEG or WebP data URL. Remote URLs are not accepted.
              pattern: ^data:image/(png|jpeg|webp);base64,
              example: data:image/png;base64,BASE64_IMAGE_BYTES
            - type: array
              items:
                type: string
                description: >-
                  Base64 PNG, JPEG or WebP data URL. Remote URLs are not
                  accepted.
                pattern: ^data:image/(png|jpeg|webp);base64,
                example: data:image/png;base64,BASE64_IMAGE_BYTES
          description: >-
            Reference data URL(s). The model controls the minimum and maximum
            count.
      required:
        - model
        - prompt
      additionalProperties: false
      not:
        required:
          - image
          - images
      description: >-
        Reference images must be PNG, JPEG or WebP; decoded references total at
        most 25 MiB. JSON body limit is 40 MiB. Each image must be at most 16384
        pixels per side and 40 million pixels.
    ImageRequestMultipart:
      type: object
      properties:
        model:
          type: string
          description: Current public image model ID from GET /models.
          minLength: 1
          maxLength: 150
          example: your-image-model-id
        prompt:
          type: string
          description: >-
            Nonempty UTF-8 prompt, within this model's
            limits.max_prompt_characters.
          minLength: 1
          example: A quiet mountain lake at sunrise
        'n':
          type: integer
          description: One output image.
          enum:
            - 1
          default: 1
        response_format:
          type: string
          description: Images are returned inline; hosted URL responses are unavailable.
          enum:
            - b64_json
          default: b64_json
        resolution:
          type: string
          description: >-
            An advertised tier from limits.supported_resolutions. Omit to use
            the model default.
        aspect_ratio:
          type: string
          description: >-
            An advertised value from limits.supported_aspect_ratios. Omit to use
            the model default.
        size:
          type: string
          description: >-
            Alias accepting auto, an advertised resolution tier, or WIDTHxHEIGHT
            that maps to a supported tier and aspect ratio. Conflicting explicit
            options are rejected; exact pixel dimensions are not guaranteed.
          default: auto
        output_format:
          type: string
          description: Output format. jpeg is normalized to jpg.
          enum:
            - png
            - jpg
            - jpeg
            - webp
          default: png
        format:
          type: string
          description: Alias used when output_format is absent.
          enum:
            - png
            - jpg
            - jpeg
            - webp
        stream:
          type: boolean
          description: Images return completed JSON only.
          enum:
            - false
          default: false
        user:
          type: string
          description: >-
            Accepted for client compatibility; it does not affect image
            generation.
        image:
          type: string
          description: >-
            One uploaded PNG, JPEG or WebP file. Repeated image[] fields also
            work for multiple files.
          format: binary
        images:
          type: array
          items:
            type: string
            format: binary
          description: >-
            Alternative reference-file array; send repeated images[] fields. Do
            not combine image and images.
      required:
        - model
        - prompt
      additionalProperties: false
      not:
        required:
          - image
          - images
      description: >-
        Reference files total at most 25 MiB. Reference count, prompt length,
        resolutions and ratios are model-specific.
    ImageResponse:
      type: object
      properties:
        created:
          type: integer
          description: Unix timestamp.
          format: int64
        request_id:
          type: string
          description: Matches the X-Request-Id header.
        model:
          type: string
          description: Public image model ID.
        data:
          type: array
          items:
            type: object
            properties:
              b64_json:
                type: string
                description: Base64 image bytes.
                format: byte
              mime_type:
                type: string
                enum:
                  - image/png
                  - image/jpeg
                  - image/webp
              width:
                type: integer
                description: Actual pixel width.
                minimum: 1
              height:
                type: integer
                description: Actual pixel height.
                minimum: 1
            required:
              - b64_json
              - mime_type
              - width
              - height
          minItems: 1
          maxItems: 1
        usage:
          type: object
          properties:
            input_tokens:
              type: integer
            output_tokens:
              type: integer
            prompt_tokens:
              type: integer
              description: Alias for input_tokens.
            completion_tokens:
              type: integer
              description: Alias for output_tokens.
            total_tokens:
              type: integer
            images:
              type: integer
              enum:
                - 1
            tokens_reported:
              type: boolean
              description: >-
                False means counters were unavailable and token fields are zero;
                those zero values are not measured usage.
          required:
            - input_tokens
            - output_tokens
            - prompt_tokens
            - completion_tokens
            - total_tokens
            - images
            - tokens_reported
        nomask:
          type: object
          properties:
            cost_usd:
              type: number
              description: Settled debit in USD.
            model_cost_usd:
              type: number
              description: Model charge in USD.
            resolution:
              type: string
              description: Resolved tier, or null when the model has none.
              nullable: true
            aspect_ratio:
              type: string
            output_format:
              type: string
              enum:
                - png
                - jpg
                - webp
            reference_images:
              type: integer
              minimum: 0
            pricing_type:
              type: string
              enum:
                - resolution
                - tokens
          required:
            - cost_usd
            - model_cost_usd
            - resolution
            - aspect_ratio
            - output_format
            - reference_images
            - pricing_type
      required:
        - created
        - request_id
        - model
        - data
        - usage
        - nomask
    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
  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
    XRateLimitLimitRequestsDay:
      description: Maximum image requests in the day window.
      schema:
        type: string
    XRateLimitRemainingRequestsDay:
      description: Remaining image requests in the day window.
      schema:
        type: string
    XRateLimitResetDay:
      description: Seconds until the image day window resets.
      schema:
        type: string
    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'
    Error409:
      description: >-
        Image idempotency key was already accepted; image results are not
        replayed.
      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'
    Error415:
      description: Unsupported image request content type.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/XRequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Error429Images:
      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-Requests-Day:
          $ref: '#/components/headers/XRateLimitLimitRequestsDay'
        X-RateLimit-Remaining-Requests-Day:
          $ref: '#/components/headers/XRateLimitRemainingRequestsDay'
        X-RateLimit-Reset-Day:
          $ref: '#/components/headers/XRateLimitResetDay'
        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.