openapi: 3.1.0
info:
  title: Segmind API
  description: >-
    Segmind provides API access to top AI models for rapid prototyping
    and deployment, including synchronous and asynchronous model inference,
    fine-tuning, and asset upload. Authenticated with an API key header.
  version: "1"
  contact:
    name: Segmind
    url: https://www.segmind.com/
servers:
  - url: https://api.segmind.com
    description: Segmind model inference and account API
  - url: https://workflows-api.segmind.com
    description: Segmind workflows/storage API
security:
  - apiKeyAuth: []
tags:
  - name: Inference
    description: Synchronous and asynchronous model inference
  - name: Account
    description: User account and credits
  - name: Fine-tuning
    description: Fine-tuning request management and data handling
  - name: Storage
    description: Upload reusable assets
paths:
  /v1/{model_name}:
    post:
      tags: [Inference]
      summary: Synchronous model inference
      description: >-
        Submit a request to a model and wait for the response. Suitable for
        models that complete within roughly 60 seconds.
      operationId: invokeModelSync
      parameters:
        - in: path
          name: model_name
          required: true
          schema: { type: string }
          description: Model identifier, e.g. fast-flux-schnell
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
              properties:
                prompt: { type: string }
      responses:
        '200':
          description: Model inference response
  /v2/{model_name}:
    post:
      tags: [Inference]
      summary: Asynchronous model inference
      description: Submit an async request; returns a request_id.
      operationId: invokeModelAsync
      parameters:
        - in: path
          name: model_name
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
              properties:
                prompt: { type: string }
      responses:
        '200':
          description: Async request accepted
          content:
            application/json:
              schema:
                type: object
                properties:
                  request_id: { type: string }
  /v2/requests/{request_id}/status:
    get:
      tags: [Inference]
      summary: Get lightweight request status
      operationId: getRequestStatus
      parameters:
        - in: path
          name: request_id
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Status payload
          content:
            application/json:
              schema:
                type: object
                properties:
                  status: { type: string }
  /v2/requests/{request_id}:
    get:
      tags: [Inference]
      summary: Get full async result
      operationId: getRequestResult
      parameters:
        - in: path
          name: request_id
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Full async result
  /v1/get-user-credits:
    get:
      tags: [Account]
      summary: Retrieve current credit balance
      operationId: getUserCredits
      responses:
        '200':
          description: Credits payload
          content:
            application/json:
              schema:
                type: object
                properties:
                  credits: { type: number }
  /finetune/request/submit:
    post:
      tags: [Fine-tuning]
      summary: Initiate a fine-tuning job
      operationId: submitFinetune
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200': { description: Fine-tune request accepted }
  /finetune/request/details:
    get:
      tags: [Fine-tuning]
      summary: Get details for a fine-tune request
      operationId: getFinetuneDetails
      parameters:
        - in: query
          name: request_id
          required: true
          schema: { type: string }
      responses:
        '200': { description: Fine-tune details }
  /finetune/request/list:
    get:
      tags: [Fine-tuning]
      summary: List fine-tuning requests
      operationId: listFinetuneRequests
      responses:
        '200': { description: Array of fine-tune requests }
  /finetune/request/access-update:
    put:
      tags: [Fine-tuning]
      summary: Update fine-tuned model access (public/private)
      operationId: updateFinetuneAccess
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                request_id: { type: string }
                access: { type: string, enum: [public, private] }
      responses:
        '200': { description: Updated }
  /finetune/request/upload/pre-signed-url:
    get:
      tags: [Fine-tuning]
      summary: Obtain a pre-signed upload URL for fine-tune data
      operationId: getFinetuneUploadUrl
      responses:
        '200': { description: Pre-signed URL response }
  /finetune/request/file/download:
    get:
      tags: [Fine-tuning]
      summary: Download trained model weights
      operationId: downloadFinetuneFile
      parameters:
        - in: query
          name: request_id
          required: true
          schema: { type: string }
      responses:
        '200': { description: File download URL or stream }
  /upload-asset:
    post:
      tags: [Storage]
      summary: Upload a file as a reusable asset (workflows-api host)
      operationId: uploadAsset
      servers:
        - url: https://workflows-api.segmind.com
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        '200': { description: Asset upload response }
components:
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key