3D 模型

创建 3D 模型生成任务

POST/3d_models/meshes

通过文本、单张图片或多视角图片集生成 3D 网格模型。

请求体

Content-Type: application/jsonRequired: true

Request Body Schema

application/json

Model3dMeshRequestUsePrompt

└prompt

required

string(Prompt)

Text prompt for text-to-3D generation. Provide this field only when you want to generate a mesh from text.

└model

string(Model)

Enum: pro flash

3D mesh generation model to run for this request. Available values: `pro`, `flash`.

Default: `pro`

└with_texture

boolean(With Texture)

When true, also generate texture maps for the produced mesh.

Default: `false`

└hd_texture

boolean(Hd Texture)

When true, upsample generated textures to a higher resolution.

Default: `false`

└pbr_texture

boolean(Pbr Texture)

When true, also generate physically based rendering (PBR) texture maps.

Default: `false`

└options

TaskRequestOptions | null

Optional task execution controls for the task

└block

boolean | null

When true, wait for task completion and return the terminal response immediately. When false, return a task reference for polling.

└priority

integer | null[0..255]

Task dispatch priority within this client. Larger values are consumed earlier. Must not exceed the client's `mq_priority`. When omitted, defaults to the client's `mq_priority`.

Model3dMeshRequestUseInputImage

└input_image

required

string(Input Image)

Single reference image input for image-to-3D generation. Provide this field only for single-view reconstruction. Accepts an existing relative URI path, a base64-encoded file payload (including `data:` URLs), or an HTTP/HTTPS file URL.

└model

string(Model)

Enum: pro flash

3D mesh generation model to run for this request. Available values: `pro`, `flash`.

Default: `pro`

└with_texture

boolean(With Texture)

When true, also generate texture maps for the produced mesh.

Default: `false`

└hd_texture

boolean(Hd Texture)

When true, upsample generated textures to a higher resolution.

Default: `false`

└pbr_texture

boolean(Pbr Texture)

When true, also generate physically based rendering (PBR) texture maps.

Default: `false`

└options

TaskRequestOptions | null

Optional task execution controls for the task

└block

boolean | null

When true, wait for task completion and return the terminal response immediately. When false, return a task reference for polling.

└priority

integer | null[0..255]

Task dispatch priority within this client. Larger values are consumed earlier. Must not exceed the client's `mq_priority`. When omitted, defaults to the client's `mq_priority`.

Model3dMeshRequestUseInputImages

└input_images

required

object(Model3DMultiviewImageInput)

└front

required

string(Front)

Front view image input. Accepts an existing relative URI path, a base64-encoded file payload (including `data:` URLs), or an HTTP/HTTPS file URL.

└left

string | null

Left view image input. Accepts an existing relative URI path, a base64-encoded file payload (including `data:` URLs), or an HTTP/HTTPS file URL.

└back

string | null

Back view image input. Accepts an existing relative URI path, a base64-encoded file payload (including `data:` URLs), or an HTTP/HTTPS file URL.

└right

string | null

Right view image input. Accepts an existing relative URI path, a base64-encoded file payload (including `data:` URLs), or an HTTP/HTTPS file URL.

└model

string(Model)

Enum: pro flash

3D mesh generation model to run for this request. Available values: `pro`, `flash`.

Default: `pro`

└with_texture

boolean(With Texture)

When true, also generate texture maps for the produced mesh.

Default: `false`

└hd_texture

boolean(Hd Texture)

When true, upsample generated textures to a higher resolution.

Default: `false`

└pbr_texture

boolean(Pbr Texture)

When true, also generate physically based rendering (PBR) texture maps.

Default: `false`

└options

TaskRequestOptions | null

Optional task execution controls for the task

└block

boolean | null

When true, wait for task completion and return the terminal response immediately. When false, return a task reference for polling.

└priority

integer | null[0..255]

Task dispatch priority within this client. Larger values are consumed earlier. Must not exceed the client's `mq_priority`. When omitted, defaults to the client's `mq_priority`.

响应

通用错误码说明请查看：错误处理。

Response Schema

200application/json

└task_uuid

required

string(Task Uuid)

Unique identifier for the task

└task_type

required

string(Task Type)

Logical task category used by the backend pipeline.

└model

required

string(Model)

Model or worker name assigned to the task.

└status

required

string(TaskStatus)

Enum: QUEUED PROCESSING COMPLETED FAILED

└created_at

required

integer(Created At)

Unix timestamp, in seconds, when the task was created.

└completed_at

required

integer(Completed At)

Unix timestamp, in seconds, when the task finished successfully.

└result

required

array(Result)

