Status: {status} ({progress}%)
{/* Link to view progress on main site */}
{webViewUrl && (
View on main site
)}
{/* 2D styled preview */}
{preview2dUrl && (
2D Style Preview
)}
{/* 3D Model Viewer */}
{glbUrl && (
3D Model
)}
);
}
```
## API Reference
### `initTransfer3D(config?)`
Initialize the default SDK client. Call this once at app startup to configure the base URL and authentication token for all API calls.
**Parameters:**
- `config.baseURL` (optional): API base URL. Falls back to environment variables.
- `config.token` (optional): Bearer authentication token. Falls back to environment variables.
**Example:**
```typescript
import { initTransfer3D, getTransfer3dStyles } from '@cymmetrik-dev/3d-transfer-sdk';
// Initialize with explicit config
initTransfer3D({
baseURL: 'https://api.example.com/api',
token: 'your-api-token',
});
// Or auto-detect from environment variables
initTransfer3D();
// Now all API calls use this configuration (no need to pass client)
const styles = await getTransfer3dStyles();
```
---
### `createTransfer3DClient(config?)`
Create a separate API client instance. Use this when you need multiple clients or want to override the default configuration for specific calls.
**Parameters:**
- `config.baseURL` (optional): API base URL
- `config.token` (optional): Bearer authentication token
- `config.timeout` (optional): Request timeout in ms (default: 30000)
**Returns:** Configured axios client
---
### `getTransfer3dStyles(options)`
Get available 3D transfer styles.
**Parameters:**
- `query.default_style` (optional): string - Filter to return only this style
**Example:**
```typescript
// Get all styles
const allStyles = await getTransfer3dStyles({ client });
// Get single style (useful for single-style deployments)
const singleStyle = await getTransfer3dStyles({
client,
query: { default_style: 'smart' },
});
```
**Returns:**
```typescript
{
success: true,
data: Array<{
mode_key: string; // Style identifier (e.g., 'smart')
mode_name: string; // Display name (e.g., 'Q版公仔')
mode_description: string;
preview_image_url: string | null;
}>
}
```
> **Note:** If `default_style` is specified but not found, API returns all styles as fallback.
---
### `initiateTransfer3dConversion(options)`
Upload an image and start the 3D conversion process.
**Parameters:**
- `body.image`: File - Image to convert (max 10MB, supported: jpg, png, webp)
- `body.style`: string - Style key from `getTransfer3dStyles()`
- `body.additional_instruction` (optional): string - Custom style guidance (max 2000 chars)
- `body.auto_3d` (optional): boolean - Auto-proceed to 3D after 2D completes (default: `true`)
**Example:**
```typescript
// Basic conversion (auto 2D → 3D)
const result = await initiateTransfer3dConversion({
client,
body: {
image: imageFile,
style: 'smart',
},
});
// With additional instruction for fine-tuning
const result = await initiateTransfer3dConversion({
client,
body: {
image: imageFile,
style: 'smart',
additional_instruction: '增加金色高光效果，使用暖色調',
},
});
// 2D-only mode: Stop after 2D style transfer
const result = await initiateTransfer3dConversion({
client,
body: {
image: imageFile,
style: 'smart',
auto_3d: false, // Will stop at 2D_COMPLETED status
},
});
```
**Additional Instruction Use Cases:**
- Fine-tune style output (e.g., "更卡通化", "增加質感")
- Specify colors or materials (e.g., "使用暖色調", "金屬質感")
- Adjust lighting effects (e.g., "增加高光", "柔和陰影")
> **Note:** `additional_instruction` is **appended** to the style's base instructions, not replaced.
**Returns:**
```typescript
{
success: true,
data: {
request_id: string; // UUID for status polling
chat_thread_id: number; // Internal ChatThread ID (for add-to-cart)
status: 'PENDING';
message: string;
}
}
```
---
### `triggerTransfer3dConversion(options)`
Trigger 3D generation for a request that completed 2D styling. Use this when you initiated a conversion with `auto_3d: false`.
**Parameters:**
- `body.request_id`: string - The request ID from the original `/convert` call
**Example:**
```typescript
// After status shows '2D_COMPLETED', trigger 3D generation
const result = await triggerTransfer3dConversion({
client,
body: {
request_id: 'uuid-xxx',
},
});
```
**Returns:**
```typescript
{
success: true,
data: {
request_id: string;
chat_thread_id: number; // Internal ChatThread ID (for add-to-cart)
status: 'IN_PROGRESS';
message: '3D conversion initiated';
}
}
```
**Error Responses:**
- `400` - 2D style transfer not yet completed
- `400` - 3D conversion already in progress or completed
- `404` - Request not found
---
### `getTransfer3dStatus(options)`
Get the status of a conversion request.
**Parameters:**
- `path.requestId`: string - Request ID from conversion response
**Returns:**
```typescript
{
success: true,
data: {
request_id: string;
status: 'PENDING' | 'IN_PROGRESS' | '2D_COMPLETED' | 'COMPLETED' | 'FAILED';
phase: '2d_style_transfer' | '3d_generation_pending' | '3d_generation';
progress: number; // 0-100 (2D_COMPLETED = 50%)
web_view_url: string; // URL to view progress on main site
auto_3d?: boolean; // Present for API requests, indicates if 3D will auto-start
result?: {
preview_2d_url: string; // Available when 2D transfer completes
model_3d_url: string; // Available when fully completed
glb_url: string; // GLB file URL (same as model_3d_url)
};
error?: string; // Present if status is FAILED
}
}
```
> **Note:** When `auto_3d: false`, the status will be `2D_COMPLETED` (not `COMPLETED`) when 2D styling finishes. Call `triggerTransfer3dConversion()` to start 3D generation.
---
### `getTransfer3DProduct(options)`
Get product information by slug, including name, description, price, and images.
**Parameters:**
- `path.slug`: string - The product slug
**Example:**
```typescript
import {
createTransfer3DClient,
getTransfer3DProduct,
getDefaultProductSlug,
} from '@cymmetrik-dev/3d-transfer-sdk';
const client = createTransfer3DClient();
// Get product by slug
const { data } = await getTransfer3DProduct({
client,
path: { slug: 'my-product-slug' },
});
console.log('Product:', data.data.name);
console.log('Price:', data.data.price?.formatted);
console.log('Main Image:', data.data.main_image_url);
// Or use default product slug from environment
const defaultSlug = getDefaultProductSlug();
if (defaultSlug) {
const { data } = await getTransfer3DProduct({
client,
path: { slug: defaultSlug },
});
}
```
**Returns:**
```typescript
{
success: true,
data: {
slug: string;
name: string;
description: string;
price: {
value: number; // Price in smallest currency unit
formatted: string; // e.g., "NT$1,990"
currency: string; // e.g., "TWD"
} | null;
main_image_url: string | null;
images: Array<{
url: string;
alt: string;
}>;
variants: Array<{
id: number; // Variant ID (use for add-to-cart)
sku: string; // SKU code
options: Array<{ // Variant options (e.g., color, size)
name: string; // Option name (e.g., "顏色")
value: string; // Option value (e.g., "紅色")
}>;
price: {
value: number;
formatted: string;
currency: string;
};
}>;
}
}
```
**Example with Variants:**
```typescript
const { data } = await getTransfer3DProduct({
client,
path: { slug: 'my-product' },
});
// Display product with variant selector
console.log('Product:', data.data.name);
data.data.variants.forEach((variant) => {
const optionText = variant.options
.map(o => `${o.name}: ${o.value}`)
.join(', ');
console.log(`- ${variant.sku} (${optionText}): ${variant.price.formatted}`);
});
// Add specific variant to cart
const selectedVariant = data.data.variants[0];
const cartUrl = buildAddToCartUrl('https://shop.example.com', {
products: [{ model_type: 'product_variant', model_id: selectedVariant.id }],
});
```
---
### `getDefaultProductSlug()`
Get the default product slug from environment variables.
**Returns:** `string | undefined`
**Example:**
```typescript
import { getDefaultProductSlug } from '@cymmetrik-dev/3d-transfer-sdk';
const slug = getDefaultProductSlug();
// Returns value from VITE_DEFAULT_PRODUCT_SLUG, NEXT_PUBLIC_DEFAULT_PRODUCT_SLUG, etc.
```
---
### `getDefaultStyle()`
Get the default style from environment variables.
**Returns:** `string | undefined`
**Example:**
```typescript
import { getDefaultStyle } from '@cymmetrik-dev/3d-transfer-sdk';
const style = getDefaultStyle();
// Returns value from VITE_TRANSFER_3D_DEFAULT_STYLE, etc.
```
---
## Add to Cart Redirect
The SDK provides helper functions to build URLs that add products to the shopping cart and redirect users. This feature:
- Works for both logged-in users and guest users
- Supports adding multiple products at once
- Allows custom redirect URLs after adding to cart
- No authentication token required (public endpoint)
### `buildAddToCartUrl(baseURL, options)`
Build a URL that adds products to cart and redirects.
**Parameters:**
- `baseURL`: string - The shop's base URL (without `/api`)
- `options.products`: CartProduct[] - Products to add
- `options.redirectUrl`: string (optional) - Redirect URL after adding (default: `/cart`)
**CartProduct interface:**
```typescript
interface CartProduct {
model_type:
| 'Lunar\\Models\\ProductVariant'
| 'Projects\\Frontier\\Models\\FrontierOrder'
| 'Projects\\Frontier\\Models\\ChatThread'; // Auto-creates FrontierOrder
model_id: number;
quantity?: number; // default: 1
}
```
**Example:**
```typescript
import { buildAddToCartUrl } from '@cymmetrik-dev/3d-transfer-sdk';
// Add single product
const url = buildAddToCartUrl('https://shop.example.com', {
products: [{ model_type: 'product_variant', model_id: 123 }],
});
// Result: https://shop.example.com/api/3d-transfer/add-to-cart?products=[{"model_type":"product_variant","model_id":123}]
// Add multiple products with quantities
const url = buildAddToCartUrl('https://shop.example.com', {
products: [
{ model_type: 'product_variant', model_id: 123, quantity: 2 },
{ model_type: 'product_variant', model_id: 456, quantity: 1 },
],
});
// With custom redirect URL
const url = buildAddToCartUrl('https://shop.example.com', {
products: [{ model_type: 'product_variant', model_id: 123 }],
redirectUrl: '/checkout',
});
// Add 3D model by ChatThread ID (auto-creates FrontierOrder if needed)
const url = buildAddToCartUrl('https://shop.example.com', {
products: [{ model_type: 'Projects\\Frontier\\Models\\ChatThread', model_id: chatThreadId }],
});
// Or add existing FrontierOrder directly
const url = buildAddToCartUrl('https://shop.example.com', {
products: [{ model_type: 'Projects\\Frontier\\Models\\FrontierOrder', model_id: 789 }],
});
```
---
### `buildAddToCartUrlFromEnv(options)`
Build add-to-cart URL using the API URL from environment variables.
**Parameters:**
- `options.products`: CartProduct[] - Products to add
- `options.redirectUrl`: string (optional) - Redirect URL after adding
**Returns:** `string | null` - URL or null if API URL not configured
**Example:**
```typescript
import { buildAddToCartUrlFromEnv } from '@cymmetrik-dev/3d-transfer-sdk';
const url = buildAddToCartUrlFromEnv({
products: [{ model_type: 'product_variant', model_id: 123 }],
});
if (url) {
window.location.href = url;
}
```
---
### Add to Cart - React Example
```tsx
import { buildAddToCartUrl, getTransfer3DProduct } from '@cymmetrik-dev/3d-transfer-sdk';
function BuyButton({ productId }: { productId: number }) {
const handleBuy = () => {
const url = buildAddToCartUrl('https://shop.example.com', {
products: [{ model_type: 'product_variant', model_id: productId }],
redirectUrl: '/checkout',
});
window.location.href = url;
};
return (