Bria Dataset API

openapi: 3.2.0
info:
  title: Tailored Generation API Reference Dataset API
  version: ''
  description: "Tailored Generation provides capabilities to generate visuals (photos, illustrations, vectors) \nthat preserve and faithfully reproduce specific IP elements or guidelines, ensuring consistency \nacross all generated outputs.\n\nThe Tailored Generation APIs allow you to manage and train tailored models that maintain the \nintegrity of your visual IP. You can train models through our Console or implement training \ndirectly via API.\n\n**Fully Automated Training Mode**\nBria supports users in training high-quality finetuned models without the guesswork. Based on the selected IP type & dataset, Bria automatically selects the right training parameters. \nThis means that the user only needs to spend time curating their dataset.\n\n**Advanced Customization and Access:** Bria offers 2 types of advanced training customization: Expert training mode and source-code & weights.\n  - **Expert training mode** is for LoRa Finetune experts and provides the ability to finetune training parameters and upload larger training datasets.\n  - **Source-code & Weights** is for developers seeking deeper customization and access to Bria's source-available GenAI models via [Hugging Face](https://huggingface.co/briaai).  \n\nAll methods allow full control over fine-tuning, pipeline creation, and integration into proprietary workflows—empowering AI teams to develop and optimize their own generative AI solutions.\n\nThe Tailored Generation Training API provides a set of endpoints to manage the entire lifecycle \nof a tailored generation project:\n\n1. **Project Management**: Create and manage projects that define IP characteristics:\n  - **Create and Retrieve Projects**: Use the `/projects` endpoints to create a new project or \n    retrieve existing projects that belong to your organization.\n  - **Define IP Type**: Specify the IP type (e.g., multi_object_set, defined_character, \n    stylized_scene) and medium.\n  - **Manage Project Details**: Use the `/projects/{id}` endpoints to update or delete \n    specific projects.\n\n2. **Dataset Management**: Organize and refine datasets within your projects:\n  - **Create and Retrieve Datasets**: Use the `/datasets` endpoints to create new datasets or \n    retrieve existing ones.\n  - **Generate a Visual Schema**\n    - Use `/tailored-gen/generate_visual_schema` to create a structured visual schema using 5-10 sample images.\n  - **Refine Structured Data**\n    - Use `/tailored-gen/refine_structured_prompt` to iterate on your **Visual Schema** or **Image Captions** using natural language instructions.\n    - *Example:* You can send your generated schema with the instruction \"Character's name is Lucy\" to improve the training metadata programmatically.\n  - **Upload and Manage Images**: \n    - **Basic upload**: Use `/datasets/{dataset_id}/images` to upload up to 200 images individually.\n    - **Bulk upload**: Use `/datasets/{dataset_id}/images/bulk` to upload zip files with >200 high-quality images (Advanced).\n  - **Clone Datasets**: Create variations of existing datasets using the clone functionality.\n\n3. **Model Management**: Train and optimize tailored models based on your datasets:\n  - **Create and Retrieve Models**: Use the `/models` endpoints to create new models or list \n    existing ones.\n  - **Choose training mode**: Select between Fully automated mode (automatic training based on Bria's recipes) and Expert mode (for training parameter tweaking).\n  - **Monitor and Control**: Manage the model lifecycle, including training start/stop, \n    status monitoring, and version control over the training parameters.\n\n4. **Generation Capabilities**:\n  - **Image Generation**: Use `/image/generate/tailored` for text-to-image generation.\n  - **Structured Prompting**: Use `/structured_prompt/generate/tailored` to create structured prompts via VLM before generation.\n  - **Video Generation**: Use `/video/generate/tailored/image-to-video` to animate tailored images.\n\n### **Training Process**\n\nTo train a tailored model:\n\n1. **Create a Project**: Use the `/projects` endpoint to define your IP type and medium.\n2. **Create a Dataset**: Use the `/datasets` endpoint to create a dataset within your project.\n3. **Define Visual Identity**:\n   - **Step A (Generate):** Call `/tailored-gen/generate_visual_schema`, sampling 5-10 images from your input set.\n   - **Step B (Refine - Optional):** Call `/tailored-gen/refine_structured_prompt` with the generated schema and instructions to tweak the definitions (e.g., \"Remove references to blue background\").\n   - **Step C (Apply):** Update the dataset with the final schema using `/datasets/{dataset_id}`.\n4. **Upload Images**: Upload images using the `/datasets/{dataset_id}/images` or `/datasets/{dataset_id}/images/bulk` endpoints \n  (minimum resolution: 1024x1024px). note: if you upload images before updating the visual schema, use the Regenerate All Captions endpoint to caption the images.\n5. **Prepare Dataset**: Review auto-generated captions (you can also use `refine_structured_prompt` to fix specific image captions) and update the dataset status to 'completed'.\n6. **Create Model**: Use the `/models` endpoint to create a model, which requires a training mode.\n7. **Start Training**: Initiate training via the `/models/{id}/start_training` endpoint. \n  Training typically takes 4-6 hours.\n8. **Monitor Progress**: Check the training status using the `/models/{id}` endpoint until \n  training is 'Completed'.\n9. **Generate Images**: \n  - Use `v2/image/generate/tailored` for text-to-image generation.\n"