List of generated 3D model URIs. Returned asset URIs are relative paths that can be reused directly in compatible input fields.

└result[]

string

└metadata

Model3dMetadata[] | null

Additional metadata for each generated 3D model.

└metadata[]

object(Model3dMetadata)

└reference_images

string[] | null

Reference image URIs used to generate or texture the model, in the order they were consumed. Returned asset URIs are relative paths that can be reused directly in compatible input fields.

└reference_images[]

string

└preview_image

string | null

Preview render URI for the generated 3D model. Returned asset URIs are relative paths that can be reused directly in compatible input fields.

└t_pose_model

string | null

Rigged T-pose model URI, when the pipeline produces one. Returned asset URIs are relative paths that can be reused directly in compatible input fields.

└mesh_info

object | null

Mesh statistics or renderer metadata for the generated model.

└preview_video

string | null

Preview render video URI for the generated 3D model. Returned asset URIs are relative paths that can be reused directly in compatible input fields.

└downloads

any[] | null

Temporary download links for related generated assets. Flattened list of presigned HTTP download descriptors for every URI returned in `result` or this object.

└downloads[]

any

也可能返回 201，表示任务已接受并在后台异步执行。使用响应体中的 task_uuid 轮询对应的 GET 端点获取结果。了解同步 vs 异步 →

立即体验

curl https://api.v2fun.ai/api/v1/3d_models/meshes \
  -X POST \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "prompt": "<prompt>"
    }'

Response 200 OK

{
  "task_uuid": "<task_uuid>",
  "task_type": "<task_type>",
  "model": "<model>",
  "status": "<taskstatus>",
  "created_at": 0,
  "completed_at": 0,
  "result": []
}

获取 3D 模型生成任务

GET/3d_models/meshes/{task_uuid}

获取 3D 模型生成任务的当前状态或最终输出。

参数

名称	位置	必填	类型	说明
`task_uuid`	path	是	string	Task UUID returned when the 3D mesh job was created.

响应

通用错误码说明请查看：错误处理。

Response Schema

200application/json

└task_uuid

required

string(Task Uuid)

Unique identifier for the task

└task_type

required

string(Task Type)

Logical task category used by the backend pipeline.

└model

required

string(Model)

Model or worker name assigned to the task.

└status

required

string(TaskStatus)

Enum: QUEUED PROCESSING COMPLETED FAILED

└created_at

required

integer(Created At)

Unix timestamp, in seconds, when the task was created.

└completed_at

required

integer(Completed At)

Unix timestamp, in seconds, when the task finished successfully.

└result

required

array(Result)

List of generated 3D model URIs. Returned asset URIs are relative paths that can be reused directly in compatible input fields.

└result[]

string

└metadata

Model3dMetadata[] | null

Additional metadata for each generated 3D model.

└metadata[]

object(Model3dMetadata)

└reference_images

string[] | null

Reference image URIs used to generate or texture the model, in the order they were consumed. Returned asset URIs are relative paths that can be reused directly in compatible input fields.

└reference_images[]

string

└preview_image

string | null

Preview render URI for the generated 3D model. Returned asset URIs are relative paths that can be reused directly in compatible input fields.

└t_pose_model

string | null

Rigged T-pose model URI, when the pipeline produces one. Returned asset URIs are relative paths that can be reused directly in compatible input fields.

└mesh_info

object | null

Mesh statistics or renderer metadata for the generated model.

└preview_video

string | null

Preview render video URI for the generated 3D model. Returned asset URIs are relative paths that can be reused directly in compatible input fields.

└downloads

any[] | null

Temporary download links for related generated assets. Flattened list of presigned HTTP download descriptors for every URI returned in `result` or this object.

└downloads[]

any

立即体验

curl https://api.v2fun.ai/api/v1/3d_models/meshes/<task_uuid> \
  -H "Authorization: Bearer $YOUR_API_KEY"

Response 200 OK

{
  "task_uuid": "<task_uuid>",
  "task_type": "<task_type>",
  "model": "<model>",
  "status": "<taskstatus>",
  "created_at": 0,
  "completed_at": 0,
  "result": []
}

创建模型贴图任务

POST/3d_models/textures

通过文本、单张参考图片或多视角参考图片，为已有 3D 模型生成贴图。

请求体

Content-Type: application/jsonRequired: true

Request Body Schema

application/json

Model3dTextureRequestUsePrompt

└prompt

required

string(Prompt)

Text prompt describing the target material or surface appearance.

└input_model

required

string(Input Model)

3D model input that should receive new textures. Accepts an existing relative URI path, a base64-encoded file payload (including `data:` URLs), or an HTTP/HTTPS file URL.

