@forgeax-extension/character-3d 0.1.2

package/server/providers/gateway-client.ts

@@ -0,0 +1,171 @@
+import type { LitellmEnv } from '../env';
+
+export type FetchLike = (url: string, init: RequestInit) => Promise<Response>;
+
+export type GatewayStatus = 'succeeded' | 'failed' | 'pending';
+
+export interface GatewayClientDeps {
+  env: LitellmEnv;
+  fetchImpl?: FetchLike;
+  sleep?: (ms: number) => Promise<void>;
+}
+
+export interface PollOptions {
+  timeoutMs: number;
+  intervalMs: number;
+  label?: string;
+}
+
+const FAILURE_STATUSES = new Set(['failed', 'error', 'fail', 'canceled', 'cancelled']);
+
+export class GatewayClient {
+  private readonly env: LitellmEnv;
+  private readonly fetchImpl: FetchLike;
+  private readonly sleep: (ms: number) => Promise<void>;
+
+  constructor(deps: GatewayClientDeps) {
+    this.env = deps.env;
+    this.fetchImpl = deps.fetchImpl ?? ((url, init) => fetch(url, init));
+    this.sleep = deps.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  }
+
+  async post(path: string, body: unknown): Promise<Record<string, unknown>> {
+    const resp = await this.fetchImpl(`${this.env.baseUrl}${path}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${this.env.apiKey}` },
+      body: JSON.stringify(body),
+    });
+    return readJsonOrThrow(resp);
+  }
+
+  async get(path: string): Promise<Record<string, unknown>> {
+    const resp = await this.fetchImpl(`${this.env.baseUrl}${path}`, {
+      method: 'GET',
+      headers: { Authorization: `Bearer ${this.env.apiKey}` },
+    });
+    return readJsonOrThrow(resp);
+  }
+
+  async pollTask(path: string, options: PollOptions): Promise<Record<string, unknown>> {
+    const deadline = Date.now() + options.timeoutMs;
+    let lastError: unknown = null;
+
+    while (Date.now() < deadline) {
+      try {
+        const resp = await this.get(path);
+        const status = normalizeGatewayStatus(resp.status);
+        if (status === 'succeeded') return resp;
+        if (status === 'failed') {
+          throw Object.assign(
+            new Error(`${options.label ?? 'gateway task'} failed: ${gatewayErrorMessage(resp) ?? String(resp.status ?? 'failed')}`),
+            { code: 'provider_failed' },
+          );
+        }
+      } catch (error) {
+        lastError = error;
+        if (isTerminalGatewayError(error)) throw error;
+      }
+      await this.sleep(options.intervalMs);
+    }
+
+    const suffix = lastError instanceof Error ? `; last error: ${lastError.message}` : '';
+    throw Object.assign(new Error(`${options.label ?? 'gateway task'} poll timed out${suffix}`), {
+      code: 'provider_timeout',
+      lastError,
+    });
+  }
+
+  async download(url: string, options: { format?: string; image?: boolean } = {}): Promise<Uint8Array> {
+    const resp = await this.fetchImpl(url, { method: 'GET' });
+    if (!resp.ok) throw httpError(resp.status);
+    const data = new Uint8Array(await resp.arrayBuffer());
+    if (data.byteLength === 0) {
+      throw Object.assign(new Error(`download returned empty bytes: ${safeUrlForError(url)}`), {
+        code: 'provider_empty_download',
+      });
+    }
+    if (options.format === 'glb' && !hasGlbMagic(data)) {
+      throw Object.assign(new Error(`download is not a GLB: ${safeUrlForError(url)}`), {
+        code: 'provider_invalid_download',
+      });
+    }
+    if (options.image && !hasImageExtension(url)) {
+      throw Object.assign(new Error(`download URL is not an image: ${safeUrlForError(url)}`), {
+        code: 'provider_invalid_download',
+      });
+    }
+    return data;
+  }
+}
+
+export function normalizeGatewayStatus(status: unknown): GatewayStatus {
+  const value = String(status ?? '').toLowerCase();
+  if (value === 'succeeded') return 'succeeded';
+  if (FAILURE_STATUSES.has(value)) return 'failed';
+  return 'pending';
+}
+
+export function gatewayErrorMessage(resp: Record<string, unknown>): string | undefined {
+  const err = resp.error as Record<string, unknown> | undefined;
+  return err && typeof err.message === 'string' && err.message ? err.message : undefined;
+}
+
+async function readJsonOrThrow(resp: Response): Promise<Record<string, unknown>> {
+  if (!resp.ok) {
+    const body = await resp.text().catch(() => '');
+    throw httpError(resp.status, body);
+  }
+  return (await resp.json()) as Record<string, unknown>;
+}
+
+export function httpError(
+  status: number,
+  body = '',
+): Error & { code: string; status: number; httpStatus: number; body?: string } {
+  const code =
+    status === 400 ? 'provider_bad_request'
+    : status === 401 ? 'provider_unauthorized'
+    : status === 402 ? 'provider_insufficient_credits'
+    : status === 404 ? 'provider_not_enabled'
+    : status === 429 ? 'provider_rate_limited'
+    : 'provider_http_error';
+  const snippet = body.replace(/\s+/g, ' ').trim().slice(0, 240);
+  const suffix = snippet ? `: ${snippet}` : '';
+  return Object.assign(new Error(`gateway http ${status}${suffix}`), {
+    code,
+    status,
+    httpStatus: status,
+    ...(snippet ? { body: snippet } : {}),
+  });
+}
+
+function isTerminalGatewayError(error: unknown): boolean {
+  const code = (error as { code?: unknown } | null)?.code;
+  return (
+    code === 'provider_bad_request' ||
+    code === 'provider_unauthorized' ||
+    code === 'provider_insufficient_credits' ||
+    code === 'provider_not_enabled' ||
+    code === 'provider_rate_limited' ||
+    code === 'provider_failed'
+  );
+}
+
+function hasGlbMagic(data: Uint8Array): boolean {
+  return data.length >= 4 && data[0] === 0x67 && data[1] === 0x6c && data[2] === 0x54 && data[3] === 0x46;
+}
+
+function hasImageExtension(url: string): boolean {
+  const path = url.split('?', 1)[0] ?? url;
+  return /\.(png|jpe?g|webp|gif)$/i.test(path);
+}
+
+function safeUrlForError(url: string): string {
+  try {
+    const parsed = new URL(url);
+    parsed.search = '';
+    return parsed.toString();
+  } catch {
+    return url.split('?', 1)[0] ?? url;
+  }
+}

