openapi: 3.1.0
info:
  title: ModelRush Public API
  version: 2026-09-04.3
  summary: One API for text, image, video, and voice models
  description: >-
    Public discovery and representative authenticated ModelRush API contracts.
    Model and region availability are time-sensitive; call the discovery endpoints
    before selecting a model or execution region. Authenticated generation operations
    may create billable usage. Keep API keys server-side.
    The Apache-2.0 license covers this API description, not access to the
    hosted service or its underlying implementation. Service use remains
    governed by the linked terms of service.
  termsOfService: https://modelrush.ai/terms
  contact:
    name: ModelRush
    url: https://modelrush.ai
    email: info@modelrush.ai
  license:
    name: Apache 2.0
    identifier: Apache-2.0
externalDocs:
  description: ModelRush documentation
  url: https://modelrush.ai/docs
servers:
  - url: https://api.modelrush.ai/v1
    description: Production
tags:
  - name: Discovery
  - name: Chat
  - name: Images
  - name: Video
  - name: Audio
  - name: Predictions
  - name: Uploads
  - name: Webhooks
security:
  - bearerAuth: []
paths:
  /models:
    get:
      operationId: listModels
      summary: List callable models
      description: Returns current model capabilities, limits, examples, regions, and the registry revision.
      tags: [Discovery]
      security: []
      responses:
        "200":
          description: Current model inventory
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ModelList"
  /regions:
    get:
      operationId: listRegions
      summary: List API surfaces and regions
      tags: [Discovery]
      security: []
      responses:
        "200":
          description: Current API surfaces and configured regions
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RegionList"
  /chat/completions:
    post:
      operationId: createChatCompletion
      summary: Create a chat completion
      description: Creates a synchronous JSON completion or an SSE stream using an OpenAI-compatible request shape.
      tags: [Chat]
      x-modelrush-billable: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ChatCompletionRequest"
      responses:
        "200":
          description: Completion object or SSE stream
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
            text/event-stream:
              schema:
                type: string
        "4XX":
          $ref: "#/components/responses/Error"
  /images/generations:
    post:
      operationId: createImageGeneration
      summary: Generate images
      tags: [Images]
      x-modelrush-billable: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ImageGenerationRequest"
      responses:
        "200":
          description: Synchronous image result
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        "202":
          description: Asynchronous image Prediction
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Prediction"
        "4XX":
          $ref: "#/components/responses/Error"
  /images/edits:
    post:
      operationId: createImageEdit
      summary: Edit one or more source images
      description: >-
        Accepts JSON image URLs/data URIs or multipart image files. Face and head
        swap operations require explicit per-request portrait-rights confirmation.
      tags: [Images]
      x-modelrush-billable: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ImageEditRequest"
          multipart/form-data:
            schema:
              type: object
              required: [model, image]
              properties:
                model:
                  type: string
                prompt:
                  type: string
                image:
                  oneOf:
                    - type: string
                      format: binary
                    - type: array
                      items:
                        type: string
                        format: binary
                mask:
                  type: string
                  format: binary
                person_rights_confirmed:
                  type: boolean
      responses:
        "200":
          description: Synchronous image edit result
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        "202":
          description: Asynchronous image-edit Prediction
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Prediction"
        "4XX":
          $ref: "#/components/responses/Error"
  /videos/generations:
    post:
      operationId: createVideoGeneration
      summary: Create an asynchronous video job
      tags: [Video]
      x-modelrush-billable: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/VideoGenerationRequest"
      responses:
        "202":
          description: Queued video generation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Prediction"
        "4XX":
          $ref: "#/components/responses/Error"
  /videos/generations/{id}:
    get:
      operationId: getVideoGeneration
      summary: Get video job status
      tags: [Video]
      parameters:
        - $ref: "#/components/parameters/ResourceId"
      responses:
        "200":
          description: Current video job status
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Prediction"
        "404":
          $ref: "#/components/responses/Error"
  /audio/speech:
    post:
      operationId: createSpeech
      summary: Synthesize WAV speech
      tags: [Audio]
      x-modelrush-billable: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SpeechRequest"
      responses:
        "200":
          description: WAV audio
          content:
            audio/wav:
              schema:
                type: string
                contentMediaType: audio/wav
                contentEncoding: binary
        "4XX":
          $ref: "#/components/responses/Error"
  /audio/transcriptions:
    post:
      operationId: createTranscription
      summary: Transcribe audio
      description: Accepts a JSON HTTPS/data-URI audio reference or a multipart audio file.
      tags: [Audio]
      x-modelrush-billable: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TranscriptionRequest"
          multipart/form-data:
            schema:
              type: object
              required: [model, file]
              properties:
                model:
                  type: string
                file:
                  type: string
                  format: binary
                language:
                  type: string
                enable_itn:
                  type: boolean
                region:
                  type: string
      responses:
        "200":
          description: Synchronous transcription
          content:
            application/json:
              schema:
                type: object
                required: [id, text, model]
                properties:
                  id:
                    type: string
                  text:
                    type: string
                  model:
                    type: string
                  duration:
                    type: number
                  modelrush_region:
                    type: string
        "202":
          description: Asynchronous transcription Prediction
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Prediction"
        "4XX":
          $ref: "#/components/responses/Error"
  /predictions/{id}:
    get:
      operationId: getPrediction
      summary: Get a unified media Prediction
      tags: [Predictions]
      parameters:
        - $ref: "#/components/parameters/ResourceId"
      responses:
        "200":
          description: Current Prediction state
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Prediction"
        "404":
          $ref: "#/components/responses/Error"
    delete:
      operationId: cancelPrediction
      summary: Request Prediction cancellation
      tags: [Predictions]
      parameters:
        - $ref: "#/components/parameters/ResourceId"
      responses:
        "200":
          description: Terminal Prediction state
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Prediction"
        "409":
          $ref: "#/components/responses/Error"
  /uploads:
    post:
      operationId: createUpload
      summary: Create a private media upload slot
      tags: [Uploads]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [content_type, size_bytes]
              properties:
                content_type:
                  type: string
                  enum: [image/jpeg, image/png, image/webp, audio/mpeg, audio/wav, audio/x-wav, audio/mp4, video/mp4, video/webm]
                size_bytes:
                  type: integer
                  minimum: 1
                  maximum: 104857600
      responses:
        "201":
          description: Short-lived signed upload URL
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Upload"
        "4XX":
          $ref: "#/components/responses/Error"
  /uploads/{id}:
    get:
      operationId: getUpload
      summary: Inspect and verify an upload
      tags: [Uploads]
      parameters:
        - $ref: "#/components/parameters/ResourceId"
      responses:
        "200":
          description: Upload state and short-lived input URL when ready
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Upload"
        "404":
          $ref: "#/components/responses/Error"
    delete:
      operationId: deleteUpload
      summary: Delete a private upload
      tags: [Uploads]
      parameters:
        - $ref: "#/components/parameters/ResourceId"
      responses:
        "200":
          description: Deletion confirmation
          content:
            application/json:
              schema:
                type: object
                required: [id, object, deleted]
                properties:
                  id:
                    type: string
                  object:
                    const: upload
                  deleted:
                    const: true
  /webhooks/endpoints:
    get:
      operationId: listWebhookEndpoints
      summary: List webhook endpoints
      tags: [Webhooks]
      responses:
        "200":
          description: Account webhook endpoints
          content:
            application/json:
              schema:
                type: object
                required: [object, data]
                properties:
                  object:
                    const: list
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/WebhookEndpoint"
    post:
      operationId: createWebhookEndpoint
      summary: Create a signed webhook endpoint
      description: The signing secret is returned only in the creation response.
      tags: [Webhooks]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [url]
              properties:
                url:
                  type: string
                  format: uri
                  maxLength: 2048
      responses:
        "201":
          description: Created endpoint and one-time signing secret
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/WebhookEndpoint"
                  - type: object
                    required: [signing_secret]
                    properties:
                      signing_secret:
                        type: string
                        writeOnly: true
        "4XX":
          $ref: "#/components/responses/Error"
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: ModelRush API key
  parameters:
    ResourceId:
      name: id
      in: path
      required: true
      schema:
        type: string
  responses:
    Error:
      description: Structured API error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
  schemas:
    ModelList:
      type: object
      required: [object, data]
      properties:
        object:
          const: list
        data:
          type: array
          items:
            type: object
            required: [id, object, owned_by, modality, api_types, available_regions, operations]
            properties:
              id:
                type: string
              object:
                const: model
              owned_by:
                const: modelrush
              modality:
                type: string
              api_types:
                type: array
                items:
                  type: string
              gateway_status:
                type: string
              available_regions:
                type: array
                items:
                  type: string
              registry_revision:
                type: string
              operations:
                type: array
                items:
                  type: object
                  additionalProperties: true
            additionalProperties: true
        registry:
          type: object
          additionalProperties: true
      additionalProperties: true
    RegionList:
      type: object
      required: [api_surfaces, platform_surfaces, default_region, regions]
      properties:
        api_surfaces:
          type: array
          items:
            type: object
            additionalProperties: true
        platform_surfaces:
          type: array
          items:
            type: object
            additionalProperties: true
        default_region:
          type: string
        registry_revision:
          type: string
        regions:
          type: array
          items:
            type: object
            required: [id, label, configured, availableApiTypes]
            properties:
              id:
                type: string
              label:
                type: string
              configured:
                type: boolean
              availableApiTypes:
                type: array
                items:
                  type: string
            additionalProperties: true
      additionalProperties: true
    ChatCompletionRequest:
      type: object
      required: [model, messages]
      properties:
        model:
          type: string
        messages:
          type: array
          minItems: 1
          items:
            type: object
            required: [role, content]
            properties:
              role:
                type: string
              content: {}
            additionalProperties: true
        stream:
          type: boolean
          default: false
        temperature:
          type: number
        max_tokens:
          type: integer
          minimum: 1
        reasoning_effort:
          type: string
        tools:
          type: array
          items:
            type: object
            additionalProperties: true
        tool_choice: {}
        parallel_tool_calls:
          type: boolean
        response_format:
          type: object
          additionalProperties: true
        stream_options:
          type: object
          additionalProperties: true
        store:
          const: false
        region:
          type: string
      additionalProperties: true
    ImageGenerationRequest:
      type: object
      required: [model, prompt]
      properties:
        model:
          type: string
        prompt:
          type: string
          minLength: 1
          maxLength: 5000
        n:
          type: integer
          minimum: 1
          maximum: 4
          default: 1
        size:
          type: string
        quality:
          type: string
        output_format:
          type: string
        watermark:
          type: boolean
        thinking_mode:
          type: boolean
        region:
          type: string
      additionalProperties: true
    ImageEditRequest:
      type: object
      required: [model, image]
      properties:
        model:
          type: string
        prompt:
          type: string
          maxLength: 5000
        image:
          oneOf:
            - type: string
            - type: array
              items:
                type: string
        mask:
          type: string
        n:
          type: integer
          minimum: 1
          maximum: 4
        size:
          type: string
        quality:
          type: string
        output_format:
          type: string
        watermark:
          type: boolean
        person_rights_confirmed:
          type: boolean
        region:
          type: string
      additionalProperties: true
    VideoGenerationRequest:
      type: object
      required: [model, prompt]
      properties:
        model:
          type: string
        prompt:
          type: string
        duration:
          type: integer
        ratio:
          type: string
          enum: [adaptive, "16:9", "9:16", "1:1", "4:3", "3:4", "21:9"]
        resolution:
          type: string
        image:
          type: string
        last_image:
          type: string
        reference_images:
          type: array
          maxItems: 10
          items:
            type: string
        reference_videos:
          type: array
          maxItems: 5
          items:
            type: string
        reference_audios:
          type: array
          maxItems: 5
          items:
            type: string
        audio:
          type: boolean
        audio_url:
          type: string
          format: uri
        region:
          type: string
      additionalProperties: true
    SpeechRequest:
      type: object
      required: [model, input, voice]
      properties:
        model:
          type: string
        input:
          type: string
        voice:
          type: string
        language_type:
          type: string
        region:
          type: string
      additionalProperties: true
    TranscriptionRequest:
      type: object
      required: [model]
      properties:
        model:
          type: string
        audio:
          type: string
        file:
          type: string
        language:
          type: string
        enable_itn:
          type: boolean
          default: true
        parameters:
          type: object
          additionalProperties: true
        region:
          type: string
      anyOf:
        - required: [audio]
        - required: [file]
      additionalProperties: true
    Prediction:
      type: object
      required: [id, status]
      properties:
        id:
          type: string
        object:
          type: string
        status:
          type: string
          enum: [queued, processing, succeeded, failed, cancelled, expired]
        provider_status:
          type: string
        model:
          type: string
        modelrush_region:
          type: string
        poll_url:
          type: string
        output: {}
        error:
          $ref: "#/components/schemas/ErrorObject"
      additionalProperties: true
    Upload:
      type: object
      required: [id, object, status, content_type, size_bytes, expires_at]
      properties:
        id:
          type: string
        object:
          const: upload
        status:
          type: string
        content_type:
          type: string
        size_bytes:
          type: integer
        duration_seconds:
          type: [number, "null"]
        upload_url:
          type: string
          format: uri
          writeOnly: true
        upload_headers:
          type: object
          additionalProperties:
            type: string
        upload_url_expires_in:
          type: integer
        input_url:
          type: string
          format: uri
          readOnly: true
        input_url_expires_in:
          type: integer
        expires_at:
          type: string
      additionalProperties: true
    WebhookEndpoint:
      type: object
      required: [id, object, url, enabled, created_at]
      properties:
        id:
          type: string
        object:
          const: webhook_endpoint
        url:
          type: string
          format: uri
        enabled:
          type: boolean
        failure_count:
          type: integer
        created_at:
          type: string
      additionalProperties: true
    ErrorObject:
      type: object
      required: [code, message, type]
      properties:
        code:
          type: string
        message:
          type: string
        type:
          type: string
      additionalProperties: true
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          $ref: "#/components/schemas/ErrorObject"
      additionalProperties: true