tripo-cli 0.1.0

package/dist/core/region.js

@@ -0,0 +1,45 @@
+/**
+ * Region auto-detection: a Tripo API key is valid in exactly one region
+ * (ov = openapi.tripo3d.ai, cn = openapi.tripo3d.com), so instead of asking
+ * the user "which region?" we probe both with the key and let the facts
+ * decide. First successful probe wins; both failing means the key is dead.
+ */
+import { REGION_DEFAULTS } from '../config/config.js';
+import { TripoClient } from './client.js';
+const PROBE_TIMEOUT_MS = 12_000;
+export function defaultProbeBases() {
+    return { ov: REGION_DEFAULTS.ov.api, cn: REGION_DEFAULTS.cn.api };
+}
+/**
+ * Probe both regions concurrently; resolve as soon as one accepts the key
+ * (the other side may be slow/unreachable from this network — e.g. the
+ * overseas host from mainland China — and must not delay the answer).
+ * Returns undefined when both regions reject or are unreachable.
+ */
+export async function detectRegionForKey(key, bases = defaultProbeBases()) {
+    const probe = async (region) => {
+        try {
+            const client = new TripoClient({
+                apiKey: key,
+                baseUrl: bases[region],
+                maxRetries: 0,
+                timeoutMs: PROBE_TIMEOUT_MS,
+            });
+            return { region, balance: await client.getBalance() };
+        }
+        catch {
+            return undefined;
+        }
+    };
+    return new Promise((resolve) => {
+        let pending = 2;
+        for (const region of ['ov', 'cn']) {
+            void probe(region).then((hit) => {
+                if (hit)
+                    resolve(hit);
+                else if (--pending === 0)
+                    resolve(undefined);
+            });
+        }
+    });
+}

package/dist/core/requests.js

