3D Models

Create a 3D mesh generation task

POST/3d_models/meshes

Generate a 3D mesh from text, a single image, or a multi-view image set.

Request Body

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`.

Responses

For standard error codes, see Error Handling.

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

This endpoint may also return 201 when the task is accepted for asynchronous execution. Use the task_uuid from the response body to poll the corresponding GET endpoint for the result. Sync vs async →

Try It

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": []
}

Get a 3D mesh generation task

GET/3d_models/meshes/{task_uuid}

Retrieve the current status or final output of a 3D mesh generation task.

Parameters

Name	In	Required	Type	Description
task_uuid	path	Yes	string	Task UUID returned when the 3D mesh job was created.

Responses

For standard error codes, see Error Handling.

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

Try It

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": []
}

Create a texture generation task

POST/3d_models/textures

Generate textures for an existing 3D model from text, a single reference image, or multi-view reference images.

Request Body

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`.

Responses

For standard error codes, see Error Handling.

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

This endpoint may also return 201 when the task is accepted for asynchronous execution. Use the task_uuid from the response body to poll the corresponding GET endpoint for the result. Sync vs async →

Try It

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 a texture generation task

GET/3d_models/textures/{task_uuid}

Retrieve the current status or final output of a 3D texture generation task.

Parameters

Name	In	Required	Type	Description
task_uuid	path	Yes	string	Task UUID returned when the texture generation job was created.

Responses

For standard error codes, see Error Handling.

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

Try It

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": []
}

Create a remeshing task

POST/3d_models/remeshings

Retopologize an existing 3D model into a target mesh density and topology.

Request Body

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`.

Responses

For standard error codes, see Error Handling.

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

This endpoint may also return 201 when the task is accepted for asynchronous execution. Use the task_uuid from the response body to poll the corresponding GET endpoint for the result. Sync vs async →

Try It

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 a remeshing task

GET/3d_models/remeshings/{task_uuid}

Retrieve the current status or final output of a remeshing task.

Parameters

Name	In	Required	Type	Description
task_uuid	path	Yes	string	Task UUID returned when the remeshing job was created.

Responses

For standard error codes, see Error Handling.

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

Try It

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": []
}

Create a model conversion task

POST/3d_models/conversions

Convert an existing 3D model into another file format.

Request Body

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`.

Responses

For standard error codes, see Error Handling.

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

This endpoint may also return 201 when the task is accepted for asynchronous execution. Use the task_uuid from the response body to poll the corresponding GET endpoint for the result. Sync vs async →

Try It

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 a model conversion task

GET/3d_models/conversions/{task_uuid}

Retrieve the current status or final output of a 3D model conversion task.

Parameters

Name	In	Required	Type	Description
task_uuid	path	Yes	string	Task UUID returned when the conversion job was created.

Responses

For standard error codes, see Error Handling.

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

Try It

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": []
}

Create a 3D model rendering task

POST/3d_models/renderings

Render preview images or a preview video for an existing 3D model.

Request Body

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`.

Responses

For standard error codes, see Error Handling.

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

This endpoint may also return 201 when the task is accepted for asynchronous execution. Use the task_uuid from the response body to poll the corresponding GET endpoint for the result. Sync vs async →

Try It

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 a 3D model rendering task

GET/3d_models/renderings/{task_uuid}

Retrieve the current status or final output of a 3D model rendering task.

Parameters

Name	In	Required	Type	Description
task_uuid	path	Yes	string	Task UUID returned when the rendering job was created.

Responses

For standard error codes, see Error Handling.

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

Try It

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": []
}