package/server/providers/gateway-data.ts

@@ -0,0 +1,182 @@
+// gateway-data.ts — SSOT for parsing the LiteLLM 3D gateway `data[]` output.
+//
+// Every provider (meshy, hunyuan-workflow, hunyuan-rest) polls the same gateway
+// task endpoint, which returns outputs as a `data[]` array of
+// { url, type, format } entries. Two shared quirks live here so the three
+// providers can't drift:
+//
+//   1. Model binaries are usually type:'mesh' (format=glb/fbx/…). Hunyuan
+//      auto-rig via LiteLLM also emits type:'rigged_model' for FBX — still keyed
+//      by format. We key model urls by format.
+//   2. Every *other* PNG — the rendered thumbnail AND all PBR texture maps —
+//      is tagged type:'preview'. Keying the thumbnail off `type` alone let the
+//      LAST type:'preview' entry (texture_0_emission.png, a near-black map)
+//      overwrite the real render (preview.png), so saved previews came out
+//      black (the marketplace #16 gateway regression). Real Meshy filenames:
+//        output/preview.png                          → the render (thumbnail)
+//        output/texture_0.png                        → base_color
+//        output/texture_0_{metallic,roughness,normal,emission}.png → PBR maps
+//      So non-mesh images are classified by filename, not the gateway `type`.
+
+const IMAGE_EXT = /\.(png|jpe?g|webp)$/i;
+const MESH_EXTS = new Set(['glb', 'fbx', 'obj', 'usdz', 'stl']);
+
+function formatFromUrl(url: string): string {
+  const ext = gatewayFileName(url).split('.').pop()?.toLowerCase() ?? '';
+  return MESH_EXTS.has(ext) ? ext : '';
+}
+
+// Flatten a gateway task response's `data[]` into a flat url map:
+//   out[<format>]         mesh urls keyed by format (glb/fbx/obj/usdz/stl)
+//   out.__thumbnail       the rendered preview image
+//   out.__texture_<kind>  texture maps (base_color/metallic/roughness/…)
+export function extractGatewayUrls(resp: Record<string, unknown>): Record<string, string> {
+  const out: Record<string, string> = {};
+  const data = resp.data;
+  if (Array.isArray(data)) {
+    for (const raw of data) {
+      if (typeof raw !== 'object' || !raw) continue;
+      const item = raw as Record<string, unknown>;
+      const directUrl = item.url;
+      if (typeof directUrl === 'string' && directUrl) {
+        assignGatewayUrl(out, directUrl, String(item.type ?? ''), String(item.format ?? ''), item);
+      }
+      for (const [key, value] of Object.entries(item)) {
+        if (!key.endsWith('_url') || typeof value !== 'string' || !value) continue;
+        assignHunyuanStyleUrl(out, key, value);
+      }
+    }
+  }
+  for (const [key, value] of Object.entries(resp)) {
+    if (!key.endsWith('_url') || typeof value !== 'string' || !value) continue;
+    assignHunyuanStyleUrl(out, key, value);
+  }
+  return out;
+}
+
+function assignGatewayUrl(
+  out: Record<string, string>,
+  url: string,
+  type: string,
+  format: string,
+  item: Record<string, unknown>,
+): void {
+  const typ = type.toLowerCase();
+  const fmt = format.toLowerCase();
+  // Model binaries: gateway usually tags type:'mesh'. LiteLLM Hunyuan auto-rig
+  // tags the rigged FBX as type:'rigged_model' (format:'fbx') — still a model
+  // URL we must keep (else apply-motion loses FBX transport). Probed 2026-07-17.
+  if (typ === 'mesh' || typ === 'rigged_model' || typ === 'animated_model') {
+    // Rodin/Volcengine hyper3d-gen2 (live 2026-08-14): type=mesh, format=null,
+    // URL still ends in .glb. Empty format used to drop the only mesh.
+    const key = MESH_EXTS.has(fmt) ? fmt : formatFromUrl(url);
+    if (key) out[key] = url;
+    return;
+  }
+  // Defensive: some gateways omit type but set format to a mesh extension.
+  if (!typ && (fmt === 'fbx' || fmt === 'glb' || fmt === 'obj' || fmt === 'usdz' || fmt === 'stl')) {
+    out[fmt] = url;
+    return;
+  }
+
+  // Non-mesh entry: classify by output filename, because the gateway tags the
+  // render and every texture map alike as type:'preview'.
+  const name = gatewayFileName(url);
+  if (/^preview\./i.test(name)) {
+    // The real render. Wins over any earlier fallback thumbnail.
+    out.__thumbnail = url;
+  } else if (/^texture_/i.test(name)) {
+    // A PBR texture map — never the thumbnail. base_color feeds the optional
+    // texture sidefile; the rest are kept but currently unused downstream.
+    out[`__texture_${textureKindFromName(name)}`] = url;
+  } else if (type === 'texture') {
+    // Defensive: a future gateway that tags textures correctly.
+    const kind = String(item.texture_kind ?? format) || 'base_color';
+    out[`__texture_${kind}`] = url;
+  } else if (!out.__thumbnail && IMAGE_EXT.test(name)) {
+    // Fallback for gateways that name the render differently: take the first
+    // rendered image. Non-image outputs (e.g. .mtl) are ignored.
+    out.__thumbnail = url;
+  }
+}
+
+function assignHunyuanStyleUrl(out: Record<string, string>, key: string, url: string): void {
+  if (key === 'glb_url' || key.endsWith('_glb_url')) out.glb = url;
+  else if (key === 'fbx_url' || key.endsWith('_fbx_url')) out.fbx = url;
+  else if (key === 'obj_url' || key.endsWith('_obj_url')) out.obj = url;
+  else if (key === 'usdz_url' || key.endsWith('_usdz_url')) out.usdz = url;
+  else if (key === 'stl_url' || key.endsWith('_stl_url')) out.stl = url;
+  else if (key === 'thumbnail_url' || key === 'preview_url' || key === 'image_url') out.__thumbnail = url;
+}
+
+// Rig-specific URL extraction. The Meshy auto-rig gateway response carries
+// FIVE mesh entries per format, and `extractGatewayUrls`' `out[format] = url`
+// (last-wins) lets the final `Animation_*_withSkin_armature.glb` (a
+// skeleton-only 288-face proxy, no mesh) overwrite `Character_output.glb` (the
+// full rigged mesh). That made gen3d store a skeleton-only rigged_model.glb
+// → viewport showed 288 faces, mesh invisible. Classify by Meshy output
+// filename instead:
+//   Character_output.{glb,fbx}                 → the rigged model (mesh+skeleton)
+//   Animation_Walking_withSkin.{glb,fbx}       → free walk clip (full mesh+anim)
+//   Animation_Running_withSkin.{glb,fbx}       → free run clip (full mesh+anim)
+//   *_armature.{glb,fbx}                       → skeleton-only proxies (skipped)
+// `extractGatewayUrls` is left untouched for generate/animate, whose responses
+// carry one mesh per format and don't need this disambiguation.
+export interface RigUrls {
+  glb: string | undefined;
+  fbx: string | undefined;
+  walkGlb: string | undefined;
+  walkFbx: string | undefined;
+  runGlb: string | undefined;
+  runFbx: string | undefined;
+}
+
+export function extractRigUrls(resp: Record<string, unknown>): RigUrls {
+  const out: RigUrls = {
+    glb: undefined,
+    fbx: undefined,
+    walkGlb: undefined,
+    walkFbx: undefined,
+    runGlb: undefined,
+    runFbx: undefined,
+  };
+  const data = resp.data;
+  if (!Array.isArray(data)) return out;
+  for (const raw of data) {
+    if (typeof raw !== 'object' || !raw) continue;
+    const item = raw as Record<string, unknown>;
+    const url = item.url;
+    if (typeof url !== 'string' || !url) continue;
+    if (String(item.type ?? '') !== 'mesh') continue;
+    const format = String(item.format ?? '');
+    if (format !== 'glb' && format !== 'fbx') continue;
+    const name =
+      typeof item.name === 'string' && item.name.trim() ? item.name.trim() : gatewayFileName(url);
+    const isGlb = format === 'glb';
+    if (/^Character_output\./i.test(name)) {
+      if (isGlb) out.glb = url;
+      else out.fbx = url;
+    } else if (/^Animation_Walking_withSkin\./i.test(name)) {
+      if (isGlb) out.walkGlb = url;
+      else out.walkFbx = url;
+    } else if (/^Animation_Running_withSkin\./i.test(name)) {
+      if (isGlb) out.runGlb = url;
+      else out.runFbx = url;
+    }
+    // _armature variants and anything else: ignored (skeleton-only, no mesh).
+  }
+  return out;
+}
+
+function gatewayFileName(url: string): string {
+  const path = url.split('?', 1)[0] ?? url;
+  return path.split('/').pop() ?? '';
+}
+
+// texture_0.png → base_color ; texture_0_metallic.png → metallic
+function textureKindFromName(name: string): string {
+  const stem = name.replace(IMAGE_EXT, '');
+  const m = /^texture_\d+(?:_(.+))?$/i.exec(stem);
+  if (!m) return 'base_color';
+  return m[1] ? m[1].toLowerCase() : 'base_color';
+}