@@ -0,0 +1,197 @@
+/**
+ * Request builders: turn (step + args + resolved input) into the exact
+ * endpoint + JSON payload, applying knowledge-base validation first.
+ * Unknown extra args pass through untouched (the server maps them into
+ * `parameters`), so new API options work without a CLI release.
+ */
+import { getStep } from '../knowledge/chains.js';
+import { validateConvertParams, validateDecimateParams, validateGenerationParams, validateRetargetParams, } from '../knowledge/params.js';
+import { CAPABILITY_DEFAULTS, SEGMENT_MODELS, TEXTURE_MODELS, normalizeModel, normalizeRigModel, } from '../knowledge/models.js';
+import { UsageError } from './errors.js';
+function ensure(result) {
+    if (result.errors.length > 0) {
+        throw new UsageError(result.errors.join('; '));
+    }
+}
+/** 3D generation: text-to-model. */
+export function buildTextToModel(prompt, model, params) {
+    const validated = validateGenerationParams(model, params);
+    ensure(validated);
+    return {
+        request: {
+            endpoint: '/v3/generation/text-to-model',
+            payload: { prompt, model: normalizeModel(model), ...validated.params },
+        },
+        taskType: 'text_to_model',
+        warnings: validated.warnings,
+    };
+}
+/** 3D generation: image-to-model (input = file_token/url/task_id). */
+export function buildImageToModel(input, model, params) {
+    const validated = validateGenerationParams(model, params);
+    ensure(validated);
+    return {
+        request: {
+            endpoint: '/v3/generation/image-to-model',
+            payload: { input, model: normalizeModel(model), ...validated.params },
+        },
+        taskType: 'image_to_model',
+        warnings: validated.warnings,
+    };
+}
+/** 3D generation: multiview-to-model. Views ordered [front, left, back, right]. */
+export function buildMultiviewToModel(views, model, params) {
+    const validated = validateGenerationParams(model, params);
+    ensure(validated);
+    const inputs = ['front', 'left', 'back', 'right']
+        .filter((v) => views[v])
+        .map((v) => ({ [v]: views[v] }));
+    if (!views.front)
+        throw new UsageError('multiview requires a front view');
+    if (inputs.length < 2)
+        throw new UsageError('multiview requires at least 2 views');
+    return {
+        request: {
+            endpoint: '/v3/generation/multiview-to-model',
+            payload: { inputs, model: normalizeModel(model), ...validated.params },
+        },
+        taskType: 'multiview_to_model',
+        warnings: validated.warnings,
+    };
+}
+/** Image generation: text-to-image / image-to-image.
+ * Server task types (TaskType enum): text-to-image → `text_to_image`,
+ * image-to-image → `generate_image`. */
+export function buildTextToImage(prompt, params) {
+    return {
+        request: {
+            endpoint: '/v3/generation/text-to-image',
+            payload: { prompt, model: params.model ?? CAPABILITY_DEFAULTS.textToImage, ...omit(params, ['model']) },
+        },
+        taskType: 'text_to_image',
+        warnings: [],
+    };
+}
+export function buildImageToImage(input, params) {
+    return {
+        request: {
+            endpoint: '/v3/generation/image-to-image',
+            payload: { input, model: params.model ?? CAPABILITY_DEFAULTS.imageToImage, ...omit(params, ['model']) },
+        },
+        taskType: 'generate_image',
+        warnings: [],
+    };
+}
+export function buildImageToMultiview(input, params) {
+    return {
+        request: { endpoint: '/v3/generation/image-to-multiview', payload: { input, ...params } },
+        taskType: 'generate_multiview_image',
+        warnings: [],
+    };
+}
+export function buildEditMultiview(input, params) {
+    return {
+        request: { endpoint: '/v3/generation/edit-multiview', payload: { input, ...params } },
+        taskType: 'edit_multiview_image',
+        warnings: [],
+    };
+}
+export function buildImageToSplat(input, params) {
+    return {
+        request: { endpoint: '/v3/generation/image-to-splat', payload: { input, ...params } },
+        taskType: 'image_to_splat',
+        warnings: [],
+    };
+}
+/**
+ * Processing step (texture/convert/rig/...): validate per step, then build.
+ * `input` must already be a task_id / file_token / URL.
+ */
+export function buildStepRequest(stepName, input, args) {
+    const def = getStep(stepName);
+    if (!def)
+        throw new UsageError(`unknown step "${stepName}"`);
+    let params = { ...args };
+    const warnings = [];
+    switch (def.name) {
+        case 'convert': {
+            const v = validateConvertParams(params);
+            ensure(v);
+            params = v.params;
+            warnings.push(...v.warnings);
+            break;
+        }
+        case 'decimate': {
+            const v = validateDecimateParams(params);
+            ensure(v);
+            params = v.params;
+            warnings.push(...v.warnings);
+            break;
+        }
+        case 'retarget': {
+            const v = validateRetargetParams(params);
+            ensure(v);
+            params = v.params;
+            warnings.push(...v.warnings);
+            break;
+        }
+        case 'rig': {
+            // Marketing names (rig-v1.0/rig-v2.0) are rejected by the server; normalize to wire versions.
+            params.model = params.model === undefined
+                ? CAPABILITY_DEFAULTS.rig
+                : normalizeRigModel(String(params.model));
+            break;
+        }
+        case 'texture': {
+            const model = params.model === undefined
+                ? CAPABILITY_DEFAULTS.texture
+                : normalizeModel(String(params.model));
+            if (!TEXTURE_MODELS.includes(model)) {
+                throw new UsageError(`texture model must be one of ${TEXTURE_MODELS.join('/')} (got "${String(params.model)}")`);
+            }
+            params.model = model;
+            break;
+        }
+        case 'segment': {
+            if (params.model !== undefined && !SEGMENT_MODELS.includes(String(params.model))) {
+                throw new UsageError(`segment model must be one of ${SEGMENT_MODELS.join('/')} (got "${String(params.model)}")`);
+            }
+            break;
+        }
+        case 'stylize': {
+            if (typeof params.style !== 'string') {
+                throw new UsageError('stylize requires style (lego/voxel/voronoi/minecraft)');
+            }
+            break;
+        }
+        case 'smartsegment': {
+            if (params.seg_type === undefined)
+                params.seg_type = 'model';
+            // seg_type=model requires a 4×4 column-major transform (16 floats); the
+            // identity matrix means "use the model's own coordinates" and avoids a
+            // guaranteed 400 when the caller doesn't care about placement.
+            if (params.seg_type === 'model' && params.transform === undefined) {
+                params.transform = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1];
+                warnings.push('smartsegment(model) requires a transform matrix; defaulted to identity');
+            }
+            break;
+        }
+    }
+    // smartsegment's task type depends on seg_type (server: smartsegment_image|smartsegment_model).
+    const taskType = def.name === 'smartsegment'
+        ? params.seg_type === 'image'
+            ? 'smartsegment_image'
+            : 'smartsegment_model'
+        : def.produces;
+    return {
+        request: { endpoint: def.endpoint, payload: { input, ...params } },
+        taskType,
+        warnings,
+    };
+}
+function omit(obj, keys) {
+    const out = { ...obj };
+    for (const k of keys)
+        delete out[k];
+    return out;
+}

