API quickstart

1. Activate an endpointCopy Anchor Link

Subscribe to Plus or Pro. Blobz creates one active endpoint for the account after Dodo confirms the first successful payment. Checkout redirects alone do not grant access.

Copy the endpoint URL from the dashboard. Customers do not create API keys and do not need an Authorization header.

2. Approve the website originCopy Anchor Link

Add the exact origin that will embed the image:

https://app.example.com

An origin is only the scheme, hostname, and optional port. Do not include a path, query, fragment, or wildcard. Production origins must use HTTPS. HTTP is accepted only for localhost and 127.0.0.1 during development.

3. Add the imageCopy Anchor Link

<img
  src="https://YOUR_BLOBZ_HOST/api/v1/avatars/ENDPOINT_ID?name=Janaki&amp;frame=rounded&amp;palette=%23f2f1f4%2C%237c6cf2&amp;size=80"
  crossorigin="anonymous"
  width="80"
  height="80"
  alt="Janaki avatar"
/>

crossorigin="anonymous" is required. It makes the cross-origin image request use CORS and send the page's Origin header. The server echoes an approved origin in Access-Control-Allow-Origin.

Query parametersCopy Anchor Link

Unknown parameters, repeated parameters, missing name, malformed colours, and out-of-range sizes return 422. The full URL may not exceed 4096 characters.

URL constructionCopy Anchor Link

Use URL and URLSearchParams instead of string concatenation:

const imageUrl = new URL(
  "/api/v1/avatars/ENDPOINT_ID",
  "https://YOUR_BLOBZ_HOST",
);

imageUrl.searchParams.set("name", user.id);
imageUrl.searchParams.set("frame", "circle");
imageUrl.searchParams.set("palette", "#eef9ff,#38bdf8");
imageUrl.searchParams.set("size", "96");

When writing literal HTML, escape query separators as &. JSX accepts the normal URL string.