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

# OpenAI SDK — images.generate (sync)



## OpenAPI

````yaml mountsea-api.mint.json POST /ms/v1/images/generations
openapi: 3.0.0
info:
  title: mountsea-api
  description: >-
    mountsea unified AI API — video, image, and audio generation.


    ### Async task flow

    1. `POST /ms/v1/run/{endpoint_slug}` — submit a job (returns Task with
    `status: queued`).

    2. `GET /ms/v1/tasks/{task_id}` — poll until `succeeded` (`output.images` /
    `output.videos` / `output.audio`) or `failed`/`timeout` (`error`).
       Or pass `webhook_url` in the submit body for a signed terminal callback (`x-ms-signature`).
    3. `GET /ms/v1/endpoints[/{slug}]` — marketplace listing with
    `input_schema`, `output_schema`, and `examples`.


    ### Request body

    - `{ "input": { ... } }` — all parameters and media URLs per endpoint
    `input_schema`.

    - Optional `webhook_url` for callbacks.


    ### SDK compatibility (optional)

    Prefer the native async API above? Skip this section.


    - **OpenAI SDK** — `baseURL = https://{gateway}/ms/v1`
      - Image (sync): `POST /ms/v1/images/generations|edits` — gpt-image-2 family
      - Video (async): `POST /ms/v1/videos` + `GET /ms/v1/videos/{id}` — sora-2 → Veo lite/pro slugs
    - **Gemini SDK** — `httpOptions.baseUrl = https://{gateway}/ms`
      - Image (sync): `POST /ms/v1beta/models/{model}:generateContent` — nano-banana family
      - Video (async): `POST /ms/v1beta/models/{model}:predictLongRunning` + poll `GET /ms/v1beta/operations/{task_id}`

    Unsupported `model` → **HTTP 400** before any task is created (no charge).

    Successful calls bill the **same endpoint slug** as the equivalent
    `/ms/v1/run/...` API.
  version: 1.0.0
  contact: {}
servers:
  - url: https://api.mountsea.ai
    description: API Gateway
security: []
tags:
  - name: Run
    description: Submit async tasks by endpoint slug
  - name: Tasks
    description: Poll or cancel tasks
  - name: Endpoints (marketplace)
    description: Endpoint catalog and schemas
  - name: SDK Compatibility
    description: >-
      OpenAI / Gemini official SDK — sync image APIs (same billing as native
      run)
  - name: Admin - Catalog (internal)
    description: Internal admin (swagger only, not public gateway)
paths:
  /ms/v1/images/generations:
    post:
      tags:
        - SDK Compatibility
      summary: OpenAI SDK — images.generate (sync)
      description: >-
        Use the official **OpenAI Node/Python SDK** with our API key and gateway
        base URL.


        ```ts

        import OpenAI from 'openai';

        const client = new OpenAI({
          baseURL: 'https://{gateway}/ms/v1',
          apiKey: 'ms-...',
        });

        await client.images.generate({
          model: 'gpt-image-2',
          prompt: '...',
          size: '1024x1024',
          quality: 'high',
          n: 1,
        });

        ```


        **Supported models** (others → `400 Unsupported OpenAI image model`):

        - `gpt-image-2`

        - `gpt-image-1`

        - `gpt-image-*`

        - `dall-e-*`


        **Billing**: same as native `POST
        /ms/v1/run/openai/gpt-image-2/text-to-image` —

        charged by `quality`, `image_size` / pixel count, and `num_images` after
        success.


        **Note**: synchronous HTTP response; internally uses the same routing
        pipeline as `/ms/v1/run`.
      operationId: openaiImagesGenerations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OpenAiImagesGenerationRequest'
            example:
              model: gpt-image-2
              prompt: A cinematic scene with soft natural lighting.
              size: 1024x1024
              quality: high
              'n': 1
      responses:
        '200':
          $ref: '#/components/responses/OpenAiImagesResponse200'
        '400':
          $ref: '#/components/responses/BadRequestResponse'
      security:
        - bearerAuth: []
components:
  schemas:
    OpenAiImagesGenerationRequest:
      type: object
      required:
        - model
        - prompt
      properties:
        model:
          type: string
          example: gpt-image-2
        prompt:
          type: string
        'n':
          type: integer
          description: Maps to num_images
        size:
          type: string
          example: 1024x1024
        quality:
          type: string
          enum:
            - low
            - medium
            - high
        output_format:
          type: string
          enum:
            - png
            - jpeg
            - webp
    OpenAiImagesResponse:
      type: object
      properties:
        created:
          type: integer
        data:
          type: array
          items:
            type: object
            properties:
              b64_json:
                type: string
    ErrorBody:
      type: object
      properties:
        statusCode:
          type: integer
          example: 400
        message:
          type: string
        error:
          type: string
  responses:
    OpenAiImagesResponse200:
      description: OpenAI ImagesResponse (data[].b64_json)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OpenAiImagesResponse'
    BadRequestResponse:
      description: Validation failed or unsupported model
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorBody'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````