└hd_texture

boolean(Hd Texture)

When true, upsample generated textures to a higher resolution.

Default: `false`

└pbr_texture

boolean(Pbr Texture)

When true, also generate physically based rendering (PBR) texture maps.

Default: `true`

└keep_uv

boolean(Keep Uv)

When true, preserve the original UV layout instead of rebuilding it.

Default: `true`

└options

TaskRequestOptions | null

Optional task execution controls for the task

└block

boolean | null

When true, wait for task completion and return the terminal response immediately. When false, return a task reference for polling.

└priority

integer | null[0..255]

Task dispatch priority within this client. Larger values are consumed earlier. Must not exceed the client's `mq_priority`. When omitted, defaults to the client's `mq_priority`.

Model3dTextureRequestUseInputImage

└input_image

required

string(Input Image)

Single reference image input for texture generation. Accepts an existing relative URI path, a base64-encoded file payload (including `data:` URLs), or an HTTP/HTTPS file URL.

└input_model

required

string(Input Model)

3D model input that should receive new textures. Accepts an existing relative URI path, a base64-encoded file payload (including `data:` URLs), or an HTTP/HTTPS file URL.

└hd_texture

boolean(Hd Texture)

When true, upsample generated textures to a higher resolution.

Default: `false`

└pbr_texture

boolean(Pbr Texture)

When true, also generate physically based rendering (PBR) texture maps.

Default: `true`

└keep_uv

boolean(Keep Uv)

When true, preserve the original UV layout instead of rebuilding it.

Default: `true`

└options

TaskRequestOptions | null

Optional task execution controls for the task

└block

boolean | null

When true, wait for task completion and return the terminal response immediately. When false, return a task reference for polling.

└priority

integer | null[0..255]

Task dispatch priority within this client. Larger values are consumed earlier. Must not exceed the client's `mq_priority`. When omitted, defaults to the client's `mq_priority`.

Model3dTextureRequestUseInputImages

└input_images

required

object(Model3DMultiviewImageInput)

└front

required

string(Front)

Front view image input. Accepts an existing relative URI path, a base64-encoded file payload (including `data:` URLs), or an HTTP/HTTPS file URL.

└left

string | null

Left view image input. Accepts an existing relative URI path, a base64-encoded file payload (including `data:` URLs), or an HTTP/HTTPS file URL.

└back

string | null

Back view image input. Accepts an existing relative URI path, a base64-encoded file payload (including `data:` URLs), or an HTTP/HTTPS file URL.

└right

string | null

Right view image input. Accepts an existing relative URI path, a base64-encoded file payload (including `data:` URLs), or an HTTP/HTTPS file URL.

└input_model

required

string(Input Model)

3D model input that should receive new textures. Accepts an existing relative URI path, a base64-encoded file payload (including `data:` URLs), or an HTTP/HTTPS file URL.

└hd_texture

boolean(Hd Texture)

When true, upsample generated textures to a higher resolution.

Default: `false`

└pbr_texture

boolean(Pbr Texture)

When true, also generate physically based rendering (PBR) texture maps.

Default: `true`

└keep_uv

boolean(Keep Uv)

When true, preserve the original UV layout instead of rebuilding it.

Default: `true`

└options

TaskRequestOptions | null

Optional task execution controls for the task

└block

boolean | null

When true, wait for task completion and return the terminal response immediately. When false, return a task reference for polling.

└priority

integer | null[0..255]

Task dispatch priority within this client. Larger values are consumed earlier. Must not exceed the client's `mq_priority`. When omitted, defaults to the client's `mq_priority`.

响应

通用错误码说明请查看：错误处理。

Response Schema

200application/json

└task_uuid

required

string(Task Uuid)

Unique identifier for the task

└task_type

required

string(Task Type)

Logical task category used by the backend pipeline.

└model

required

string(Model)

Model or worker name assigned to the task.

└status

required

string(TaskStatus)

Enum: QUEUED PROCESSING COMPLETED FAILED

└created_at

required

integer(Created At)

Unix timestamp, in seconds, when the task was created.

└completed_at

required

integer(Completed At)

Unix timestamp, in seconds, when the task finished successfully.

└result

required

array(Result)

List of generated 3D model URIs. Returned asset URIs are relative paths that can be reused directly in compatible input fields.

└result[]

string

└metadata

Model3dMetadata[] | null

Additional metadata for each generated 3D model.

└metadata[]

object(Model3dMetadata)

└reference_images

string[] | null

Reference image URIs used to generate or texture the model, in the order they were consumed. Returned asset URIs are relative paths that can be reused directly in compatible input fields.

└reference_images[]

string

