openapi: 3.1.0
info:
  title: API Reference subpackage_datasets subpackage_models API
  version: 1.0.0
servers:
- url: https://api.ideogram.ai
tags:
- name: subpackage_models
paths:
  /v1/ideogram-v3/train-model:
    post:
      operationId: train-model-v-3
      summary: Train a custom Ideogram v3 model
      description: 'Start training a custom Ideogram v3 model from a dataset using default hyperparameters. The dataset must contain at least 15 images and a maximum of 100 images.

        '
      tags:
      - subpackage_models
      parameters:
      - name: Api-Key
        in: header
        description: API key for access control. Use in the header with the name \"Api-Key\"
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Training started successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrainDatasetModelResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                description: Any type
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                description: Any type
        '404':
          description: Dataset not found
          content:
            application/json:
              schema:
                description: Any type
      requestBody:
        description: Training configuration
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TrainModelV3Request'
  /models:
    get:
      operationId: list-custom-models
      summary: List models
      description: 'Lists custom models for the authenticated user. Use the `scope` parameter to control which models are returned. If omitted, returns both owned models and models shared with the user''s organization via the model registry. `owned` returns only models created by the user. `shared` returns only models shared via the model registry, excluding the user''s own models.

        '
      tags:
      - subpackage_models
      parameters:
      - name: scope
        in: query
        description: 'Controls which models are returned. Omit to return both owned and shared models combined. `owned` returns only models created by the authenticated user. `shared` returns only models shared with the user''s organization via the model registry.

          '
        required: false
        schema:
          $ref: '#/components/schemas/ModelsGetParametersScope'
      - name: status
        in: query
        description: 'Filter by model status. Applied to owned models only; shared models in the model registry are already filtered to available versions. Example: `?status=TRAINING&status=COMPLETED`

          '
        required: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/ModelStatus'
      - name: Api-Key
        in: header
        description: API key for access control. Use in the header with the name \"Api-Key\"
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Models retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListModelsResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                description: Any type
  /models/{model_id}:
    get:
      operationId: get-custom-model
      summary: Get model details
      description: 'Get detailed information about a specific custom model. The user must either own the model or the model must be shared with the user''s organization via the model registry. Returns 404 if the model is not found or not accessible.

        '
      tags:
      - subpackage_models
      parameters:
      - name: model_id
        in: path
        required: true
        schema:
          type: string
      - name: Api-Key
        in: header
        description: API key for access control. Use in the header with the name \"Api-Key\"
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Model retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetModelResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                description: Any type
        '404':
          description: Model not found
          content:
            application/json:
              schema:
                description: Any type
components:
  schemas:
    ModelsGetParametersScope:
      type: string
      enum:
      - owned
      - shared
      title: ModelsGetParametersScope
    TrainDatasetModelResponse:
      type: object
      properties:
        model_id:
          type: string
          description: Unique identifier of the created model.
        dataset_id:
          type: string
          description: Identifier of the dataset used for training.
        training_status:
          type: string
          description: Current training status of the model.
        model_name:
          type: string
          description: Name of the model.
      required:
      - model_id
      - dataset_id
      - training_status
      - model_name
      title: TrainDatasetModelResponse
    GetModelResponse:
      type: object
      properties:
        model:
          $ref: '#/components/schemas/CustomModel'
      required:
      - model
      title: GetModelResponse
    ListModelsResponse:
      type: object
      properties:
        models:
          type: array
          items:
            $ref: '#/components/schemas/CustomModel'
          description: List of models.
      required:
      - models
      title: ListModelsResponse
    ModelStatus:
      type: string
      enum:
      - CREATING
      - DRAFT
      - TRAINING
      - COMPLETED
      - ERRORED
      - ARCHIVED
      description: The status of a custom model.
      title: ModelStatus
    TrainModelV3Request:
      type: object
      properties:
        dataset_id:
          type: string
          description: ID of the dataset to train the model from.
        model_name:
          type: string
          description: 'Name for the trained model. Must be 5-30 characters, alphanumeric with spaces and hyphens allowed.

            '
      required:
      - dataset_id
      - model_name
      description: 'Training request for a custom Ideogram v3 model using default hyperparameters.

        '
      title: TrainModelV3Request
    CustomModel:
      type: object
      properties:
        model_id:
          type: string
          description: Unique identifier for the model (base64 URL-safe encoded UUID).
        custom_model_uri:
          type:
          - string
          - 'null'
          description: 'A custom model URI in the format model/<model_name>/version/<version_name>.

            Use this URI when generating images with this model. Only present for models

            that have been registered in the model registry.

            '
        name:
          type: string
          description: Display name of the model.
        status:
          $ref: '#/components/schemas/ModelStatus'
        dataset_id:
          type:
          - string
          - 'null'
          description: ID of the dataset (collection) the model was trained from.
        creation_time:
          type: string
          format: date-time
          description: When the model was created.
        last_update_time:
          type:
          - string
          - 'null'
          format: date-time
          description: When the model was last updated.
        is_available_for_generation:
          type: boolean
          description: Whether the model is available for image generation.
        is_owned:
          type: boolean
          description: Whether the authenticated user owns this model.
      required:
      - model_id
      - name
      - status
      - creation_time
      - is_available_for_generation
      - is_owned
      description: A custom model.
      title: CustomModel
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Api-Key
      description: API key for access control. Use in the header with the name \"Api-Key\"