Skip to content

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.

7.8 KB
Raw Blame
// POST /api/vroid/import: pull one VRoid Hub character model into the
// caller's three.ws avatar library.
//
// Download flow (developer.vroid.com/en/api/load-character.html, verified
// live): POST /api/download_licenses {character_model_id} mints a
// DownloadLicense, then GET /api/download_licenses/{id}/download 302s to an
// S3 presigned URL that serves the actual VRM/GLB bytes. Both calls live in
// api/_lib/vroid/client.js.
//
// License enforcement (task 3 of 092-partners-09-vroid-hub-import.md): the
// import itself is always allowed (a creator's own download license already
// cleared that), but what three.ws lets the *imported avatar* do afterward
// (become a public agent, be exported again, be modified, be monetized) is
// gated by api/_lib/vroid/license.js and stored on the avatar so every later
// surface (agent creation, export, the garment/remesh tools, marketplace
// listing) can re-check it without another Hub round trip.

import { getSessionUser } from '../_lib/auth.js';
import { cors, json, method, error, readJson, wrap } from '../_lib/http.js';
import { requireCsrf } from '../_lib/csrf.js';
import { limits } from '../_lib/rate-limit.js';
import { vroidConfigured } from '../_lib/vroid/config.js';
import { hubGet, issueDownloadLicense, resolveDownloadUrl, CHARACTER_MODEL_PATH } from '../_lib/vroid/client.js';
import { getValidVroidToken } from '../_lib/vroid/token-store.js';
import { evaluateLicense, creditLineFor } from '../_lib/vroid/license.js';
import { createAvatar, storageKeyFor, enforceQuotas, isPlanLimitError } from '../_lib/avatars.js';
import { putObject } from '../_lib/r2.js';
import { isValidGlbHeader } from '../_lib/glb-inspect.js';
import { sha256 } from '../_lib/crypto.js';
import { slug as slugSchema } from '../_lib/validate.js';

const MAX_IMPORT_BYTES = 200 * 1024 * 1024;
const DOWNLOAD_TIMEOUT_MS = 60_000;

function slugFor(name) {
	const base = String(name || 'vroid-avatar')
		.toLowerCase()
		.replace(/[^a-z0-9]+/g, '-')
		.replace(/^-+|-+$/g, '')
		.slice(0, 48);
	const candidate = base || 'vroid-avatar';
	return slugSchema.safeParse(candidate).success ? candidate : 'vroid-avatar';
}

async function downloadBytes(url) {
	const ac = new AbortController();
	const timer = setTimeout(() => ac.abort(), DOWNLOAD_TIMEOUT_MS);
	try {
		const res = await fetch(url, { signal: ac.signal });
		if (!res.ok) {
			const err = new Error(`VRoid Hub file download returned HTTP ${res.status}`);
			err.status = 502;
			throw err;
		}
		const contentLength = Number(res.headers.get('content-length'));
		if (Number.isFinite(contentLength) && contentLength > MAX_IMPORT_BYTES) {
			const err = new Error('model exceeds the maximum importable size');
			err.status = 413;
			throw err;
		}
		const ab = await res.arrayBuffer();
		if (ab.byteLength > MAX_IMPORT_BYTES) {
			const err = new Error('model exceeds the maximum importable size');
			err.status = 413;
			throw err;
		}
		return Buffer.from(ab);
	} finally {
		clearTimeout(timer);
	}
}

