Vertopal
Tools
CONVERTERS
API Menu

Structure

Each file conversion workflow (from uploading the input file to downloading the output result), is performed by a job. Each job consists of several tasks. In other words, each request sent to the API endpoints is considered a unique task, which is itself a child of a job.

The workflow below illustrates how a simple JPG to WEBP conversion (job) consists of different tasks:

Job A (JPG to WEBP Conversion Workflow)
    Task A1 (Upload JPG)
    Task A2 (Convert to WEBP)
    Task A3 (Generate URL)
    Task A4 (Download WEBP from Generated URL)

It is usual that each convert job begins with an upload task and ends with a download task. Processing tasks such as the convert task often lie in the middle. Each task gets and returns data with a specific structure for its request and responses.

Request

Field Keys

data object required

Any data that needs to be sent to the task is sent by this field. Each primary key of a data field is a data key.

Data Keys

app string<uuid> required

The App ID to which this request is being sent.

connector string<uuid> required

This connects the task to another task. You used this key in the data because you received it in the output of the results of another task.
Note, avoid sending it to start upload tasks, these tasks are mostly starters of jobs and do not need a connector data key, but in other types of tasks, it should be sent as the required data key to start the task.

include array

Specifies what items should be returned in the response. It must contain a sub-array of pre-defined values.

Default
["result"]
Values
["entity", "payload", "result"]
mode string

Manages how to run the task.

Default
sync
Values
sync|async
callback string<url>

The URL that the response will be sent by POST method to it after the task is completed. The domain of the URL must be verified with Vertopal for the app.

parameters object required

The parameters specific to each task are sent in this key. Each primary key of parameters is a parameter key.
Note, This data key is not required only when the task has no parameters or all parameters are optional.

The example code of this section shows the structure of the task request. You may 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", "payload", "result"],
    "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", "payload", "result"],
    "parameters": {
        "output": "jpg"
    }
}'

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

from vertopal.api.v1 import API

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

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

require "vendor/autoload.php";

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

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

Response

Task Keys

entity object

Include the specifications and details of the entity.

payload object

Whatever was sent by the data field is returned exactly.

result object

It shows the task result that contains output, error, and warning keys.

Entity Keys

id string<uuid>

The Task ID is unique. Also, If the task has a connector output key, this ID is equal to it.

type string

Specifies the entity type.

Values
task
endpoint string<path>

Includes the path of the endpoint that follows the API version.

status string

Shows the current status of the task.
Note that the completed task does not mean it is successful, a task may have been completed with an error.

Values
hold|running|completed
vcredits number<integer>

If the task consumes vCredits and is completed successfully, this is the number of vCredits consumed by the task.

Range
0<=x
created_at string<datetime>

The datetime of the task when the status was changed to "hold".

started_at string<datetime>

The datetime of the task when the status was changed to "running".

completed_at string<datetime>

The datetime of the task when the status was changed to "completed".

Result Keys

output object

The specific output of each task is returned. It contains various keys that depend on the task output.

error object

Shows the error that caused the task to fail. This contains code and message keys. The code is the error name and its value is an explanation of the error that occurred.

warning object

The messages that improve endpoint usage or task performance. This is a key-value, where each key is a warning name and its value is how to resolve it.

HTTP Status Codes

OK 200

The task has been executed successfully without any errors.

INVALID_DATA_KEY 400

The [NAME] key in the data is invalid.

INVALID_FIELD 400

The [NAME] field is invalid.

INVALID_PARAMETER 400

The [NAME] parameter is invalid.

MISMATCH_DEPENDENT_TASK 400

The dependent task is mismatched with the current task.

MISMATCH_VERSION_DEPENDENT_TASK 400

The dependent task API version is mismatched with the current task API version.

MISSING_REQUIRED_DATA_KEY 400

The [NAME] key in the data is required.

MISSING_REQUIRED_FIELD 400

The [NAME] field is required.

MISSING_REQUIRED_PARAMETER 400

The [NAME] parameter is required.

WRONG_TYPE_DATA_KEY 400

The [NAME] key in the data has the wrong type.

WRONG_TYPE_FIELD 400

The [NAME] field has the wrong type.

WRONG_TYPE_PARAMETER 400

The [NAME] parameter has the wrong type.

WRONG_VALUE_DATA_KEY 400

The [NAME] key in the data has the wrong value.

WRONG_VALUE_PARAMETER 400

The [NAME] parameter has the wrong value.

FREE_PLAN_DISALLOWED 403

To use Vertopal API, activating a premium plan is required.

INSUFFICIENT_VCREDITS 403

You do not have enough vCredits to run this task.

ONLY_DEVELOPMENT_REQUEST 403

The only request of files with the registered hash is allowed in development.

DOWNLOAD_EXPIRED 404

The download of this converted file has expired.

FILE_NOT_EXISTS 404

The [STATE] file not exists.

NOT_FOUND 404

The API Endpoint is not found.

NOT_READY_DEPENDENT_TASK 404

The dependent task has not been completed correctly.

NO_CONNECTOR_DEPENDENT_TASK 404

The Connector is not dependent on any other Task.

POST_METHOD_ALLOWED 405

Only the POST method is allowed.

INTERNAL_SERVER_ERROR 500

Oops, Something went wrong! Please contact us if the error persists.

The example code of this section shows the structure of the task response. You can check your current rate limit status based on the specific response headers.
JSON
{
    "entity": {
        "id": "[ENTITY_ID]",
        "type": "task",
        "endpoint": "v1/convert/file",
        "status": "completed",
        "vcredits": 1,
        "created_at": "2023-03-21 20:20:17",
        "started_at": "2023-03-21 20:20:18",
        "completed_at": "2023-03-21 20:21:00"
    },
    "payload": {
        "app": "[APP_ID]",
        "connector": "[CONNECTOR]",
        "include": [
            "entity",
            "payload",
            "result"
        ],
        "parameters": {
            "output": "jpg"
        }
    },
    "result": {
        "output": {
            "connector": "[NEW_CONNECTOR]",
            "status": "successful",
            "duration": 6
        },
        "error": {},
        "warning": {}
    }
}
Loading, Please Wait...