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

# Run a multi-model comparison (async)

> Send one prompt to N models and reserve credits for all of them atomically. If the wallet cannot cover the sum, nothing is charged and the call returns 402. The number of models is capped by your plan (Free 2, Pro 3, Studio 6, Team 12).



## OpenAPI

````yaml /api-reference/openapi.json post /v1/comparisons
openapi: 3.1.0
info:
  title: Rimp API
  version: 1.0.0
  description: >-
    AI generation API across 8 modalities — image, video, voice, music, avatar,
    chat, 3D and upscale. Multi-model side-by-side comparisons, unified billing,
    one API key.
servers:
  - url: https://api.rimp.io
    description: Production
security:
  - bearerAuth: []
paths:
  /v1/comparisons:
    post:
      summary: Run a multi-model comparison (async)
      description: >-
        Send one prompt to N models and reserve credits for all of them
        atomically. If the wallet cannot cover the sum, nothing is charged and
        the call returns 402. The number of models is capped by your plan (Free
        2, Pro 3, Studio 6, Team 12).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - prompt
                - models
              properties:
                prompt:
                  type: string
                  maxLength: 4000
                models:
                  type: array
                  minItems: 2
                  maxItems: 12
                  items:
                    type: string
                params_shared:
                  type: object
                  additionalProperties: true
      responses:
        '202':
          description: >-
            Comparison queued. Poll /v1/comparisons/{id} or subscribe via
            webhook.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Comparison'
        '402':
          description: Insufficient credits — nothing was charged.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Comparison:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
          enum:
            - comparison
        status:
          type: string
          enum:
            - queued
            - running
            - succeeded
            - partial
            - failed
        prompt:
          type: string
        params_shared:
          type: object
          additionalProperties: true
        reserved_credits:
          type: integer
        created_at:
          type: string
          format: date-time
        finished_at:
          type: string
          format: date-time
          nullable: true
        generations:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              model:
                type: string
              status:
                type: string
              charged_credits:
                type: integer
              refunded_credits:
                type: integer
              error_code:
                type: string
                nullable: true
              outputs:
                type: array
                items:
                  $ref: '#/components/schemas/GenerationOutput'
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
            code:
              type: string
            message:
              type: string
            param:
              type: string
            request_id:
              type: string
          required:
            - type
            - code
            - message
    GenerationOutput:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
          enum:
            - image
            - video
            - audio
            - thumbnail
        mime:
          type: string
        width:
          type: integer
          nullable: true
        height:
          type: integer
          nullable: true
        duration_s:
          type: string
          nullable: true
        url:
          type: string
          format: uri
        moderation_status:
          type: string
          enum:
            - pending
            - approved
            - flagged
            - blocked
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key

````