\n
\n );\n}\n```\n\n## API Reference\n\n### `initTransfer3D(config?)`\n\nInitialize the default SDK client. Call this once at app startup to configure the base URL and authentication token for all API calls.\n\n**Parameters:**\n- `config.baseURL` (optional): API base URL. Falls back to environment variables.\n- `config.token` (optional): Bearer authentication token. Falls back to environment variables.\n\n**Example:**\n```typescript\nimport { initTransfer3D, getTransfer3dStyles } from '@cymmetrik-dev/3d-transfer-sdk';\n\n// Initialize with explicit config\ninitTransfer3D({\n baseURL: 'https://api.example.com/api',\n token: 'your-api-token',\n});\n\n// Or auto-detect from environment variables\ninitTransfer3D();\n\n// Now all API calls use this configuration (no need to pass client)\nconst styles = await getTransfer3dStyles();\n```\n\n---\n\n### `createTransfer3DClient(config?)`\n\nCreate a separate API client instance. Use this when you need multiple clients or want to override the default configuration for specific calls.\n\n**Parameters:**\n- `config.baseURL` (optional): API base URL\n- `config.token` (optional): Bearer authentication token\n- `config.timeout` (optional): Request timeout in ms (default: 30000)\n\n**Returns:** Configured axios client\n\n---\n\n### `getTransfer3dStyles(options)`\n\nGet available 3D transfer styles.\n\n**Parameters:**\n- `query.default_style` (optional): string - Filter to return only this style\n\n**Example:**\n```typescript\n// Get all styles\nconst allStyles = await getTransfer3dStyles({ client });\n\n// Get single style (useful for single-style deployments)\nconst singleStyle = await getTransfer3dStyles({\n client,\n query: { default_style: 'smart' },\n});\n```\n\n**Returns:**\n```typescript\n{\n success: true,\n data: Array<{\n mode_key: string; // Style identifier (e.g., 'smart')\n mode_name: string; // Display name (e.g., 'Q版公仔')\n mode_description: string;\n preview_image_url: string | null;\n }>\n}\n```\n\n> **Note:** If `default_style` is specified but not found, API returns all styles as fallback.\n\n---\n\n### `initiateTransfer3dConversion(options)`\n\nUpload an image and start the 3D conversion process.\n\n**Parameters:**\n- `body.image`: File - Image to convert (max 10MB, supported: jpg, png, webp)\n- `body.style`: string - Style key from `getTransfer3dStyles()`\n- `body.additional_instruction` (optional): string - Custom style guidance (max 2000 chars)\n- `body.auto_3d` (optional): boolean - Auto-proceed to 3D after 2D completes (default: `true`)\n\n**Example:**\n```typescript\n// Basic conversion (auto 2D → 3D)\nconst result = await initiateTransfer3dConversion({\n client,\n body: {\n image: imageFile,\n style: 'smart',\n },\n});\n\n// With additional instruction for fine-tuning\nconst result = await initiateTransfer3dConversion({\n client,\n body: {\n image: imageFile,\n style: 'smart',\n additional_instruction: '增加金色高光效果，使用暖色調',\n },\n});\n\n// 2D-only mode: Stop after 2D style transfer\nconst result = await initiateTransfer3dConversion({\n client,\n body: {\n image: imageFile,\n style: 'smart',\n auto_3d: false, // Will stop at 2D_COMPLETED status\n },\n});\n```\n\n**Additional Instruction Use Cases:**\n- Fine-tune style output (e.g., \"更卡通化\", \"增加質感\")\n- Specify colors or materials (e.g., \"使用暖色調\", \"金屬質感\")\n- Adjust lighting effects (e.g., \"增加高光\", \"柔和陰影\")\n\n> **Note:** `additional_instruction` is **appended** to the style's base instructions, not replaced.\n\n**Returns:**\n```typescript\n{\n success: true,\n data: {\n request_id: string; // UUID for status polling\n chat_thread_id: number; // Internal ChatThread ID (for add-to-cart)\n status: 'PENDING';\n message: string;\n }\n}\n```\n\n---\n\n### `triggerTransfer3dConversion(options)`\n\nTrigger 3D generation for a request that completed 2D styling. Use this when you initiated a conversion with `auto_3d: false`.\n\n**Parameters:**\n- `body.request_id`: string - The request ID from the original `/convert` call\n\n**Example:**\n```typescript\n// After status shows '2D_COMPLETED', trigger 3D generation\nconst result = await triggerTransfer3dConversion({\n client,\n body: {\n request_id: 'uuid-xxx',\n },\n});\n```\n\n**Returns:**\n```typescript\n{\n success: true,\n data: {\n request_id: string;\n chat_thread_id: number; // Internal ChatThread ID (for add-to-cart)\n status: 'IN_PROGRESS';\n message: '3D conversion initiated';\n }\n}\n```\n\n**Error Responses:**\n- `400` - 2D style transfer not yet completed\n- `400` - 3D conversion already in progress or completed\n- `404` - Request not found\n\n---\n\n### `getTransfer3dStatus(options)`\n\nGet the status of a conversion request.\n\n**Parameters:**\n- `path.requestId`: string - Request ID from conversion response\n\n**Returns:**\n```typescript\n{\n success: true,\n data: {\n request_id: string;\n status: 'PENDING' | 'IN_PROGRESS' | '2D_COMPLETED' | 'COMPLETED' | 'FAILED';\n phase: '2d_style_transfer' | '3d_generation_pending' | '3d_generation';\n progress: number; // 0-100 (2D_COMPLETED = 50%)\n web_view_url: string; // URL to view progress on main site\n auto_3d?: boolean; // Present for API requests, indicates if 3D will auto-start\n result?: {\n preview_2d_url: string; // Available when 2D transfer completes\n model_3d_url: string; // Available when fully completed\n glb_url: string; // GLB file URL (same as model_3d_url)\n };\n error?: string; // Present if status is FAILED\n }\n}\n```\n\n> **Note:** When `auto_3d: false`, the status will be `2D_COMPLETED` (not `COMPLETED`) when 2D styling finishes. Call `triggerTransfer3dConversion()` to start 3D generation.\n\n---\n\n### `getTransfer3DProduct(options)`\n\nGet product information by slug, including name, description, price, and images.\n\n**Parameters:**\n- `path.slug`: string - The product slug\n\n**Example:**\n```typescript\nimport {\n createTransfer3DClient,\n getTransfer3DProduct,\n getDefaultProductSlug,\n} from '@cymmetrik-dev/3d-transfer-sdk';\n\nconst client = createTransfer3DClient();\n\n// Get product by slug\nconst { data } = await getTransfer3DProduct({\n client,\n path: { slug: 'my-product-slug' },\n});\n\nconsole.log('Product:', data.data.name);\nconsole.log('Price:', data.data.price?.formatted);\nconsole.log('Main Image:', data.data.main_image_url);\n\n// Or use default product slug from environment\nconst defaultSlug = getDefaultProductSlug();\nif (defaultSlug) {\n const { data } = await getTransfer3DProduct({\n client,\n path: { slug: defaultSlug },\n });\n}\n```\n\n**Returns:**\n```typescript\n{\n success: true,\n data: {\n slug: string;\n name: string;\n description: string;\n price: {\n value: number; // Price in smallest currency unit\n formatted: string; // e.g., \"NT$1,990\"\n currency: string; // e.g., \"TWD\"\n } | null;\n main_image_url: string | null;\n images: Array<{\n url: string;\n alt: string;\n }>;\n variants: Array<{\n id: number; // Variant ID (use for add-to-cart)\n sku: string; // SKU code\n options: Array<{ // Variant options (e.g., color, size)\n name: string; // Option name (e.g., \"顏色\")\n value: string; // Option value (e.g., \"紅色\")\n }>;\n price: {\n value: number;\n formatted: string;\n currency: string;\n };\n }>;\n }\n}\n```\n\n**Example with Variants:**\n```typescript\nconst { data } = await getTransfer3DProduct({\n client,\n path: { slug: 'my-product' },\n});\n\n// Display product with variant selector\nconsole.log('Product:', data.data.name);\n\ndata.data.variants.forEach((variant) => {\n const optionText = variant.options\n .map(o => `${o.name}: ${o.value}`)\n .join(', ');\n console.log(`- ${variant.sku} (${optionText}): ${variant.price.formatted}`);\n});\n\n// Add specific variant to cart\nconst selectedVariant = data.data.variants[0];\nconst cartUrl = buildAddToCartUrl('https://shop.example.com', {\n products: [{ model_type: 'product_variant', model_id: selectedVariant.id }],\n});\n```\n\n---\n\n### `getDefaultProductSlug()`\n\nGet the default product slug from environment variables.\n\n**Returns:** `string | undefined`\n\n**Example:**\n```typescript\nimport { getDefaultProductSlug } from '@cymmetrik-dev/3d-transfer-sdk';\n\nconst slug = getDefaultProductSlug();\n// Returns value from VITE_DEFAULT_PRODUCT_SLUG, NEXT_PUBLIC_DEFAULT_PRODUCT_SLUG, etc.\n```\n\n---\n\n### `getDefaultStyle()`\n\nGet the default style from environment variables.\n\n**Returns:** `string | undefined`\n\n**Example:**\n```typescript\nimport { getDefaultStyle } from '@cymmetrik-dev/3d-transfer-sdk';\n\nconst style = getDefaultStyle();\n// Returns value from VITE_TRANSFER_3D_DEFAULT_STYLE, etc.\n```\n\n---\n\n## Add to Cart Redirect\n\nThe SDK provides helper functions to build URLs that add products to the shopping cart and redirect users. This feature:\n- Works for both logged-in users and guest users\n- Supports adding multiple products at once\n- Allows custom redirect URLs after adding to cart\n- No authentication token required (public endpoint)\n\n### `buildAddToCartUrl(baseURL, options)`\n\nBuild a URL that adds products to cart and redirects.\n\n**Parameters:**\n- `baseURL`: string - The shop's base URL (without `/api`)\n- `options.products`: CartProduct[] - Products to add\n- `options.redirectUrl`: string (optional) - Redirect URL after adding (default: `/cart`)\n\n**CartProduct interface:**\n```typescript\ninterface CartProduct {\n model_type:\n | 'Lunar\\\\Models\\\\ProductVariant'\n | 'Projects\\\\Frontier\\\\Models\\\\FrontierOrder'\n | 'Projects\\\\Frontier\\\\Models\\\\ChatThread'; // Auto-creates FrontierOrder\n model_id: number;\n quantity?: number; // default: 1\n}\n```\n\n**Example:**\n```typescript\nimport { buildAddToCartUrl } from '@cymmetrik-dev/3d-transfer-sdk';\n\n// Add single product\nconst url = buildAddToCartUrl('https://shop.example.com', {\n products: [{ model_type: 'product_variant', model_id: 123 }],\n});\n// Result: https://shop.example.com/api/3d-transfer/add-to-cart?products=[{\"model_type\":\"product_variant\",\"model_id\":123}]\n\n// Add multiple products with quantities\nconst url = buildAddToCartUrl('https://shop.example.com', {\n products: [\n { model_type: 'product_variant', model_id: 123, quantity: 2 },\n { model_type: 'product_variant', model_id: 456, quantity: 1 },\n ],\n});\n\n// With custom redirect URL\nconst url = buildAddToCartUrl('https://shop.example.com', {\n products: [{ model_type: 'product_variant', model_id: 123 }],\n redirectUrl: '/checkout',\n});\n\n// Add 3D model by ChatThread ID (auto-creates FrontierOrder if needed)\nconst url = buildAddToCartUrl('https://shop.example.com', {\n products: [{ model_type: 'Projects\\\\Frontier\\\\Models\\\\ChatThread', model_id: chatThreadId }],\n});\n\n// Or add existing FrontierOrder directly\nconst url = buildAddToCartUrl('https://shop.example.com', {\n products: [{ model_type: 'Projects\\\\Frontier\\\\Models\\\\FrontierOrder', model_id: 789 }],\n});\n```\n\n---\n\n### `buildAddToCartUrlFromEnv(options)`\n\nBuild add-to-cart URL using the API URL from environment variables.\n\n**Parameters:**\n- `options.products`: CartProduct[] - Products to add\n- `options.redirectUrl`: string (optional) - Redirect URL after adding\n\n**Returns:** `string | null` - URL or null if API URL not configured\n\n**Example:**\n```typescript\nimport { buildAddToCartUrlFromEnv } from '@cymmetrik-dev/3d-transfer-sdk';\n\nconst url = buildAddToCartUrlFromEnv({\n products: [{ model_type: 'product_variant', model_id: 123 }],\n});\n\nif (url) {\n window.location.href = url;\n}\n```\n\n---\n\n### Add to Cart - React Example\n\n```tsx\nimport { buildAddToCartUrl, getTransfer3DProduct } from '@cymmetrik-dev/3d-transfer-sdk';\n\nfunction BuyButton({ productId }: { productId: number }) {\n const handleBuy = () => {\n const url = buildAddToCartUrl('https://shop.example.com', {\n products: [{ model_type: 'product_variant', model_id: productId }],\n redirectUrl: '/checkout',\n });\n window.location.href = url;\n };\n\n return (\n \n );\n}\n\n// Or use as a link\nfunction BuyLink({ productId }: { productId: number }) {\n const url = buildAddToCartUrl('https://shop.example.com', {\n products: [{ model_type: 'product_variant', model_id: productId }],\n });\n\n return (\n \n 加入購物車\n \n );\n}\n```\n\n---\n\n### Add to Cart - HTML Example\n\n```html\n\n\n 加入購物車\n\n\n\n\n 立即購買\n\n```\n\n---\n\n### Complete Workflow: 3D Model to Cart\n\n```tsx\nimport {\n createTransfer3DClient,\n initiateTransfer3dConversion,\n getTransfer3dStatus,\n buildAddToCartUrl,\n} from '@cymmetrik-dev/3d-transfer-sdk';\n\n// Full workflow: Upload image → Convert → Add to cart\nasync function convertAndAddToCart(imageFile: File) {\n const client = createTransfer3DClient();\n\n // 1. Start conversion and get chat_thread_id\n const { data: conversionData } = await initiateTransfer3dConversion({\n client,\n body: { image: imageFile, style: 'smart' },\n });\n\n const { request_id: requestId, chat_thread_id: chatThreadId } = conversionData.data;\n console.log('ChatThread ID:', chatThreadId); // Use this for add-to-cart\n\n // 2. Poll until completed\n let status = 'PENDING';\n while (status !== 'COMPLETED' && status !== 'FAILED') {\n await new Promise((r) => setTimeout(r, 2000));\n const { data } = await getTransfer3dStatus({ client, path: { requestId } });\n status = data.data.status;\n }\n\n // 3. Add to cart using ChatThread ID (auto-creates FrontierOrder)\n if (status === 'COMPLETED') {\n const cartUrl = buildAddToCartUrl('https://shop.example.com', {\n products: [{\n model_type: 'Projects\\\\Frontier\\\\Models\\\\ChatThread',\n model_id: chatThreadId,\n }],\n });\n window.location.href = cartUrl;\n }\n}\n```\n\n## Conversion Phases\n\n| Phase | Progress | Description |\n|-------|----------|-------------|\n| `2d_style_transfer` | 0-50% | Image is being styled with AI |\n| `3d_generation_pending` | 50% | 2D complete, waiting for 3D to start |\n| `3d_generation` | 50-100% | 3D model is being generated |\n\n**Note:** The `preview_2d_url` becomes available when the phase changes to `3d_generation_pending` or `3d_generation`, allowing you to show the styled image while the 3D model is still being generated.\n\n## Status Values\n\n| Status | Description |\n|--------|-------------|\n| `PENDING` | Conversion request queued |\n| `IN_PROGRESS` | Currently processing (2D or 3D) |\n| `2D_COMPLETED` | 2D styling finished, waiting for 3D trigger (only when `auto_3d: false`) |\n| `COMPLETED` | Full conversion finished (2D + 3D) |\n| `FAILED` | An error occurred |\n\n> **Tip:** For `auto_3d: false` requests, poll until `status === '2D_COMPLETED'`, show the `preview_2d_url`, then call `triggerTransfer3dConversion()` when ready.\n\n## TypeScript Types\n\n```typescript\nimport type {\n // Request/Response types (auto-generated)\n GetTransfer3dStylesResponse,\n InitiateTransfer3dConversionData,\n InitiateTransfer3dConversionResponse,\n TriggerTransfer3dConversionData,\n TriggerTransfer3dConversionResponse,\n GetTransfer3dStatusData,\n GetTransfer3dStatusResponse,\n GetTransfer3DProductData,\n GetTransfer3DProductResponse,\n // Add to cart types\n CartProduct,\n AddToCartOptions,\n} from '@cymmetrik-dev/3d-transfer-sdk';\n\n// Helper functions\nimport {\n getDefaultProductSlug,\n getDefaultStyle,\n buildAddToCartUrl,\n buildAddToCartUrlFromEnv,\n} from '@cymmetrik-dev/3d-transfer-sdk';\n\n// API functions\nimport {\n getTransfer3dStyles,\n initiateTransfer3dConversion,\n triggerTransfer3dConversion,\n getTransfer3dStatus,\n getTransfer3DProduct,\n} from '@cymmetrik-dev/3d-transfer-sdk';\n\n// React component types\nimport type { ModelViewerProps } from '@cymmetrik-dev/3d-transfer-sdk/react';\n```\n\n## Error Handling\n\n```typescript\nimport { AxiosError } from 'axios';\n\ntry {\n const response = await initiateTransfer3dConversion({\n client,\n body: { image: file, style: 'smart' },\n });\n} catch (error) {\n if (error instanceof AxiosError) {\n if (error.response?.status === 401) {\n console.error('Authentication failed. Check your API token.');\n } else if (error.response?.status === 422) {\n console.error('Validation error:', error.response.data.errors);\n } else if (error.response?.status === 429) {\n console.error('Rate limit exceeded. Please try again later.');\n }\n }\n throw error;\n}\n```\n\n## Demo Application\n\nA complete React demo application is available in the [examples/react-demo](https://github.com/cympotek/mobius-frontier/tree/main/builds/3d-transfer-sdk/examples/react-demo) directory.\n\nTo run the demo:\n\n```bash\ncd examples/react-demo\npnpm install\ncp .env.example .env # Configure your API URL and token\npnpm dev\n```\n\n## Support\n\n- [GitHub Issues](https://github.com/cympotek/mobius-frontier/issues)\n\n---\n\n*This SDK is auto-generated from the Mobius Frontier OpenAPI specification using [@hey-api/openapi-ts](https://heyapi.vercel.app/)*\n","readmeFilename":"README.md"}Status: {status} ({progress}%)
\n\n {/* Link to view progress on main site */}\n {webViewUrl && (\n \n View on main site\n \n )}\n\n {/* 2D styled preview */}\n {preview2dUrl && (\n\n 
\n
\n )}\n\n {/* 3D Model Viewer */}\n {glbUrl && (\n 2D Style Preview
\n\n
\n )}\n