servers:
- url: https://engine.prod.bria-api.com/v2/
tags:
- name: Dataset
  description: Manage training datasets
paths:
  /tailored-gen/datasets:
    post:
      summary: Create Dataset
      tags:
      - Dataset
      servers:
      - url: https://engine.prod.bria-api.com/v1
      description: 'Create a new dataset.


        Datasets use JSON structured data (`visual_schema`) for training. You must generate a visual schema via `/generate_visual_schema` before completing the dataset.


        **Completion Requirements:**

        Minimum 5 images required to mark as completed.


        **Upload types**:

        * **Basic upload type**: Supports up to 200 images, uploading image files

        * **Advanced upload type**: Supports up to 5000 images, uploading a zip file

        '
      operationId: create-dataset
      parameters:
      - in: header
        name: api_token
        schema:
          type: string
        required: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                project_id:
                  type: integer
                  description: Associated project ID (required)
                name:
                  type: string
                  description: Dataset name (required)
                upload_type:
                  type: string
                  description: The method used to upload images to the dataset.
                  enum:
                  - basic
                  - advanced
                  default: basic
            example:
              project_id: 123
              name: dataset v1
              upload_type: basic
      responses:
        '201':
          description: Dataset successfully created
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  project_id:
                    type: integer
                  name:
                    type: string
                  visual_schema:
                    type:
                    - string
                    - 'null'
                    description: A string containing the JSON structure representing the visual backbone. Must be generated via `/generate_visual_schema`.
                  status:
                    type: string
                    enum:
                    - draft
                  captions_update_status:
                    type: string
                    enum:
                    - empty
                    - in_progress
                    - completed
                  upload_type:
                    type: string
                    enum:
                    - basic
                    - advanced
                  created_at:
                    type: string
                    format: date-time
                  updated_at:
                    type: string
                    format: date-time
              example:
                id: 456
                project_id: 123
                name: dataset v1
                visual_schema: null
                status: draft
                captions_update_status: empty
                upload_type: basic
                created_at: '2024-05-26T12:00:00Z'
                updated_at: '2024-05-26T12:00:00Z'
        '400':
          description: Bad request - validation error
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Project not found
        '429':
          description: Request limit exceeded.
        '500':
          description: Internal server error
    get:
      summary: Get Datasets
      tags:
      - Dataset
      servers:
      - url: https://engine.prod.bria-api.com/v1
      description: Retrieve a list of all datasets. If there are no datasets, returns an empty array.
      operationId: get-datasets
      parameters:
      - in: header
        name: api_token
        schema:
          type: string
        required: true
      responses:
        '200':
          description: Successfully retrieved datasets
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                    project_id:
                      type: integer
                    name:
                      type: string
                    visual_schema:
                      type:
                      - string
                      - 'null'
                    status:
                      type: string
                      enum:
                      - draft
                      - completed
                    captions_update_status:
                      type: string
                      enum:
                      - empty
                      - in_progress
                      - completed
                    upload_type:
                      type: string
                      enum:
                      - basic
                      - advanced
                    images_count:
                      type: integer
                    created_at:
                      type: string
                      format: date-time
                    updated_at:
                      type: string
                      format: date-time
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '429':
          description: Request limit exceeded.
        '500':
          description: Internal server error
  /tailored-gen/projects/{project_id}/datasets:
    get:
      summary: Get Datasets by Project
      tags:
      - Dataset
      servers:
      - url: https://engine.prod.bria-api.com/v1
      description: Retrieve all datasets for a specific project.
      operationId: get-datasets-by-project
      parameters:
      - in: path
        name: project_id
        schema:
          type: string
        required: true
      - in: header
        name: api_token
        schema:
          type: string
        required: true
      - in: query
        name: include_models
        required: false
        schema:
          type: boolean
          default: false
        description: If true, include model objects using the dataset.
      - in: query
        name: include_models_ids
        required: false
        schema:
          type: boolean
          default: false
        description: If true, include model IDs using the dataset.
      responses:
        '200':
          description: Successfully retrieved datasets
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                    project_id:
                      type: integer
                    name:
                      type: string
                    visual_schema:
                      type:
                      - string
                      - 'null'
                    upload_type:
                      type: string
                      enum:
                      - basic
                      - advanced
                    images_count:
                      type: integer
                    status:
                      type: string
                      enum:
                      - draft
                      - completed
                    captions_update_status:
                      type: string
                      enum:
                      - empty
                      - in_progress
                      - completed
                    models:
                      type: array
                      description: Only included when include_models=true
                      items:
                        type: object
                    model_ids:
                      type: array
                      description: Only included when include_models_ids=true
                      items:
                        type: string
                    created_at:
                      type: string
                      format: date-time
                    updated_at:
                      type: string
                      format: date-time
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Project not found
        '429':
          description: Request limit exceeded.
        '500':
          description: Internal server error
  /tailored-gen/datasets/{dataset_id}:
    get:
      summary: Get Dataset by ID
      tags:
      - Dataset
      servers:
      - url: https://engine.prod.bria-api.com/v1
      description: Retrieve a specific dataset including its images.
      operationId: get-dataset-by-id
      parameters:
      - in: path
        name: dataset_id
        schema:
          type: integer
        required: true
      - in: header
        name: api_token
        schema:
          type: string
        required: true
      - in: query
        name: max_images
        schema:
          type: integer
          minimum: 1
          maximum: 200
          default: 200
        description: The maximum number of images to retrieve.
      responses:
        '200':
          description: Successfully retrieved dataset
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  project_id:
                    type: integer
                  name:
                    type: string
                  visual_schema:
                    type:
                    - string
                    - 'null'
                  status:
                    type: string
                    enum:
                    - draft
                    - completed
                  captions_update_status:
                    type: string
                    enum:
                    - empty
                    - in_progress
                    - completed
                  upload_type:
                    type: string
                    enum:
                    - basic
                    - advanced
                  images_count:
                    type: integer
                  images:
                    type: array
                    description: Array of images in the dataset (up to 200, controlled by max_images)
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                        dataset_id:
                          type: integer
                        caption:
                          type: string
                        caption_source:
                          type:
                          - string
                          - 'null'
                          enum:
                          - automatic
                          - manual
                        upload_source_url:
                          type:
                          - string
                          - 'null'
                        image_name:
                          type: string
                        image_url:
                          type: string
                        thumbnail_url:
                          type: string
                        created_at:
                          type: string
                          format: date-time
                        updated_at:
                          type: string
                          format: date-time
                  created_at:
                    type: string
                    format: date-time
                  updated_at:
                    type: string
                    format: date-time
              example:
                id: 456
                project_id: 123
                name: dataset v1
                visual_schema: '{"style": "...", "colors": "..."}'
                status: completed
                captions_update_status: completed
                upload_type: basic
                images_count: 2
                images:
                - id: 789
                  dataset_id: 456
                  caption: '{"subject": "character standing", ...}'
                  caption_source: automatic
                  upload_source_url: null
                  image_name: lora_standing.png
                  image_url: https://api.example.com/files/lora_standing.png
                  thumbnail_url: https://api.example.com/files/lora_standing_thumb.png
                  created_at: '2024-05-26T12:30:00Z'
                  updated_at: '2024-05-26T12:30:00Z'
                created_at: '2024-05-26T12:00:00Z'
                updated_at: '2024-05-26T14:30:00Z'
        '400':
          description: Bad request.
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Dataset not found
        '429':
          description: Request limit exceeded.
        '500':
          description: Internal server error
    put:
      summary: Update Dataset
      tags:
      - Dataset
      servers:
      - url: https://engine.prod.bria-api.com/v1
      description: "Update a dataset.\n\nYou can update `visual_schema` only when the dataset status is `draft`.\n  \n**Completion Requirements:**\nTo set `status` to `completed`, the dataset must have at least **5 images**.\n"
      operationId: update-dataset
      parameters:
      - in: path
        name: dataset_id
        schema:
          type: integer
        required: true
      - in: header
        name: api_token
        schema:
          type: string
        required: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                visual_schema:
                  type: string
                  description: A string containing the JSON structure from `/generate_visual_schema`. Can only be updated when status is `draft`.
                status:
                  type: string
                  enum:
                  - draft
                  - completed
      responses:
        '200':
          description: Dataset successfully updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  project_id:
                    type: integer
                  name:
                    type: string
                  visual_schema:
                    type:
                    - string
                    - 'null'
                  status:
                    type: string
                    enum:
                    - draft
                    - completed
                  captions_update_status:
                    type: string
                    enum:
                    - empty
                    - in_progress
                    - completed
                  upload_type:
                    type: string
                    enum:
                    - basic
                    - advanced
                  created_at:
                    type: string
                    format: date-time
                  updated_at:
                    type: string
                    format: date-time
        '400':
          description: Bad request - Validation error.
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Dataset not found
        '409':
          description: Conflict error - Cannot update visual_schema for a completed dataset, or insufficient images to complete.
        '429':
          description: Request limit exceeded.
        '500':
          description: Internal server error
    delete:
      summary: Delete Dataset
      tags:
      - Dataset
      servers:
      - url: https://engine.prod.bria-api.com/v1
      description: Delete a specific dataset. Deletes all associated images.
      operationId: delete-dataset
      parameters:
      - in: path
        name: dataset_id
        schema:
          type: integer
        required: true
      - in: header
        name: api_token
        schema:
          type: string
        required: true
      responses:
        '204':
          description: Dataset successfully deleted
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Dataset not found
        '409':
          description: Cannot delete a dataset that is used by a model in training
        '429':
          description: Request limit exceeded.
        '500':
          description: Internal server error
  /tailored-gen/datasets/{dataset_id}/clone:
    post:
      summary: Clone Dataset As Draft
      tags:
      - Dataset
      servers:
      - url: https://engine.prod.bria-api.com/v1
      description: Create a new draft dataset based on an existing one. This is useful when you would like to use the same dataset again for another training, but with some modification (create a variation). The cloned dataset inherits the `visual_schema` from the source dataset.
      operationId: clone-dataset
      parameters:
      - in: path
        name: dataset_id
        schema:
          type: integer
        required: true
      - in: header
        name: api_token
        schema:
          type: string
        required: true
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: New dataset name. Defaults to "Copy of [original name]"
                description:
                  type: string
                  description: New dataset description.
            example:
              name: Copy of dataset v1 - modified version
              description: Modified version with additional poses
      responses:
        '201':
          description: Dataset successfully cloned
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  project_id:
                    type: integer
                  name:
                    type: string
                  visual_schema:
                    type:
                    - string
                    - 'null'
                  status:
                    type: string
                    enum:
                    - draft
                  captions_update_status:
                    type: string
                    enum:
                    - empty
                    - in_progress
                    - completed
                  upload_type:
                    type: string
                    enum:
                    - basic
                    - advanced
                  images_count:
                    type: integer
                  images:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                        dataset_id:
                          type: integer
                        caption:
                          type: string
                        caption_source:
                          type: string
                          enum:
                          - automatic
                        image_name:
                          type: string
                        image_url:
                          type: string
                        thumbnail_url:
                          type: string
                        created_at:
                          type: string
                          format: date-time
                        updated_at:
                          type: string
                          format: date-time
                  created_at:
                    type: string
                    format: date-time
                  updated_at:
                    type: string
                    format: date-time
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Dataset not found
        '429':
          description: Request limit exceeded.
        '500':
          description: Internal server error
  /tailored-gen/datasets/{dataset_id}/images:
    post:
      summary: Upload Image Files
      tags:
      - Dataset
      servers:
      - url: https://engine.prod.bria-api.com/v1
      description: "Upload a new image to a dataset.\n\n**Image Requirements:**\n- Recommended minimum resolution: 1024x1024 pixels for best quality\n  - By default, smaller images (down to 256x256) will be automatically upscaled (`increase_resolution=true`)\n  - To strictly enforce the 1024x1024 minimum, set `increase_resolution=false`\n- Supported formats: jpg, jpeg, png, webp\n- Preferably use original high-quality assets\n\n**Dataset Guidelines:**\n- Recommended: 5-50 images for optimal results\n- Maximum supported: 200 images\n- Ensure consistency in style, structure, and visual elements\n- Balance diversity in content while maintaining consistency in key elements\n\n**For optimal training (especially for characters/objects):**\n- Subject should occupy most of the image area\n- Minimize unnecessary margins around the subject\n- Transparent backgrounds will be converted to black\n- For character datasets: include diverse poses, environments, attires, and interactions\n\n**Constraints:**\n- Can only be used by \"basic\" upload type datasets. Use images/bulk for advanced datasets.\n- Dataset must have at least 5 images\n- Dataset cannot exceed 200 images\n- Cannot upload to a completed dataset\n\nThis API endpoint supports content moderation via an optional parameter.\n"
      operationId: upload-image
      parameters:
      - in: path
        name: dataset_id
        schema:
          type: integer
        required: true
      - in: header
        name: api_token
        schema:
          type: string
        required: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: Image file to upload (required if image_url not provided)
                image_url:
                  type: string
                  description: URL of image to upload (required if file not provided)
                image_name:
                  type: string
                  description: Custom name for the image (optional)
                increase_resolution:
                  type: boolean
                  default: true
                  description: 'When enabled (default), input images smaller than 1024x1024 but larger than 256x256 will be automatically upscaled.

                    If false, images must be at least 1024x1024 pixels.

                    '
                content_moderation:
                  type: boolean
                  default: false
            example:
              image_url: https://example.com/images/character_pose.jpg
              image_name: character_standing_pose.jpg
      responses:
        '201':
          description: Image successfully uploaded
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  dataset_id:
                    type: integer
                  caption:
                    type:
                    - string
                    - 'null'
                    description: The generated caption. Null if uploaded without a visual schema.
                  caption_source:
                    type:
                    - string
                    - 'null'
                    enum:
                    - automatic
                    - manual
                    - pending
                  image_name:
                    type: string
                  image_url:
                    type: string
                  thumbnail_url:
                    type: string
                  created_at:
                    type: string
                    format: date-time
                  updated_at:
                    type: string
                    format: date-time
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Dataset not found
        '409':
          description: Conflict error (completed dataset or max images reached)
        '412':
          description: Precondition Failed (resolution too low)
        '415':
          description: Unsupported Media Type.
        '422':
          description: Unprocessable Entity (moderation failure or invalid URL)
        '429':
          description: Request limit exceeded.
        '500':
          description: Internal server error
    get:
      summary: Get Images
      tags:
      - Dataset
      servers:
      - url: https://engine.prod.bria-api.com/v1
      description: Retrieve all images in a specific dataset.
      operationId: get-images
      parameters:
      - in: path
        name: dataset_id
        schema:
          type: integer
        required: true
      - in: header
        name: api_token
        schema:
          type: string
        required: true
      responses:
        '200':
          description: Successfully retrieved images
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                    dataset_id:
                      type: integer
                    caption:
                      type: string
                    caption_source:
                      type: string
                      enum:
                      - automatic
                      - manual
                    image_name:
                      type: string
                    image_url:
                      type: string
                    thumbnail_url:
                      type: string
                    created_at:
                      type: string
                      form

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