package/dist/core/task-service.js

@@ -0,0 +1,167 @@
+/**
+ * The shared task engine: resolve inputs, pre-check balance, submit, record
+ * history, watch progress, download artifacts, notify. Every task-producing
+ * command (make/generate/model/anim/mesh/pipeline/batch) runs through here so
+ * behavior is identical everywhere.
+ */
+import { basename } from 'node:path';
+import { resolvePlatformBaseUrl, resolveRegion } from '../config/config.js';
+import { loadContext, updateContext } from '../config/context.js';
+import { RefError, appendHistory, readHistory, resolveReference, slugify, updateHistoryStatus } from '../config/history.js';
+import { t } from '../i18n.js';
+import { detectInput } from '../util/input-detect.js';
+import { notifyDone } from '../util/notify.js';
+import { createSpinner } from '../util/spinner.js';
+import { defaultOutputDir, downloadArtifacts } from './download.js';
+import { ApiError, UsageError, balanceSuggestion } from './errors.js';
+import { isQuiet, log, warn } from './output.js';
+import { uploadLocalFile } from './upload.js';
+/** Resolve a user input string into the API `input` value (upload as needed). */
+export async function resolveInputValue(client, raw) {
+    const detected = detectInput(raw);
+    switch (detected.kind) {
+        case 'history-ref': {
+            let entry;
+            try {
+                entry = resolveReference(detected.value);
+            }
+            catch (err) {
+                if (err instanceof RefError)
+                    throw new UsageError(err.message);
+                throw err;
+            }
+            if (!entry)
+                throw new UsageError(`cannot resolve reference ${raw}`);
+            return { value: entry.task_id, sourceTaskType: entry.type };
+        }
+        case 'image-file':
+        case 'model-file': {
+            const token = await uploadLocalFile(client, detected.value);
+            return { value: token };
+        }
+        case 'task-id':
+            return { value: detected.value };
+        case 'file-token':
+        case 'url':
+            return { value: detected.value };
+        case 'text':
+            throw new UsageError(`expected a file/url/task reference, got text: "${raw}"`);
+    }
+}
+/** Balance pre-check: warns when low, errors when empty. */
+export async function precheckBalance(client) {
+    let balance;
+    try {
+        const data = await client.getBalance();
+        balance = Number(data.balance);
+    }
+    catch {
+        return; // pre-check must never block task creation on transient errors
+    }
+    if (Number.isNaN(balance))
+        return;
+    if (balance <= 0) {
+        throw new ApiError({ apiCode: 2010, suggestion: balanceSuggestion(undefined, balance) });
+    }
+    if (balance < 30) {
+        warn(t({
+            zh: `余额仅剩 ${balance} 积分,任务可能因余额不足失败(tripo topup 充值)`,
+            en: `balance is down to ${balance} credits; tasks may fail (run "tripo topup")`,
+        }));
+    }
+}
+/** Submit one task and (by default) watch it to completion + download. */
+export async function runTask(options) {
+    const { client, request, taskType } = options;
+    if (options.precheckBalance !== false)
+        await precheckBalance(client);
+    const taskId = await client.createTask(request.endpoint, request.payload);
+    const name = uniqueName(slugify(options.name));
+    const entry = {
+        task_id: taskId,
+        type: taskType,
+        name,
+        status: 'queued',
+        created_at: new Date().toISOString(),
+        endpoint: request.endpoint,
+        payload: request.payload,
+    };
+    appendHistory(entry);
+    updateContext({ last_task_id: taskId });
+    log(t({ zh: `任务已创建 ${taskId} (@${name})`, en: `task created ${taskId} (@${name})` }));
+    if (options.noWait) {
+        return { task_id: taskId, type: taskType, status: 'queued' };
+    }
+    const spinner = createSpinner(`${taskType} · queued`, isQuiet());
+    let task;
+    try {
+        task = await (await import('./watch.js')).watchTask(client, taskId, {
+            timeoutMs: options.timeoutMs,
+            onProgress: (detail) => {
+                const pct = typeof detail.progress === 'number' ? ` ${detail.progress}%` : '';
+                spinner.update(`${taskType} · ${detail.status}${pct} · ${taskId.slice(0, 8)}`);
+            },
+        });
+    }
+    catch (err) {
+        spinner.fail(`${taskType} · ${taskId}`);
+        updateHistoryStatus(taskId, 'failed');
+        throw err;
+    }
+    updateHistoryStatus(taskId, 'success', { credits_consumed: task.credits_consumed });
+    spinner.succeed(`${taskType} · ${taskId}` +
+        (task.credits_consumed !== undefined
+            ? t({ zh: ` · 消耗 ${task.credits_consumed} 积分`, en: ` · ${task.credits_consumed} credits` })
+            : ''));
+    const result = {
+        task_id: taskId,
+        type: taskType,
+        status: task.status,
+        credits_consumed: task.credits_consumed,
+    };
+    if (!options.noDownload) {
+        const baseDir = options.outDir ?? loadContext().output_dir ?? process.cwd();
+        const dir = defaultOutputDir(baseDir, name, taskId);
+        const dlSpinner = createSpinner(t({ zh: '下载产物…', en: 'downloading artifacts…' }), isQuiet());
+        try {
+            const artifacts = await downloadArtifacts(task, dir, entry, {
+                onFile: (f) => dlSpinner.update(t({ zh: `下载 ${f}`, en: `downloading ${f}` })),
+            });
+            dlSpinner.succeed(t({ zh: `产物已保存 ${artifacts.outputDir}`, en: `artifacts saved to ${artifacts.outputDir}` }));
+            result.output_dir = artifacts.outputDir;
+            result.files = artifacts.files.map((f) => basename(f));
+            result.model_file = artifacts.modelFile;
+            result.preview = artifacts.preview;
+            updateHistoryStatus(taskId, 'success', { output_dir: artifacts.outputDir });
+        }
+        catch (err) {
+            dlSpinner.fail(t({ zh: '产物下载失败(任务本身已成功)', en: 'artifact download failed (the task itself succeeded)' }));
+            warn(String(err instanceof Error ? err.message : err));
+            warn(t({ zh: `可重试:tripo task get ${taskId} --download`, en: `retry with: tripo task get ${taskId} --download` }));
+        }
+    }
+    if (options.notify) {
+        notifyDone('Tripo', t({ zh: `${taskType} 完成`, en: `${taskType} finished` }));
+    }
+    return result;
+}
+/** Ensure history names stay unique by appending -2, -3, ... on collision. */
+function uniqueName(base) {
+    const names = new Set(readHistory().map((e) => e.name));
+    if (!names.has(base))
+        return base;
+    for (let i = 2;; i++) {
+        const candidate = `${base}-${i}`;
+        if (!names.has(candidate))
+            return candidate;
+    }
+}
+/**
+ * Region-specific billing entry: the cn console has a dedicated Alipay
+ * recharge page (/billing/recharge); the ov console does Stripe top-up
+ * inline on /billing. Both consoles auto-prefix the language segment.
+ */
+export function topupUrl() {
+    const path = resolveRegion() === 'cn' ? '/billing/recharge' : '/billing';
+    return `${resolvePlatformBaseUrl()}${path}`;
+}

