openapi: 3.0.0
info:
  title: AI Image Generator
  description: >
    # Overview

    Discover the power of AI with our innovative text-to-image generator!
    Transform your ideas into stunning visuals instantly, experiment with
    prompts, explore unique styles like cartoons, oil paintings, or sketches,
    and let your creativity shine through. Whether you're an artist, designer,
    or creative soul, our tool offers endless possibilities to bring your vision
    to life. Add images as references to inspire new artistic directions while
    letting AI refine them into entirely original masterpieces.


    Want more inspirations? Please refer to
    https://yce.makeupar.com/ai-art-generator.


    Use cases:

    ![AI Image
    Generator](https://bcw-media.s3.ap-northeast-1.amazonaws.com/text_to_image_v3_video_02f161f909.jpg
    "AI Image Generator")


    ![AI Image
    Generator](https://bcw-media.s3.ap-northeast-1.amazonaws.com/text_to_image_v4_poster_092d2fbb9f.jpg
    "AI Image Generator")


    Sample output:

    ![AI Image
    Generator](https://bcw-media.s3.ap-northeast-1.amazonaws.com/text_to_image_topbanner_dt_2_e325681588.jpg
    "AI Image Generator")


    ![AI Image
    Generator](https://bcw-media.s3.ap-northeast-1.amazonaws.com/text_to_image_topbanner_dt_5_8b4fa13c6a.jpg
    "AI Image Generator")


    ## File Specs & Errors


    * Supported Formats & Dimensions


    |AI Feature|Supported Dimensions|Supported File Size|Supported Formats|

    | ---- | ---- | ---- | ---- |

    | V1.0 Text to Image | Output: 1024 pixels on the long side. | Prompt cannot
    exceed 500 characters | N/A |

    | V2.0 Text to Image | Output: The default resolution is 1664 × 928, with
    supported resolutions of 1664 × 928 (16:9), 1472 × 1104 (4:3), 1328 × 1328
    (1:1), 1104 × 1472 (3:4), and 928 × 1664 (9:16). | Prompt cannot exceed 800
    characters | N/A |

    | V2.0 Image to Image | Input: Both the width and height must fall within
    the range of 384 to 3072 pixels. <br>Output: Customizable width and height
    range from 512 to 2,048 pixels, while the default configuration maintains a
    total pixel count of approximately 1,024 × 1,024 with an aspect ratio based
    on the input image. | <10MB<br> Prompt cannot exceed 800 characters | JPG,
    JPEG, PNG, BMP, TIFF, WEBP, and GIF. <br>For animated GIFs, only the first
    frame is processed. |


    * Error Codes


    | Error Code | Description |

    | ---------- | ----------- |

    | exceed_max_filesize | The uploaded file size exceeds the maximum allowed
    limit. |

    | invalid_parameter | One or more parameters are missing or invalid |

    | error_download_image | Failed to download the source image. |

    | error_decode_image | Failed to decode or parse the source image. |

    | error_nsfw_content_detected | Not Safe For Work content was detected in
    the source image. |

    | error_unsupport_ratio | The aspect ratio of the input image is not
    supported. |

    | unknown_internal_error | An unspecified internal error occurred. |


    ---


    ## Unit Consumption


    | AI Feature | Unit Consumed |

    |---|---|

    | AI Image Generator V1.0 | 2 |

    | AI Image Generator V2.0 | 1 |


    ---
  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/perfectbeauty/youcam/privacy-policy-api
servers:
  - url: https://yce-api-01.makeupar.com
tags:
  - name: V2.0
    description: >-
      With the AI Image Generator V2.0 API, you can instantly generate
      high-quality images from text prompts or existing images with improved
      visual, detail, and consistency.
  - name: V1.0
    description: >-
      AI Image Generator API allows you to generate images from text prompts
      using predefined templates.
paths:
  /s2s/v2.0/task/template/text-to-image:
    get:
      summary: List predefined templates.
      tags:
        - V1.0
      security:
        - BearerAuthenticationV2: []
      parameters:
        - name: page_size
          in: query
          schema:
            type: integer
            example: 20
          description: >-
            Number of results to return in this page. Valid value should be
            between 1 and 20. 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':
          $ref: '#/components/responses/TemplateResponse'
        '400':
          $ref: '#/components/responses/InvalidParameters'
        '401':
          $ref: '#/components/responses/InvalidApiKey'
  /s2s/v2.0/task/text-to-image:
    post:
      summary: Run an AI Image Generator task.
      description: >
        AI tasks are asynchronous. Prefer webhook-based completion handling when
        the feature supports webhooks. Configure your webhook endpoint, verify
        webhook signatures, and use the received `task_id` to query the task
        result after a `success` or `error` notification. See the [webhook
        integration guide](/develop/webhook.md) for setup and verification
        details.


        If webhooks are not supported for the feature, or if your integration
        cannot use webhooks, implement polling. After starting an AI task, keep
        polling the task status endpoint at the given `polling_interval` until
        the task status is either `success` or `error`.


        Do not stop polling a running task for longer than the allowed polling
        window. If the task is not polled in time, the task may expire; a later
        status check can return `InvalidTaskId` even if processing finished, and
        the consumed units may still be charged.
      tags:
        - V1.0
      security:
        - BearerAuthenticationV2: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - type: object
                  required:
                    - prompt
                    - template_id
                  properties:
                    prompt:
                      type: string
                      description: Prompt to generate image
                      example: A little cat
                    negative_prompt:
                      type: string
                      description: Prompt what DO NOT want
                      example: dog
                    template_id:
                      type: string
                      description: >-
                        ID of the template. List predefined templates first, and
                        use the id of a template.
                      example: good_template_001
                    steps:
                      type: integer
                      description: >-
                        Steps affect image quality and time of processing. <br>
                        Recommended Step Counts <br> 10-15 Steps: Ideal for
                        quick prompt testing and making broad tweaks. <br> 15–20
                        Steps: The community sweet spot. Most models hit their
                        ideal quality-to-time ratio in this range. <br> 20–30
                        Steps: Best for generating highly detailed subjects,
                        like faces, fur, or architectural elements.
                      example: 10
                    cfg_scale:
                      type: number
                      description: >-
                        The CFG (Classifier-Free Guidance) scale is a
                        mathematical setting that dictates how strictly an AI
                        model adheres to your text prompt. <br> Low CFG (1 – 4):
                        The AI has high creative freedom. It loosely interprets
                        your prompt, which can lead to abstract, painterly
                        results, or images that wander off-topic entirely. <br>
                        Medium CFG (5 – 10): The ideal sweet spot. The generator
                        follows your text closely while still maintaining
                        natural, high-quality visuals. <br> High CFG (11+): The
                        AI clings to every single word in your prompt. While
                        details become sharper and more literal, pushing the
                        scale too high often results in over-saturated colors,
                        noise, and unnatural artifacts.
                      example: 4
                    seed:
                      type: array
                      description: >-
                        Each image is generated with a unique seed. Using same
                        seed to recreate the same image. Only accept 1 seed.
                      items:
                        type: integer
                        example: 3843718472198472
                    width_ratio:
                      type: integer
                      description: The width of ratio of image.
                      example: 3
                    height_ratio:
                      type: integer
                      description: The height of ratio of image.
                      example: 4
      responses:
        '200':
          description: Successful execution of the task
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicRunTaskResponseV2'
        '400':
          description: Failed execution of task
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/RunError'
        '401':
          $ref: '#/components/responses/InvalidApiKey'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /s2s/v2.0/task/text-to-image/{task_id}:
    get:
      summary: Check a AI Image Generator task status.
      tags:
        - V1.0
      security:
        - BearerAuthenticationV2: []
      parameters:
        - name: task_id
          in: path
          required: true
          schema:
            type: string
            example: grH0CvsgXuAIHLUzD0V1Ol34hoet3R1tvdbtiVHrDb6_UqCLKIejAIajwxrhOAfe
          description: ID of task to check
      responses:
        '200':
          description: Successful check of the task status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskStatusResponseV2'
        '400':
          $ref: '#/components/responses/InvalidTaskId'
        '401':
          $ref: '#/components/responses/InvalidApiKey'
        '500':
          $ref: '#/components/responses/TaskTimeout'
  /s2s/v2.0/task/text-to-image/youcam:
    post:
      summary: Run an AI Image Generator task V2 for text to image.
      description: >
        AI tasks are asynchronous. Prefer webhook-based completion handling when
        the feature supports webhooks. Configure your webhook endpoint, verify
        webhook signatures, and use the received `task_id` to query the task
        result after a `success` or `error` notification. See the [webhook
        integration guide](/develop/webhook.md) for setup and verification
        details.


        If webhooks are not supported for the feature, or if your integration
        cannot use webhooks, implement polling. After starting an AI task, keep
        polling the task status endpoint at the given `polling_interval` until
        the task status is either `success` or `error`.


        Do not stop polling a running task for longer than the allowed polling
        window. If the task is not polled in time, the task may expire; a later
        status check can return `InvalidTaskId` even if processing finished, and
        the consumed units may still be charged.
      tags:
        - V2.0
      security:
        - BearerAuthenticationV2: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - type: object
                  required:
                    - model
                    - prompt
                  properties:
                    model:
                      type: string
                      description: Model name.
                      enum:
                        - youcam-image-v2
                    prompt:
                      type: string
                      minLength: 1
                      maxLength: 800
                      description: >-
                        A positive prompt describing the image content, style,
                        and composition you want. <br>Supports Chinese and
                        English. Maximum length is 800 characters. Each Chinese
                        character, letter, digit, or symbol counts as one
                        character.
                      example: >-
                        A sitting orange cat with a joyful expression, lively
                        and adorable, highly realistic.
                    negative_prompt:
                      type: string
                      minLength: 1
                      maxLength: 500
                      description: >-
                        A negative prompt describing what you do not want in the
                        image. <br>Supports Chinese and English. Maximum length
                        is 500 characters.
                      example: >-
                        Low resolution, low quality, distorted limbs, malformed
                        fingers, oversaturated colors, wax-like appearance, no
                        facial details, overly smooth surfaces, AI-generated
                        look. Chaotic composition. Blurry or distorted text.
                    size:
                      type: string
                      description: >-
                        Output image resolution, formatted as width\*height.
                        <br> Supported resolutions and their aspect ratios:
                        <br>- 1664\*928 (default): 16:9 <br>- 1472\*1104: 4:3
                        <br>- 1328\*1328: 1:1 <br>- 1104\*1472: 3:4 <br>-
                        928\*1664: 9:16
                      enum:
                        - 1664*928
                        - 1472*1104
                        - 1328*1328
                        - 1104*1472
                        - 928*1664
                      example: 1664*928
                      default: 1664*928
                    prompt_extend:
                      type: boolean
                      description: >-
                        Enable smart prompt rewriting. The model optimizes the
                        positive prompt. Does not affect the negative prompt.
                      example: true
                      default: true
                      enum:
                        - true
                        - false
                      x-enumDescriptions:
                        'true': >-
                          Enables rewriting. Use this for more diverse image
                          content; the model adds details.
                        'false': >-
                          Disables rewriting. Use this for tighter control over
                          image details.
      responses:
        '200':
          description: Successful execution of the task
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicRunTaskResponseV2'
        '400':
          description: Failed execution of task
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/RunError'
        '401':
          $ref: '#/components/responses/InvalidApiKey'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /s2s/v2.0/task/text-to-image/youcam/{task_id}:
    get:
      summary: Check the status of a AI Image Generator task V2 for text to image.
      tags:
        - V2.0
      security:
        - BearerAuthenticationV2: []
      parameters:
        - name: task_id
          in: path
          required: true
          schema:
            type: string
            example: grH0CvsgXuAIHLUzD0V1Ol34hoet3R1tvdbtiVHrDb6_UqCLKIejAIajwxrhOAfe
          description: ID of task to check
      responses:
        '200':
          description: Successful check of the task status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskStatusResponseV2'
        '400':
          $ref: '#/components/responses/InvalidTaskId'
        '401':
          $ref: '#/components/responses/InvalidApiKey'
        '500':
          $ref: '#/components/responses/TaskTimeout'
  /s2s/v2.0/task/image-to-image/youcam:
    post:
      summary: Run an AI Image Generator task V2 for image to image.
      description: >
        AI tasks are asynchronous. Prefer webhook-based completion handling when
        the feature supports webhooks. Configure your webhook endpoint, verify
        webhook signatures, and use the received `task_id` to query the task
        result after a `success` or `error` notification. See the [webhook
        integration guide](/develop/webhook.md) for setup and verification
        details.


        If webhooks are not supported for the feature, or if your integration
        cannot use webhooks, implement polling. After starting an AI task, keep
        polling the task status endpoint at the given `polling_interval` until
        the task status is either `success` or `error`.


        Do not stop polling a running task for longer than the allowed polling
        window. If the task is not polled in time, the task may expire; a later
        status check can return `InvalidTaskId` even if processing finished, and
        the consumed units may still be charged.
      tags:
        - V2.0
      security:
        - BearerAuthenticationV2: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - anyOf:
                    - title: Run task with src_file_urls
                      type: object
                      required:
                        - src_file_urls
                      properties:
                        src_file_urls:
                          type: array
                          minItems: 1
                          maxItems: 3
                          description: >-
                            The file URLs from upload file API. Should provide
                            either 'src_file_urls' or 'src_file_ids'.
                          example:
                            - https://example.com/selfie.jpg
                            - https://example.com/selfie.jpg
                            - https://example.com/selfie.jpg
                          items:
                            type: string
                    - title: Run task with 3 angle src file IDs
                      type: object
                      required:
                        - src_file_ids
                      properties:
                        src_file_ids:
                          type: array
                          minItems: 1
                          maxItems: 3
                          description: >-
                            The file IDs from upload file API. Should provide
                            either 'src_file_urls' or 'src_file_ids'.
                          example:
                            - pfNK5PuRe0MrwLHcGA3DOmB1ahwfXTbYHjv+KoBIxbE=
                            - pkVzplMv8Y1QPgHbqtKfyJmg+xJDUbTP16YijZ3qARNf
                            - B5LNohvvO+7d/78Ymuhp6vMiSooN/5DX9oVuupzkKctf
                          items:
                            type: string
                - type: object
                  required:
                    - model
                    - prompt
                  properties:
                    model:
                      type: string
                      description: Model name.
                      enum:
                        - youcam-image-v2
                    prompt:
                      type: string
                      minLength: 1
                      maxLength: 800
                      description: >-
                        The image editing instruction (positive prompt) that
                        describes the elements and visual features you want in
                        the generated image. <br>This parameter supports Chinese
                        and English with a maximum length of 800 characters.
                        Each Chinese character or English letter counts as one
                        character.
                      example: >-
                        Make the girl from Image 1 wear the black dress from
                        Image 2 and sit in the pose from Image 3. Keep her
                        clothing, hairstyle, and expression unchanged, and
                        ensure the action is natural and smooth.
                    negative_prompt:
                      type: string
                      minLength: 1
                      maxLength: 500
                      description: >-
                        The negative prompt, describing content you do not want
                        in the generated image. <br>This parameter supports
                        Chinese and English with a maximum length of 500
                        characters. Each Chinese character or English letter
                        counts as one character.
                      example: >-
                        low resolution, error, worst quality, low quality,
                        disfigured, extra fingers, bad proportions.
                    size:
                      type: string
                      description: >-
                        Specifies the resolution of the output image in the
                        width*height format, such as "1024\*1536". <br>- The
                        width and height must each be in the range of [512,
                        2048] pixels. <br>- By default, the total number of
                        pixels is approximately 1024\*1024, with an aspect ratio
                        similar to the input image (or the last image in a
                        multi-image request). <br>When you specify the size
                        parameter, the system uses the width and height
                        specified by size as the target and adjusts the width
                        and height of the actual output image to the nearest
                        multiple of 16. For example, if you specify 1033\*1032,
                        the output image dimensions are 1040\*1024.
                        <br>Recommended resolutions for common aspect ratios:
                        <br>- 1:1: 1024\*1024, 1536\*1536 <br>- 2:3: 768\*1152,
                        1024\*1536 <br>- 3:2: 1152\*768, 1536\*1024 <br>- 3:4:
                        960\*1280, 1080\*1440 <br>- 4:3: 1280\*960, 1440\*1080
                        <br>- 9:16: 720\*1280, 1080\*1920 <br>- 16:9: 1280\*720,
                        1920\*1080 <br>- 21:9: 1344\*576, 2048\*872
                      example: 1024*1024
                    prompt_extend:
                      type: boolean
                      description: >-
                        Enable smart prompt rewriting. The model optimizes the
                        positive prompt. Does not affect the negative prompt.
                      example: true
                      default: true
                      enum:
                        - true
                        - false
                      x-enumDescriptions:
                        'true': >-
                          Enables rewriting. Use this for more diverse image
                          content; the model adds details.
                        'false': >-
                          Disables rewriting. Use this for tighter control over
                          image details.
      responses:
        '200':
          description: Successful execution of the task
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicRunTaskResponseV2'
        '400':
          description: Failed execution of task
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/RunError'
        '401':
          $ref: '#/components/responses/InvalidApiKey'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /s2s/v2.0/task/image-to-image/youcam/{task_id}:
    get:
      summary: Check the status of a AI Image Generator task V2 for image to image.
      tags:
        - V2.0
      security:
        - BearerAuthenticationV2: []
      parameters:
        - name: task_id
          in: path
          required: true
          schema:
            type: string
            example: grH0CvsgXuAIHLUzD0V1Ol34hoet3R1tvdbtiVHrDb6_UqCLKIejAIajwxrhOAfe
          description: ID of task to check
      responses:
        '200':
          description: Successful check of the task status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskStatusResponseV2'
        '400':
          $ref: '#/components/responses/InvalidTaskId'
        '401':
          $ref: '#/components/responses/InvalidApiKey'
        '500':
          $ref: '#/components/responses/TaskTimeout'
