Common Response Structures

This section details the common data structures you will encounter when interacting with the Triverse API. These payloads are consistently used across various endpoints to provide standardized information regarding task creation, status updates, and asset downloads.

Task Creation Response Payload (`TaskCreationResponsePayload`)

All task creation endpoints (e.g., Image to 3D, Text to 3D) return a StandardResponse containing this payload. It provides immediate details about the newly initiated task.

Field	Type	Description
`task_uuid`	UUID	The unique identifier for the task. Use this for status queries, downloads, or WebSocket subscriptions.
`name`	String	The name of the task; defaults to `task_uuid` if not provided.
`created_at`	Date	The UTC timestamp when the task was created.
`is_public`	Boolean	Indicates whether the task is publicly visible.
`task_priority`	Integer	The scheduling priority of the task (0 is default).
`status`	String	The initial status of the task, typically `PENDING`.
`flow_name`	String	The name of the underlying workflow (e.g., `image-to-model`).
`input`	Object	A snapshot of the standardized request parameters (e.g., `image_url`, `prompt`).
`costCredits`	Integer / Null	The number of credits frozen for this task. Credits are unfrozen if the task fails and officially deducted upon success.

Example:

{
  "code": 0,
  "message": "success",
  "data": {
    "task_uuid": "92483a80-236c-4889-9a95-4c90bb64dfd8",
    "name": "image-to-model-92483a80",
    "created_at": "2025-08-05T12:39:48.228522Z",
    "is_public": true,
    "task_priority": 0,
    "status": "PENDING",
    "flow_name": "image-to-model",
    "input": {
      "image_url": "https://triverse-public.oss-cn-beijing.aliyuncs.com/tasks/.../input.png",
      "model_version": "v2",
      "polygon_limit": 1000000,
      "texture_size": 1024
    },
    "costCredits": 120
  }
}

Flow Status Payload (`FlowStatusPayload`)

This payload is returned by GET /api/v1/tasks/{task_uuid} and pushed via WebSocket updates. It provides comprehensive details about the current state and progress of an ongoing task.

Field	Type	Description
`flowName`	String	The name of the Prefect flow executing the task.
`taskId`	UUID	The unique identifier of the task.
`status`	String	The current status of the task (e.g., `PENDING`, `RUNNING`, `SUCCESS`, `FAILED`, `CANCELLED`).
`input`	Object	A snapshot of the input parameters used to trigger the task.
`output`	Object	The execution results or intermediate states returned by Prefect. The structure varies depending on the flow.
`createTime`	Date	The UTC creation time of the flow run.

Example:

{
  "code": 0,
  "message": "success",
  "data": {
    "flowName": "image-to-model",
    "taskId": "92483a80-236c-4889-9a95-4c90bb64dfd8",
    "status": "RUNNING",
    "input": {
      "image_url": "https://triverse-public.oss-cn-beijing.aliyuncs.com/tasks/.../input.png",
      "model_version": "v2",
      "polygon_limit": 1000000,
      "texture_size": 1024
    },
    "output": {
      "geometry_job_status": "COMPLETED",
      "texture_job_status": "IN_PROGRESS",
      "preprocessed_image_url": [
        "https://triverse-public.oss-cn-beijing.aliyuncs.com/tasks/.../preprocessed_input_image_0.png"
      ],
      "geometry_model_url": [
        "https://triverse-public.oss-cn-beijing.aliyuncs.com/tasks/.../textureless_model_0.glb"
      ],
      "textured_model_url": null
    },
    "createTime": "2025-08-05T12:39:48.228522Z"
  }
}

Download Response (`DownloadResponse`)

This payload is returned by GET /api/v1/tasks/url/{task_uuid} and provides URLs for downloading generated assets.

Field	Type	Description
`download_url`	String	A direct URL to download the asset file.
`preview_url`	String	(Optional) A URL to a preview image of the asset.
`asset_id`	UUID	(Optional) The unique identifier for the asset.
`kind`	String	(Optional) The type of asset (e.g., `model`, `image`).

Example:

{
  "code": 0,
  "message": "success",
  "data": {
    "download_url": "https://triverse-public.oss-cn-beijing.aliyuncs.com/tasks/.../model.glb",
    "preview_url": "https://triverse-public.oss-cn-beijing.aliyuncs.com/tasks/.../preview.png",
    "asset_id": "c3b5b8a0-5b1f-4b7e-8c1a-9a8b7c6d5e4f",
    "kind": "model"
  }
}

Common Response Structures

Task Creation Response Payload (TaskCreationResponsePayload)

Flow Status Payload (FlowStatusPayload)

Download Response (DownloadResponse)

On this page

Task Creation Response Payload (`TaskCreationResponsePayload`)

Flow Status Payload (`FlowStatusPayload`)

Download Response (`DownloadResponse`)