API reference

Get an avatar bundle

Fetch the runtime bundle the renderer draws an avatar from.

Fetch the runtime bundle for an avatar: the assets and configuration the renderer needs to draw it.

GEThttps://api.zeroweight.ai/api/v1/avatars/bundle/{avatar_id}

Parameters#

avatar_idstringrequired

Path parameter. The avatar’s unique identifier.

Authenticate with X-ZW-Api-Key, as with every REST route here.

Access rules#

Case	Allowed
You own the avatar	Always.
The avatar is public	Yes, with any valid API key.
The avatar’s status is not available	No. 403, whoever is asking.

Example#

curl -H "X-ZW-Api-Key: $ZEROWEIGHT_API_KEY" \
  https://api.zeroweight.ai/api/v1/avatars/bundle/avatar_123

200 OKjson

{ "payload": "<encrypted-payload-string>" }

Hand payload straight to renderer.init(canvas, { payload }). It is opaque: nothing in your code should parse it.

A browser must not hold your API key, so put a route of your own in front of this one. It is also the right place to cache: a bundle changes rarely and is the largest thing you will fetch, while the REST routes are rate-limited at 200 requests per minute per IP.

app/api/avatar-bundle/[avatarId]/route.ts

export async function GET(
  _request: Request,
  { params }: { params: Promise<{ avatarId: string }> },
) {
  const { avatarId } = await params;

  const response = await fetch(
    `https://api.zeroweight.ai/api/v1/avatars/bundle/${avatarId}`,
    { headers: { "X-ZW-Api-Key": process.env.ZEROWEIGHT_API_KEY! } },
  );

  return new Response(await response.text(), {
    status: response.status,
    headers: {
      "Content-Type": "application/json",
      // A bundle is immutable in practice. Caching it is the difference
      // between one upstream fetch and one per visitor.
      "Cache-Control": "public, max-age=300, stale-while-revalidate=3600",
    },
  });
}

Add your own authorisation to that route. It is your endpoint: whoever can call it can fetch the bundle, and your user model is the only thing that knows whether they should.

Errors#

Errors follow the shape { "detail": "…" }.

Status	detail
`401`	Invalid API key
`403`	Avatar is no longer available
`404`	Avatar not found
`429`	Rate limit exceeded