└preview_image

string | null

Preview render URI for the generated 3D model. Returned asset URIs are relative paths that can be reused directly in compatible input fields.

└t_pose_model

string | null

Rigged T-pose model URI, when the pipeline produces one. Returned asset URIs are relative paths that can be reused directly in compatible input fields.

└mesh_info

object | null

Mesh statistics or renderer metadata for the generated model.

└preview_video

string | null

Preview render video URI for the generated 3D model. Returned asset URIs are relative paths that can be reused directly in compatible input fields.

└downloads

any[] | null

Temporary download links for related generated assets. Flattened list of presigned HTTP download descriptors for every URI returned in `result` or this object.

└downloads[]

any

也可能返回 201，表示任务已接受并在后台异步执行。使用响应体中的 task_uuid 轮询对应的 GET 端点获取结果。了解同步 vs 异步 →

立即体验

curl https://api.v2fun.ai/api/v1/3d_models/textures \
  -X POST \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "prompt": "<prompt>",
      "input_model": "<input_model>"
    }'

Response 200 OK

{
  "task_uuid": "<task_uuid>",
  "task_type": "<task_type>",
  "model": "<model>",
  "status": "<taskstatus>",
  "created_at": 0,
  "completed_at": 0,
  "result": []
}

获取模型贴图任务

GET/3d_models/textures/{task_uuid}

获取 3D 贴图生成任务的当前状态或最终输出。

参数

名称	位置	必填	类型	说明
`task_uuid`	path	是	string	Task UUID returned when the texture generation job was created.

响应

通用错误码说明请查看：错误处理。

Response Schema

200application/json

└task_uuid

required

string(Task Uuid)

Unique identifier for the task

└task_type

required

string(Task Type)

Logical task category used by the backend pipeline.

└model

required

string(Model)

Model or worker name assigned to the task.

└status

required

string(TaskStatus)

Enum: QUEUED PROCESSING COMPLETED FAILED

└created_at

required

integer(Created At)

Unix timestamp, in seconds, when the task was created.

└completed_at

required

integer(Completed At)

Unix timestamp, in seconds, when the task finished successfully.

└result

required

array(Result)

List of generated 3D model URIs. Returned asset URIs are relative paths that can be reused directly in compatible input fields.

└result[]

string

└metadata

Model3dMetadata[] | null

Additional metadata for each generated 3D model.

└metadata[]

object(Model3dMetadata)

└reference_images

string[] | null

Reference image URIs used to generate or texture the model, in the order they were consumed. Returned asset URIs are relative paths that can be reused directly in compatible input fields.

└reference_images[]

string

└preview_image

string | null

Preview render URI for the generated 3D model. Returned asset URIs are relative paths that can be reused directly in compatible input fields.

└t_pose_model

string | null

Rigged T-pose model URI, when the pipeline produces one. Returned asset URIs are relative paths that can be reused directly in compatible input fields.

└mesh_info

object | null

Mesh statistics or renderer metadata for the generated model.

└preview_video

string | null

Preview render video URI for the generated 3D model. Returned asset URIs are relative paths that can be reused directly in compatible input fields.

└downloads

any[] | null

Temporary download links for related generated assets. Flattened list of presigned HTTP download descriptors for every URI returned in `result` or this object.

└downloads[]

any

立即体验

curl https://api.v2fun.ai/api/v1/3d_models/textures/<task_uuid> \
  -H "Authorization: Bearer $YOUR_API_KEY"

Response 200 OK

{
  "task_uuid": "<task_uuid>",
  "task_type": "<task_type>",
  "model": "<model>",
  "status": "<taskstatus>",
  "created_at": 0,
  "completed_at": 0,
  "result": []
}

创建网格优化任务

POST/3d_models/remeshings

将已有 3D 模型重拓扑为目标网格密度与拓扑结构。

请求体

Content-Type: application/jsonRequired: true

Request Body Schema

application/json

└input_model

required

string(Input Model)

3D model input to remesh. Accepts an existing relative URI path, a base64-encoded file payload (including `data:` URLs), or an HTTP/HTTPS file URL.

└mesh_count

integer | null

Target polygon count for the remeshed model.

└mesh_topology

string(MeshTopologyEnum)

Enum: triangle quad

└options

TaskRequestOptions | null

Optional task execution controls for the task

└block

boolean | null

When true, wait for task completion and return the terminal response immediately. When false, return a task reference for polling.

└priority

integer | null[0..255]

Task dispatch priority within this client. Larger values are consumed earlier. Must not exceed the client's `mq_priority`. When omitted, defaults to the client's `mq_priority`.

响应

通用错误码说明请查看：错误处理。

