Oxen Ai API

openapi: 3.2.0
info:
  title: oxen AI API
  version: 0.243.1
servers:
- url: https://hub.oxen.ai
  variables: {}
security: []
tags:
- name: Ai
paths:
  /api/ai/audio/generate:
    post:
      callbacks: {}
      description: Creates audio (e.g. speech) from a text prompt.
      operationId: OxenApiWeb.Controllers.ModelController.generate_audio
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AudioGenerateRequest'
        description: Audio generation request
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AudioGenerateResponse'
          description: Generated audio
        '400':
          content:
            application/json:
              schema:
                type: object
          description: Invalid request
      summary: Generate audio
      tags:
      - Ai
  /api/ai/chat/completions:
    post:
      callbacks: {}
      description: Generates a model response for the given conversation. Compatible with the OpenAI chat completions API.
      operationId: OxenApiWeb.Controllers.ModelController.get_model_response
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatCompletionRequest'
        description: Chat completion request
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatCompletionResponse'
          description: Chat completion
        '400':
          content:
            application/json:
              schema:
                type: object
          description: Invalid request
      summary: Create chat completion
      tags:
      - Ai
  /api/ai/generations:
    get:
      callbacks: {}
      description: Paginated browse view of completed and in-flight generations for a namespace. Use `/api/ai/queue` for the lean polling view of in-flight rows.
      operationId: OxenApiWeb.Controllers.GenerationsController.index
      parameters:
      - description: ''
        in: query
        name: namespace
        required: false
        schema:
          type: string
      - description: ''
        in: query
        name: model
        required: false
        schema:
          type: string
      - description: ''
        in: query
        name: media_type
        required: false
        schema:
          enum:
          - image
          - video
          type: string
      - description: ''
        in: query
        name: status
        required: false
        schema:
          enum:
          - queued
          - processing
          - succeeded
          - failed
          - cancelled
          type: string
      - description: ''
        in: query
        name: repo
        required: false
        schema:
          type: string
      - description: ''
        in: query
        name: folder
        required: false
        schema:
          type: string
      - description: ''
        in: query
        name: page
        required: false
        schema:
          default: 1
          minimum: 1
          type: integer
      - description: ''
        in: query
        name: page_size
        required: false
        schema:
          default: 50
          maximum: 1000
          minimum: 1
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerationsListResponse'
          description: Generation list
      summary: List past generations
      tags:
      - Ai
  /api/ai/generations/{generation_id}:
    get:
      callbacks: {}
      description: Full metadata for a single generation, including cost and the user who triggered it.
      operationId: OxenApiWeb.Controllers.GenerationsController.show
      parameters:
      - description: ''
        in: path
        name: generation_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerationsShowResponse'
          description: Generation details
        '404':
          content:
            application/json:
              schema:
                type: object
          description: Generation not found
      summary: Get generation details
      tags:
      - Ai
  /api/ai/images/edit:
    post:
      callbacks: {}
      description: Edits an image given a prompt and source image.
      operationId: OxenApiWeb.Controllers.ModelController.edit_image
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImageEditRequest'
        description: Image edit request
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImageGenerateResponse'
          description: Edited images
        '400':
          content:
            application/json:
              schema:
                type: object
          description: Invalid request
      summary: Edit image
      tags:
      - Ai
  /api/ai/images/generate:
    post:
      callbacks: {}
      description: Creates an image from a text prompt.
      operationId: OxenApiWeb.Controllers.ModelController.generate_image
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImageGenerateRequest'
        description: Image generation request
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImageGenerateResponse'
          description: Generated images
        '400':
          content:
            application/json:
              schema:
                type: object
          description: Invalid request
      summary: Generate image
      tags:
      - Ai
  /api/ai/models:
    get:
      callbacks: {}
      description: Lists all available models. OpenAI-compatible.
      operationId: OxenApiWeb.Controllers.ModelsController.index
      parameters:
      - description: ''
        in: query
        name: provider_name
        required: false
        schema:
          type: string
      - description: ''
        in: query
        name: developer_name
        required: false
        schema:
          type: string
      - description: ''
        in: query
        name: action
        required: false
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListModelsResponse'
          description: Model list
      summary: List models
      tags:
      - Ai
  /api/ai/models/favorites:
    get:
      callbacks: {}
      operationId: OxenApiWeb.Controllers.ModelsController.list_favorites
      parameters: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListModelsResponse'
          description: Favorite models
      summary: List favorite models
      tags:
      - Ai
  /api/ai/models/featured:
    get:
      callbacks: {}
      operationId: OxenApiWeb.Controllers.ModelsController.list_featured
      parameters: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListModelsResponse'
          description: Featured models
      summary: List featured models
      tags:
      - Ai
  /api/ai/models/search:
    get:
      callbacks: {}
      operationId: OxenApiWeb.Controllers.ModelsController.search
      parameters:
      - description: ''
        in: query
        name: search
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListModelsResponse'
          description: Search results
      summary: Search models
      tags:
      - Ai
  /api/ai/models/{id}:
    delete:
      callbacks: {}
      operationId: OxenApiWeb.Controllers.ModelsController.delete_custom_model
      parameters:
      - description: ''
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Model'
          description: Deleted model
        '404':
          content:
            application/json:
              schema:
                type: object
          description: Model not found
      summary: Delete custom model
      tags:
      - Ai
    get:
      callbacks: {}
      description: Retrieves a model by ID or name. OpenAI-compatible.
      operationId: OxenApiWeb.Controllers.ModelsController.show
      parameters:
      - description: Model ID (UUID) or name
        in: path
        name: id
        required: true
        schema:
          type: string
      - description: Pass "live" to refresh deployment status from provider before responding
        in: query
        name: deployment_status
        required: false
        schema:
          enum:
          - live
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Model'
          description: Model details
        '404':
          content:
            application/json:
              schema:
                type: object
          description: Model not found
      summary: Retrieve model
      tags:
      - Ai
    put:
      callbacks: {}
      operationId: OxenApiWeb.Controllers.ModelsController.update
      parameters:
      - description: ''
        in: path
        name: id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
        description: Model update params
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Model'
          description: Updated model
      summary: Update model
      tags:
      - Ai
  /api/ai/models/{id}/activate:
    post:
      callbacks: {}
      description: Activates an inactive model deployment.
      operationId: OxenApiWeb.Controllers.ModelsController.wake
      parameters:
      - description: ''
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Model'
          description: Model activated
      summary: Activate model deployment
      tags:
      - Ai
  /api/ai/models/{id}/deactivate:
    post:
      callbacks: {}
      operationId: OxenApiWeb.Controllers.ModelsController.deactivate
      parameters:
      - description: ''
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Model'
          description: Model deactivated
      summary: Deactivate model deployment
      tags:
      - Ai
  /api/ai/models/{id}/favorite:
    delete:
      callbacks: {}
      operationId: OxenApiWeb.Controllers.ModelsController.delete_favorite
      parameters:
      - description: ''
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Model'
          description: Model unfavorited
      summary: Unfavorite a model
      tags:
      - Ai
    post:
      callbacks: {}
      operationId: OxenApiWeb.Controllers.ModelsController.create_favorite
      parameters:
      - description: ''
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Model'
          description: Model favorited
      summary: Favorite a model
      tags:
      - Ai
  /api/ai/queue:
    get:
      callbacks: {}
      description: Lean polling view of the workbench render queue. Returns active generations (status queued or processing) by default; pass an explicit `status=` filter to include terminal rows. For paginated history with cost aggregates, use `/api/ai/generations`.
      operationId: OxenApiWeb.Controllers.QueueController.index
      parameters:
      - description: ''
        in: query
        name: namespace
        required: false
        schema:
          type: string
      - description: ''
        in: query
        name: model
        required: false
        schema:
          type: string
      - description: ''
        in: query
        name: media_type
        required: false
        schema:
          enum:
          - image
          - video
          type: string
      - description: ''
        in: query
        name: status
        required: false
        schema:
          enum:
          - queued
          - processing
          - succeeded
          - failed
          - cancelled
          type: string
      - description: ''
        in: query
        name: repo
        required: false
        schema:
          type: string
      - description: ''
        in: query
        name: folder
        required: false
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueueListResponse'
          description: Generation list
      summary: List in-flight queue items
      tags:
      - Ai
    post:
      callbacks: {}
      description: Enqueues an async image or video generation job.
      operationId: OxenApiWeb.Controllers.QueueController.create
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QueueCreateRequest'
        description: Queue request
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueueCreateResponse'
          description: Generation enqueued
        '400':
          content:
            application/json:
              schema:
                type: object
          description: Invalid request
      summary: Enqueue generation
      tags:
      - Ai
  /api/ai/queue/{generation_id}:
    delete:
      callbacks: {}
      description: Cancels a generation. The row is retained with status set to cancelled.
      operationId: OxenApiWeb.Controllers.QueueController.delete
      parameters:
      - description: ''
        in: path
        name: generation_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueueDeleteResponse'
          description: Generation cancelled
        '404':
          content:
            application/json:
              schema:
                type: object
          description: Generation not found
      summary: Cancel generation
      tags:
      - Ai
    get:
      callbacks: {}
      description: Retrieves metadata for a single queued generation.
      operationId: OxenApiWeb.Controllers.QueueController.show
      parameters:
      - description: ''
        in: path
        name: generation_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueueGenerationResponse'
          description: Generation details
        '404':
          content:
            application/json:
              schema:
                type: object
          description: Generation not found
      summary: Get generation status
      tags:
      - Ai
  /api/ai/videos/generate:
    post:
      callbacks: {}
      description: Creates a video from a text prompt.
      operationId: OxenApiWeb.Controllers.ModelController.generate_video
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VideoGenerateRequest'
        description: Video generation request
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VideoGenerateResponse'
          description: Generated videos
        '400':
          content:
            application/json:
              schema:
                type: object
          description: Invalid request
      summary: Generate video
      tags:
      - Ai
