Polytrons can be submitted through the web user-interface (web UI) or through the API. This document will cover how to submit Polytrons using the developer-oriented API.
This page is currently under construction. The Polyverse API is still undergoing rapid changes as we're preparing for launch. If you have question regarding the setup, or if you encounter outdated information, please reach out to your contact at Abstract Polyverse.
The submission of Polytrons is done over a simple, yet powerful HTTP API. The main route for submission is the /task/process route. This route expects a HTTP multipart request with the request body.
The following represents a simple Polytron request to the Blend polytron. Keep in mind, that you can easily generate the request.json from the web UI by starting to process a Polytron and then selecting Generate JSON. Alternatively, if you've already processed a Polytron, you can download the request.json from its result page by clicking on the Request Data button.
POST https://api.polyverse.cloud/task/process
Content-Type: multipart/form-data; boundary=xEhxLzlaFxsbzJlDwXEWkNsu7Ts9aRca
Authorization: bearer <user-token>
--xEhxLzlaFxsbzJlDwXEWkNsu7Ts9aRca
Content-Disposition: form-data; name="request.json"
Content-Type: application/json
{
"TimeoutInSeconds": 180,
"NotifyByEmail": false,
"Name": "My Blend Request",
"Identifier": "InstaMAT",
"Data": {
"GraphID": "5fdaddf9-c419-470f-a8e1-48dd2be0b425",
"Parameters": {
"Foreground": "https://demo.polyverse.cloud/Polyverse.png",
"Background": "https://demo.polyverse.cloud/InstaMAT.png",
},
"ImageFormat": "PNG",
"MeshFormat": "FBX",
"PointCloudFormat": "PLY",
"GrayscalePermutation": false,
"ExecutionFormat": {
"Type": "Normalized16",
"Width": 1024,
"Height": 1024
},
"OutputFilter": ""
}
}
--xEhxLzlaFxsbzJlDwXEWkNsu7Ts9aRca--
As mentioned before, the submission request is a HTTP multipart request. The only mandatory part of this request is request.json. This part specifies the Polytron to execute, policies for request completion as well as input and output information for the Polytron.
Additional files can be attached as parts to the request. All parts, except request.json, will be forwarded unchanged to the Polytron. This allows uploading images, 3D meshes and other resources for a Polytron to use as input.
Upon submission, the Polytron task will be put on a queue and executed on an instance available for processing. After the execution is completed, outputs will be available for download over the API.
Polyverse is not a data storage solution. The outputs are only stored for a few days before they are permanently deleted from the server. Download the results of your Polytron task as soon as possible after it completes, or export it to a Polyverse Asset Library.
Once a Polytron is submitted, the server will reply with a Task object. This object contains the information for your newly submitted task, including the ID that allows you to check for the progress or download results once it's completed.
{
"ID": "ca491041-139d-49de-bec2-68869e658e86",
"Identifier": "InstaMAT",
"TimeoutInSeconds": 100,
"NotificationURL": "",
"NotifyByEmail": false,
"Name": "My Request",
"Progress": 0,
"CreationDate": "2023-09-13T10:34:40.452Z",
"UpdateDate": "2023-09-13T10:34:40.452Z",
"ExecutionTime": 0,
"TokenCost": 3,
"Status": "Waiting",
"Error": null,
"Data": {
"GraphID": "5fdaddf9-c419-470f-a8e1-48dd2be0b425",
"GraphName": "Blend",
"PackageFileName": "",
"Parameters": {
"Foreground": "https://demo.polyverse.cloud/Polyverse.png",
"Background": "https://demo.polyverse.cloud/InstaMAT.png"
},
"ImageFormat": "PNG",
"MeshFormat": "FBX",
"PointCloudFormat": "PLY",
"GrayscalePermutation": false,
"ExecutionFormat": {
"Type": "Normalized16",
"Width": 1024,
"Height": 1024
},
"OutputFilter": ""
},
"Inputs": [
{
"Name": "4c1a256f-043e-40f1-b908-2c6e35a53b81.png",
"Size": 39366
},
{
"Name": "c1044193-dcca-4f1b-b4c7-78107174b2fc.png",
"Size": 39366
}
],
"Object": {
"ID": "5fdaddf9-c419-470f-a8e1-48dd2be0b425",
"Name": "Blend",
"Author": "InstaMaterial GmbH",
"Version": "1.73",
"Category": "Image/Blend",
"GraphType": "Atom",
"Identifier": "InstaMAT",
"FriendlyName": "Blend",
"Documentation": "Mixes or blends together two images, a foreground image on top of a background one, with a configurable blend mode and optional mask (which used with the alpha channel of the top image). The alpha blending for images with alpha channels can also be configured.",
"IsPreviewAvailable": true,
"PreviewURL": "https://hello.polyverse.cloud/preview/object/5fdaddf9-c419-470f-a8e1-48dd2be0b425/preview.png",
"IsUserFavorite": false
}
}
Of all the fields, the ones of most interest to most users is ID, which uniquely identifies the task within the system, Status which indicates the status of the task, whether it has started execution or is waiting and Progress which gives an estimate how far along the Polytron execution is.
The submission of a Polytron is made through a JSON object. This object specifies the Polytron to be executed, parameters, input and output configuration.
{
"TimeoutInSeconds": 100,
"NotifyByEmail": false,
"Name": "My Request",
"Identifier": "InstaMAT",
"Data": {
// Explained below.
}
}
| Parameter | Description |
|---|---|
| TimeoutInSeconds | Required. Specifies the maximum number of seconds the task should execute. This allows controlling the maximum amount of tokens a task can cost. The submitting account will still be charged with the processing cost up until the point. |
| Identifier | Required. Specifies an identifier for the Polytron executor to submit the task to. |
| NotifyByEmail | Optional. If set to true, will send an email whenever the task execution is finished. |
| Name | Optional. Specifies the name of the task. This name is only informative and has no effect on the task execution. |
| InstanceType | Required. Determines the instance type that is used for the execution. The token cost for the processing scales based on the type. |
| Data | Required. This is the Polytron-specific payload. The format of this data is defined by the Polytron itself. See below for a detailed documentation for more information on this object. |
As mentioned in the section above, the data object is specified by the Polytron and its executor. It's typically best to setup the Polytron through the web UI and inspect the request.json that can be generated by the UI to understand the possibilities and requirements of a Polytron.
{
"GraphID": "5fdaddf9-c419-470f-a8e1-48dd2be0b425",
"GraphName": "Blend",
"PackageFileName": "",
"Parameters": {
"Foreground": "https://hello.polyverse.cloud/AbstractPolyverse-Logo-BlackOnWhite-Medium.png",
"Background": "task://7e70757e-0f5c-4c16-8ebd-a7c8f26f349e/Blend_ElementImage_Output.jpg",
"Opacity": 0.5
},
"ImageFormat": "PNG",
"MeshFormat": "FBX",
"PointCloudFormat": "PLY",
"GrayscalePermutation": false,
"ExecutionFormat": {
"Type": "Normalized16",
"Width": 1024,
"Height": 1024
},
"OutputFilter": ""
}
| Parameter | Description |
|---|---|
| GraphID or ObjectID | Required. Specifies the Polytron to execute. Can be found using the web UI to search for Polytrons. |
| ImageFormat | Required. Specify the format to output any resulting image as. |
| MeshFormat | Required. Specify the format to output any resulting mesh as. |
| PointCloudFormat | Required. Specify the format to output any resulting point cloud as. |
| GrayscalePermutation | Optional. Controls if the color or grayscale permutation of the node will be executed. |
| ExecutionFormat | Context dependant. Determines the execution format. |
| ExecutionFormat.Type | Optional, For most executions, it's recommended to execute at 'Normalized16'. |
| ExecutionFormat.Width, ExecutionFormat.Height | Optional. Controls the size of the execution. Typically, controls the output image size. Larger executions will take longer to process. |
The Polytron parameters are how the inputs of a Polytron are specified. Inputs can vary, and they directly depend on the Polytron you are executing. You must check the Polytron documentation to know exactly which parameters are supported.
Although the available parameters vary, the supported parameter types are fixed. The table below describes all supported types and how they should be specified.
| Type | Description |
|---|---|
| Float32 | Specifies a numeric parameter. May or may not be bounded, depending on the specific parameter. |
| Double64 | Specifies a numeric parameter. May or may not be bounded, depending on the specific parameter. |
| UInt32 | Specifies a unsigned integer with 32-bit length. |
| Int32 | Specifies a unsigned integer with 64-bit length. |
| String, ElementString | Specifies a text string. The actual meaning of this is up to the actual Polytron implementation. |
| Boolean | Specifies a boolean type, with either true or false values. |
| EnumValue | Specifies an enum value. The value is a numeric value that corresponds to the index of the enum on the Polytron parameter definition. |
| ElementImage, AtomInputImage | Specifies an image resource or a color value. If an image is used, it must point to a valid Parameter URL. |
| ElementImageGray, AtomInputImageGray | Specifies an image resource or a luminance value. If an image is used, it must point to a valid Parameter URL. |
| Image | Specifies an image resource. It must point to a valid Parameter URL. |
| Mesh, ElementMesh | Specifies a mesh resource. It must point to a valid Parameter URL. |
| ElementPointCloud | Specifies a point cloud. It must point to a valid Parameter URL. |
| Resource, ElementResource | Specifies a generic resource. It must point to a valid Parameter URL. |
| Vector(2|3|4)(UI|I|F|D) | Specifies a numerical vector with N elements. UI stands for an unsigned integer element, I for signed integer, F for 32-bit floating point and D for 64-bit floating point. |
Of all parameters, URL parameters are likely the more interesting of them. They allow compositing of tasks as well as
remote fetching of resources to execute your task.
There are in total 4 supported URL schemes (or protocols) supported:
| Scheme | Description |
|---|---|
| file | Allows specifying either a file that was attached on the multipart request. |
| http/https | Allows fetching a remote file over a plain HTTP or HTTPS request. |
| task | Allows linking the output of another task as input to a new task. |
| pkg | Specific to the Polytron implementation. Allow specifying a builtin package resource. |
File URL parameters start with file:// and allow specifying a file that was attached on the multipart request. This
allows arbitrary files to be uploaded and sent for processing by a Polytron.
Specifying a parameter as file:///my-image.png will indicate to the Polytron that it should use the file uploaded as
part of the original multipart request my-image.png as input.
The excerpt below indicates how the file contents must be attached as part of the multipart request:
--xEhxLzlaFxsbzJlDwXEWkNsu7Ts9aRca
Content-Disposition: form-data; name="my-image.png"; filename="my-image.png"
Content-Type: image/png
<data>
HTTP URL parameters start with either http:// or with https:// and allow specifying a remote resource to be
downloaded by the Polyverse to be used as input. The resource must be publicly available, and the URL must end with one
of the valid extensions for that parameter. Please check the Polytron documentation for supported file extensions for
each parameter.
Example:
https://i0.wp.com/theabstract.co/wp-content/themes/Abstract/assets/images/logos/light-logo.png?quality=90&ssl=1
Task URL parameters start with task:// followed by the taskID to fetch the results from. The URL path specifies the
output path from the execution of the task identified by taskID. They allow specifying the output of a previously
executed task as input to a new task, allowing to execute a chain of Polytrons.
Example:
task://5fdaddf9-c419-470f-a8e1-48dd2be0b425/Result.fbx
Package URL parameters start with pkg:// followed by the path to a package file to be loaded by the Polytron. The package format and how they work, is specified by the Polytron implementation. Check the Polytron documentation for more details.
Once a Polytron has finished execution, it may contain output content. What outputs and their meanings are specific to the executed Polytron. For example, a Blur Polytron will contain an image that is the result of the blurring the image, while the CAD to 3D conversion Polytron will contain a mesh result.
It's possible to manually check the status of a task. This is useful if you want to track the progress of a task or if you want to get the output download URLs for files.
To do that, a GET request must be sent to /user/library/task/<taskID> where <taskID> is the task ID, as returned by the server when first creating the task. This will return the same Task object sent to the task notification URL by the submission route, but will include up-to-date information of the task at the time its called.
If the files are available, the Files field of the Task object will now contain information about the available files
"Files": [
{
"URL": "https://polyverse/signed_download_url",
"Name": "AmbientOcclusion.jpg",
"Size": 115299,
"AvailableUntilDate": "2023-10-16T18:07:36.000Z"
}
]
Each Polytron request has a NotificationURL field. This field indicates an HTTPS (or HTTP) URL to which the results of the execution are sent to. If specified, the system will send a GET request to this URL with the taskID as parameter appended to the URL.
Below is an example of the body for the POST request that is sent for a Blend Polytron:
Notification URL: https://www.theabstract.co/polytronFinished
Request by Polyverse: GET https://www.theabstract.co/polytronFinished?taskID=<TaskID>
Use this as a callback of when your task is completed. Take this opportunity to download all the outputs of your task, as the data will be permanently deleted after a few days.