Vertopal — Free Online Converter
API Menu

Mode Strategy

For ease of the use of API, tasks are run in sync mode by default.
Depending on how you use the Vertopal API, you can decide whether the tasks will be run in sync or async mode, but we always recommend running all tasks in sync unless the task may take a long time, such as a convert file task.
Network systems may time out the request if an open request takes a long time due to no data transfer.
Here the difference between sync and async mode is more discussed.

Sync
After the task is run, the app must wait for a response stating that the task has been completed.
During all this time, the request will be blocked until the final response is received.
Now suppose a convert task takes a few hours, in this case, your app has an open request all this time and may be timed out by a network system at any moment.

Async
After the task is run, the app will immediately receive a response that specifies the task's status, typically running.
The app no longer waits for a response that indicates the task is completed, and the request will be non-blocked for the final response.
In this case, there are several scenarios to get the final response:

  • Monitoring Response: You can see the response to any task at any time by requesting in specific time periods using Monitor Response of Task. When seeing that the task is completed, this is the final response.
  • A callback URL: By specifying a URL in the callback data key, Vertopal will POST the final response after completing the task.

In the async mode, note that if the ["result"] (the default value) is set for the include data key, most of the time you will get a response with an empty result. In this case, we recommend setting ["entity", "result"] as the minimum value for the include data key to get the status of the task.

Request

The example code of this section shows the structure of the Mode Strategy 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/example/long/task
Authorization: Bearer [APP_TOKEN]

data={
    "app": "[APP_ID]",
    "mode": "async",
    "callback": "https://www.example.com/get-response.php",
    "include": ["entity", "result"]
}

curl -L -X POST 'https://api.vertopal.com/v1/example/long/task' \
-H 'Authorization: Bearer [APP_TOKEN]' \
-F 'data={
    "app": "[APP_ID]",
    "mode": "async",
    "callback": "https://www.example.com/get-response.php",
    "include": ["entity", "result"]
}'

vertopal api -v 1 vertopal/long/task \
--app "[APP_ID]" \
--token "[APP_TOKEN]" \
-F data='{
    "app": "%app-id%",
    "mode": "async",
    "callback": "https://www.vertopal.com/get-response.php",
    "include": ["entity", "result"]
}'

from vertopal.api.v1 import API

API.example_long_task(
    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::exampleLongTask(
    "jpg",
    $credential,
    "[CONNECTOR]",
    null,
    V1::ASYNC
);

Response

HTTP Status Codes

OK 200

The task has been executed successfully without any errors.

INVALID_CALLBACK 400

The callback is invalid.

UNVERIFIED_DOMAIN_CALLBACK 403

The domain of callback is not verified.

The example code of this section shows the structure of the Mode Strategy response. You may see the other response structure keys such as entity keys.
JSON
{
    "entity": {
        "type": "task",
        "endpoint": "v1/example/long/task",
        "status": "running",
        // other entity keys
    },
    "result": {
        "output": {},
        "error": {},
        "warning": {}
    }
}
Loading, Please Wait...