Image Operation

💡 API calls require authentication. Refer to Interface Authentication for authentication

POST {apiPrefix}/image/transform

Submit conversion task

• If task addition fails, the failure reason is returned synchronously
• If task addition succeeds, the task ID is returned synchronously. Third parties can get task status by calling status query request or configuring task callback notifications.

Request Body

Content-Type is application/json

Parameter Name	Type	Description	Required
fileUrl	string	File download address	Yes
filename	string	Filename with extension	Yes
tokenType	string	Third-party token type, value is cookie or header	No
tokenValue	string	Third-party token value, passed back when zOffice downloads files or callback notifications	No
callback	string	Callback address. zOffice will callback to notify status after conversion task completion	Yes
imageOptions	object	Image operation related options	Yes
tiledWatermark	object	Tiled watermark When tiled watermark is an image, the rotation angle parameter value options are (90,180,270), pass according to the given rotation angle	No
textWatermark	object	Text watermark	No
msPicWatermark	object	Image watermark The rotation angle parameter value options are (90,180,270), pass according to the given rotation angle	No

• Types currently support JPG, JPEG, PNG, BMP, image size maximum cannot exceed 50m

• For the above common parameters (except imageOptions, tiledWatermark, textWatermark, msPicWatermark), see Common Field Description in this document

• The three watermark parameters will only use one watermark, priority (tiled watermark > text watermark > image watermark)

• tiledWatermark parameter description see Type/TiledWatermark in this document

• textWatermark parameter description see Type/TextWatermark in this document

• msPicWatermark parameter description see Type/MsPicWatermark in this document

• imageOptions parameter description

  Parameter Name	Type	Description	Required
  scale	number	Given percentage (0-200) (default 0 no scaling, 200 means enlarge to 200% of original, less than 100 means scale down by percentage, greater than 100 means scale up by percentage), both height and width scale by specified percentage Priority (scale > width > height)	No
  width	number	Given width (0-2000) (px), scale proportionally by width Priority (scale > width > height)	No
  height	number	Given height (0-2000) (px), scale proportionally by height Priority (scale > width > height)	No
  rotate	number	Image rotation angle (90,180,270) rotate image by given rotation angle	No
  quality	number	Image quality (0-100) compress image quality, can only modify JPG/JPEG image quality	No
  horizontalFlip	boolean	Horizontal mirror flip	No
  verticalFlip	boolean	Vertical mirror flip	No

Request Example

1. Scale down to 50% of original, and rotate 90 degrees

   {
       "fileUrl": "Source file download address",
       "filename": "Source filename",
       "tokenType":"cookie",
       "tokenValue":"zdocs_access_token={{zdocs_access_token}}",
       "callback": "Callback address",
       "imageOptions":{ 
           "scale": 50,   
           "rotate": 90
       }
   }

2. Scale proportionally by width 500px, and horizontal mirror flip, then add tiled text watermark

   {
       "fileUrl": "Source file download address",
       "filename": "Source filename",
       "tokenType":"cookie",
       "tokenValue":"zdocs_access_token={{zdocs_access_token}}",
       "callback": "Callback address",
       "imageOptions":{ 
           "width": 500,   
           "horizontalFlip": true
       },
       "tiledWatermark": { 
           "line1": "watermark for test", 
           "line2": "", 
           "line3": "", 
           "line4": "", 
           "withDate": true, 
           "fontcolor": "#cecece", 
           "transparent": 70, 
           "rotation": 315, 
           "fontsize": "30", 
           "font": "SimHei", 
           "isFontBold": true,
           "isFontItalic": true,
           "spacing": 50 
       }
   }

3. All parameters display. The following watermark parameters are all displayed, in practice just choose one

   {
       "fileUrl": "Source file download address",
       "filename": "Source filename",
       "tokenType":"cookie",
       "tokenValue":"zdocs_access_token={{zdocs_access_token}}",
       "callback": "Callback address",
       "imageOptions":{
           "scale":100, 
           "width":0,  
           "height":0,
           "rotate":0, 
           "quality":0,  
           "horizontalFlip":false, 
           "verticalFlip":false,  
       },
       "tiledWatermark": { 
           "line1": "watermark for test", 
           "line2": "", 
           "line3": "", 
           "line4": "", 
           "picUrl": "Image link", 
           "picName": "Image name with extension", 
           "picScale": 50,
           "withDate": true, 
           "fontcolor": "#cecece", 
           "transparent": 70, 
           "rotation": 315, 
           "fontsize": "30", 
           "font": "SimHei", 
           "isFontBold": true,
           "isFontItalic": true,
           "spacing": 50 
       },
       "textWatermark": {
           "text": "watermark for test",
           "fontcolor": "#DC134C",
           "fontsize": "40",
           "font": "SimHei",
           "isFontBold": true,
           "isFontItalic": true,
           "rotation": 90,
           "transparent": 70,
           "position": "CENTER"
       },
       "msPicWatermark": {
           "picUrl": "Image link",
           "picName": "Image name with extension",
           "picScale": 50,
           "rotation": 90,
           "transparent": 70,
           "position": "CENTER"
       }
   }

Normal Response:

{
    "taskId": "6f6598c8-c87e-420b-b6c4-6f1b187201dc",
    "code": "Ok",
    "detail": {
        "taskStatus": "IN_QUEUE"
    }
}

Error Response:

{
    "taskId": "695fbf6e-90d2-42ba-83d5-00e81e5e366e",
    "code": "TaskQueueCongestion",
    "detail": {
        "taskStatus": "FAIL"
    }
}