Quickstart

Tagging your first 3D asset using our public API

๐Ÿ“˜

This guide will get you started with tagging your first asset using our 3D Tagging API. For a no-code way to try out our tags, visit our Playground.

1: Sign up for a Loci account

If you havenโ€™t already, sign up for an account with Loci. Each account is preloaded with 100 free credits, so you can get started straight away.

2: Grab your API key

To make a tagging request, you will need your API key. You can find it under Account & Billing in the Dashboard.

3: Tag your first asset

๐Ÿšง

Loci supports a wide range of 3D asset types. You can find out more about what our 3D Tagging Endpoint supports here.

We will now send a 3D asset to our endpoint for tagging! If you don't have one handy, you can find a nice variety of assets available for free download here.

We will be sending the asset to our tagging endpoint at https://prod.loci-api.com/tag/tag-3d-asset. Our endpoint supports both direct asset upload, and linking to external (pre-hosted) asset URLs. For the purposes if this tutorial, we will be using the direct upload functionality. You can find the full specification of our tagging endpoint here.

Below are prepared code snippets for Python, Node.js and C#, where we send an asset to our endpoint, being sure to set our API key in the header using x-api-key.

from pprint import pprint

import requests

API_URL = "https://prod.loci-api.com/tag/tag-3d-asset"
API_KEY = ""  # your API key
ASSET_FILE = "/path/to/my_asset_file.glb"

with open(ASSET_FILE, "rb") as file:
    response = requests.post(API_URL, headers={"x-api-key": API_KEY}, files={"asset_file": file})

pprint(response.json())
const axios = require('axios');
const FormData = require('form-data');
const fs = require('fs');

const url = "https://prod.loci-api.com/tag/tag-3d-asset";
const filePath = "/path/to/my_asset_file.glb";

const form = new FormData();
form.append('asset_file', fs.createReadStream(filePath));

const headers = {
    ...form.getHeaders(),
    "x-api-key": "<<x-api-key>>",
};

axios.post(url, form, { headers })
  .then(response => {
    console.log(response.data);
  })
  .catch(error => {
    console.error('Error:', error);
  });

 
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        // Setup
        var url = "https://prod.loci-api.com/tag/tag-3d-asset";
        var filePath = "/path/to/my_asset_file.glb";

        using (var client = new HttpClient())
        using (var content = new MultipartFormDataContent())
        {
            content.Add(new StreamContent(File.OpenRead(filePath)), "asset_file", "my_asset_file.glb");

            client.DefaultRequestHeaders.Add("x-api-key", "<<x-api-key>>");

            // Optional parameters
            content.Add(new StringContent("my_asset_name"), "asset_name");
            // Add other parameters as needed

            // Call API
            var response = await client.PostAsync(url, content);

            // Process Response
            Console.WriteLine(await response.Content.ReadAsStringAsync());
        }
    }
}

In return, we will send you back the tags for your asset, as well as a host of other useful data such as detected colors, textures and other metadata about your file.

{
  "filename": "my_test_asset.glb",
  "tags": [
    "mythological creature",
    "fantasy creature",
    "superhero",
    "jumpsuit",
    "standing",
  ],
  "colors": [
    {
      "name": "Brown > Maroon",
      "rgb": [
        128,
        0,
        0
      ],
      "hex_code": "#800000",
      "proportion": 0.5615
    },
    {
      "name": "Gray > Black",
      "rgb": [
        0,
        0,
        0
      ],
      "hex_code": "#000000",
      "proportion": 0.3476
    }
  ],
  "metadata": {
    "num_vertices": 16544,
    "num_edges": 38341,
    "num_polygons": 22497,
    "num_submeshes": 7,
    "num_animations": 0,
    "animation_names": [],
    "num_materials": 1,
    "materials_names": [
      "material_1",
    ],
    "num_texture_images": 1,
    "texture_names": [
      "Image_1",
    ],
    "mesh_names": [
      "Object_8",
    ]
  }
}

It's that simple to start tagging with Loci! For a deeper dive into our API, you can view our Public API Documentation or Tutorials Section.

While our freeform tagging API is the perfect fit for many use cases, there are instances where may wish to tag your assets with specific classes through the use of customised taxonomies. You can read more about our Custom Classification product here.


Whatโ€™s Next