openapi: 3.1.0
info:
  title: AI Ring Virtual Try-On API (v1.8)
  version: 1.0.0
  description: >-
    Easily Create Your AR Ring or Engagement Ring Try Ons. You Only Need to
    Upload Images. Opt for 2D images for effortless yet high-quality virtual
    try-on experiences with minimal effort.
servers:
  - url: https://api.example.com
    description: Production server
paths:
  /s2s/v2.0/task/ring:
    post:
      summary: AI Ring Virtual Try-On
      description: >-
        Easily Create Your AR Ring or Engagement Ring Try Ons. You Only Need to
        Upload Images.
      operationId: AIRingVirtualTryOn
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RingRunTaskV2'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      task_id:
                        type: string
                      status:
                        type: string
                      results:
                        type: array
                        items:
                          type: object
                          properties:
                            url:
                              type: string
components:
  schemas:
    RingRunTaskV2:
      oneOf:
        - $ref: '#/components/schemas/RingRunTaskV21'
        - $ref: '#/components/schemas/RingRunTaskV22'
        - $ref: '#/components/schemas/RingRunTaskV23'
        - $ref: '#/components/schemas/RingRunTaskV24'
    RingRunTaskV21:
      type: object
      required:
        - source_info
        - ref_file_urls
        - src_file_url
        - object_infos
      properties:
        source_info:
          $ref: '#/components/schemas/SourceInfo'
        ref_file_urls:
          type: array
          items:
            type: string
          description: >-
            Url of the reference file to run task. The url should be publicly
            accessible.
          example:
            - https://example.com/vto_sku.jpg
        refmsk_file_urls:
          type: array
          items:
            type: string
          nullable: true
          default: null
          description: >-
            Url of the reference mask file to run task. The url should be
            publicly accessible.
          example:
            - https://example.com/vto_sku_mask.jpg
        src_file_url:
          type: string
          description: Url of the file to run task. The url should be publicly accessible.
          example: https://example.com/selfie.jpg
        srcmsk_file_url:
          type: string
          nullable: true
          default: null
          description: >-
            Url of the source mask file to run task. The url should be publicly
            accessible.
          example: https://example.com/src_mask.jpg
        object_infos:
          type: array
          items:
            $ref: '#/components/schemas/ObjectInfo'
    RingRunTaskV22:
      type: object
      required:
        - source_info
        - ref_file_ids
        - src_file_url
        - object_infos
      properties:
        source_info:
          $ref: '#/components/schemas/SourceInfo'
        ref_file_ids:
          type: array
          items:
            type: string
          description: >-
            ID of the reference file file to run task. File ID from upload file
            API.
          example:
            - pfNK5PuRe0MrwLHcGA3DOmB1ahwfXTbYHjv+KoBIxbE=
        refmsk_file_ids:
          type: array
          items:
            type: string
          nullable: true
          default: null
          description: >-
            ID of the reference mask file file to run task. File ID from upload
            file API.
          example:
            - pfNK5PuRe0MrwLHcGA3DOmB1ahwfXTbYHjv+KoBIxbE=
        src_file_url:
          type: string
          description: Url of the file to run task. The url should be publicly accessible.
          example: https://example.com/selfie.jpg
        srcmsk_file_url:
          type: string
          nullable: true
          default: null
          description: >-
            Url of the source mask file to run task. The url should be publicly
            accessible.
          example: https://example.com/src_mask.jpg
        object_infos:
          type: array
          items:
            $ref: '#/components/schemas/ObjectInfo'
    RingRunTaskV23:
      type: object
      required:
        - source_info
        - ref_file_urls
        - src_file_id
        - object_infos
      properties:
        source_info:
          $ref: '#/components/schemas/SourceInfo'
        ref_file_urls:
          type: array
          items:
            type: string
          description: >-
            Url of the reference file to run task. The url should be publicly
            accessible.
          example:
            - https://example.com/vto_sku.jpg
        refmsk_file_urls:
          type: array
          items:
            type: string
          nullable: true
          default: null
          description: >-
            Url of the reference mask file to run task. The url should be
            publicly accessible.
          example:
            - https://example.com/vto_sku_mask.jpg
        src_file_id:
          type: string
          description: ID of file to run task. File ID from upload file API.
          example: pfNK5PuRe0MrwLHcGA3DOmB1ahwfXTbYHjv+KoBIxbE=
        srcmsk_file_id:
          type: string
          nullable: true
          default: null
          description: >-
            ID of the source mask file to run task. File ID from upload file
            API.
          example: pfNK5PuRe0MrwLHcGA3DOmB1ahwfXTbYHjv+KoBIxbE=
        object_infos:
          type: array
          items:
            $ref: '#/components/schemas/ObjectInfo'
    RingRunTaskV24:
      type: object
      required:
        - source_info
        - ref_file_ids
        - src_file_id
        - object_infos
      properties:
        source_info:
          $ref: '#/components/schemas/SourceInfo'
        ref_file_ids:
          type: array
          items:
            type: string
          description: >-
            ID of the reference file file to run task. File ID from upload file
            API.
          example:
            - pfNK5PuRe0MrwLHcGA3DOmB1ahwfXTbYHjv+KoBIxbE=
        refmsk_file_ids:
          type: array
          items:
            type: string
          nullable: true
          default: null
          description: >-
            ID of the reference mask file file to run task. File ID from upload
            file API.
          example:
            - pfNK5PuRe0MrwLHcGA3DOmB1ahwfXTbYHjv+KoBIxbE=
        src_file_id:
          type: string
          description: ID of file to run task. File ID from upload file API.
          example: pfNK5PuRe0MrwLHcGA3DOmB1ahwfXTbYHjv+KoBIxbE=
        srcmsk_file_id:
          type: string
          nullable: true
          default: null
          description: >-
            ID of the source mask file to run task. File ID from upload file
            API.
          example: pfNK5PuRe0MrwLHcGA3DOmB1ahwfXTbYHjv+KoBIxbE=
        object_infos:
          type: array
          items:
            $ref: '#/components/schemas/ObjectInfo'
    SourceInfo:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: The source url or File ID.
          example: https://example.com/selfie.jpg
        mask_name:
          type: string
          nullable: true
          default: null
          description: The source mask url or File ID.
          example: https://example.com/src_mask.jpg
    ObjectInfo:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: >-
            The reference url or File ID. Indicate which reference product image
            should be matched.
          example: https://example.com/vto_sku.jpg
        mask_name:
          type: string
          nullable: true
          default: null
          description: >-
            The reference mask url or File ID. Indicate which reference product
            image should be matched.
          example: https://example.com/vto_sku_mask.jpg
        parameter:
          $ref: '#/components/schemas/RingParameter'
    RingParameter:
      type: object
      properties:
        ring_ambient_light_intensity:
          type: number
          minimum: 0
          maximum: 1
          nullable: true
          default: 1
          description: Ambient light adjustment intensity for the ring.
          example: 1
        ring_anchor_point:
          type: array
          items:
            type: array
            items:
              type: integer
            minItems: 2
            maxItems: 2
          minItems: 2
          maxItems: 2
          nullable: true
          default: null
          description: >-
            The anchor point of the ring image, marking the 2 farthest points
            along the inner edge of the ring. Type 2x2 list of integers. Range 2
            (x, y) pixel coordinates. Default null (use engine default)
          example: null
        ring_need_remove_background:
          type: boolean
          nullable: true
          default: true
          description: Whether the ring image needs background removal.
          example: true
        ring_shadow_intensity:
          type: number
          minimum: 0
          maximum: 1
          nullable: true
          default: 0.15
          description: Shadow intensity applied to the ring (higher = darker shadow).
          example: 0.15
        ring_wearing_finger:
          type: integer
          enum:
            - 0
            - 1
            - 2
            - 3
            - 4
          nullable: true
          default: null
          description: >-
            Defines on which finger the ring is worn. Default null (use engine
            default). Range 0 to 4 [thumb to pinky]
          example: null
        ring_wearing_location:
          type: number
          minimum: 0
          maximum: 1
          nullable: true
          default: null
          description: >-
            Defines the placement of the ring on the selected finger in the user
            photo. Range 0.0 to 1.0 (0 = base of the finger, 1 = first knuckle)
          example: null