package/dist/core/upload.js

@@ -0,0 +1,42 @@
+/** Local file → file_token upload with size/type guards. */
+import { readFile, stat } from 'node:fs/promises';
+import { basename, extname } from 'node:path';
+import { UsageError } from './errors.js';
+import { IMAGE_EXTS, MODEL_EXTS } from '../util/input-detect.js';
+const IMAGE_MAX = 20 * 1024 * 1024;
+const MODEL_MAX = 150 * 1024 * 1024;
+const MIME = {
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.webp': 'image/webp',
+    '.bmp': 'image/bmp',
+    '.tiff': 'image/tiff',
+    '.tif': 'image/tiff',
+    '.glb': 'model/gltf-binary',
+    '.fbx': 'application/octet-stream',
+    '.obj': 'text/plain',
+    '.stl': 'application/octet-stream',
+};
+export async function uploadLocalFile(client, filePath) {
+    const ext = extname(filePath).toLowerCase();
+    const isImage = IMAGE_EXTS.has(ext);
+    const isModel = MODEL_EXTS.has(ext);
+    if (!isImage && !isModel) {
+        throw new UsageError(`unsupported file type "${ext}" for upload`);
+    }
+    // The server's upload whitelist has no gltf: a .gltf references external
+    // .bin/texture files, so a single-file upload would be incomplete anyway.
+    if (ext === '.gltf') {
+        throw new UsageError('the upload API does not accept .gltf (it references external files) — export as .glb, or host it and pass the URL');
+    }
+    const info = await stat(filePath);
+    const limit = isImage ? IMAGE_MAX : MODEL_MAX;
+    if (info.size > limit) {
+        throw new UsageError(`${basename(filePath)} is ${(info.size / 1024 / 1024).toFixed(1)}MB, exceeding the ${limit / 1024 / 1024}MB ${isImage ? 'image' : 'model'} limit`);
+    }
+    const bytes = await readFile(filePath);
+    const blob = new Blob([bytes], { type: MIME[ext] ?? 'application/octet-stream' });
+    const { file_token } = await client.uploadFile(basename(filePath), blob);
+    return file_token;
+}

package/dist/core/viewer-assets.js

@@ -0,0 +1,24 @@
+/** Static HTML template for the local model-viewer preview page. */
+export function viewerHtml(modelFileName, title) {
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escapeHtml(title)} · Tripo</title>
+<script type="module" src="https://ajax.googleapis.com/ajax/libs/model-viewer/3.5.0/model-viewer.min.js"></script>
+<style>
+  html, body { margin: 0; height: 100%; background: #101014; color: #e8e8ec; font: 14px/1.5 system-ui, sans-serif; }
+  model-viewer { width: 100%; height: 100%; --poster-color: transparent; }
+  .bar { position: fixed; top: 0; left: 0; right: 0; display: flex; justify-content: space-between; padding: 10px 16px; font-size: 13px; color: #9a9aa6; pointer-events: none; }
+</style>
+</head>
+<body>
+<div class="bar"><span>${escapeHtml(title)}</span><span>drag to rotate · scroll to zoom</span></div>
+<model-viewer src="${encodeURI(modelFileName)}" camera-controls auto-rotate shadow-intensity="1" exposure="0.9" ar></model-viewer>
+</body>
+</html>`;
+}
+function escapeHtml(text) {
+    return text.replace(/[&<>"']/g, (ch) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[ch]);
+}

package/dist/core/viewer.js

@@ -0,0 +1,59 @@
+/**
+ * Local 3D preview: serve the model file + a model-viewer page on an
+ * ephemeral localhost port. The browser is an optional enhancement — the
+ * files are already on disk; headless callers just get the file path.
+ */
+import { createServer } from 'node:http';
+import { readFile } from 'node:fs/promises';
+import { basename, extname } from 'node:path';
+import { viewerHtml } from './viewer-assets.js';
+const CONTENT_TYPES = {
+    '.glb': 'model/gltf-binary',
+    '.gltf': 'model/gltf+json',
+    '.html': 'text/html; charset=utf-8',
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.webp': 'image/webp',
+    '.usdz': 'model/vnd.usdz+zip',
+};
+/** Start a one-model preview server; resolves once listening. */
+export async function startViewer(modelFile, title) {
+    const fileName = basename(modelFile);
+    const server = createServer((req, res) => {
+        void (async () => {
+            const url = new URL(req.url ?? '/', 'http://localhost');
+            try {
+                if (url.pathname === '/') {
+                    res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+                    res.end(viewerHtml(fileName, title));
+                    return;
+                }
+                if (decodeURIComponent(url.pathname.slice(1)) === fileName) {
+                    const data = await readFile(modelFile);
+                    res.writeHead(200, {
+                        'Content-Type': CONTENT_TYPES[extname(fileName).toLowerCase()] ?? 'application/octet-stream',
+                        'Content-Length': data.length,
+                    });
+                    res.end(data);
+                    return;
+                }
+                res.writeHead(404);
+                res.end('not found');
+            }
+            catch {
+                res.writeHead(500);
+                res.end('error');
+            }
+        })();
+    });
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(0, '127.0.0.1', resolve);
+    });
+    const address = server.address();
+    const port = typeof address === 'object' && address ? address.port : 0;
+    return {
+        url: `http://127.0.0.1:${port}/`,
+        close: () => server.close(),
+    };
+}

package/dist/core/watch.js

@@ -0,0 +1,42 @@
+/**
+ * Adaptive task polling: start at 2s; when the API reports running_left_time
+ * take max(2, left*0.5); otherwise back off exponentially capped at 30s.
+ */
+import { sleep } from './client.js';
+import { TaskFailedError } from './errors.js';
+export async function watchTask(client, taskId, options = {}) {
+    const timeoutMs = options.timeoutMs ?? 30 * 60 * 1000;
+    const deadline = Date.now() + timeoutMs;
+    let interval = 2000;
+    let backoff = 2000;
+    for (;;) {
+        const task = await client.getTask(taskId);
+        options.onProgress?.(task);
+        if (task.status === 'success')
+            return task;
+        // Terminal failure states (server enum also has banned/expired beyond failed/cancelled).
+        if (['failed', 'cancelled', 'banned', 'expired'].includes(task.status)) {
+            if (options.throwOnFailure === false)
+                return task;
+            throw new TaskFailedError(taskId, task.status, extractFailureReason(task));
+        }
+        if (Date.now() > deadline) {
+            throw new TaskFailedError(taskId, 'timeout', `still ${task.status} after ${Math.round(timeoutMs / 1000)}s (task keeps running server-side; check later with "tripo task get ${taskId}")`);
+        }
+        const left = task.running_left_time ?? task.output?.running_left_time;
+        if (typeof left === 'number' && left > 0) {
+            interval = Math.max(2000, left * 500);
+            backoff = 2000;
+        }
+        else {
+            interval = backoff;
+            backoff = Math.min(backoff * 1.5, 30_000);
+        }
+        await sleep(interval);
+    }
+}
+function extractFailureReason(task) {
+    const out = task.output ?? {};
+    const candidate = out.message ?? out.error ?? out.reason;
+    return typeof candidate === 'string' ? candidate : undefined;
+}

package/dist/i18n.js

@@ -0,0 +1,19 @@
+/** Minimal bilingual UX strings. Locale: config override > env (LANG/LC_ALL). */
+let currentLocale;
+export function setLocale(locale) {
+    currentLocale = locale;
+}
+export function getLocale() {
+    if (currentLocale)
+        return currentLocale;
+    const env = process.env.LC_ALL || process.env.LC_MESSAGES || process.env.LANG || '';
+    return /^zh/i.test(env) ? 'zh' : 'en';
+}
+/** Pick the localized variant of a bilingual pair. */
+export function t(pair) {
+    return getLocale() === 'zh' ? pair.zh : pair.en;
+}
+/** Pick the localized variant of a bilingual string list. */
+export function tList(pair) {
+    return getLocale() === 'zh' ? pair.zh : pair.en;
+}