Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
// POST /api/v1/ai/image — text→image for agents, over x402.
//
// Productizes the platform's text→image lanes (api/_mcp3d/text-to-image.js:
// NVIDIA NIM FLUX, Google Vertex/Gemini image, Replicate backstop) as a single
// versioned, bazaar-discoverable endpoint with a free daily quota funnel:
//
// • First N images/day per IP are FREE (payment bypassed). ← funnel
// • Past the quota, the call falls through to x402: $0.02 USDC/image. ← revenue
//
// A generated image is persisted to R2 by the lane itself and returned as a
// durable https URL. No API key, no account — an agent can try it wallet-free,
// then pay per image once it's past the free tier.
//
// GET /api/v1/ai/image → compact discovery doc (price, quota, lanes)
// GET /api/v1/ai/image?health=1 → per-lane configured/reachable, no quota burn
// POST /api/v1/ai/image → { prompt, aspect_ratio?, seed? } → image
//
// Honest degradation: with NO image lane configured the POST returns 503
// `not_configured` naming the env vars to set (NVIDIA_API_KEY /
// GOOGLE_CLOUD_PROJECT + GCP_SERVICE_ACCOUNT_JSON / REPLICATE_API_TOKEN); it
// starts serving the moment any one of them lands.
import { paidEndpoint } from '../../_lib/x402-paid-endpoint.js';
import { buildBazaarSchema } from '../../_lib/x402-spec.js';
import { installAccessControl } from '../../_lib/x402/access-control.js';
import { withService, declareHttpDiscovery } from '../../_lib/x402/bazaar-helpers.js';
import { priceFor } from '../../_lib/x402-prices.js';
import { cors, error, json, method, wrap, readBody } from '../../_lib/http.js';
import { clientIp } from '../../_lib/rate-limit.js';
import { textToImage } from '../../_mcp3d/text-to-image.js';
import {
imageLaneConfig,
imageLaneHealth,
missingLaneEnv,
dimensionsFor,
providerLabel,
isProviderRefusal,
refusalReason,
SUPPORTED_ASPECT_RATIOS,
} from '../../_lib/ai-image-lanes.js';
import { peekFreeQuota, reserveFreeQuota, releaseFreeQuota, freePerDay } from '../../_lib/ai-image-quota.js';
import { isInlineImageRef } from '../../_lib/image-persist.js';
const ROUTE = '/api/v1/ai/image';
const PRICE_ATOMICS = priceFor('ai-image', '20000'); // $0.02 USDC per image above quota
const MAX_PROMPT = 2000;
const MIN_PROMPT = 3;
const MAX_SEED = 4_294_967_295; // uint32 — the widest seed the flux lanes accept
const MAX_BODY_BYTES = 16_384; // generous ceiling for a { prompt, aspect_ratio, seed } JSON body
// ── Bazaar discovery (uniqueness first) ──────────────────────────────────────
const DESCRIPTION =
'Text-to-image for agents over x402 — pay $0.02 USDC per image, no API key, ' +
'no account; runs on NVIDIA NIM / Google Vertex lanes. The first 5 images per ' +
'day per IP are free, then each image is a single on-chain USDC micropayment. ' +
'Returns a durable https URL to the rendered PNG/JPEG.';
const INPUT_EXAMPLE = { prompt: 'a brass owl figurine on a plain white background', aspect_ratio: '1:1' };
const INPUT_SCHEMA = {
$schema: 'https://json-schema.org/draft/2020-12/schema',
type: 'object',
required: ['prompt'],
properties: {
prompt: {
type: 'string',
minLength: MIN_PROMPT,
maxLength: MAX_PROMPT,
description: 'The image description to render.',
},
aspect_ratio: {
type: 'string',
enum: [...SUPPORTED_ASPECT_RATIOS],
default: '1:1',
description: 'Output aspect ratio. Defaults to 1:1.',
},
seed: {
type: 'integer',
minimum: 0,
maximum: MAX_SEED,
description: 'Optional deterministic seed (honored on the NIM / Replicate flux lanes; ignored by Vertex/Gemini, which has no seed parameter).',
},
},
};
const OUTPUT_EXAMPLE = {
url: 'https://three.ws/cdn/forge/refs/6f1c0c2e-2a4d-4b6e-9b1a-3c5d7e9f0a1b.jpg',
provider: 'nvidia-nim',
model: 'black-forest-labs/flux.1-schnell',
width: 1024,
height: 1024,
aspect_ratio: '1:1',
seed: null,
free: true,
quota: { used: 1, limit: 5, remaining: 4, resetAt: '2026-07-08T00:00:00.000Z' },
};
const OUTPUT_SCHEMA = {
$schema: 'https://json-schema.org/draft/2020-12/schema',
type: 'object',
required: ['url', 'provider', 'width', 'height'],
properties: {
url: { type: 'string', format: 'uri', description: 'Durable https URL to the rendered image.' },
provider: { type: 'string', description: 'Lane that served the image: nvidia-nim | vertex | replicate.' },
model: { type: 'string' },
width: { type: 'integer' },
height: { type: 'integer' },
aspect_ratio: { type: 'string' },
seed: { type: ['integer', 'null'] },
free: { type: 'boolean', description: 'True when served from the free daily quota (no payment).' },
quota: {
type: 'object',
properties: {
used: { type: 'integer' },
limit: { type: 'integer' },
remaining: { type: 'integer' },
resetAt: { type: 'string', format: 'date-time' },
},
},
},
};
const BAZAAR = declareHttpDiscovery({
method: 'POST',
bodyType: 'json',
input: INPUT_EXAMPLE,
inputSchema: INPUT_SCHEMA,
output: { example: OUTPUT_EXAMPLE, schema: OUTPUT_SCHEMA },
});
// ── Handler helpers ──────────────────────────────────────────────────────────
function badRequest(code, message) {
return Object.assign(new Error(message), { status: 400, code });
}
// Validate + normalize the request body. Throws a 400 on any client fault, so a
// paid caller is never charged for a malformed request (the throw lands before
// settlement) and a free caller never spends a quota slot on one.
function parseImageRequest(rawBody) {
let body;
try {
body = JSON.parse(rawBody || '{}');
} catch {
throw badRequest('invalid_json', 'Request body must be valid JSON.');
}
const prompt = typeof body?.prompt === 'string' ? body.prompt.trim() : '';
if (!prompt) throw badRequest('invalid_prompt', '"prompt" is required and must be a non-empty string.');
if (prompt.length < MIN_PROMPT) throw badRequest('invalid_prompt', `"prompt" must be at least ${MIN_PROMPT} characters.`);
if (prompt.length > MAX_PROMPT) throw badRequest('prompt_too_long', `"prompt" must be at most ${MAX_PROMPT} characters.`);
let aspectRatio = '1:1';
if (body?.aspect_ratio != null) {
aspectRatio = String(body.aspect_ratio);
if (!SUPPORTED_ASPECT_RATIOS.includes(aspectRatio)) {
throw badRequest('invalid_aspect_ratio', `"aspect_ratio" must be one of: ${SUPPORTED_ASPECT_RATIOS.join(', ')}.`);
}
}
let seed;
if (body?.seed != null) {
if (!Number.isInteger(body.seed) || body.seed < 0 || body.seed > MAX_SEED) {
throw badRequest('invalid_seed', `"seed" must be an integer between 0 and ${MAX_SEED}.`);
}
seed = body.seed;
}
return { prompt, aspectRatio, seed };
}
// Map a text-to-image lane error onto a designed HTTP status. A safety refusal
// is a terminal verdict about the prompt (422, never retried); a rate-limit /
// outage / billing failure is transient (429 / 503). The paidEndpoint wrapper
// turns any throw here into an error response WITHOUT settling, so the buyer is
// never charged for a failed generation.
function mapLaneError(err) {
if (isProviderRefusal(err)) {
return Object.assign(new Error(refusalReason(err)), { status: 422, code: 'content_refused' });
}
if (err?.code === 'unconfigured') {
return Object.assign(
new Error(`No image lane is configured. Set one of: ${missingLaneEnv().join(', ')}.`),
{ status: 503, code: 'not_configured' },
);
}
if (err?.code === 'rate_limited') {
const retryAfter = Number.isFinite(err.retryAfter) ? err.retryAfter : 10;
return Object.assign(new Error('Image generation is briefly busy — retry shortly.'), {
status: 429,
code: 'rate_limited',
retryAfter,
});
}
if (err?.code === 'provider_unreachable' || err?.code === 'billing') {
return Object.assign(new Error('The image lane is temporarily unavailable — retry shortly.'), {
status: 503,
code: 'lane_unavailable',
});
}
return Object.assign(new Error(err?.message || 'Image generation failed.'), {
status: 502,
code: 'generation_failed',
});
}
// Generate one image and shape the response. Shared by the free-bypass path and
// the paid path — `free` distinguishes them so the response is honest about
// whether a payment happened, and the quota slot is spent ONLY on the free path
// and ONLY after a real image is delivered.
async function generateAndRespond({ prompt, aspectRatio, seed }, { free, ip }) {
const config = imageLaneConfig();
if (!config.anyConfigured) {
throw Object.assign(
new Error(`No image lane is configured. Set one of: ${missingLaneEnv().join(', ')}.`),
{ status: 503, code: 'not_configured' },
);
}
// The free slot is reserved atomically BEFORE the (seconds-long, paid-upstream)
// generation, so a burst of concurrent requests from one IP cannot all pass the
// access-control peek and all generate. It is refunded if no image is delivered.
let quota = null;
if (free) {
quota = await reserveFreeQuota(ip);
if (!quota.granted) {
throw Object.assign(
new Error('The daily free image allowance for this address is used up. Pay per image with x402 to continue.'),
{ status: 429, code: 'free_quota_exhausted' },
);
}
}
try {
return await generateImage({ prompt, aspectRatio, seed }, { free, quota });
} catch (err) {
if (quota?.counted) await releaseFreeQuota(ip);
throw err;
}
}
async function generateImage({ prompt, aspectRatio, seed }, { free, quota }) {
let result;
try {
result = await textToImage(prompt, { aspectRatio, seed });
} catch (err) {
throw mapLaneError(err);
}
const url = result?.imageUrl;
// The lane drew the image but object storage refused to keep it, so the bytes
// came back inline (see api/_lib/image-persist.js). Our own workers read an
// inline reference happily; a third-party caller of this endpoint cannot,
// because the contract here is a durable https URL it can fetch later. So the
// honest answer is a transient storage fault, not "generation_failed". That
// told the caller to retry a prompt that was never the problem, and told the
// operator nothing at all while the R2 credential sat rejected for hours
// (2026-09-09, and again from 03:15 UTC on 2026-09-11).
if (isInlineImageRef(url)) {
throw Object.assign(
new Error('The image was generated but could not be stored: object storage is rejecting writes. Retry shortly.'),
// 5xx descriptions are redacted to a support ref on this route, so the
// machine-readable code is what a caller reacts to and the sentence is
// what the operator reads next to that ref in the logs.
{ status: 503, code: 'storage_unavailable' },
);
}
if (!url || !/^https?:\/\//.test(url)) {
throw Object.assign(new Error('Image lane returned no usable image URL.'), {
status: 502,
code: 'generation_failed',
});
}
const { width, height } = dimensionsFor(aspectRatio);
return {
url,
provider: providerLabel(result),
model: result.model || null,
width,
height,
aspect_ratio: aspectRatio,
seed: Number.isInteger(seed) ? seed : null,
free: Boolean(free),
...(quota ? { quota: { used: quota.used, limit: quota.limit, remaining: quota.remaining, resetAt: quota.resetAt } } : {}),
};
}
// ── Paid endpoint (free-quota funnel → x402) ─────────────────────────────────
const paidImage = paidEndpoint({
route: ROUTE,
method: 'POST',
priceAtomics: PRICE_ATOMICS,
networks: ['solana', 'base'],
description: DESCRIPTION,
bazaar: BAZAAR,
service: withService({
serviceName: 'three.ws AI Image',
tags: ['image', 'text-to-image', 'ai', 'agent', 'solana'],
}),
requiredScope: 'x402:bypass',
// Free-tier funnel: an IP still under its daily quota bypasses payment. The
// slot is only spent AFTER a real image ships (in generateAndRespond), so a
// validation error / refusal / outage never burns a free generation. Peek is
// read-only and fails open, so a Redis hiccup can't wrongly demand payment.
accessControl: installAccessControl({
requiredScope: 'x402:bypass',
resolveCaller: async ({ req }) => {
const ip = clientIp(req);
const q = await peekFreeQuota(ip);
if (q.allowed) {
return { grantAccess: true, reason: 'ai_image_free_daily', callerId: `ip:${ip}` };
}
return null;
},
}),
async handler({ req, bypass }) {
const buf = await readBody(req, MAX_BODY_BYTES);
const parsed = parseImageRequest(buf.toString('utf8'));
const free = bypass?.reason === 'ai_image_free_daily';
return generateAndRespond(parsed, { free, ip: clientIp(req) });
},
});
// ── GET surfaces: discovery + health (both free, no quota burn) ──────────────
const health = wrap(async (req, res) => {
if (cors(req, res, { methods: 'GET,OPTIONS' })) return;
if (!method(req, res, ['GET'])) return;
const report = await imageLaneHealth();
return json(res, report.configured ? 200 : 503, { ...report, generated_at: new Date().toISOString() });
});
const discovery = wrap(async (req, res) => {
if (cors(req, res, { methods: 'GET,OPTIONS' })) return;
if (!method(req, res, ['GET'])) return;
const config = imageLaneConfig();
return json(res, 200, {
route: ROUTE,
method: 'POST',
description: DESCRIPTION,
free_tier: { images_per_day_per_ip: freePerDay(), then: 'x402 pay-per-image' },
price_usdc: (Number(PRICE_ATOMICS) / 1e6).toFixed(6),
price_atomics: String(PRICE_ATOMICS),
networks: ['solana', 'base'],
input: INPUT_SCHEMA,
output_example: OUTPUT_EXAMPLE,
lanes_configured: { nim: config.nim, vertex: config.vertex, replicate: config.replicate },
health: `${ROUTE}?health=1`,
});
});
// Single default export multiplexes the path: GET ?health=1 → health probe,
// other GET → discovery doc, everything else → the paid POST endpoint (which
// owns CORS/method enforcement, the free-quota bypass, and the 402 challenge).
export default function handler(req, res) {
if (req.method === 'GET') {
let hasHealth = false;
try {
hasHealth = new URL(req.url, 'http://localhost').searchParams.has('health');
} catch { /* malformed url → treat as discovery */ }
return hasHealth ? health(req, res) : discovery(req, res);
}
// Honest degradation: with NO image lane configured, answer every POST with a
// clean 503 that NAMES the env vars to set — before the payment dance, so a
// buyer is never challenged (or charged) for a good we cannot deliver. This
// runs here rather than inside the paid handler because a handler throw for a
// 5xx is sanitized to a generic "internal error" by the error boundary, which
// would hide the actionable env-var list. The moment any lane env lands, this
// check passes and the funnel (free quota → 402) takes over unchanged.
if (req.method === 'POST' && !imageLaneConfig().anyConfigured) {
if (cors(req, res, { methods: 'POST,OPTIONS' })) return;
return error(
res,
503,
'not_configured',
`No image lane is configured. Set one of: ${missingLaneEnv().join(', ')}.`,
);
}
return paidImage(req, res);
}