Response Schema

200application/json

└task_uuid

required

string(Task Uuid)

Unique identifier for the task

└task_type

required

string(Task Type)

Logical task category used by the backend pipeline.

└model

required

string(Model)

Model or worker name assigned to the task.

└status

required

string(TaskStatus)

Enum: QUEUED PROCESSING COMPLETED FAILED

└created_at

required

integer(Created At)

Unix timestamp, in seconds, when the task was created.

└completed_at

required

integer(Completed At)

Unix timestamp, in seconds, when the task finished successfully.

└result

required

array(Result)

List of generated 3D model URIs. Returned asset URIs are relative paths that can be reused directly in compatible input fields.

└result[]

string

└metadata

Model3dMetadata[] | null

Additional metadata for each generated 3D model.

└metadata[]

object(Model3dMetadata)

└reference_images

string[] | null

Reference image URIs used to generate or texture the model, in the order they were consumed. Returned asset URIs are relative paths that can be reused directly in compatible input fields.

└reference_images[]

string

└preview_image

string | null

Preview render URI for the generated 3D model. Returned asset URIs are relative paths that can be reused directly in compatible input fields.

└t_pose_model

string | null

Rigged T-pose model URI, when the pipeline produces one. Returned asset URIs are relative paths that can be reused directly in compatible input fields.

└mesh_info

object | null

Mesh statistics or renderer metadata for the generated model.

└preview_video

string | null

Preview render video URI for the generated 3D model. Returned asset URIs are relative paths that can be reused directly in compatible input fields.

└downloads

any[] | null

Temporary download links for related generated assets. Flattened list of presigned HTTP download descriptors for every URI returned in `result` or this object.

└downloads[]

any

也可能返回 201，表示任务已接受并在后台异步执行。使用响应体中的 task_uuid 轮询对应的 GET 端点获取结果。了解同步 vs 异步 →

立即体验

curl https://api.v2fun.ai/api/v1/3d_models/remeshings \
  -X POST \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "input_model": "<input_model>"
    }'

Response 200 OK

{
  "task_uuid": "<task_uuid>",
  "task_type": "<task_type>",
  "model": "<model>",
  "status": "<taskstatus>",
  "created_at": 0,
  "completed_at": 0,
  "result": []
}

获取网格优化任务

GET/3d_models/remeshings/{task_uuid}

获取网格优化任务的当前状态或最终输出。

参数

名称	位置	必填	类型	说明
`task_uuid`	path	是	string	Task UUID returned when the remeshing job was created.

响应

通用错误码说明请查看：错误处理。

Response Schema

200application/json

└task_uuid

required

string(Task Uuid)

Unique identifier for the task

└task_type

required

string(Task Type)

Logical task category used by the backend pipeline.

└model

required

string(Model)

Model or worker name assigned to the task.

└status

required

string(TaskStatus)

Enum: QUEUED PROCESSING COMPLETED FAILED

└created_at

required

integer(Created At)

Unix timestamp, in seconds, when the task was created.

└completed_at

required

integer(Completed At)

Unix timestamp, in seconds, when the task finished successfully.

└result

required

array(Result)

List of generated 3D model URIs. Returned asset URIs are relative paths that can be reused directly in compatible input fields.

└result[]

string

└metadata

Model3dMetadata[] | null

Additional metadata for each generated 3D model.

└metadata[]

object(Model3dMetadata)

└reference_images

string[] | null

Reference image URIs used to generate or texture the model, in the order they were consumed. Returned asset URIs are relative paths that can be reused directly in compatible input fields.

└reference_images[]

string

└preview_image

string | null

Preview render URI for the generated 3D model. Returned asset URIs are relative paths that can be reused directly in compatible input fields.

└t_pose_model

string | null

Rigged T-pose model URI, when the pipeline produces one. Returned asset URIs are relative paths that can be reused directly in compatible input fields.

└mesh_info

object | null

Mesh statistics or renderer metadata for the generated model.

└preview_video

string | null

Preview render video URI for the generated 3D model. Returned asset URIs are relative paths that can be reused directly in compatible input fields.

└downloads

any[] | null

Temporary download links for related generated assets. Flattened list of presigned HTTP download descriptors for every URI returned in `result` or this object.

└downloads[]

any

立即体验

curl https://api.v2fun.ai/api/v1/3d_models/remeshings/<task_uuid> \
  -H "Authorization: Bearer $YOUR_API_KEY"

Response 200 OK

{
  "task_uuid": "<task_uuid>",
  "task_type": "<task_type>",
  "model": "<model>",
  "status": "<taskstatus>",
  "created_at": 0,
  "completed_at": 0,
  "result": []
}

