Media Processing Server Documentation
General Information
The media server is available at retoucher.hz.labs.retouch4.me.
All API requests are made to /api/v1/<route>, for example:
https://retoucher.hz.labs.retouch4.me/api/v1/retoucher/getFile/s0me-very-l0ng-1d
The general retouching pipeline is as follows:
- The image processing task is submitted via
/retoucher/start
- While processing is pending, you can request the current status at
/retoucher/status/{id}
- If the process completes successfully, the result can be fetched from
/retoucher/getFile/{id}
Register Task /retoucher/start
Request Description
| Protocol | HTTP |
| Method | POST |
| contentType | multipart/form-data |
The following fields are expected in the request body:
- file - an image file in jpeg, png, or jpg format
- token - user token
- payload - JSON string describing the task
Processing
- The task is registered on the server and receives a unique ID
- User token is verified
- The task is queued for processing and returns the task ID
Successful Response
If the request is successful, the task is queued, and the server returns
a JSON object with the following fields:
- status - 200
- id - unique task ID used to request the result and processing status
- retouchQuota - remaining retouch attempts for the user for the current day
Possible Errors
If the request is missing a file, the server returns a 400 error with message="No file uploaded"
If there are issues on the server, it returns a 500 error with an error message.
If the CRM returns a 4xx error, a 4xx error code and message="Token issue" are returned.
If the server cannot communicate with the CRM or returns a 200 status, processing continues.
Retouch Status Request /retoucher/status/{id}
| Protocol | HTTP |
| Method | GET |
Request Description
GET request, id is passed in the URL.
Example request:
https://retoucher.hz.labs.retouch4.me/api/v1/retoucher/status/s0me-very-l0ng-1d
Successful Response
In case of a successful request, the server returns JSON with the following fields:
- status - 200
- state - task status
- completed - task completed successfully
- failed - an error occurred during processing
- waiting - task is waiting in queue
- active - task is being processed
- delayed - task is delayed
- progress - number between 0 and 100, indicating the progress of the task
- reason - if the state is failed, the reason field will contain an error message
Possible Errors
If no task with the given id is found, the server returns a 404 error
If there is a server error, a 500 error is returned
Notes
It's better not to request status updates too frequently, such as using a 1-second interval
Get Retouch Result /retoucher/getFile/{id}
Request Description
GET request, id is passed as a param in the URL (similar to the status request).
Successful Response
Depending on the task, this endpoint returns:
- JSON (for mode=facefeatures)
- Image (for mode=retouch4fun)
- ZIP archive with images (for mode=professional and when layers=1 is set in at least one of the plugins, check Task Description how to set layers property) Otherwise, it returns an Image.
This documentation covers tasks with mode=professional, so the response is expected to be a ZIP archive.
Possible Errors
If no task with the given id is found, the server returns a 404 error
If there is a server error, a 500 error is returned
Notes
The /retoucher/getFile request should be made only after receiving a status with state="completed". Even if progress=100, the result may not yet be saved in a file, and the server won’t be able to return it.
It’s also not possible to request old files, as the results are stored for only 24 hours.
Limitations
Before submitting a retouch request, you should check the file (photo or archive) for limitations. The list of limitations can be obtained with a GET request to /info/limits
This endpoint returns JSON in the following format:
{
image: {
formats: ["png", "jpg", "jpeg"],
maxFileSizeInMB: 100,
maxMegapixels: 250
},
archive: {
formats: ["zip"]
}
}
The JSON above indicates that the allowed image formats are png, jpg, jpeg, the maximum file size is 100 MB, and the image resolution should not exceed 250 megapixels.
If these limitations are violated, the task may not be processed.
At the moment, this endpoint is not available in production.