package/server/providers/gateway-models.ts

@@ -0,0 +1,49 @@
+// LiteLLM 3D gateway model ids — SSOT for Meshy / Hunyuan / Rodin / VISVISE.
+// Hunyuan/Meshy verified 2026-07-16. Rodin/VISVISE verified 2026-08-14
+// (docs/evidence/gateway-rodin-visvise-probe-2026-08-14.json).
+// Older lab ids (hunyuan-3d-v3.1-*-wf, *-gamestudio, motion-retarget, …) are
+// superseded by the shorter gateway aliases below.
+
+export const MESHY_GATEWAY_MODELS = {
+  text: 'meshy-3d-text',
+  image: 'meshy-3d-image',
+  views: 'meshy-3d-multi-image',
+  refine: 'meshy-3d-text',
+  autoRig: 'meshy-3d-auto-rigging',
+  animation: 'meshy-3d-animation',
+} as const;
+
+export const HUNYUAN_GATEWAY_MODELS = {
+  text: 'hunyuan-3d-text',
+  image: 'hunyuan-3d-image',
+  views: 'hunyuan-3d-views',
+  autoRig: 'hunyuan-3d-rigging',
+  motion: 'hunyuan-3d-motion',
+  // Not listed on the current gateway catalog — keep ids for when ops adds them.
+  pose: 'hunyuan-3d-images-pose-standardization',
+  lowPoly: 'hunyuan-3d-low-poly-v1.5',
+} as const;
+
+export const RODIN_GATEWAY_MODELS = {
+  generate: 'rodin-3d',
+} as const;
+
+export const VISVISE_GATEWAY_MODELS = {
+  generate: 'visvise-3d',
+  mid: 'visvise-3d-mid',
+  low: 'visvise-3d-low',
+  pose: 'visvise-image-pose',
+  autoRig: 'visvise-rigging',
+  skinning: 'visvise-skinning',
+  textMotion: 'visvise-text-motion',
+  videoMotion: 'visvise-video-motion',
+} as const;
+
+export type VisviseQuality = 'standard' | 'mid' | 'low';
+
+/** C1: visvise-3d-mid is image-only (`image_url` required). Text never uses mid. */
+export function visviseGenerateModel(mode: 'text' | 'image', quality?: VisviseQuality): string {
+  if (mode === 'image' && quality === 'mid') return VISVISE_GATEWAY_MODELS.mid;
+  if (quality === 'low') return VISVISE_GATEWAY_MODELS.low;
+  return VISVISE_GATEWAY_MODELS.generate;
+}