创建格式转换任务

POST/3d_models/conversions

将已有 3D 模型转换为另一种文件格式。

请求体

Content-Type: application/jsonRequired: true

Request Body Schema

application/json

└input_model

required

string(Input Model)

3D model input to convert. Accepts an existing relative URI path, a base64-encoded file payload (including `data:` URLs), or an HTTP/HTTPS file URL.

└output_format

required

string(Model3dConversionFormat)

Enum: obj ply stl fbx glb usdz 3mf

└rotation_x

number(Rotation X)

Rotation around the X axis in degrees applied to the model during conversion.

Default: `0`

└rotation_y

number(Rotation Y)

Rotation around the Y axis in degrees applied to the model during conversion.

Default: `0`

└rotation_z

number(Rotation Z)

Rotation around the Z axis in degrees applied to the model during conversion.

Default: `0`

└target_size

anyOf(Target Size)

Target longest-edge size for the converted model. Can be a single value or a list of values. If omitted, no size adjustment is applied.

└target_size_1

number

└target_size_2

array

└target_size_2[]

number

└target_size_3

null

└uniform_color

string | null

Hex color (e.g. '#FF8800') to assign to all meshes as a Principled BSDF Base Color. If omitted, original materials are kept.

└options

TaskRequestOptions | null

Optional task execution controls for the task

└block

boolean | null

When true, wait for task completion and return the terminal response immediately. When false, return a task reference for polling.

└priority

integer | null[0..255]

Task dispatch priority within this client. Larger values are consumed earlier. Must not exceed the client's `mq_priority`. When omitted, defaults to the client's `mq_priority`.

响应

通用错误码说明请查看：错误处理。

Response Schema

200application/json

└task_uuid

required

string(Task Uuid)

Unique identifier for the task

└task_type

required

string(Task Type)

Logical task category used by the backend pipeline.

└model

required

string(Model)

Model or worker name assigned to the task.

└status

required

string(TaskStatus)

Enum: QUEUED PROCESSING COMPLETED FAILED

└created_at

required

integer(Created At)

Unix timestamp, in seconds, when the task was created.

└completed_at

required

integer(Completed At)

Unix timestamp, in seconds, when the task finished successfully.

└result

required

array(Result)

List of generated 3D model URIs. Returned asset URIs are relative paths that can be reused directly in compatible input fields.

└result[]

string

└metadata

Model3dMetadata[] | null

Additional metadata for each generated 3D model.

└metadata[]

object(Model3dMetadata)

└reference_images

string[] | null

Reference image URIs used to generate or texture the model, in the order they were consumed. Returned asset URIs are relative paths that can be reused directly in compatible input fields.

└reference_images[]

string

└preview_image

string | null

Preview render URI for the generated 3D model. Returned asset URIs are relative paths that can be reused directly in compatible input fields.

└t_pose_model

string | null

Rigged T-pose model URI, when the pipeline produces one. Returned asset URIs are relative paths that can be reused directly in compatible input fields.

└mesh_info

object | null

Mesh statistics or renderer metadata for the generated model.

└preview_video

string | null

Preview render video URI for the generated 3D model. Returned asset URIs are relative paths that can be reused directly in compatible input fields.

└downloads

any[] | null

Temporary download links for related generated assets. Flattened list of presigned HTTP download descriptors for every URI returned in `result` or this object.

└downloads[]

any

也可能返回 201，表示任务已接受并在后台异步执行。使用响应体中的 task_uuid 轮询对应的 GET 端点获取结果。了解同步 vs 异步 →

立即体验

curl https://api.v2fun.ai/api/v1/3d_models/conversions \
  -X POST \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "input_model": "<input_model>",
      "output_format": "<model3dconversionformat>"
    }'

Response 200 OK

{
  "task_uuid": "<task_uuid>",
  "task_type": "<task_type>",
  "model": "<model>",
  "status": "<taskstatus>",
  "created_at": 0,
  "completed_at": 0,
  "result": []
}

获取格式转换任务

GET/3d_models/conversions/{task_uuid}

获取格式转换任务的当前状态或最终输出。

参数

名称	位置	必填	类型	说明
`task_uuid`	path	是	string	Task UUID returned when the conversion job was created.

响应

通用错误码说明请查看：错误处理。

Response Schema

200application/json

└task_uuid

required

string(Task Uuid)

Unique identifier for the task

└task_type

required

string(Task Type)

Logical task category used by the backend pipeline.

└model

required

string(Model)

Model or worker name assigned to the task.

└status

required

string(TaskStatus)

Enum: QUEUED PROCESSING COMPLETED FAILED

