Versions_CreateVersionPreview

POST

/v1/accounts/{account}/datasets/{dataset}/versionPreviews

const url = 'https://dev-api.qualiastudios.dev/v1/accounts/example/datasets/example/versionPreviews';
const options = {
  method: 'POST',
  headers: {'X-API-Key': '<X-API-Key>', 'Content-Type': 'application/json'},
  body: '{"parent":"example","include":["CLASS_UNSPECIFIED"],"validateOnly":true,"requestId":"example"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://dev-api.qualiastudios.dev/v1/accounts/example/datasets/example/versionPreviews \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <X-API-Key>' \
  --data '{ "parent": "example", "include": [ "CLASS_UNSPECIFIED" ], "validateOnly": true, "requestId": "example" }'

Previews the version an upload or a merged dataset would publish (“Apply all”): freezes the takes include picks, each with the edit drawn on it, and starts measuring them. Answers at once, MEASURING; read it again until READY. Supersedes the caller’s MEASURING, READY or FAILED preview of the dataset; FAILED_PRECONDITION while the caller’s preview of it is PUBLISHING. Writes nothing the dataset reads. With validate_only, writes nothing at all and answers the counts it would have (no name, no measurements), and needs only read access. FAILED_PRECONDITION for a mixture (CreateVersion tags its head). (— api-linter: core::0133::method-signature=disabled api-linter: core::0133::http-body=disabled aip.dev/not-precedent: a preview is computed from the dataset; the caller names only which takes it takes. —)

Authorizations

ApiKey

Parameters

Path Parameters

account

required

string

The account id.

dataset

required

string

The dataset id.

Request Body^required

application/json

Request for Versions.CreateVersionPreview. (— api-linter: core::0133::request-resource-field=disabled api-linter: core::0133::request-id-field=disabled aip.dev/not-precedent: a preview is computed from the dataset, not written by the caller, and its id is server-assigned. —)

object

parent

required

Accounts/{account}/datasets/{dataset}: an upload or a merged dataset.

string

include

Which takes to take, by how they stand: every take in any class named. Empty means KEPT_BY_PERSON. Review need not be finished: a take nobody has ruled on is KEPT, or FLAGGED. (— api-linter: core::0133::request-unknown-fields=disabled aip.dev/not-precedent: the selection a preview is computed from. —)

Array<string>

Allowed values: CLASS_UNSPECIFIED KEPT_BY_PERSON KEPT FLAGGED REJECTED REJECTED_BY_PERSON

validateOnly

Answer the counts the preview would have and write nothing. Also answers versus the newest tag, from the same read-only snapshot; changed_count remains zero (it describes changes to a saved READY preview).

boolean

requestId

Idempotency key (AIP-155): a retry with the same id within 24 hours returns the first call’s preview instead of making another.

string

Responses

200

application/json

What a version would be: the dataset’s takes as they stand now, picked by how they stand (include), each with the edit drawn on it (its draft) cut out of the recorded bytes and measured, before anything is published (“Apply all” in the Create version dialog). Making one writes nothing a dataset reads: head, its episodes, their standing, their profiles and every draft stay as they are. PublishVersionPreview turns it into a tag: each edited take is cut into new episodes beside the take, and the tag pins exactly the takes and windows the preview froze, however they have changed since (changed_count says how many have).

A caller has at most one live preview of a dataset (MEASURING, READY, PUBLISHING or FAILED): a new CreateVersionPreview supersedes the caller’s earlier one when it is MEASURING, READY or FAILED, and is refused (FAILED_PRECONDITION) while it is PUBLISHING, which only its publish ends. Uploads and merged datasets have them; a mixture is tagged from head (CreateVersion).

The {version_preview} id is a UUID.

Served by qds-api.

object

name

Accounts/{account}/datasets/{dataset}/versionPreviews/{version_preview}

string

include

Which takes it took, by how they stood when it was made.

Array<string>

Allowed values: CLASS_UNSPECIFIED KEPT_BY_PERSON KEPT FLAGGED REJECTED REJECTED_BY_PERSON

state

Where it is.

string format: enum

Allowed values: STATE_UNSPECIFIED MEASURING READY PUBLISHING PUBLISHED FAILED DISCARDED SUPERSEDED EXPIRED

measuredWindowCount

Windows measured so far, of window_count. A window is one stretch of one take the version would hold: the take as recorded, its trim, or one piece of its split.

string

windowCount

Windows to measure.

string

episodeCount

Episodes the version would pin: each take it has as recorded, and each new episode an edited take becomes.

string

durationSeconds

Recorded time those episodes span, seconds.

number format: double

editedCount

Takes the version would publish with the edit drawn on them.

string

trimmedCount

Edited takes that become one new episode (a trim, new subtasks or both).

string

splitCount

Edited takes that become two or more new episodes.

string

pieceCount

New episodes the edited takes become, across every edited take.

string

includedFlaggedCount

Episodes it would pin that stand FLAGGED.

string

includedRejectedCount

Episodes it would pin that stand REJECTED.

string

unmeasuredCount

Windows with nothing in them to measure. Their episodes are still in the version; the preview’s charts leave them out.

string

unprofiledCount

Takes with no profile of the recording as it was taken: the layer the preview’s charts draw behind the version’s leaves them out.

string

unprocessable

Takes it leaves out, and why: the version will not have them.

Array<object>

A take the preview leaves out, and why.

object

episode

Accounts/{account}/datasets/{dataset}/episodes/{episode}: the take.

string

label

The take as a person finds it in the dataset, e.g. “episode 41 · pick_cup_041”.

string

reasonCode

Why, as a stable UPPER_SNAKE_CASE code to branch on: KEEPS_NOTHING (the drawing keeps no frame), TOO_MANY_PIECES (more than 512), ALREADY_SPLIT (drawn on a take split before), A_PIECE (drawn on a piece of one), UNMEASURABLE (its windows failed to measure three times), and others to come.

string

reason

Why, in a person’s words: “the drawing keeps nothing”.

string

changedCount

Takes it took whose ruling, drawing, labels or recording changed since it was made. Publishing it still publishes them as previewed. Counted only while READY; 0 otherwise.

string

versus

How it compares with the dataset’s newest tag; unset when there is none. Set while READY and on a validate_only response. Validation reads both selections in one read-only snapshot. To count changes since a particular newest preview-made tag, validate with that tag’s include and check this tag still matches; retry the newest-tag read if it changed. (— api-linter: core::0140::prepositions=disabled aip.dev/not-precedent: “versus” names the comparison the dialog shows, not a relationship to another field. —)

object

tag

The newest tag (“1.2”).

string

addedCount

Episodes the preview has and the tag does not.

string

removedCount

Episodes the tag has and the preview does not.

string

changedCount

Takes in both, at another revision or with another edit.

string

unchangedCount

Episodes in both, the same.

string

sameAsVersion

A tag (“1.2”) holding exactly the episodes it would pin, if there is one: publishing it would make that tag again. Empty otherwise, and until it is READY. (— api-linter: core::0140::prepositions=disabled aip.dev/not-precedent: the dialog’s “Same as 1.2”. —)

string

version

Accounts/{account}/datasets/{dataset}/versions/{version}: the tag it was published as, once PUBLISHED.

string

publishError

Why it cannot be published as it stands (a merged dataset whose uploads freeze different training contracts), or why the last PublishVersionPreview stopped short of a tag, naming the takes. Empty when nothing stands in the way.

string

creator

Who made it, a person or an API key: its owner, the only caller who publishes or discards it.

object

kind

What kind of actor it is.

string format: enum

Allowed values: KIND_UNSPECIFIED PERSON VALIDATION RULE MODEL OPERATOR SYSTEM

user

The person’s user id when kind is PERSON; empty otherwise.

string

displayName

The person’s display name at the time, for rendering without a lookup.

string

agent

The rule code, or the model id (e.g. “gemini-robotics-er”), when not a person.

string

run

The run a model or rule finding came from, when it has one.

string

apiKey

The API key’s id when a person acted through one; empty for a session. Never the key itself.

string

attribution

Signed identity evidence recorded with the change, kept apart from the principal above. Unset on older records and wherever none was signed.

object

authentication

How the principal authenticated.

string format: enum

Allowed values: AUTHENTICATION_UNSPECIFIED SESSION API_KEY SERVICE

initiator

The user id of a person verified as starting the work: the person of a session, or the person a trusted service’s signed job record names. Empty when nobody was verified.

string

initiatorDisplayName

The initiator’s display name at the time, never their email.

string

credentialCreator

The user id of the key’s creator at the time. Not who used the key.

string

credentialOwner

Who owned the key at the time.

string format: enum

Allowed values: CREDENTIAL_OWNER_UNSPECIFIED PERSON SPACE

credentialOwnerSpace

The owning space’s id (a workspace or the organization) when credential_owner is SPACE.

string

createTime

When it was made.

string format: date-time

updateTime

When it last changed.

string format: date-time

readyTime

When it became READY; unset before.

string format: date-time

expireTime

When it EXPIRES unless it is published first.

string format: date-time

draftsUnpublishedCount

Takes of the dataset with an edit drawn that no tag has published yet, whether the preview took them or not.

string

Example

{
  "include": [
    "CLASS_UNSPECIFIED"
  ],
  "state": "STATE_UNSPECIFIED",
  "creator": {
    "kind": "KIND_UNSPECIFIED",
    "attribution": {
      "authentication": "AUTHENTICATION_UNSPECIFIED",
      "credentialOwner": "CREDENTIAL_OWNER_UNSPECIFIED"
    }
  }
}

default

Default error response

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"
    }
  ]
}

Versions_CreateVersionPreview

Authorizations

Parameters

Path Parameters

Request Body required

Responses

200

Example

default

Example generated

Request Body^required

Example ^generated