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.

feat(sketchfab): add a dry-run-first backfill that tags pre-2026-10-09 uploads createdwithai, with tests and docs

nirholas309a22c284c7
diff --git a/docs/sketchfab.md b/docs/sketchfab.md
index b35bff5e9..fc9e07fa7 100644
--- a/docs/sketchfab.md
+++ b/docs/sketchfab.md
@@ -91,3 +91,21 @@ State lives in the `sketchfab_uploads` table (one row per creation:
when the brand-safety gate parked it). Code:
[`api/cron/sketchfab-showcase.js`](https://github.com/nirholas/three.ws/blob/main/api/cron/sketchfab-showcase.js)
and [`api/_lib/sketchfab.js`](https://github.com/nirholas/three.ws/blob/main/api/_lib/sketchfab.js).
+
+## Backfilling the AI tag on older uploads
+
+New uploads carry `createdwithai` from 2026-10-09 (commit `919e54e82`). Models the account
+published before that date do not, and Sketchfab can file them as "Human Created". The backfill
+script adds the tag to every model that lacks it and changes nothing else:
+
+```bash
+eval "$(node scripts/read-service-env.mjs '^SKETCHFAB_API_TOKEN$')"
+node scripts/sketchfab-retag.mjs # dry run: prints exactly what would change
+node scripts/sketchfab-retag.mjs --apply # PATCH /v3/models/{uid} for each model missing the tag
+node scripts/sketchfab-retag.mjs # second dry run: must report 0 to change
+```
+
+Without a token, `--user <username>` runs a read-only dry run against the public listing. Sketchfab
+replaces the whole tag list on PATCH, so each request carries the model's existing tags in order
+plus `createdwithai`, and nothing else. A `429` is retried after Sketchfab's `Retry-After`.
+Tests: `tests/sketchfab-retag.test.js`.
diff --git a/scripts/sketchfab-retag.mjs b/scripts/sketchfab-retag.mjs
new file mode 100644
index 000000000..7065a68e4
--- /dev/null
+++ b/scripts/sketchfab-retag.mjs
@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+// Backfill Sketchfab's "Created With AI" tag (slug `createdwithai`) onto models the
+// three.ws showcase account uploaded before commit 919e54e82 (2026-10-09), when new
+// uploads started carrying it. Dry run by default; --apply performs the edits.
+//
+// USAGE
+// node scripts/sketchfab-retag.mjs --user <sketchfab-username> # dry run, public listing
+// SKETCHFAB_API_TOKEN=... node scripts/sketchfab-retag.mjs # dry run, own account (/v3/me/models)
+// SKETCHFAB_API_TOKEN=... node scripts/sketchfab-retag.mjs --apply # make the changes
+//
+// The token is the same Data API token the showcase cron uses. Get it with:
+// eval "$(node scripts/read-service-env.mjs '^SKETCHFAB_API_TOKEN$')"
+//
+// Only the `tags` field is sent. Sketchfab's PATCH /v3/models/{uid} replaces the whole
+// tag list, so the request carries every existing tag plus `createdwithai`, in the
+// original order, and nothing else about the model is touched.
+
+import { pathToFileURL } from 'node:url';
+
+export const AI_TAG = 'createdwithai';
+const API_BASE = 'https://api.sketchfab.com/v3';
+const PAGE_SIZE = 24;
+const MAX_RETRIES = 5;
+
+export function tagNames(model) {
+ return (model.tags || []).map((t) => (typeof t === 'string' ? t : t.name)).filter(Boolean);
+}
+
+export function hasAiTag(model) {
+ return tagNames(model).some((n) => n.toLowerCase() === AI_TAG);
+}
+
+// The exact PATCH body for a model, or null when it already carries the tag.
+export function buildPatch(model) {
+ if (hasAiTag(model)) return null;
+ return { tags: [...tagNames(model), AI_TAG] };
+}
+
+// Plan the whole backfill: what would change and what is already compliant.
+export function planRetag(models) {
+ const changes = [];
+ let compliant = 0;
+ for (const m of models) {
+ const body = buildPatch(m);
+ if (body) changes.push({ uid: m.uid, name: m.name, url: m.viewerUrl, body });
+ else compliant++;
+ }
+ return { changes, compliant, total: models.length };
+}
+
+function sleep(ms) {
+ return new Promise((r) => setTimeout(r, ms));
+}
+
+// fetch that honours Sketchfab's 429 Retry-After (seconds) with a bounded retry budget.
+export async function sfFetch(url, init = {}, fetchImpl = fetch, wait = sleep) {
+ for (let attempt = 0; ; attempt++) {
+ const res = await fetchImpl(url, init);
+ if (res.status !== 429 || attempt >= MAX_RETRIES) return res;
+ const retryAfter = Number(res.headers.get('retry-after'));
+ await wait((Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter : 2 ** attempt) * 1000);
+ }
+}
+
+export async function listModels({ token, user }, fetchImpl = fetch, wait = sleep) {
+ const headers = token ? { authorization: `Token ${token}` } : {};
+ let url = token && !user
+ ? `${API_BASE}/me/models?count=${PAGE_SIZE}`
+ : `${API_BASE}/models?user=${encodeURIComponent(user)}&count=${PAGE_SIZE}`;
+ const models = [];
+ while (url) {
+ const res = await sfFetch(url, { headers }, fetchImpl, wait);
+ if (!res.ok) throw new Error(`list failed: ${res.status} ${(await res.text()).slice(0, 200)}`);
+ const body = await res.json();
+ models.push(...(body.results || []));
+ url = body.next || null;
+ }
+ return models;
+}
+
+export async function applyChange(change, token, fetchImpl = fetch, wait = sleep) {
+ const res = await sfFetch(
+ `${API_BASE}/models/${encodeURIComponent(change.uid)}`,
+ {
+ method: 'PATCH',
+ headers: { authorization: `Token ${token}`, 'content-type': 'application/json' },
+ body: JSON.stringify(change.body),
+ },
+ fetchImpl,
+ wait,
+ );
+ if (res.status !== 200 && res.status !== 204) {
+ throw new Error(`patch ${change.uid} failed: ${res.status} ${(await res.text()).slice(0, 200)}`);
+ }
+}
+
+async function main() {
+ const argv = process.argv.slice(2);
+ const apply = argv.includes('--apply');
+ const ui = argv.indexOf('--user');
+ const user = ui >= 0 ? argv[ui + 1] : null;
+ const token = process.env.SKETCHFAB_API_TOKEN || null;
+ if (!token && !user) {
+ console.error('Set SKETCHFAB_API_TOKEN (own account) or pass --user <username> (public dry run).');
+ process.exit(2);
+ }
+ if (apply && !token) {
+ console.error('--apply needs SKETCHFAB_API_TOKEN.');
+ process.exit(2);
+ }
+
+ const models = await listModels({ token, user });
+ const plan = planRetag(models);
+ console.log(`${plan.total} models listed, ${plan.compliant} already tagged, ${plan.changes.length} to change.`);
+ for (const c of plan.changes) {
+ console.log(`${apply ? 'PATCH' : 'would PATCH'} ${c.uid} "${c.name}" tags -> ${JSON.stringify(c.body.tags)}`);
+ if (apply) await applyChange(c, token);
+ }
+ if (!apply && plan.changes.length) console.log('Dry run. Re-run with --apply to make these changes.');
+ if (apply) console.log(`Applied ${plan.changes.length} changes. Re-run without --apply: it should report 0 to change.`);
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] || '').href) {
+ main().catch((e) => {
+ console.error(e.message);
+ process.exit(1);
+ });
+}
diff --git a/tests/sketchfab-retag.test.js b/tests/sketchfab-retag.test.js
new file mode 100644
index 000000000..8712b2380
--- /dev/null
+++ b/tests/sketchfab-retag.test.js
@@ -0,0 +1,65 @@
+import { describe, it, expect } from 'vitest';
+import {
+ AI_TAG,
+ buildPatch,
+ planRetag,
+ sfFetch,
+ listModels,
+ applyChange,
+} from '../scripts/sketchfab-retag.mjs';
+
+const tag = (n) => ({ name: n, slug: n });
+
+describe('sketchfab-retag', () => {
+ it('adds createdwithai after the existing tags and sends only tags', () => {
+ const body = buildPatch({ uid: 'a', tags: [tag('threews'), tag('ai-generated')] });
+ expect(body).toEqual({ tags: ['threews', 'ai-generated', AI_TAG] });
+ });
+
+ it('returns null when the tag is already present (case-insensitive)', () => {
+ expect(buildPatch({ uid: 'a', tags: [tag('CreatedWithAI')] })).toBeNull();
+ });
+
+ it('plans only the models missing the tag', () => {
+ const plan = planRetag([
+ { uid: '1', name: 'x', tags: [tag('a')] },
+ { uid: '2', name: 'y', tags: [tag(AI_TAG)] },
+ { uid: '3', name: 'z', tags: [] },
+ ]);
+ expect(plan.total).toBe(3);
+ expect(plan.compliant).toBe(1);
+ expect(plan.changes.map((c) => c.uid)).toEqual(['1', '3']);
+ });
+
+ it('waits Retry-After on 429 then succeeds', async () => {
+ const waits = [];
+ let n = 0;
+ const f = async () =>
+ n++ === 0
+ ? { status: 429, headers: new Headers({ 'retry-after': '3' }) }
+ : { status: 200, headers: new Headers() };
+ const res = await sfFetch('u', {}, f, async (ms) => waits.push(ms));
+ expect(res.status).toBe(200);
+ expect(waits).toEqual([3000]);
+ });
+
+ it('follows pagination and sends an authenticated PATCH with a tags-only body', async () => {
+ const calls = [];
+ const f = async (url, init = {}) => {
+ calls.push({ url, init });
+ if (url.includes('cursor=2'))
+ return { ok: true, status: 200, headers: new Headers(), json: async () => ({ results: [{ uid: '2' }], next: null }) };
+ if (init.method === 'PATCH') return { ok: true, status: 204, headers: new Headers() };
+ return { ok: true, status: 200, headers: new Headers(), json: async () => ({ results: [{ uid: '1' }], next: 'https://api.sketchfab.com/v3/me/models?cursor=2' }) };
+ };
+ const models = await listModels({ token: 't' }, f);
+ expect(models.map((m) => m.uid)).toEqual(['1', '2']);
+ expect(calls[0].url).toContain('/me/models');
+ await applyChange({ uid: 'abc', body: { tags: ['x', AI_TAG] } }, 't', f);
+ const patch = calls.at(-1);
+ expect(patch.init.method).toBe('PATCH');
+ expect(patch.url).toBe('https://api.sketchfab.com/v3/models/abc');
+ expect(patch.init.headers.authorization).toBe('Token t');
+ expect(JSON.parse(patch.init.body)).toEqual({ tags: ['x', AI_TAG] });
+ });
+});