└created_at

required

integer(Created At)

Unix timestamp, in seconds, when the task was created.

└completed_at

required

integer(Completed At)

Unix timestamp, in seconds, when the task finished successfully.

└result

required

array(Result)

List of generated 3D model URIs. Returned asset URIs are relative paths that can be reused directly in compatible input fields.

└result[]

string

└metadata

Model3dMetadata[] | null

Additional metadata for each generated 3D model.

└metadata[]

object(Model3dMetadata)

└reference_images

string[] | null

Reference image URIs used to generate or texture the model, in the order they were consumed. Returned asset URIs are relative paths that can be reused directly in compatible input fields.

└reference_images[]

string

└preview_image

string | null

Preview render URI for the generated 3D model. Returned asset URIs are relative paths that can be reused directly in compatible input fields.

└t_pose_model

string | null

Rigged T-pose model URI, when the pipeline produces one. Returned asset URIs are relative paths that can be reused directly in compatible input fields.

└mesh_info

object | null

Mesh statistics or renderer metadata for the generated model.

└preview_video

string | null

Preview render video URI for the generated 3D model. Returned asset URIs are relative paths that can be reused directly in compatible input fields.

└downloads

any[] | null

Temporary download links for related generated assets. Flattened list of presigned HTTP download descriptors for every URI returned in `result` or this object.

└downloads[]

any

立即体验

curl https://api.v2fun.ai/api/v1/3d_models/conversions/<task_uuid> \
  -H "Authorization: Bearer $YOUR_API_KEY"

Response 200 OK

{
  "task_uuid": "<task_uuid>",
  "task_type": "<task_type>",
  "model": "<model>",
  "status": "<taskstatus>",
  "created_at": 0,
  "completed_at": 0,
  "result": []
}

创建渲染预览任务

POST/3d_models/renderings

为已有 3D 模型渲染预览图片或预览视频。

请求体

Content-Type: application/jsonRequired: true

Request Body Schema

application/json

└input_model

required

string(Input Model)

3D model input to render into preview assets. Accepts an existing relative URI path, a base64-encoded file payload (including `data:` URLs), or an HTTP/HTTPS file URL.

└output_type

string(Model3dRenderingOutputType)

Enum: image video

└options

TaskRequestOptions | null

Optional task execution controls for the task

└block

boolean | null

When true, wait for task completion and return the terminal response immediately. When false, return a task reference for polling.

└priority

integer | null[0..255]

Task dispatch priority within this client. Larger values are consumed earlier. Must not exceed the client's `mq_priority`. When omitted, defaults to the client's `mq_priority`.

响应

通用错误码说明请查看：错误处理。

Response Schema

200application/json

ImageResponse

└task_uuid

required

string(Task Uuid)

Unique identifier for the task

└task_type

required

string(Task Type)

Logical task category used by the backend pipeline.

└model

required

string(Model)

Model or worker name assigned to the task.

└status

required

string(TaskStatus)

Enum: QUEUED PROCESSING COMPLETED FAILED

└created_at

required

integer(Created At)

Unix timestamp, in seconds, when the task was created.

└completed_at

required

integer(Completed At)

Unix timestamp, in seconds, when the task finished successfully.

└result

required

array(Result)

Generated, edited, or processed image URI list. Returned asset URIs are relative paths that can be reused directly in compatible input fields.

└result[]

string

└metadata

any(Metadata)

Additional task-specific metadata returned with the result.

VideoResponse

└task_uuid

required

string(Task Uuid)

Unique identifier for the task

└task_type

required

string(Task Type)

Logical task category used by the backend pipeline.

└model

required

string(Model)

Model or worker name assigned to the task.

└status

required

string(TaskStatus)

Enum: QUEUED PROCESSING COMPLETED FAILED

└created_at

required

integer(Created At)

Unix timestamp, in seconds, when the task was created.

└completed_at

required

integer(Completed At)

Unix timestamp, in seconds, when the task finished successfully.

└result

required

array(Result)

Generated or rendered video URI list. Returned asset URIs are relative paths that can be reused directly in compatible input fields.

└result[]

string

└metadata

anyOf(Metadata)

Additional metadata describing the generated video and optional last frame image, or per-model rendering metadata for preview video tasks.

VideoGenerationMetadata

└last_frame

string | null

Stored last frame image URI, when `return_last_frame` was requested. Returned asset URIs are relative paths that can be reused directly in compatible input fields.

└downloads

any[] | null

Temporary download links for the generated video and optional last frame image. Flattened list of presigned HTTP download descriptors for every URI returned in `result` or this object.

└downloads[]

any

└metadata_2

array

└metadata_2[]

