Skip to content
Qualia Docs

Versions_StartMaterialization

POST
/v1/accounts/{account}/datasets/{dataset}/versions/{version}/materializations/{materialization}:start
 
curl --request POST \
  --url https://dev-api.qualiastudios.dev/v1/accounts/example/datasets/example/versions/example/materializations/example:start \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <X-API-Key>' \
  --data '{ "name": "example" }'

Starts rendering a tag in the id’s layout, or picks up the rendering already there: it never renders twice. Answers at once; read the materialization again until SUCCEEDED, then list its artifacts. FAILED_PRECONDITION for head (tag it first) and when the rendering failed for good (the message says why); UNAVAILABLE when the renderer cannot be reached (retry).

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters ”
account
required
string

The account id.

dataset
required
string

The dataset id.

version
required
string

The version id.

materialization
required
string

The materialization id.

Request Body required

Section titled “Request Body required ”
Media type application/json

Request for Versions.StartMaterialization.

object
name
required

Accounts/{account}/datasets/{dataset}/versions/{version}/materializations/{materialization}: a tag, stable or a digest prefix, and the layout.

string
Example generated
{
  "name": "example"
}

Responses

Section titled “ Responses ”

200

Section titled “200 ”

OK

Media type application/json

A tag rendered as a LeRobot or MCAP ROS2 dataset, to download (QUA-3084). The files stay in object storage: each artifact carries a short-lived signed URI to its immutable object, never the bytes. Rendering runs in the background: StartMaterialization begins it, and every later call, from anyone, finds the same rendering. A tag never moves, so the same tag rendered by the same renderer gives the same files, byte for byte.

The {materialization} id is the layout: lerobot-v3 (LeRobot v3.0), lerobot-v2-1 (LeRobot v2.1) or mcap-ros2 (one ROS 2 MCAP file per episode). head is not pinned, so it has none: tag it first.

Served by qds-api.

object
name

Accounts/{account}/datasets/{dataset}/versions/{version}/materializations/{materialization}. The version segment is the tag, also when the request named stable or a digest prefix.

string
state

How far the rendering is.

string format: enum
Allowed values: STATE_UNSPECIFIED NOT_STARTED RUNNING SUCCEEDED INTERRUPTED
digest

“b3:”, once SUCCEEDED: one hash over every artifact’s path and content, so two renderings with one digest are the same files.

string
artifactCount

Files in the rendered dataset, once SUCCEEDED.

string
episodeCount

Episodes in it, once SUCCEEDED.

string
frameCount

Frames in it, once SUCCEEDED.

string
renderer

“b3:”: the renderer revision this rendering is for. A new renderer starts over at NOT_STARTED.

string
Example 
{
  "state": "STATE_UNSPECIFIED"
}

default

Section titled “default ”

Default error response

Media type application/json

The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.

object
code

The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].

integer format: int32
message

A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.

string
details

A list of messages that carry the error details. There is a common set of message types for APIs to use.

Array<object>

Contains an arbitrary serialized message along with a @type that describes the type of the serialized message.

object
@type

The type of the serialized message.

string
key
additional properties
any
Example generated
{
  "code": 1,
  "message": "example",
  "details": [
    {
      "@type": "example"
    }
  ]
}