components:
  schemas:
    Model:
      description: Represents a model available for inference or fine-tuning. Compatible with the OpenAI model object.
      properties:
        capabilities:
          properties:
            input:
              items:
                type: string
              type: array
            output:
              items:
                type: string
              type: array
          type: object
        created:
          description: Unix timestamp when the model was registered
          type: integer
        deployments:
          description: Active deployments. Empty for base models.
          items:
            properties:
              status:
                enum:
                - active
                - inactive
                - deploying
                - deactivating
                - error
                - unknown
                type: string
            type: object
          type: array
        description:
          type:
          - string
          - 'null'
        developer:
          properties:
            logo:
              type:
              - string
              - 'null'
            name:
              type: string
          type:
          - object
          - 'null'
        display_name:
          type: string
        endpoint:
          description: API endpoint to call this model
          enum:
          - /chat/completions
          - /images/generate
          - /videos/generate
          type: string
        fine_tuning:
          description: Fine-tuning info, or null if model is not fine-tuneable
          properties:
            actions:
              description: Supported fine-tune action types
              items:
                type: string
              type: array
            cost_per_second:
              type:
              - number
              - 'null'
          type:
          - object
          - 'null'
        id:
          description: Model identifier used in API calls
          type: string
        image_url:
          type:
          - string
          - 'null'
        model_type:
          enum:
          - base
          - custom
          type: string
        object:
          enum:
          - model
          type: string
        owned_by:
          description: '"oxen" for base models, owner namespace for custom models'
          type: string
        pricing:
          properties:
            cost_per_image:
              type:
              - number
              - 'null'
            cost_per_image_grid:
              additionalProperties:
                additionalProperties:
                  type: number
                type: object
              description: 'Cost per image keyed by quality then resolution tier (e.g. {"high": {"4K": 1.47}})'
              type:
              - object
              - 'null'
            cost_per_second:
              type:
              - number
              - 'null'
            cost_per_second_by_resolution:
              additionalProperties:
                type: number
              description: 'Cost per output second keyed by resolution (e.g. {"480p": 0.096})'
              type:
              - object
              - 'null'
            cost_per_second_high_res:
              type:
              - number
              - 'null'
            cost_per_second_with_audio:
              type:
              - number
              - 'null'
            input_cost_per_token:
              type:
              - number
              - 'null'
            method:
              enum:
              - token
              - time
              - per_image
              - per_video_output_second
              type: string
            output_cost_per_token:
              type:
              - number
              - 'null'
          type: object
        released_at:
          type:
          - string
          - 'null'
        request_schema:
          description: JSON Schema describing model-specific parameters
          type:
          - object
          - 'null'
        showcase:
          description: Optional marketing content rendered on the public model showcase page
          properties:
            gallery:
              items:
                properties:
                  alt:
                    type: string
                  category:
                    type:
                    - string
                    - 'null'
                  details:
                    type:
                    - string
                    - 'null'
                  prompt:
                    type:
                    - string
                    - 'null'
                  src:
                    description: Absolute URL
                    type: string
                  title:
                    type:
                    - string
                    - 'null'
                required:
                - src
                - alt
                type: object
              type: array
            hero_image:
              description: Absolute URL
              type:
              - string
              - 'null'
            tagline:
              type:
              - string
              - 'null'
          type:
          - object
          - 'null'
        source_model:
          description: Base model this was fine-tuned from
          type:
          - string
          - 'null'
        summary:
          type:
          - string
          - 'null'
      required:
      - id
      - object
      - created
      - owned_by
      title: Model
      type: object
    QueueCreateResponse:
      properties:
        generations:
          items:
            properties:
              generation_id:
                format: uuid
                type: string
              status:
                enum:
                - queued
                type: string
            required:
            - generation_id
            - status
            type: object
          type: array
      required:
      - generations
      title: QueueCreateResponse
      type: object
    VideoGenerateResponse:
      properties:
        created:
          type: integer
        model:
          type: string
        videos:
          items:
            properties:
              url:
                type: string
            type: object
          type: array
      title: VideoGenerateResponse
      type: object
    ImageGenerateRequest:
      properties:
        model:
          description: Model ID to use for image generation
          type: string
        n:
          default: 1
          description: Number of images to generate
          type: integer
        prompt:
          description: Text prompt describing the desired image
          type: string
        seed:
          type:
          - integer
          - 'null'
        size:
          description: Image size
          type:
          - string
          - 'null'
      required:
      - model
      - prompt
      title: ImageGenerateRequest
      type: object
    QueueGenerationResponse:
      description: Compact status payload for a single queued generation, used by the workbench to poll progress. For the full payload (cost, user, etc.), see `/api/ai/generations/:id`.
      properties:
        completed_at:
          description: Unix timestamp
          type:
          - integer
          - 'null'
        enqueued_at:
          description: Unix timestamp
          type: integer
        error_message:
          type:
          - string
          - 'null'
        generation_id:
          format: uuid
          type: string
        media_type:
          enum:
          - image
          - video
          type: string
        model_name:
          type: string
        result_url:
          type:
          - string
          - 'null'
        started_at:
          description: Unix timestamp
          type:
          - integer
          - 'null'
        status:
          enum:
          - queued
          - processing
          - succeeded
          - failed
          - cancelled
          type: string
        target_directory:
          type:
          - string
          - 'null'
        target_namespace:
          type:
          - string
          - 'null'
        target_repo:
          type:
          - string
          - 'null'
      required:
      - generation_id
      - model_name
      - media_type
      - status
      - enqueued_at
      title: QueueGenerationResponse
      type: object
    AudioGenerateResponse:
      properties:
        audios:
          items:
            properties:
              url:
                type: string
            type: object
          type: array
        created:
          type: integer
        model:
          type: string
      title: AudioGenerateResponse
      type: object
    ListModelsResponse:
      description: OpenAI-compatible response for listing models.
      properties:
        data:
          items:
            $ref: '#/components/schemas/Model'
          type: array
        object:
          enum:
          - list
          type: string
      required:
      - object
      - data
      title: ListModelsResponse
      type: object
    QueueListResponse:
      description: Lean polling view of the workbench render queue. Active (`queued`/`processing`) rows by default; pass an explicit `status=` filter to include terminal rows. For paginated browse with cost aggregates, see `/api/ai/generations`.
      properties:
        count:
          type: integer
        generations:
          items:
            properties:
              completed_at:
                description: Unix timestamp
                type:
                - integer
                - 'null'
              enqueued_at:
                description: Unix timestamp
                type: integer
              error_message:
                type:
                - string
                - 'null'
              generation_id:
                format: uuid
                type: string
              media_type:
                enum:
                - image
                - video
                type: string
              model_name:
                type: string
              result_url:
                type:
                - string
                - 'null'
              started_at:
                description: Unix timestamp
                type:
                - integer
                - 'null'
              status:
                enum:
                - queued
                - processing
                - succeeded
                - failed
                - cancelled
                type: string
              target_directory:
                type:
                - string
                - 'null'
              target_namespace:
                type:
                - string
                - 'null'
              target_repo:
                type:
                - string
                - 'null'
            required:
            - generation_id
            - model_name
            - media_type
            - status
            - enqueued_at
            type: object
          type: array
      required:
      - count
      - generations
      title: QueueListResponse
      type: object
    ImageGenerateResponse:
      properties:
        created:
          type: integer
        images:
          items:
            properties:
              revised_prompt:
                type:
                - string
                - 'null'
              url:
                type: string
            type: object
          type: array
        model:
          type: string
      title: ImageGenerateResponse
      type: object
    ImageEditRequest:
      properties:
        image:
          description: URL of the source image
          type: string
        mask:
          description: URL of the mask image
          type:
          - string
          - 'null'
        model:
          type: string
        n:
          default: 1
          type: integer
        prompt:
          description: Text instruction for the edit
          type: string
        size:
          type:
          - string
          - 'null'
      required:
      - model
      - prompt
      - image
      title: ImageEditRequest
      type: object
    GenerationsShowResponse:
      description: Standard success envelope wrapping a single generation under `generation`. The inner object is the same per-row shape returned by the list endpoint (request params merged in at the top level), so the frontend can reuse one type for both.
      properties:
        generation:
          properties:
            completed_at:
              description: Unix timestamp
              type:
              - integer
              - 'null'
            cost:
              description: Charged amount for this row (decimal as string).
              type:
              - string
              - 'null'
            enqueued_at:
              description: Unix timestamp
              type: integer
            error_message:
              type:
              - string
              - 'null'
            generation_id:
              format: uuid
              type: string
            media_type:
              enum:
              - image
              - video
              type: string
            model_name:
              type: string
            result_url:
              type:
              - string
              - 'null'
            started_at:
              description: Unix timestamp
              type:
              - integer
              - 'null'
            status:
              enum:
              - queued
              - processing
              - succeeded
              - failed
              - cancelled
              type: string
            target_directory:
              type:
              - string
              - 'null'
            target_namespace:
              type:
              - string
              - 'null'
            target_repo:
              type:
              - string
              - 'null'
            user_id:
              format: uuid
              type:
              - string
              - 'null'
            user_image:
              type:
              - string
              - 'null'
            username:
              type:
              - string
              - 'null'
          required:
          - generation_id
          - model_name
          - media_type
          - status
          - enqueued_at
          type: object
        status:
          example: success
          type: string
        status_message:
          example: resource_found
          type: string
      required:
      - status
      - generation
      - status_message
      title: GenerationsShowResponse
      type: object
    ChatCompletionResponse:
      properties:
        choices:
          items:
            properties:
              finish_reason:
                type: string
              index:
                type: integer
              message:
                properties:
                  content:
             

# --- truncated at 32 KB (41 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/oxen/refs/heads/main/openapi/oxen-ai-api-openapi.yml