object

└metadata_3

null

也可能返回 201，表示任务已接受并在后台异步执行。使用响应体中的 task_uuid 轮询对应的 GET 端点获取结果。了解同步 vs 异步 →

立即体验

curl https://api.v2fun.ai/api/v1/3d_models/renderings \
  -X POST \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "input_model": "<input_model>"
    }'

Response 200 OK

{
  "task_uuid": "<task_uuid>",
  "task_type": "<task_type>",
  "model": "<model>",
  "status": "<taskstatus>",
  "created_at": 0,
  "completed_at": 0,
  "result": []
}

获取渲染预览任务

GET/3d_models/renderings/{task_uuid}

获取 3D 模型渲染任务的当前状态或最终输出。

参数

名称	位置	必填	类型	说明
`task_uuid`	path	是	string	Task UUID returned when the rendering job was created.

响应

通用错误码说明请查看：错误处理。

Response Schema

200application/json

ImageResponse

└task_uuid

required

string(Task Uuid)

Unique identifier for the task

└task_type

required

string(Task Type)

Logical task category used by the backend pipeline.

└model

required

string(Model)

Model or worker name assigned to the task.

└status

required

string(TaskStatus)

Enum: QUEUED PROCESSING COMPLETED FAILED

└created_at

required

integer(Created At)

Unix timestamp, in seconds, when the task was created.

└completed_at

required

integer(Completed At)

Unix timestamp, in seconds, when the task finished successfully.

└result

required

array(Result)

Generated, edited, or processed image URI list. Returned asset URIs are relative paths that can be reused directly in compatible input fields.

└result[]

string

└metadata

any(Metadata)

Additional task-specific metadata returned with the result.

VideoResponse

└task_uuid

required

string(Task Uuid)

Unique identifier for the task

└task_type

required

string(Task Type)

Logical task category used by the backend pipeline.

└model

required

string(Model)

Model or worker name assigned to the task.

└status

required

string(TaskStatus)

Enum: QUEUED PROCESSING COMPLETED FAILED

└created_at

required

integer(Created At)

Unix timestamp, in seconds, when the task was created.

└completed_at

required

integer(Completed At)

Unix timestamp, in seconds, when the task finished successfully.

└result

required

array(Result)

Generated or rendered video URI list. Returned asset URIs are relative paths that can be reused directly in compatible input fields.

└result[]

string

└metadata

anyOf(Metadata)

Additional metadata describing the generated video and optional last frame image, or per-model rendering metadata for preview video tasks.

VideoGenerationMetadata

└last_frame

string | null

Stored last frame image URI, when `return_last_frame` was requested. Returned asset URIs are relative paths that can be reused directly in compatible input fields.

└downloads

any[] | null

Temporary download links for the generated video and optional last frame image. Flattened list of presigned HTTP download descriptors for every URI returned in `result` or this object.

└downloads[]

any

└metadata_2

array

└metadata_2[]

object

└metadata_3

null

立即体验

curl https://api.v2fun.ai/api/v1/3d_models/renderings/<task_uuid> \
  -H "Authorization: Bearer $YOUR_API_KEY"

Response 200 OK

{
  "task_uuid": "<task_uuid>",
  "task_type": "<task_type>",
  "model": "<model>",
  "status": "<taskstatus>",
  "created_at": 0,
  "completed_at": 0,
  "result": []
}

图像

3D 模型

动作与动画

视频

余额

3D 模型

创建 3D 模型生成任务

请求体

响应

获取 3D 模型生成任务

参数

响应

创建模型贴图任务

请求体

响应

获取模型贴图任务

参数

响应

创建网格优化任务

请求体

响应

获取网格优化任务

参数

响应

创建格式转换任务

请求体

响应

获取格式转换任务

参数

响应

创建渲染预览任务

请求体

响应

获取渲染预览任务

参数

响应

3D 模型 ​

创建 3D 模型生成任务 ​

请求体

响应

获取 3D 模型生成任务 ​

参数

响应

创建模型贴图任务 ​

请求体

响应

获取模型贴图任务 ​

参数

响应

创建网格优化任务 ​

请求体

响应

获取网格优化任务 ​

参数

响应

创建格式转换任务 ​

请求体

响应

获取格式转换任务 ​

参数

响应

创建渲染预览任务 ​

请求体

响应

获取渲染预览任务 ​

参数

响应

3D 模型

创建 3D 模型生成任务

获取 3D 模型生成任务

创建模型贴图任务

获取模型贴图任务

创建网格优化任务

获取网格优化任务

创建格式转换任务

获取格式转换任务

创建渲染预览任务

获取渲染预览任务