3D 模型 API

curl --request POST 'https://51easyai.com/api/v1/mesh3d/generate/text' \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "Trip3D-v3.1",
    "prompt": "一只坐着的卡通橘猫",
    "enable_texture": true,
    "enable_pbr": true
  }'

interface Mesh3dFile {
  // 以下来源字段至少传一个；调用 OpenAPI 时优先使用 url 或 path
  url?: string
  path?: string
  file_token?: string
  object?: {
    bucket: string
    key: string
  }

  // 文件元信息，用于平台格式、大小和分辨率校验
  type?: string
  originalname?: string
  mimetype?: string
  size?: number
  width?: number
  height?: number
}

type Mesh3dViewType =
  | 'front'
  | 'left_front'
  | 'right_front'
  | 'left'
  | 'right'
  | 'back'
  | 'top'
  | 'bottom'

interface Mesh3dViewImage {
  view_type: Mesh3dViewType
  file: Mesh3dFile
}

interface Mesh3dGenerateBaseRequest {
  model: string
  enable_texture?: boolean
  enable_pbr?: boolean
  texture_quality?: 'standard' | 'detailed'
  geometry_quality?: 'standard' | 'detailed'
  topology?: 'triangle' | 'quad'
  face_limit?: number
  seed?: number
  texture_seed?: number
  auto_size?: boolean
  generate_parts?: boolean
  smart_low_poly?: boolean
  export_uv?: boolean
  style?: string
  geometry_file_format?: 'glb' | 'usdz' | 'fbx' | 'obj' | 'stl' | string
  texture_delight?: boolean
  t_pose?: boolean
  geometry_instruct_mode?: 'faithful' | 'creative'
  is_micro?: boolean
}

interface TextToModelRequest extends Mesh3dGenerateBaseRequest {
  prompt: string
  negative_prompt?: string
  image_seed?: number
}

interface ImageToModelRequest extends Mesh3dGenerateBaseRequest {
  file: Mesh3dFile
  texture_alignment?: string
  orientation?: string
  enable_image_autofix?: boolean
}

interface MultiviewToModelRequest extends Mesh3dGenerateBaseRequest {
  view_images: Mesh3dViewImage[]
  texture_alignment?: string
  orientation?: string
  enable_image_autofix?: boolean

  // 兼容旧协议，槽位顺序固定为 [front, left, back, right]；新接入请使用 view_images
  files?: Array<Mesh3dFile | null>
}

{
  "model": "混元3D-v3.1",
  "prompt": "一只坐着的卡通橘猫，完整身体，干净拓扑",
  "enable_texture": false,
  "enable_pbr": false,
  "face_limit": 3000
}

interface Mesh3dEditBaseRequest {
  model: string
  history_id: string
}

interface SegmentationRequest extends Mesh3dEditBaseRequest {
  model_version_seg?: string
}

interface CompletionRequest extends Mesh3dEditBaseRequest {
  part_names: string[]
  model_version_seg?: string
}

interface SmartLowpolyRequest extends Mesh3dEditBaseRequest {
  topology?: 'triangle' | 'quad'
  face_limit?: number | 'auto' | 'high' | 'medium' | 'low'
  quad?: boolean
  part_names?: string[]
  bake?: boolean
}

interface TexturePrompt {
  text?: string
  image?: Mesh3dFile
  style_image?: Mesh3dFile
  view_images?: Mesh3dViewImage[]

  // 兼容旧协议，槽位顺序固定为 [front, left, back, right]
  images?: Mesh3dFile[]
}

interface TextureRequest extends Mesh3dEditBaseRequest {
  enable_texture?: boolean
  enable_pbr?: boolean
  texture?: boolean
  pbr?: boolean
  seed?: number
  texture_seed?: number
  texture_quality?: 'standard' | 'detailed' | string
  texture_alignment?: 'original_image' | 'geometry' | string
  part_names?: string[]
  compress?: 'geometry' | string
  bake?: boolean
  texture_prompt?: TexturePrompt
}

interface ConvertRequest extends Mesh3dEditBaseRequest {
  format: string
  topology?: 'triangle' | 'quad'
  force_symmetry?: boolean
  face_limit?: number
  flatten_bottom?: boolean
  flatten_bottom_threshold?: number
  texture_size?: number
  texture_format?: string
  pivot_to_center_bottom?: boolean
  with_animation?: boolean
  pack_uv?: boolean
  bake?: boolean
  part_names?: string[]
  scale_factor?: number
  animate_in_place?: boolean
  export_vertex_colors?: boolean
  export_orientation?: string
  fbx_preset?: string
  quad?: boolean
}

type CheckRiggableRequest = Mesh3dEditBaseRequest

interface RigRequest extends Mesh3dEditBaseRequest {
  out_format?: 'glb' | 'fbx'
  rig_type?: 'biped' | 'quadruped' | 'hexapod' | 'octopod' | 'avian' | 'serpentine' | 'aquatic' | string
  spec?: 'mixamo' | 'tripo' | string
  rigging_model_version?: 'v2.5-20260210' | 'v2.0-20250506' | 'v1.0-20240301'
}

