Vertopal
Tools
CONVERTERS
API Menu

Convert File

POST /v1/convert/file

Converts the uploaded file to the target format. We recommend running it in the async mode based on mode strategy.

Request

Parameter Keys

output string required

The output format. If the output format also has a type, separate it with a hyphen.

Example
txt-markdown
input string

The input format. If the input format also has a type, separate it with a hyphen.
If this parameter key is not sent, The uploaded file extension (and maybe with a default type) is assumed.

Example
tex-beamer
The example code of this section shows the structure of the Convert File request. You may see the other request structure keys such as data keys and see how the request is authenticated.
HTTP
cURL
CLI
Python
PHP
POST https://api.vertopal.com/v1/convert/file
Authorization: Bearer [APP_TOKEN]

data={
    "app": "[APP_ID]",
    "connector": "[CONNECTOR]",
    "include": ["entity", "result"],
    "mode": "async",
    "parameters": {
        "output": "jpg"
    }
}

curl -L -X POST 'https://api.vertopal.com/v1/convert/file' \
-H 'Authorization: Bearer [APP_TOKEN]' \
-F 'data={
    "app": "[APP_ID]",
    "connector": "[CONNECTOR]",
    "include": ["entity", "result"],
    "mode": "async",
    "parameters": {
        "output": "jpg"
    }
}'

vertopal api -v 1 convert/file \
--app "[APP_ID]" \
--token "[APP_TOKEN]" \
-F data='{
    "app": "%app-id%",
    "connector": "[CONNECTOR]",
    "include": ["entity", "result"],
    "mode": "async",
    "parameters": {
        "output": "jpg"
    }
}'

from vertopal.api.v1 import API

API.convert(
    output_format="jpg",
    app="[APP_ID]",
    token="[APP_TOKEN]",
    connector="[CONNECTOR]",
    input_format=None,
    mode=API.ASYNC,
)

use Vertopal\API\Credential;
use Vertopal\API\V1;

require "vendor/autoload.php";

$credential = new Credential("[APP_ID]", "[APP_TOKEN]");

V1::convert(
    "jpg",
    $credential,
    "[CONNECTOR]",
    null,
    V1::ASYNC
);

Response

Output Keys

connector string<uuid>

The connector for connecting to another task as the data key.

status string

The status of the conversion.

Values
waiting|pending|successful|failed
duration number<integer>

The time elapsed until the conversion was finished in seconds.

HTTP Status Codes

OK 200

The task has been executed successfully without any errors.

FAILED_CONVERT 200

The conversion has failed.

INVALID_INPUT_FORMAT 200

The [INPUT] format is not found in the valid input formats.

INVALID_OUTPUT_FORMAT 200

The [OUTPUT] format is not found in the valid output formats.

NOT_MATCH_EXTENSION_AND_INPUT 200

The file extension ([FILE_EXTENSION]) does not match the input extension ([INPUT_EXTENSION]).

NO_CONVERTER_INPUT_TO_OUTPUT 200

There is no converter for [INPUT] format to [OUTPUT] format.

WRONG_INPUT_FORMAT_STRUCTURE 200

The input format has the wrong structure.

WRONG_OUTPUT_FORMAT_STRUCTURE 200

The output format has the wrong structure.

The example code of this section shows the structure of the Convert File response. You may see the other response structure keys such as entity keys.
JSON
{
    "entity": {
        "id": "[ENTITY_ID]",
        "type": "task",
        "endpoint": "v1/convert/file",
        "status": "running",
        "vcredits": 0,
        "created_at": "2023-03-23 15:20:05",
        "started_at": "2023-03-23 15:20:07",
        "completed_at": null
    },
    "result": {
        "output": {},
        "error": {},
        "warning": {}
    }
}
Loading, Please Wait...