components:
  securitySchemes:
    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'.
  schemas:
    Template:
      type: object
      properties:
        id:
          type: string
          description: The ID of the template. Use this as \`template_id\` when run task.
          example: good_template_001
        thumb:
          type: string
          description: The thumbnail of style.
        title:
          type: string
          description: The title of the template.
        category_name:
          type: string
          description: The category name of the template.
    BasicRunTaskResponseV2:
      type: object
      properties:
        status:
          type: integer
          description: Response status
          example: 200
        data:
          type: object
          properties:
            task_id:
              type: string
              description: >-
                ID of this task. Task result is valid to query by this ID for 24
                hours.
              example: grH0CvsgXuAIHLUzD0V1Ol34hoet3R1tvdbtiVHrDb6_UqCLKIejAIajwxrhOAfe
    RunError:
      type: object
      properties:
        status:
          type: integer
          description: Response status
          example: 400
        error:
          type: string
          description: Error message
          example: The operation could not be completed
        error_code:
          type: string
          enum:
            - InvalidParameters
            - CreditInsufficiency
            - InvalidStyleGroup
            - InvalidStyle
            - BadRequest
          description: |
            Error code:
              * InvalidParameters - Invalid request parameters
              * CreditInsufficiency - Insufficient unit to run
              * BadRequest - Unexpected request parameter
              * InvalidStyleGroup - Invalid style group id
              * InvalidStyle - Invalid style id
    EngineErrorCode:
      type: string
      nullable: true
      enum:
        - error_exceed_max_image_size
        - exceed_max_filesize
        - invalid_parameter
        - error_download_image
        - error_download_mask
        - error_decode_image
        - error_decode_mask
        - error_nsfw_content_detected
        - error_no_face
        - error_pose
        - error_face_parsing
        - error_inference
        - exceed_nsfw_retry_limits
        - error_upload
        - unknown_internal_error
      description: >
        Errors:

        - \`error_exceed_max_image_size\`  - Input image size exceeds the
        maximum limit

        - \`exceed_max_filesize\` - Input file size exceeds the maximum limit

        - \`invalid_parameter\` - Invalid parameter value

        - \`error_download_image\` - Download source image error

        - \`error_download_mask\` - Download mask image error

        - \`error_decode_image\` - Decode source image error

        - \`error_decode_mask\` - Decode mask image error

        - \`error_nsfw_content_detected\` - NSFW content detected in source
        image

        - \`error_no_face\` - No face detected on source image

        - \`error_pose\` - Failed to detect pose on source image

        - \`error_face_parsing\` - Failed to do face segmentation on source
        image

        - \`error_inference\` - Inference pipeline error

        - \`exceed_nsfw_retry_limits\` - Exceed the retry limits to avoid
        generated NSFW image

        - \`error_upload\` - Upload result image error

        - \`unknown_internal_error\` - Others
    TaskStatusResponseBodySingleUrlResultsV2:
      type: object
      properties:
        url:
          type: string
          description: URL to download this result. Valid for 2 hours
          example: https://example.com/sample-result-url
    TaskStatusResponseV2:
      type: object
      properties:
        status:
          type: integer
          description: Response status
          example: 200
        data:
          type: object
          properties:
            task_status:
              type: string
              enum:
                - running
                - success
                - error
              description: Status of this task
            error:
              $ref: '#/components/schemas/EngineErrorCode'
            error_message:
              type: string
              description: Detailed description of error
            results: null
      $ref: '#/components/schemas/TaskStatusResponseBodySingleUrlResultsV2'
  responses:
    TemplateResponse:
      description: Successful retrieval of styles
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: integer
                description: Response status
                example: 200
              data:
                type: object
                properties:
                  templates:
                    type: array
                    items:
                      $ref: '#/components/schemas/Template'
                  next_token:
                    type: string
                    example: 73a3c9e69b89
                    description: Token to query next page.
    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
    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
    TooManyRequests:
      description: Too many requests
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: integer
                example: 429
                description: Response status
              error:
                type: string
                example: Too many requests
    InvalidTaskId:
      description: Invalid task ID
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: integer
                example: 400
                description: Response status
              error:
                type: string
                example: Invalid task ID
    TaskTimeout:
      description: Task execution timeout
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: integer
                example: 500
                description: Response status
              error:
                type: string
                example: Task execution timed out
