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 (PublicTaskCreationPayload)

All task creation endpoints (for example Image to 3D and Text to 3D) return a StandardResponse containing this payload. It provides the stable public fields needed to track a newly created task. Creation responses intentionally do not include the original input payload or internal scheduling fields.

Example:

{
  "code": 0,
  "message": "success",
  "data": {
    "task_uuid": "92483a80-236c-4889-9a95-4c90bb64dfd8",
    "flow_name": "image-to-model",
    "status": "PENDING",
    "created_at": "2026-05-27T12:39:48.228522Z",
    "cost_credits": 120,
    "queue": {
      "is_queued": false,
      "position": null,
      "estimated_wait_seconds": null
    }
  }
}

Task Pricing Quote Payload (PublicTaskPricingQuotePayload)

POST /api/v1/tasks/pricing/quote returns a StandardResponse containing this payload. It lets API-key callers check the API-credit cost and current available API-credit balance before creating a task. The quote endpoint does not create a task, freeze credits, dispatch Prefect, run queue checks, or run content moderation.

Example:

{
  "code": 0,
  "message": "success",
  "data": {
    "flow_name": "image-generation",
    "params": {
      "ai_model": "seedream_4_5",
      "image_count": 4
    },
    "cost_credits": 16,
    "available_credits": 120
  }
}

Task Status Payload (PublicTaskStatusPayload)

This payload is returned by GET /api/v1/tasks/{task_uuid} and pushed via WebSocket updates. It exposes only public task state, public request input, public output assets, and public error details.

Example:

{
  "code": 0,
  "message": "success",
  "data": {
    "task_uuid": "92483a80-236c-4889-9a95-4c90bb64dfd8",
    "flow_name": "image-to-model",
    "status": "SUCCESS",
    "progress": 100,
    "created_at": "2026-05-27T12:39:48.228522Z",
    "started_at": "2026-05-27T12:40:03.000000Z",
    "completed_at": "2026-05-27T12:48:10.000000Z",
    "input": {
      "image_url": "https://triverse-public.oss-cn-beijing.aliyuncs.com/tasks/.../input.png",
      "model_version": "v2",
      "polygon_limit": 1000000,
      "texture_size": 1024
    },
    "output": {
      "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": [
        "https://triverse-public.oss-cn-beijing.aliyuncs.com/tasks/.../textured_model_0.glb"
      ],
      "preview_url": "https://triverse-public.oss-cn-beijing.aliyuncs.com/tasks/.../preview.png"
    },
    "error": null,
    "queue": null
  }
}

Generation status responses do not expose internal scheduler, worker, pricing manifest, analytics, tracking, or user-identifying fields. Fields such as flowRunId, rawPrefectState, statusDetail, userId, workQueueName, deploymentId, pricingSnapshot, and analytics context are not part of the public contract. Internal queue-like states such as QUEUING are normalized to the public QUEUED status.

Web Own Models Item Payload (PublicOwnModelItemPayload)

GET /platform/generate/own-models returns paginated records[] using this public item payload. The payload is intentionally narrower than the internal generation task VO so Web clients cannot observe scheduler, billing, analytics, audit, or provider-only fields through the task list.

request_payload may include public inputs such as image_url, model_version, polygon_limit, texture_size, prompt, ai_model, image_count, model_file, target_face_count, face_type, and export_format. It must not include internal fields such as user_id, task_id, flow_run_id, pricing_snapshot, analytics context, rawPrefectState, statusDetail, provider IDs, scheduler queue fields, or lifecycle audit fields such as dispatched_at, queued_at, and expired_at.

Download Response (DownloadResponse)

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

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