Create an Avatar Image with Open API

This page explains how to create an Avatar Image through Open API.

Avatar Image is an image created in Render-it using ZEPETO ID and Pose ID. Avatar can be created and managed in the ZEPETO app, and a list of available poses can be found on the Gallery. Avatar Images can be used on social media, profile pictures, wallpapers, etc.

3 things are required to create an Avatar Image:

How to create an Avatar Image

You can create an API Key by referring to Create an API Key. Pose ID and ZEPETO ID can be obtained by referring to the following explanation. If these 3 things are ready, you need an environment to call REST API. You can simply create and download an Avatar Image using cURL or HTTP Client.

Prepare Pose ID

A pose is an essential element for creating an Avatar Image, and includes the avatar's posture, angle, and background. You can search for the desired pose ID in the Gallery, and you can also check information such as image ratio, tags, and duration. Pose is divided into image type and animated image type, and various and unique poses are continuously updated.

In Render-it, only the poses provided in the Gallery can be used, and if you have any questions, please contact the support team ([email protected])!

Prepare ZEPETO ID

ZEPETO ID is the ID of the avatar created in the ZEPETO. The avatar's appearance and clothing can be customized in the ZEPETO, and the avatar is imported to the ZEPETO Render-it using the ZEPETO ID. Available ZEPETO IDs can be found on the Render-it Open API page. Please refer to Connect ZEPETO account for details.

⚠️

Warning: Only your connected ZEPETO ID and IDs of people who have allowed you to take pictures with them can be used.

Choose image quality

ZEPETO Render-it provides various image quality options, and you must enter the matching quality code when creating an Avatar Image. Image quality is classified according to the Avatar Image width, and the height is automatically set according to the ratio defined in the selected pose. Please refer to this page for quality code and pricing policy. If you don't see the image quality you want, please contact our support team ([email protected]).

Choose REST API

Avatar Image can be created through four methods. Depending on the content and requirements you want, you can select an appropriate method and each method has the following characteristics.

Single Image: Creates a single static Avatar Image. This is the most universal method and is used when you want to use only one pose. Both image pose and animated image pose can be used.
Multi Images: Create multiple static Avatar Images. This is effective when creating Avatar Images using the same ZEPETO ID and multiple pose IDs. Both image pose and animated image pose can be used.
Animated Image: Creates a single dynamic Avatar Image. It is an animation type image file (*.APNG) and the playback speed (FPS) can be adjusted. Only animated image poses are available.
Animated Image by frames: Creates dynamic Avatar Images by frames. The number of images created also changes according to the playback speed (FPS). Only animated image poses are available.

Call API with Sandbox!

Render-it provides a simple tool for users to try out. Go to the Sandbox page in Open API and create your own Avatar Images easily and simply. You can see the results of your chosen pose and avatar, and a code sample is provided.

⚠️

You will be charged for each API call so please be aware.

Single Image method

Creates a single static Avatar Image. Both image pose and animated image pose can be used.

URL

POST https://api.render-it.m2s.team/services/openApi/photos/{POSE_ID}?quality={QUALITY_CODE}

Header parameters

Key	Description	Example
`authorization`	Enter the API Key token created in ZEPETO Render-it. Bearer authentication is used.	`Bearer {API_KEY_TOKEN}`
`content-type`	Specifies the format for HTTP Body. It only accepts application/json.	`application/json`

Query parameters

Key	Description	Required	Default Value	ETC
`quality`	Code to determine Avatar Image quality.	Yes		Enum [W160, W240, W320, W480, W640, W960, W1280, W1600, W1920, W2560, W3200, W3840]
`redirect`	If true, redirects to the created Avatar Image URL. If false, returns the Avatar Image URL.	No	true

Body parameters

Key	Description	Limitations
`targets[i].zepetoId`	ZEPETO ID to be used when creating Avatar Image. Only your connected ZEPETO ID and IDs of people who have allowed you to take pictures with them can be used.	Minimum of 1, maximum of 8

Example

curl -i -X POST \
   -H "Authorization:Bearer {API_KEY_TOKEN}" \
   -H "Content-Type:application/json" \
   -d \
'{
  "targets": [
    {
      "zepetoId": "{ZEPETO_ID}"
    }]
}' \
 'https://api.render-it.m2s.team/services/openApi/photos/{POSE_ID}?quality=W640'

Multi Images method

Create multiple static Avatar Images. Both image pose and animated image pose can be used.

URL

POST https://api.render-it.m2s.team/services/openApi/photos

Header parameters

Key	Description	Example
`authorization`	Enter the API Key token created in ZEPETO Render-it. Bearer authentication is used.	`Bearer {API_KEY_TOKEN}`
`content-type`	Specifies the format for HTTP Body. It only accepts application/json.	`application/json`

Query parameters

Key	Description	Required	Default Value	ETC
`quality`	Code to determine Avatar Image quality.	Yes		Enum [W160, W240, W320, W480, W640, W960, W1280, W1600, W1920, W2560, W3200, W3840]

Body parameters

Key	Description	Limitations
`poseIds`	List of pose IDs to use for creating Avatar Image	Minimum of 1, maximum of 10
`targets[i].zepetoId`	ZEPETO ID to be used when creating Avatar Image. Only your connected ZEPETO ID and IDs of people who have allowed you to take pictures with them can be used.	Minimum of 1, maximum of 8

Example

curl -i -X POST \
   -H "Authorization:Bearer {API_KEY_TOKEN}" \
   -H "Content-Type:application/json" \
   -d \
