TRIVERSE Docs
API Endpoints

Upload Files

The Upload Files resource group handles file ingestion for the Triverse API. You can upload images for reference or 3D models for texturing and conversion. We support both direct multipart uploads and high-efficiency presigned URL uploads.

Upload Image

Upload an image file to be used as a reference for 3D generation. This endpoint includes automatic content moderation and rate limiting.

Endpoint

POST /upload/image

Request Body

multipart/form-data

  • file (Required): The image file to upload.

Constraints

  • Supported Formats: image/jpeg, image/png, image/webp.
  • Max Size: 50MB.
  • Rate Limit: 10 uploads per 60 seconds (combined with model uploads).

Response

Returns a file_key which is used to reference the file in subsequent generation tasks.

{
  "code": 0,
  "message": "success",
  "data": {
    "file_key": "tasks/uid_<USER_ID>/20250101/<uuid>.png"
  }
}

Example Request

cURL

curl -X POST \
  'https://api.triverse.ai/api/v1/upload/image' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -F 'file=@image.png;type=image/png'

Python

import requests

with open("image.png", "rb") as file_obj:
    response = requests.post(
        "https://api.triverse.ai/api/v1/upload/image",
        headers={"Authorization": "Bearer <YOUR_API_KEY>"},
        files={"file": ("image.png", file_obj, "image/png")},
    )
print(response.json())

Upload Model

Upload a 3D model file (geometry or textured) for further processing.

Endpoint

POST /upload/model

Query Parameters

  • modelVariant (Optional): Either geometry or textured.

Request Body

multipart/form-data

  • file (Required): The model file (e.g., .glb, .obj).

Constraints

  • Max Size: 200MB.
  • Rate Limit: Shared with image uploads (10 per 60s).

Example Request

cURL

curl -X POST \
  'https://api.triverse.ai/api/v1/upload/model?modelVariant=geometry' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -F 'file=@model.glb;type=model/gltf-binary'

JavaScript

import fs from "node:fs";

const formData = new FormData();
const fileBuffer = fs.readFileSync("model.glb");
formData.append(
  "file",
  new Blob([fileBuffer], { type: "model/gltf-binary" }),
  "model.glb"
);

const response = await fetch(
  "https://api.triverse.ai/api/v1/upload/model?modelVariant=geometry",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer <YOUR_API_KEY>",
    },
    body: formData,
  }
);
const data = await response.json();
console.log(data);

Python

import requests

with open("model.glb", "rb") as file_obj:
    response = requests.post(
        "https://api.triverse.ai/api/v1/upload/model",
        params={"modelVariant": "geometry"},
        headers={"Authorization": "Bearer <YOUR_API_KEY>"},
        files={"file": ("model.glb", file_obj, "model/gltf-binary")},
    )
print(response.json())

Presigned Upload URL

For larger files or more robust integrations, you can request a presigned URL to upload directly to our cloud storage. This bypasses the API server for the actual file transfer, improving reliability.

Endpoint

POST /upload/presigned-upload-url

Request Body

{
  "filename": "my_model.glb"
}

Workflow

  1. Request URL: Call this endpoint to get an upload_url and a file_key.
  2. Direct Upload: Perform an HTTP PUT request to the upload_url with the file's binary data.
  3. Use File: Use the file_key in your generation task request.

Example (Python)

import requests

# 1. Get the presigned URL
res = requests.post(
    "https://api.triverse.ai/api/v1/upload/presigned-upload-url",
    headers={"Authorization": "Bearer <YOUR_API_KEY>"},
    json={"filename": "model.glb"}
).json()

upload_url = res["data"]["upload_url"]
file_key = res["data"]["file_key"]

# 2. Upload the file directly
with open("model.glb", "rb") as f:
    requests.put(upload_url, data=f, headers={"Content-Type": "model/gltf-binary"})

print(f"Uploaded! File Key: {file_key}")

Presigned Download URL

Generate a temporary, secure link to download an existing asset.

Endpoint

POST /upload/presigned-get-url

Request Body

FieldTypeDescription
file_keyString(Required) The unique key of the file.
filenameString(Optional) The name to use for the downloaded file.

Example Request

cURL

curl -X 'POST' \
  'https://api.triverse.ai/api/v1/upload/presigned-get-url' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "file_key": "tasks/uid_123/20250101/abcd.png",
  "filename": "my_file.png"
}'

JavaScript

const response = await fetch(
  "https://api.triverse.ai/api/v1/upload/presigned-get-url",
  {
    method: "POST",
    headers: {
      Accept: "application/json",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      file_key: "tasks/uid_123/20250101/abcd.png",
      filename: "my_file.png",
    }),
  }
);
const data = await response.json();
console.log(data);

Python

import requests

response = requests.post(
    "https://api.triverse.ai/api/v1/upload/presigned-get-url",
    headers={"Accept": "application/json"},
    json={
        "file_key": "tasks/uid_123/20250101/abcd.png",
        "filename": "my_file.png",
    },
)
print(response.json())

User Management

Manage and query user account information, including credit balances and subscription details.

Text to 3D

Generate 3D models and geometries directly from natural text prompts.

On this page

Upload FilesUpload ImageEndpointRequest BodyConstraintsResponseExample RequestUpload ModelEndpointQuery ParametersRequest BodyConstraintsExample RequestPresigned Upload URLEndpointRequest BodyWorkflowExample (Python)Presigned Download URLEndpointRequest BodyExample Request