export default wrap(async (req, res) => {
	if (cors(req, res, { methods: 'POST,OPTIONS', credentials: true })) return;
	if (!method(req, res, ['POST'])) return;

	if (!vroidConfigured()) {
		return error(res, 501, 'not_configured', 'VRoid Hub is not connected on this deployment yet');
	}

	const session = await getSessionUser(req);
	if (!session) return error(res, 401, 'unauthorized', 'sign in required');
	if (!(await requireCsrf(req, res, session.id))) return;

	const rl = await limits.upload(session.id);
	if (!rl.success) return error(res, 429, 'rate_limited', 'too many imports, try again shortly');

	const body = await readJson(req).catch(() => ({}));
	const characterModelId = typeof body.character_model_id === 'string' ? body.character_model_id.trim() : '';
	if (!characterModelId) return error(res, 400, 'bad_request', 'character_model_id is required');

	const accessToken = await getValidVroidToken(session.id);
	if (!accessToken) {
		return error(res, 409, 'not_connected', 'connect your VRoid Hub account first', {
			connect_url: '/api/auth/vroid/connect',
		});
	}

	let detail;
	try {
		detail = await hubGet(CHARACTER_MODEL_PATH(characterModelId), accessToken);
	} catch (err) {
		return error(res, err.status || 502, err.code || 'upstream_error', err.message || 'could not load that model from VRoid Hub');
	}
	const model = detail?.character_model;
	if (!model) return error(res, 404, 'not_found', 'VRoid Hub has no model with that id');
	if (model.is_downloadable === false) {
		return error(res, 403, 'not_downloadable', 'the creator has not made this model downloadable');
	}

	const evaluated = evaluateLicense(model.license);
	const creatorName = model.character?.user?.name || null;
	const characterName = model.name || model.character?.name || null;

	let downloadLicense;
	try {
		downloadLicense = await issueDownloadLicense(characterModelId, accessToken);
	} catch (err) {
		return error(res, err.status || 502, err.code || 'license_failed', err.message || 'VRoid Hub refused to issue a download license for this model');
	}

	let downloadUrl;
	try {
		downloadUrl = await resolveDownloadUrl(downloadLicense.id, accessToken);
	} catch (err) {
		return error(res, err.status || 502, err.code || 'download_failed', err.message || 'VRoid Hub did not return a download link');
	}

	let buffer;
	try {
		buffer = await downloadBytes(downloadUrl);
	} catch (err) {
		return error(res, err.status || 502, err.code || 'download_failed', err.message || 'failed to download the model file');
	}

	if (!isValidGlbHeader(buffer)) {
		return error(res, 415, 'invalid_glb', 'VRoid Hub did not return a valid binary glTF (GLB) file');
	}

	// Canonicalize bone names + up-axis orientation at ingest, same as every
	// other import path (api/avatars/_actions.js handleUpload), so the stored
	// GLB shares one convention regardless of source. VRoid exports VRM, whose
	// humanoid bone map glb-canonicalize.js already recognizes.
	try {
		const { canonicalizeGLBBones } = await import('../../src/glb-canonicalize.js');
		const ab = buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength);
		const canonical = canonicalizeGLBBones(ab);
		if (canonical.renamed > 0 || canonical.orientationCorrected) {
			buffer = Buffer.from(canonical.buffer);
		}
	} catch (err) {
		console.warn('[vroid-import] canonicalize skipped:', err?.message);
	}

	const checksum = await sha256(buffer);
	const name = characterName || 'VRoid Hub avatar';
	const slug = slugFor(name);
	const storageKey = storageKeyFor({ userId: session.id, slug });

	try {
		await enforceQuotas(session.id, buffer.length);
	} catch (err) {
		return error(res, err.status || 402, err.code || 'plan_limit', err.message);
	}

	try {
		await putObject({ key: storageKey, body: buffer, contentType: 'model/gltf-binary' });

		const avatar = await createAvatar({
			userId: session.id,
			storageKey,
			input: {
				name,
				description: creatorName ? `Imported from VRoid Hub, created by ${creatorName}.` : 'Imported from VRoid Hub.',
				visibility: 'private',
				tags: ['vroid-hub'],
				source: 'vroid_hub',
				source_meta: {
					character_model_id: characterModelId,
					creator_name: creatorName,
					character_name: characterName,
					license: evaluated.license,
					actions: evaluated.actions,
					credit_required: evaluated.creditRequired,
					credit_line: creditLineFor({ creatorName, characterName }),
					license_url: evaluated.licenseUrl,
					imported_at: new Date().toISOString(),
				},
				content_type: 'model/gltf-binary',
				size_bytes: buffer.length,
				checksum_sha256: checksum,
			},
		});

		return json(res, 200, { avatar, edit_url: `/avatars/${avatar.id}/edit` });
	} catch (err) {
		if (isPlanLimitError(err)) {
			return error(res, 402, err.code || 'plan_limit', err.message);
		}
		console.error('[vroid-import] failed', err?.message || err);
		return error(res, err.status || 500, err.code || 'import_failed', err.message || 'import failed');
	}
});