Avatars API

The Avatars API allows you to generate 3D avatar models in GLB format based on configuration data. This is the core endpoint for creating avatars programmatically.

POST /api/process

This is the primary endpoint for generating a 3D avatar. It takes a configuration object and returns a binary .glb file ready for use in your application.

Request Headers

Request Body

The request body should be sent as multipart/form-data with a field named options containing a JSON-stringified configuration object.

Request Payload Structure

{
  "data": {
    "assets": {
      "gender": "male",           // Required: "male" or "female"
      "faceShape": "49918702",     // Required: Asset ID
      "eyeShape": "49919164",      // Required: Asset ID
      "noseShape": "49918836",     // Required: Asset ID
      "lipShape": "50094598",      // Required: Asset ID
      "skinColor": "0",            // Optional: Color index
      "hairStyle": "50012345",     // Optional: Asset ID
      "hairColor": "2",            // Optional: Color index
      "eyeColor": "50011111",      // Optional: Asset ID
      "shirt": "50022222",         // Optional: Asset ID
      "outfit": "50033333",        // Optional: Asset ID (overrides shirt)
      "glasses": "50044444",       // Optional: Asset ID
      "headWear": "50055555",      // Optional: Asset ID
      // ... more optional assets
    }
  }
}

Example: JavaScript/TypeScript

import { auth } from './firebase';

async function generateAvatar(avatarConfig) {
  const user = auth.currentUser;
  if (!user) throw new Error('User not authenticated');
  
  const token = await user.getIdToken();
  
  const formData = new FormData();
  formData.append('options', JSON.stringify({
    data: {
      assets: avatarConfig
    }
  }));
  
  const response = await fetch('https://glb.streamoji.com/api/process', {
    method: 'POST',
    headers: {
      // The token is handled internally by the library if using the provided apiUtils,
      // but if calling directly, you still need the header:
      'Authorization': `Bearer ${token}`
    },
          body: formData
  });

          if (!response.ok) {
    throw new Error(`Avatar generation failed: ${response.status}`);
  }

          // Response is a binary GLB file
          const blob = await response.blob();
          const glbUrl = URL.createObjectURL(blob);

          return glbUrl;
}

          // Usage
          const config = {
            gender: "male",
          faceShape: "49918702",
          eyeShape: "49919164",
          noseShape: "49918836",
          lipShape: "50094598",
          hairStyle: "50012345",
          hairColor: "2"
};

const avatarUrl = await generateAvatar(config);

Example: Using Avatar ID

If you've previously saved an avatar configuration, you can generate it using just the avatar ID:

async function generateAvatarById(avatarId) {
  const user = auth.currentUser;
  const token = await user.getIdToken();
  
  const response = await fetch(
    `https://glb.streamoji.com/api/process?avatarId=${avatarId}`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${token}`
      }
    }
  );
  
  if (!response.ok) {
    throw new Error(`Avatar generation failed: ${response.status}`);
  }
  
  return await response.blob();
}

Response

On success, the API returns a binary GLB file with Content-Type: model/gltf-binary.

Error Response Format

{
  "error": "Error message describing what went wrong",
  "code": "ERROR_CODE"
}

POST /api/render-thumbnail

Generate a high-quality 2D thumbnail image of an avatar without generating the full 3D model. Useful for previews and gallery views.

Request Format

Same as /api/process, but returns a PNG image instead of a GLB file.

Example

async function renderThumbnail(avatarConfig) {
  // Use the internalized apiUtils.ts which handles token retrieval:
  // const thumbnail = await renderThumbnail(avatarConfig);
  // return thumbnail;

  // OR if calling the API directly:
  const user = auth.currentUser;
  const token = await user.getIdToken();
  
  const formData = new FormData();
  formData.append('options', JSON.stringify({
    data: { assets: avatarConfig }
  }));
  
  const response = await fetch(
    'https://glb.streamoji.com/api/render-thumbnail',
    {
      method: 'POST',
      headers: { 'Authorization': `Bearer ${token}` },
      body: formData
    }
  );
  
  const blob = await response.blob();
  return URL.createObjectURL(blob); 
}

Response

Returns a PNG image with Content-Type: image/png.