'{
  "poseIds": [
    "{POSE_ID1}",
    "{POSE_ID2}"],
  "targets": [
    {
      "zepetoId": "{ZEPETO_ID}"
    }]
}' \
 'https://api.render-it.m2s.team/services/openApi/photos?quality=W640'

Animated Image method

Creates a single dynamic Avatar Image. Only animated image poses are available.

URL

POST https://api.render-it.m2s.team/services/openApi/video/{POSE_ID}

Header parameters

Key	Description	Example
`authorization`	Enter the API Key token created in ZEPETO Render-it. Bearer authentication is used.	`Bearer {API_KEY_TOKEN}`
`content-type`	Specifies the format for HTTP Body. It only accepts application/json.	`application/json`

Query parameters

Key	Description	Required	Default Value	ETC
`quality`	Code to determine Avatar Image quality.	Yes		Enum [W160, W240, W320, W480, W640, W960, W1280, W1600, W1920, W2560, W3200, W3840]
`redirect`	If true, redirects to the created Avatar Image URL. If false, returns the Avatar Image URL.	No	true

Body parameters

Key	Description	Limitations
`fps`	Frame rate per second (fps) of the image that affects the speed of image playtime. The smaller the value, the longer the playback time.	Minimum of 1, maximum of 15
`targets[i].zepetoId`	ZEPETO ID to be used when creating Avatar Image. Only your connected ZEPETO ID and IDs of people who have allowed you to take pictures with them can be used.	Minimum of 1, maximum of 8

Example

curl -i -X POST \
   -H "Authorization:Bearer {API_KEY_TOKEN}" \
   -H "Content-Type:application/json" \
   -d \
'{
  "fps": 10,
  "targets": [
    {
      "zepetoId": "{ZEPETO_ID}"
    }]
}' \
 'https://api.render-it.m2s.team/services/openApi/video/{POSE_ID}?quality=W640'

Animated Image by frames method

Creates dynamic Avatar Images by frames. Only animated image poses are available.

URL

POST https://api.render-it.m2s.team/services/openApi/video/{POSE_ID}/frames

Header parameters

Key	Description	Example
`authorization`	Enter the API Key token created in ZEPETO Render-it. Bearer authentication is used.	`Bearer {API_KEY_TOKEN}`
`content-type`	Specifies the format for HTTP Body. It only accepts application/json.	`application/json`

Query parameters

Key	Description	Required	Default Value	ETC
`quality`	Code to determine Avatar Image quality.	Yes		Enum [W160, W240, W320, W480, W640, W960, W1280, W1600, W1920, W2560, W3200, W3840]

Body parameters

Key	Description	Limitations
`fps`	Frame rate per second (fps) of the image that affects the speed of image playtime. The smaller the value, the longer the playback time.	Minimum of 1, maximum of 15
`targets[i].zepetoId`	ZEPETO ID to be used when creating Avatar Image. Only your connected ZEPETO ID and IDs of people who have allowed you to take pictures with them can be used.	Minimum of 1, maximum of 8

Example

curl -i -X POST \
   -H "Authorization:Bearer {API_KEY_TOKEN}" \
   -H "Content-Type:application/json" \
   -d \
'{
  "fps": 10,
  "targets": [
    {
      "zepetoId": "{ZEPETO_ID}"
    }]
}' \
 'https://api.render-it.m2s.team/services/openApi/video/{POSE_ID}/frames?quality=W640'

Errors

When creating Avatar Image, errors may occur in various situations. The user may have entered incorrect data, or it may be an ZEPETO Render-it service failure. Please refer to the table below for simple information and solutions.

Error code	Description	Solution
`400`	Contains unavailable parameters	Please check if the HTTP request does not deviate from the specifications defined in the document.
`401`	Not a valid API Key Token	Please check if there is a typo in the API Key Token and whether the values match.
`403`	Blocked by IP or Referrer	Please check if you are blocked due to Security Group.
`404`	Not a valid Pose ID or ZEPETO ID	Please check if the entered Pose ID and ZEPETO ID are correct.
`408`	Failures due to network outages or delays	Please contact support team.
`415`	Invalid Content-Type header	Please check if the Content-Type of the Request header is application/json.
`429`	Exceeded allowed TPS	Please check if your TPS is over. If you need to increase the TPS further, please contact our support team.
`500`	ZEPETO Render-it service failure	Please contact support team.

ETC

Format change: Avatar Image is provided in PNG format. Other formats are not supported by ZEPETO Render-it.
Image processing: Render-it does not support image processing. If you need to crop, resize, or watermark an image, you'll have to do it yourself.
Quality of Animated Image: In the case of Animated Image, the higher the fps, the higher quality Avatar Image is created. However, be aware that the charge differs depending on the quality.
Synchronization with ZEPETO Avatar: Even if the avatar's appearance or clothing is changed in the ZEPETO app, it may not be applied immediately in ZEPETO Render-it. Synchronization may take up to 60 seconds.
Download validity period: The created Avatar Image can only be downloaded for 24 hours. Save and use separately if necessary.

Connect ZEPETO account Create an API Key

Documentation

Documentation

Create an Avatar Image with Open API

How to create an Avatar Image

Prepare Pose ID

Prepare ZEPETO ID

Choose image quality

Choose REST API

Call API with Sandbox!

Single Image method

URL

Header parameters

Query parameters

Body parameters

Example

Multi Images method

URL

Header parameters

Query parameters

Body parameters

Example

Animated Image method

URL

Header parameters

Query parameters

Body parameters

Example

Animated Image by frames method

URL

Header parameters

Query parameters

Body parameters

Example

Errors

ETC