Custom uploader
The custom uploader system in ShareX lets users upload images/text/files to hosting services or shorten/share URLs. This feature is mainly used by users who host their own services.
You can export your custom uploader with the .sxcu extension, which allows users to just double-click that file to use the custom uploader.
If the destination type is configured, then ShareX can also set this custom uploader as the selected custom uploader and change the current destination to it, so users won't need any additional configuration.
In the custom uploaders list, this name will be used. The Name field is optional. When it is left empty, ShareX will automatically use the request URL domain as the name. It is suggested to leave the name field empty unless you have multiple uploaders using the same domain.
For example, if the request URL is https://example.com/upload.php and the name field is empty, then example.com will be used in the custom uploaders list.
Destination type is used when users import a custom uploader by double-clicking the .sxcu file.
List of HTTP request methods available:
If the request doesn't have a body and only parameters are used, then the GET method is preferred. If the body is Form data (multipart/form-data), then the POST method is preferred.
The request will be sent to this URL.
Example: https://example.com/upload.php
Parameters will be used to create a URL query string.
For text uploaders or URL shorteners, the {input} syntax can be used as a value to supply input text or a URL.
You can also use dynamic values like %mo to get the current month, etc.
For example, if you set parameters like this:
| Name | Value |
|---|---|
| api_key | eUM14R4g4pMS |
| private | true |
Then the query string will be appended to the request URL like this when sending the request:
https://example.com/upload.php?api_key=eUM14R4g4pMs&private=true
Headers can be used to pass additional information with the request. Most of the time, APIs use headers for authorization.
Default request headers can also be overridden, such as:
Basic access authentication example:
| Name | Value |
|---|---|
| Authorization | Basic {base64:USERNAME:PASSWORD} |
API key example:
| Name | Value |
|---|---|
| api_key | eUM14R4g4pMS |
Supported request body types:
Most of the time, if the API request method is GET, then No body will be used with parameters. If the request method is POST, then Form data (multipart/form-data) is used. This is not always the case, so you must check the API documentation to make sure what the request expects.
For a text uploader or URL shortener, the {input} syntax can be used as a value to supply input text or a URL.
This field can only be used when Body is Form data (multipart/form-data).
For example, in this HTML code: <input type="file" name="file_image">, the file form name is file_image.
These text boxes can be used to parse the response to get the URL result. If the response only contains a URL, then there is no need to write anything in the URL text box.
Make sure to also parse the error message so ShareX can show a user-friendly error message.
There is a special syntax you can use to accomplish some tasks, like parsing a URL from JSON responses.
This syntax is usable in the following sections, with a few exceptions:
For example, syntaxes that involve parsing the response are only usable in URL sections, as expected.
Note: If you would like to use {, }, |, or \ characters in any of the syntax-supported sections, then you can escape them with the \ character. For example: \{
You can find a list of all available syntaxes with example usages at the bottom.
If the response only contains a file name (or ID) and you would like to append it to the domain, then you can use this syntax.
If the response contains a full URL, then you don't have to use this syntax because an empty URL text box will use the response automatically.
Syntax:
{response}
Example URL:
https://example.com/{response}
Can be used to get the redirection URL. If no redirection happened, then it will be just the request URL.
Syntax:
{responseurl}
Example URL:
{responseurl}
Can be used to get a specific response header value.
Syntax:
{header:name}
Example URL:
{header:location}
You can use JsonPath to parse a URL from a JSON response.
Syntax:
{json:jsonPath}
{json:input|jsonPath}
Example:
{
"status": 200,
"data": {
"link": "https:\/\/example.com\/image.png"
}
}
{json:data.link}
Example 2:
{
"success": true,
"files": [
{
"name": "image.png",
"url": "https://example.com/image.png"
}
]
}
{json:files[0].url}
You can use XPath to parse a URL from an XML response.
Syntax:
{xml:xpath}
{xml:input|xpath}
Example:
<?xml version="1.0" encoding="UTF-8"?>
<files>
<file>
<name>image.png</name>
<url>https://example.com/image.png</url>
</file>
</files>
{xml:/files/file[1]/url}
If the response is not JSON or XML, then you can use a Regular expression (Regex) to parse the response text.
When writing a regex pattern, don't forget to escape {, }, |, and \ characters with \.
Syntax:
{regex:regexPattern}
{regex:regexPattern|groupIndex}
{regex:regexPattern|groupName}
{regex:input|regexPattern|groupIndex}
{regex:input|regexPattern|groupName}
Example:
{regex:(?<=href=").+(?=")}
Example with group index:
{regex:href="(.+)"|1}
Example with group name:
{regex:href="(?<url>.+)"|url}
If you are using a text custom uploader, then this syntax will be replaced with the text you are going to upload. If it is a URL shortener or URL sharing service, then the syntax will be replaced with the URL. This syntax is mainly used as an argument value.
Syntax:
{input}
Example argument:
| Name | Value |
|---|---|
| text | {input} |
This syntax will be replaced with the file name. Most of the time, you don't need to use this syntax because when doing multipart/form-data file uploads, the file name is already included in the request.
Syntax:
{filename}
Example argument:
| Name | Value |
|---|---|
| title | {filename} |
If you would like to use a random domain for each upload, you can use this syntax.
Syntax:
{random:value1|value2|value3}
Example URL:
https://{random:subdomain1|subdomain2}.{random:domain1|domain2|domain3}.com/{json:files[0].url}
This will show a window with all values as buttons so you can dynamically select which text input to use. This syntax can be useful if you have multiple domains and would like to select a specific domain for each upload.
Syntax:
{select:value1|value2|value3}
Example URL:
https://{select:domain1.com|domain2.com|domain3.com}/{json:files[0].url}
This will show an input box for the user to input text. This syntax can be used if the user prefers to write a different value for an argument or URL part for each upload.
The first parameter is the window title; the second parameter is the default text for the input box. Both parameters are optional.
Syntax:
{inputbox}
{inputbox:title}
{inputbox:title|default text}
Example URL:
https://{inputbox:Input subdomain|i}.example.com/{json:files[0].url}
This will display an output box with the specified text. It can be used for non-uploader requests, such as prompting AI and viewing the result.
Syntax:
{outputbox:text}
{outputbox:title|text}
Example URL:
{outputbox:Result|{json:choices[0].message.content}}
Encode text to Base64.
Syntax:
{base64:text}
Example header:
| Name | Value |
|---|---|
| Authorization | Basic {base64:username:password} |
ShareX custom uploader (SXCU) files are JSON files at their core.
An example JSON schema looks like this:
{
"Version": "17.0.0",
"Name": "Example",
"DestinationType": "ImageUploader, TextUploader, FileUploader",
"RequestMethod": "POST",
"RequestURL": "https://example.com/upload.php",
"Parameters": {
"Parameter1": "Value1",
"Parameter2": "Value2",
"Parameter3": "Value3"
},
"Headers": {
"Header1": "Value1",
"Header2": "Value2",
"Header3": "Value3"
},
"Body": "MultipartFormData",
"Arguments": {
"Argument1": "Value1",
"Argument2": "Value2",
"Argument3": "Value3"
},
"FileFormName": "file",
"URL": "{json:url}",
"ThumbnailURL": "{json:thumbnail_url}",
"DeletionURL": "{json:deletion_url}",
"ErrorMessage": "{json:error}"
}
Enums: