Magi 3D SDK

Universal TypeScript SDK for 3D generative AI providers. Generate 3D models from text or images using a unified API across multiple providers.

Features

- Multi-provider support: Tripo, Hunyuan (Tencent Cloud)
- Unified API: Single createTask() method for all operations
- React Hooks: useCreateTask, useTaskStatus, usePolling
- Provider metadata: PROVIDERS list and PROVIDER_TASK_TYPES mapping for UI
- TypeScript-first: Full type safety and IntelliSense
- Modern: ESM + CJS, tree-shakeable

Installation

``bash
npm install magi-3d


or

`
+------------------------------------------------------------------+
| FRONTEND (React) |
| ----------------- |
| import { useCreateTask, PROVIDERS, PROVIDER_TASK_TYPES } |
| from 'magi-3d/react'; |
| |
| Hook handles: |
| POST /api/3d/task -> submit task with providerId |
| GET /api/3d/task/:id -> poll status with providerId |
+----------------------------------+--------------------------------+
|
v
+------------------------------------------------------------------+
| BACKEND (Your API Routes) |
| ---------------------------------------------------------------- |
| import { Magi3DClient, TripoProvider } from 'magi-3d/server'; |
| |
| POST /api/3d/task -> select provider, client.createTask() |
| GET /api/3d/task/:id -> select provider, client.getTask(id) |
+------------------------------------------------------------------+
`

Quick Start

$3

`typescript
// app/api/3d/task/route.ts (Next.js App Router)
import { Magi3DClient, TripoProvider, HunyuanProvider, ProviderId } from 'magi-3d/server';

// Create provider instances (uses env vars by default)
const providers = {
[ProviderId.TRIPO]: new TripoProvider(), // Uses TRIPO_API_KEY
[ProviderId.HUNYUAN]: new HunyuanProvider({ region: 'ap-guangzhou' }) // Uses HUNYUAN_SECRET_ID/KEY
};

// Create task
export async function POST(req: Request) {
const { providerId = ProviderId.TRIPO, ...params } = await req.json();

const provider = providers[providerId as ProviderId];
if (!provider) {
return Response.json({ error: 'Invalid provider' }, { status: 400 });
}

const client = new Magi3DClient(provider);
const taskId = await client.createTask(params);
return Response.json({ taskId });
}

// app/api/3d/task/[id]/route.ts
export async function GET(
req: Request,
{ params }: { params: { id: string } }
) {
const { searchParams } = new URL(req.url);
const providerId = searchParams.get('providerId') as ProviderId;

const provider = providers[providerId];
if (!provider) {
return Response.json({ error: 'Invalid provider' }, { status: 400 });
}

const client = new Magi3DClient(provider);
const task = await client.getTask(params.id);
return Response.json(task);
}
`

$3

`tsx
'use client';

import { useState, useEffect } from 'react';
import {
useCreateTask,
useTaskStatus,
PROVIDERS,
PROVIDER_TASK_TYPES,
TaskType,
TaskStatus,
ProviderId
} from 'magi-3d/react';

// ============================================
// Example 1: Create Task with Provider Selection
// ============================================
export function Model3DGenerator() {
// Provider and task type selection
const [providerId, setProviderId] = useState(ProviderId.TRIPO);
const [taskType, setTaskType] = useState(TaskType.TEXT_TO_3D);
const [prompt, setPrompt] = useState('');

// Get available task types for selected provider
const availableTaskTypes = PROVIDER_TASK_TYPES[providerId];

// Reset task type when provider changes if current type not supported
useEffect(() => {
if (!availableTaskTypes.includes(taskType)) {
setTaskType(availableTaskTypes[0]);
}
}, [providerId, taskType, availableTaskTypes]);

// Create task hook - handles creation and automatic polling
const {
createTask,
task,
taskId,
isLoading,
progress,
error,
reset
} = useCreateTask({
api: '/api/3d',
onSuccess: (task) => {
console.log('Model URL:', task.result?.model); // Primary model URL
console.log('Raw API Response:', task.rawResponse); // Full provider response
},
onError: (err) => console.error('Generation failed:', err)
});

const handleSubmit = async () => {
await createTask({
type: taskType,
prompt,
providerId // Backend uses this to select provider
});
};

return (


3D Model Generator

{/ Provider Selection - uses PROVIDERS export /}

Provider:
value={providerId}
onChange={(e) => setProviderId(e.target.value as ProviderId)}
disabled={isLoading}
>
{PROVIDERS.map(id => (
{id.toUpperCase()}
))}

{/ Task Type Selection - uses PROVIDER_TASK_TYPES mapping /}

Task Type:
value={taskType}
onChange={(e) => setTaskType(e.target.value as TaskType)}
disabled={isLoading}
>
{availableTaskTypes.map(type => (
{type}
))}

{/ Prompt Input /}

type="text"
value={prompt}
onChange={(e) => setPrompt(e.target.value)}
placeholder="Enter your prompt..."
disabled={isLoading}
/>

{/ Submit Button /}

{isLoading ? Generating (${progress}%) : 'Generate 3D Model'}


{/ Progress Display /}
{isLoading && (




{task?.progressDetail || 'Processing...'}


)}

{/ Result Display /}
{task?.status === TaskStatus.SUCCEEDED && (

Model ready!

Download Model
{task.result?.thumbnail && (

)}

)}

{/ Error Display /}
{error &&

Error: {error.message}

}

{/ Reset Button /}
{(task || error) && !isLoading && (
Start New
)}

`typescript
import { Magi3DClient, TripoProvider, TaskType } from 'magi-3d/server';

// Uses TRIPO_API_KEY env var by default
const provider = new TripoProvider();
const client = new Magi3DClient(provider);

// Create task
const taskId = await client.createTask({
type: TaskType.TEXT_TO_3D,
prompt: 'a medieval sword'
});

// Poll until complete
const result = await client.pollUntilDone(taskId, {
onProgress: (task) => console.log(${task.progress}%)
});

console.log('Model URL:', result.result?.model); // Primary model URL
console.log('Raw Response:', result.rawResponse); // Full provider API response
`

Supported Providers

$3

`typescript
import { TripoProvider } from 'magi-3d/server';

// Option 1: Use environment variable (recommended)
const provider = new TripoProvider(); // Uses TRIPO_API_KEY

// Option 2: Explicit API key
const provider = new TripoProvider({
apiKey: 'your-tripo-api-key'
});
`

Supported Task Types:
- TEXT_TO_3D - Generate from text prompt
- IMAGE_TO_3D - Generate from image URL
- MULTIVIEW_TO_3D - Generate from multiple views
- RIG - Add skeletal rigging
- ANIMATE - Apply animation presets
- TEXTURE - Re-texture model
- REFINE - Improve quality
- DECIMATE - Reduce polygons
- CONVERT - Format conversion

$3

`typescript
import { HunyuanProvider } from 'magi-3d/server';

// Option 1: Use environment variables (recommended)
const provider = new HunyuanProvider({
region: 'ap-guangzhou'
}); // Uses HUNYUAN_SECRET_ID and HUNYUAN_SECRET_KEY

// Option 2: Explicit credentials
const provider = new HunyuanProvider({
secretId: 'your-tencent-secret-id',
secretKey: 'your-tencent-secret-key',
region: 'ap-guangzhou'
});
`

Progress Reporting: Hunyuan API does not return granular progress percentages. The SDK estimates progress based on task status:
- PENDING (WAIT) -> 0%
- PROCESSING (RUN) -> 50%
- SUCCEEDED (DONE) -> 100%

The raw Hunyuan status is available in task.progressDetail for debugging.

Supported Task Types:
- TEXT_TO_3D - Generate from text prompt
- IMAGE_TO_3D - Generate from image URL or base64
- MULTIVIEW_TO_3D - Generate from multiple views (Pro only)
- TEXTURE - Add texture to geometry (requires modelUrl)
- DECIMATE - Reduce face count (requires modelUrl)
- UV_UNWRAP - UV Unwrap (requires modelUrl)
- SEGMENT - Component generation (requires modelUrl)
- CONVERT - Format conversion (sync)

> Note: Hunyuan post-processing tasks require modelUrl instead of taskId.

React Hooks

$3

Unified hook for all task types (generation and post-processing).

`tsx
import { useCreateTask, TaskType } from 'magi-3d/react';

const {
createTask, // (params: TaskParams) => Promise
task, // StandardTask | null
taskId, // string | null
isLoading, // boolean
progress, // number (0-100)
error, // Error | null
reset, // () => void
stop // () => void
} = useCreateTask({
api: '/api/3d',
pollingInterval: 3000,
timeout: 300000,
onProgress: (task) => {},
onSuccess: (task) => {},
onError: (error) => {}
});

// Text-to-3D
createTask({ type: TaskType.TEXT_TO_3D, prompt: 'a cat', providerId: ProviderId.TRIPO });

// Image-to-3D
createTask({ type: TaskType.IMAGE_TO_3D, input: 'https://...', providerId: ProviderId.HUNYUAN });

// Post-processing (rigging - Tripo)
createTask({ type: TaskType.RIG, taskId: 'original-id', skeleton: 'biped' });

// Format conversion
createTask({ type: TaskType.CONVERT, taskId: 'original-id', format: 'fbx' });
`

$3

Track an existing task by ID. Requires providerId so the backend knows which provider to query.

`tsx
import { useTaskStatus, ProviderId } from 'magi-3d/react';

const {
task,
progress,
isPolling,
startPolling,
stopPolling,
refresh
} = useTaskStatus({
api: '/api/3d',
providerId: ProviderId.TRIPO, // Required
onComplete: (task) => console.log('Done!', task.result?.model)
});

// Start polling for existing task
startPolling('existing-task-id');
`

$3

`tsx
import { PROVIDERS, PROVIDER_TASK_TYPES, ProviderId, TaskType } from 'magi-3d/react';

// List all providers
console.log(PROVIDERS); // ['tripo', 'hunyuan']

// Get task types for a provider
const tripoTypes = PROVIDER_TASK_TYPES[ProviderId.TRIPO];
// => [TaskType.TEXT_TO_3D, TaskType.IMAGE_TO_3D, TaskType.RIG, ...]

const hunyuanTypes = PROVIDER_TASK_TYPES[ProviderId.HUNYUAN];
// => [TaskType.TEXT_TO_3D, TaskType.IMAGE_TO_3D, TaskType.TEXTURE, ...]
`

Task Types

All operations use a single createTask() method. The type field determines the operation:

| Type | Description | Required Params | Tripo | Hunyuan |
|------|-------------|-----------------|-------|---------|
| TEXT_TO_3D | Generate from text | prompt | Yes | Yes |
| IMAGE_TO_3D | Generate from image | input (URL or base64) | Yes | Yes |
| MULTIVIEW_TO_3D | Generate from views | inputs (array of URLs) | Yes | Yes |
| RIG | Add skeletal rigging | taskId, skeleton | Yes | No |
| ANIMATE | Apply animation | taskId, animation | Yes | No |
| TEXTURE | Re-texture model | taskId or modelUrl | Yes | Yes |
| REFINE | Improve quality | taskId | Yes | No |
| DECIMATE | Reduce polygons | taskId or modelUrl | Yes | Yes |
| CONVERT | Format conversion | taskId, format | Yes | Yes |

> Note: IMAGE_TO_3D and MULTIVIEW_TO_3D do not support text prompts. Use TEXT_TO_3D if you need prompt-based generation.

StandardTask Response

All providers return this normalized format:

`typescript
interface StandardTask {
id: string;
provider: 'tripo' | 'hunyuan';
type: TaskType;
status: 'PENDING' | 'PROCESSING' | 'SUCCEEDED' | 'FAILED' | 'CANCELED';
progress: number; // 0-100
progressDetail?: string; // Raw provider status

result?: {
model: string; // Primary model URL - always use this
modelGlb?: string; // GLB URL (when format is known)
modelPbr?: string; // PBR model URL
modelFbx?: string;
modelObj?: string;
thumbnail?: string;
video?: string;
};

error?: {
code: string;
message: string;
raw?: unknown; // Provider's raw error
};

rawResponse?: unknown; // Full provider API response for debugging

createdAt: number;
finishedAt?: number;
}
`

Task Status

| Status | Description |
|--------|-------------|
| PENDING | Waiting to start |
| PROCESSING | Generation in progress |
| SUCCEEDED | Complete with results |
| FAILED | Generation failed |
| CANCELED | User cancelled |

Provider Options

$3

#### Model Versions

| Version | Speed | Quality | Notes |
|---------|-------|---------|-------|
| Turbo-v1.0-20250506 | ~10s | Good | Fast prototyping |
| v3.0-20250812 | ~60s | Best | Supports geometry_quality for Ultra version|
| v2.5-20250123 | ~45s | High | Balanced |
| v2.0-20240919 | ~45s | High | Stable, Fast |
| v1.4-20240625 | ~40s | Medium | Legacy |

#### TEXT_TO_3D / IMAGE_TO_3D Parameters

| Parameter | Type | Default | Versions | Description |
|-----------|------|---------|----------|-------------|
| model_version | string | v2.5-20250123 | All | Model version |
| pbr | boolean | true | All | Enable PBR materials |
| texture | boolean | true | All | Enable texturing |
| texture_quality | 'standard' \| 'detailed' | standard | All | Texture resolution |
| texture_alignment | 'original_image' \| 'geometry' | original_image| v2.0+ | Texture alignment |
| texture_seed | number | random | v2.0+ | Reproducible textures |
| face_limit | number | - | All | Max face count |
| quad | boolean | false | v2.0+ | Quad mesh (forces FBX) |
| geometry_quality | 'standard' \| 'detailed' | standard | v3.0+ only | Geometry detail level |
| auto_size | boolean | false | v2.0+ | Real-world scale (meters) |
| orientation | 'default' \| 'align_image' | default | v2.0+ | Model orientation |
| model_seed | number | random | v2.0+ | Reproducible geometry |
| smart_low_poly | boolean | false | v2.0+ | Hand-crafted low-poly topology |
| generate_parts | boolean | false | v2.0+ | Generate segmented parts |
| compress | 'geometry' | - | v2.0+ | Apply meshopt compression |
| enable_image_autofix | boolean | false | All | Optimize input image |
| negative_prompt | string | - | Text only | Reverse direction prompt |
| image_seed | number | random | Text only | Seed for prompt processing |

#### Example

`typescript
// Text-to-3D with v3.0 features
createTask({
type: TaskType.TEXT_TO_3D,
prompt: 'a futuristic robot',
providerOptions: {
model_version: 'v3.0-20250812',
pbr: true,
texture_quality: 'detailed',
geometry_quality: 'detailed', // v3.0+ only
face_limit: 50000
}
});

// Rigging
createTask({
type: TaskType.RIG,
taskId: 'original-task-id',
skeleton: 'biped',
outFormat: 'fbx'
});

// Animation
createTask({
type: TaskType.ANIMATE,
taskId: 'rigged-task-id',
animation: 'preset:walk',
outFormat: 'glb'
});
`

---

$3

#### Versions

| Version | Concurrency | Max Faces | Speed | Use Case |
|---------|-------------|-----------|-------|----------|
| Professional (Pro) | 3 | 1,500,000 | ~120s | High-quality production |
| Rapid | 1 | - | ~30s | Fast prototyping |

#### TEXT_TO_3D / IMAGE_TO_3D Parameters (Professional)

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| EnablePBR | boolean | false | Enable PBR materials |
| FaceCount | number | 500,000 | Face count (40,000 - 1,500,000) |
| GenerateType | string | 'Normal' | Generation mode (see below) |
| PolygonType | 'triangle' \| 'quadrilateral' | triangle | Mesh type (LowPoly only) |

#### GenerateType Values (Professional)

| Value | Description | Notes |
|-------|-------------|-------|
| 'Normal' | Standard textured model | Default |
| 'LowPoly' | Optimized low-poly | Supports PolygonType |
| 'Geometry' | White model (no texture) | EnablePBR ignored |
| 'Sketch' | From sketch/line art | Can combine with prompt |

#### Example

`typescript
// Professional: High-quality generation
createTask({
type: TaskType.TEXT_TO_3D,
prompt: 'a cute cat',
providerOptions: {
EnablePBR: true,
FaceCount: 500000,
GenerateType: 'Normal'
}
});

// Professional: LowPoly with quad mesh
createTask({
type: TaskType.TEXT_TO_3D,
prompt: 'a cute rabbit',
providerOptions: {
GenerateType: 'LowPoly',
PolygonType: 'quadrilateral'
}
});

// Decimate: Reduce polygon count (requires modelUrl for Hunyuan)
createTask({
type: TaskType.DECIMATE,
modelUrl: 'https://example.com/model.glb', // Not taskId!
providerOptions: {
FaceLevel: 'low',
PolygonType: 'triangle'
}
});
`

Error Handling

The SDK provides two custom error classes for different error scenarios:

$3

`typescript
import { TaskError, ApiError } from 'magi-3d/server';

// TaskError - Thrown when a task fails during polling
// Contains the full StandardTask with error details
try {
const result = await client.pollUntilDone(taskId);
} catch (error) {
if (error instanceof TaskError) {
console.log('Error code:', error.code); // e.g., 'CONTENT_POLICY_VIOLATION'
console.log('Task:', error.task); // Full StandardTask object
console.log('Raw response:', error.task.error?.raw); // Provider's raw response
}
}

// ApiError - Thrown when API request fails (auth, validation, network)
// Contains code, httpStatus, and raw provider response
try {
const taskId = await client.createTask(params);
} catch (error) {
if (error instanceof ApiError) {
console.log('Error code:', error.code); // e.g., 'RATE_LIMIT_EXCEEDED'
console.log('HTTP status:', error.httpStatus); // e.g., 429
console.log('Raw response:', error.raw); // Provider's raw response
}
}
`

$3

`typescript
import { TaskError, ApiError, TaskStatus } from 'magi-3d/server';

// Server-side with proper error handling
try {
const taskId = await client.createTask(params);
const result = await client.pollUntilDone(taskId);
console.log('Model URL:', result.result?.model);
} catch (error) {
if (error instanceof TaskError) {
// Task failed during generation
console.log('Task failed:', error.code);
console.log('Raw response:', error.task.error?.raw);
} else if (error instanceof ApiError) {
// API request failed (auth, validation, etc.)
console.log('API error:', error.code, error.httpStatus);
console.log('Raw response:', error.raw);
}
}

// React hooks
const { task, error } = useCreateTask({ api: '/api/3d' });

if (task?.error) {
switch (task.error.code) {
case 'CONTENT_POLICY_VIOLATION':
showAlert('Content was flagged. Please modify and retry.');
break;
case 'INSUFFICIENT_CREDITS':
showAlert('Please purchase more credits.');
break;
default:
showAlert(task.error.message);
}
}
`

$3

| Tripo Code | SDK Error Code | HTTP | Description |
|------------|----------------|------|-------------|
| 1000 | SERVER_ERROR | 500 | Server error |
| 1001 | FATAL_SERVER_ERROR | 500 | Fatal server error |
| 2000 | RATE_LIMIT_EXCEEDED | 429 | Rate limit hit |
| 2001 | TASK_NOT_FOUND | 404 | Invalid task ID |
| 2002 | UNSUPPORTED_TASK_TYPE | 400 | Invalid task type |
| 2003 | INPUT_FILE_EMPTY | 400 | No input file |
| 2004 | UNSUPPORTED_FILE_TYPE | 400 | Bad file format |
| 2006 | INVALID_ORIGINAL_TASK | 400 | Bad original task |
| 2007 | ORIGINAL_TASK_NOT_SUCCESS | 400 | Original task not done |
| 2008 | CONTENT_POLICY_VIOLATION | 400 | Content banned |
| 2010 | INSUFFICIENT_CREDITS | 403 | No credits |
| 2015 | DEPRECATED_VERSION | 400 | Version deprecated |
| 2018 | MODEL_TOO_COMPLEX | 400 | Cannot remesh |

Task Status Errors:

| Status | SDK Code | Description |
|--------|----------|-------------|
| failed | GENERATION_FAILED | Model generation failed |
| banned | CONTENT_POLICY_VIOLATION | Content policy violation |
| expired | TASK_EXPIRED | Task expired |
| cancelled | TASK_CANCELED | Task was cancelled |

$3

| Hunyuan Code | SDK Error Code | Description |
|--------------|----------------|-------------|
| AuthFailure.SignatureExpire | SIGNATURE_EXPIRED | Signature expired |
| AuthFailure.SignatureFailure | SIGNATURE_FAILURE | Invalid signature |
| AuthFailure.SecretIdNotFound | SECRET_ID_NOT_FOUND | Secret ID not found |
| InvalidParameter | INVALID_PARAMETER | Invalid parameter |
| MissingParameter | MISSING_PARAMETER | Missing parameter |
| RequestLimitExceeded | RATE_LIMIT_EXCEEDED | Rate limit exceeded |
| ResourceNotFound | RESOURCE_NOT_FOUND | Resource not found |
| FailedOperation.* | OPERATION_FAILED | Operation failed (retry) |
| InternalError | INTERNAL_ERROR | Internal server error |
| ServiceUnavailable | SERVICE_UNAVAILABLE | Service unavailable |

Task Status Errors:

| Status | SDK Code | Description |
|--------|----------|-------------|
| FAILED | GENERATION_FAILED | Model generation failed |
| CANCELED | TASK_CANCELED | Task was cancelled |

---

TypeScript Support

Full TypeScript support with detailed type definitions:

`typescript
import {
// Error classes
TaskError, // Thrown when task fails during polling
ApiError, // Thrown when API request fails

// Types
type TaskParams,
type StandardTask,
type TaskArtifacts,
type TripoOptions,
type HunyuanOptions
} from 'magi-3d/server';

import {
// Provider metadata
PROVIDERS,
PROVIDER_TASK_TYPES,

// Types
type UseCreateTaskOptions,
type UseCreateTaskReturn,
type UseTaskStatusOptions,
type UseTaskStatusReturn
} from 'magi-3d/react';
`

Environment Variables

| Variable | Provider | Description |
|----------|----------|-------------|
| TRIPO_API_KEY | Tripo | API key for Tripo |
| HUNYUAN_SECRET_ID | Hunyuan | Tencent Cloud Secret ID |
| HUNYUAN_SECRET_KEY | Hunyuan | Tencent Cloud Secret Key |

E2E Testing

`bash


Setup

See scripts/test-guidelines.md` for detailed test documentation.

Requirements

- Node.js >= 18.0.0 (for server-side)
- React >= 17.0.0 (for hooks, optional peer dependency)

License

MIT

Support

- Issues: GitHub Issues
- Email: support@funmagic.ai