openapi: 3.0.0
info:
  title: Unit system
  version: ''
  termsOfService: https://www.makeupar.com/perfectbeauty/youcam/terms-of-service-api
  contact:
    email: YouCamOnlineEditor_API@perfectcorp.com
  license:
    name: Privacy policy
    url: https://www.makeupar.com/youcamapps/youcam/privacy-policy.html
  description: >
    Check your unit details and usage history. Please note that Units is the
    currency used for YouCam API operations; different AI features deduct
    different amounts of units. In this document, the code name used for a Unit
    is "Credit."
servers:
  - url: https://yce-api-01.makeupar.com
paths:
  /s2s/v1.0/client/credit:
    get:
      summary: Get unit info
      description: Display the available API units to two decimal places
      security:
        - BearerAuthentication: []
      responses:
        '200':
          description: Successful retrieval of unit info
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: Response status
                    example: 200
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          description: Unique identifier of this unit
                          example: 13105541279084536
                        type:
                          type: string
                          enum:
                            - ApiSubsToken
                            - ApiPaygToken
                          description: Type of this unit
                        amount:
                          deprecated: true
                          type: integer
                          description: >-
                            This paramenter is deprecated. Use amount_dec
                            instead. Current unit balance.
                          example: 10
                        amount_dec:
                          type: number
                          description: Remaining units displayed to two decimal places.
                          example: 10.04
                        expiry:
                          type: integer
                          description: Unix timestamp of the expiry of this unit (ms)
                          example: 1704789135000
        '401':
          $ref: '#/components/responses/Unauthorized'
  /s2s/v1.0/client/credit/history:
    get:
      summary: View unit history
      security:
        - BearerAuthentication: []
      parameters:
        - name: page_size
          in: query
          schema:
            type: integer
            example: 20
          description: >-
            Number of results to return in a page. Valid value should be between
            1 and 30. Default 20.
        - name: starting_token
          in: query
          schema:
            type: string
            example: 73a3c9e69b89
          description: >-
            Token for current page. Start with `null` for the first page, and
            use `next_token` from the previous response to start next page
      responses:
        '200':
          description: Successful retrieval of the unit usage history
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    example: 200
                    description: Response status
                  result:
                    type: object
                    properties:
                      next_token:
                        type: string
                        example: 73a3c9e69b89
                        description: Token to query next page.
                      history:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 38173479337460984
                              description: Unique identifier of the history
                            timestamp:
                              type: integer
                              example: 1703146067000
                              description: Unix timestamp of the history (ms)
                            action:
                              type: string
                              example: photo_enhance
                              enum:
                                - photo_enhance
                                - api_photo_enhance
                                - object_removal
                                - api_object_removal
                                - background_removal
                                - api_background_removal
                                - colorize
                                - api_colorize
                                - text_to_image
                                - api_text_to_image
                                - hair_style
                                - api_hair_style
                                - blur_background
                                - change_background
                                - wig
                                - trial_gift_text_to_image
                                - sign_up_gift
                                - subscription_credits
                                - subscriber_gift
                                - permanent_credits
                                - compensation_from_customer_service
                                - renew
                                - expire
                              description: Action of this history
                            target_id:
                              type: string
                              example: >-
                                7TWFkuE2Z9uR0NOxSmQ1rh4PJ5Zx7YJ5U9SAz51q0QHVwMP+Jb1XbjPsf7ZgUgLY
                              description: >-
                                Id of the target for this unit. For example,
                                when running AI Photo Enhance task, `target_id`
                                for this history will be `task_id` of the AI
                                Photo Enhance task. When purchasing unit, the
                                `target_id` for this history will be `order_id`
                            info:
                              type: object
                              properties:
                                credits:
                                  type: array
                                  example:
                                    - id: 24409059381740548
                                      amount: -2
                                    - id: 27297116883780870
                                      amount: 0
                                  description: Detailed information for each unit
                                  items:
                                    type: object
                                    properties:
                                      id:
                                        type: integer
                                        description: Id of the unit
                                      amount:
                                        deprecated: true
                                        type: integer
                                        description: >-
                                          This paramenter is deprecated. Use
                                          amount_dec instead. Total amount changed
                                          from this unit.
                                      amount_dec:
                                        type: number
                                        description: >-
                                          The net change in units recorded,
                                          presented to two decimal places.
                                dst_actions:
                                  type: array
                                  description: The dst_actions of skin analysis
                                  items:
                                    type: string
                                  example: '[ "hd_wrinkle", "hd_pore", "hd_texture" ]'
        '400':
          $ref: '#/components/responses/InvalidParameters'
        '401':
          $ref: '#/components/responses/InvalidAccessToken'
  /s2s/v2.0/credit/feature-cost:
    get:
      summary: Get feature cost
      description: >-
        Check the unit consumption for each API. The values are consistent with
        those listed at https://yce.perfectcorp.com/ai-api/api-pricing.
      security:
        - BearerAuthenticationV2: []
      parameters:
        - name: page_size
          in: query
          schema:
            type: integer
            example: 20
            minimum: 1
            maximum: 20
          description: >-
            Number of results to return in a page. Default 20. value range: [1 -
            20]
        - name: starting_token
          in: query
          schema:
            type: string
            example: MjA
          description: >-
            Token for current page. Start with `null` for the first page, and
            use `next_token` from the previous response to start next page
      responses:
        '200':
          description: Successful retrieval of the feature cost by sku
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    example: 200
                    description: Response status
                  result:
                    type: object
                    properties:
                      next_token:
                        type: string
                        example: MjA
                        description: >-
                          Token to query next page. `null` when there are no
                          more pages.
                      skus:
                        type: array
                        description: List of the skus
                        items:
                          type: object
                          properties:
                            description:
                              type: string
                              example: AI Skin Analysis for SD 1~4 concerns
                              description: Description of the sku
                            amount:
                              type: number
                              example: 9
                              description: Units consumed per `proc_unit`
                            unit:
                              type: string
                              enum:
                                - result_image
                                - second
                              example: result_image
                              description: Measurement unit of the cost
                            proc_unit:
                              type: integer
                              example: 1
                              description: >-
                                Number of `unit`s included in one charge of
                                `amount`
                            run_task_url:
                              type: string
                              example: >-
                                https://yce-api-01.makeupar.com/s2s/v2.0/task/skin-analysis
                              description: >-
                                Full URL of the task endpoint that consumes this
                                sku
              example:
                status: 200
                result:
                  next_token: MjA
                  skus:
                    - description: AI Skin Analysis for SD 1~4 concerns
                      amount: 9
                      unit: result_image
                      proc_unit: 1
                      run_task_url: >-
                        https://yce-api-01.makeupar.com/s2s/v2.0/task/skin-analysis
                    - description: AI Skin Analysis for SD 5~7 concerns
                      amount: 12
                      unit: result_image
                      proc_unit: 1
                      run_task_url: >-
                        https://yce-api-01.makeupar.com/s2s/v2.0/task/skin-analysis
        '400':
          $ref: '#/components/responses/InvalidParameters'
        '401':
          $ref: '#/components/responses/InvalidApiKey'
components:
  securitySchemes:
    BearerAuthentication:
      type: http
      scheme: bearer
      description: >-
        Use the `access_token` obtained from authentication and pass it in
        header: `Authorization:Bearer <access_token>`
    BearerAuthenticationV2:
      type: http
      scheme: bearer
      description: >-
        Use the standard 'Bearer authentication'. Put your 'API Key' in header:
        `Authorization:Bearer YOUR_API_KEY`. Notice that there is ' ' a space
        between 'Bearer' and the 'YOUR_API_KEY'.
  responses:
    Unauthorized:
      description: Authentication failed or user does not have necessary permissions
    InvalidParameters:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: integer
                example: 400
                description: Response status
              error:
                type: string
                example: Invalid parameter value
              error_code:
                type: string
                example: InvalidParameters
    InvalidAccessToken:
      description: Invalid access token
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: integer
                example: 401
                description: Response status
              error_code:
                type: string
                enum:
                  - InvalidAccessToken
                description: |
                  Error code:
                    * InvalidAccessToken - Access token is not given or not valid
    InvalidApiKey:
      description: Invalid or missing API key
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: integer
                example: 401
                description: Response status
              error:
                type: string
                example: Invalid API key