interface RetargetAnimationRequest {
  history_id: string
  model?: string
  animation?: string
  animations?: string[]
  out_format?: 'glb' | 'fbx'
  bake_animation?: boolean
  export_with_geometry?: boolean
  animate_in_place?: boolean
}

interface RefineRequest extends Mesh3dEditBaseRequest {
  draft_model_task_id?: string
}

interface StylizeRequest extends Mesh3dEditBaseRequest {
  style: string
  block_size?: number
}

{
  "model": "Trip3D-v3.1",
  "prompt": "一只坐着的卡通橘猫，完整身体，干净拓扑",
  "negative_prompt": "模糊，残缺，多个主体",
  "geometry_quality": "detailed",
  "texture_quality": "detailed",
  "enable_texture": true,
  "enable_pbr": true,
  "topology": "triangle",
  "seed": 20260714
}

{
  "model": "Trip3D-P1",
  "file": {
    "url": "https://cdn.example.com/chair-front.png",
    "originalname": "chair-front.png",
    "mimetype": "image/png",
    "width": 1024,
    "height": 1024
  },
  "enable_texture": true,
  "enable_pbr": true,
  "texture_quality": "detailed",
  "enable_image_autofix": true
}

{
  "model": "Trip3D-v3.1",
  "view_images": [
    {
      "view_type": "front",
      "file": {
        "url": "https://cdn.example.com/robot-front.png",
        "mimetype": "image/png"
      }
    },
    {
      "view_type": "left",
      "file": {
        "url": "https://cdn.example.com/robot-left.png",
        "mimetype": "image/png"
      }
    },
    {
      "view_type": "back",
      "file": {
        "url": "https://cdn.example.com/robot-back.png",
        "mimetype": "image/png"
      }
    }
  ],
  "enable_texture": true,
  "enable_pbr": true,
  "geometry_quality": "detailed"
}

{
  "model": "Trip3D-v3.1",
  "files": [
    { "url": "https://cdn.example.com/front.png" },
    { "url": "https://cdn.example.com/left.png" },
    null,
    { "url": "https://cdn.example.com/right.png" }
  ]
}

{
  "history_id": "mesh3d_history_123",
  "model": "3D拆分/补全模型v1.0"
}

{
  "history_id": "mesh3d_history_123",
  "model": "3D拆分/补全模型v1.0",
  "part_names": ["left_arm", "right_arm"]
}

{
  "history_id": "mesh3d_history_123",
  "model": "3D重拓扑模型v2.0",
  "topology": "quad",
  "face_limit": 8000,
  "bake": true
}

{
  "history_id": "mesh3d_history_123",
  "model": "3D纹理管线v2.5",
  "texture": true,
  "pbr": true,
  "texture_quality": "detailed",
  "texture_alignment": "geometry",
  "texture_seed": 42,
  "bake": true,
  "texture_prompt": {
    "text": "旧化黄铜材质，细微划痕，写实 PBR",
    "style_image": {
      "url": "https://cdn.example.com/brass-style.jpg",
      "mimetype": "image/jpeg"
    }
  }
}

{
  "history_id": "mesh3d_history_123",
  "model": "Trip3D-v3.1",
  "format": "FBX",
  "topology": "triangle",
  "texture_size": 2048,
  "texture_format": "PNG",
  "pivot_to_center_bottom": true,
  "with_animation": true,
  "pack_uv": true,
  "bake": true
}

{
  "history_id": "mesh3d_history_123",
  "model": "3D绑定算法v2.5"
}

{
  "history_id": "mesh3d_history_123",
  "model": "3D绑定算法v2.5",
  "out_format": "glb",
  "rig_type": "biped",
  "spec": "tripo",
  "rigging_model_version": "v2.5-20260210"
}

{
  "history_id": "rig_history_123",
  "model": "3D绑定算法v2.5",
  "animation": "preset:walk",
  "out_format": "glb",
  "bake_animation": true,
  "export_with_geometry": true,
  "animate_in_place": false
}

{
  "history_id": "rig_history_123",
  "animations": ["preset:idle", "preset:walk"],
  "out_format": "fbx"
}

{
  "history_id": "legacy_draft_history_123",
  "model": "Trip3D-v3.1",
  "draft_model_task_id": "legacy_upstream_draft_task_123"
}

{
  "history_id": "mesh3d_history_123",
  "model": "Trip3D-v3.1",
  "style": "minecraft",
  "block_size": 80
}

{
  "material_id": "material_123",
  "task_id": "draw_task_123",
  "mesh3d_history_id": "mesh3d_history_123"
}

{
  "material_id": "material_123",
  "task_id": "draw_task_456",
  "history_id": "mesh3d_history_456"
}