3D
创建 3D 模型生成任务
根据文本提示词、参考图片或多视图图片创建异步 3D 模型生成任务。
POST
/
openapi
/
v1
/
3dmodels
/
generations
{
"model": "dreamtech/neural4d-2.5",
"prompt": "白色摄影棚背景中的陶瓷茶壶",
"mesh_quality": "standard",
"topology": "triangle",
"target_polycount": 500000,
"with_texture": false,
"with_pbr": false,
"n": 1
}
{
"model": "dreamtech/neural4d-2.5",
"input_references": [
{ "type": "image", "file_id": "550e8400-e29b-41d4-a716-446655440000" }
],
"image_enhancement": true,
"pose": "T-pose",
"mesh_quality": "standard",
"n": 2
}
{
"model": "dreamtech/neural4d-2.5",
"input_references": [
{ "type": "image", "file_id": "550e8400-e29b-41d4-a716-446655440000" },
{ "type": "image", "file_id": "550e8400-e29b-41d4-a716-446655440001" }
],
"image_enhancement": true,
"mesh_quality": "standard",
"target_polycount": 500000
}
{
"model": "dreamtech/neural4d-2.5",
"multi_view_images": [
{ "view_type": "front", "file_id": "550e8400-e29b-41d4-a716-446655440001" },
{ "view_type": "back", "file_id": "550e8400-e29b-41d4-a716-446655440002" },
{ "view_type": "left", "file_id": "550e8400-e29b-41d4-a716-446655440003" },
{ "view_type": "right", "file_id": "550e8400-e29b-41d4-a716-446655440004" },
{ "view_type": "top", "file_id": "550e8400-e29b-41d4-a716-446655440005" },
{ "view_type": "bottom", "file_id": "550e8400-e29b-41d4-a716-446655440006" }
],
"target_polycount": 500000,
"with_texture": false,
"with_pbr": false,
"n": 1
}
{
"id": "normal-3d-c50fe63e-699d-4d61-93f5-2099ab159d6d",
"status": "queued",
"created_at": 1784044800,
"mode": "batch_image_to_3d",
"model": "dreamtech/neural4d-2.5",
"data": [
{
"uuid": "72e30159-a242-4491-a67c-2ad0cfc9efb6",
"status": "queued",
"created_at": 1784044800
},
{
"uuid": "72e30159-a242-4491-a67c-2ad0cfc9efb7",
"status": "queued",
"created_at": 1784044800
}
],
"usage": {
"credits": 60
}
}
{
"error": {
"code": "file_rejected",
"message": "The uploaded image did not pass content validation"
}
}
{
"error": {
"code": "invalid_content_type",
"message": "Content-Type must be application/json"
}
}
{
"error": {
"code": "invalid_file_id",
"message": "Request body validation failed"
}
}
{
"error": {
"code": "invalid_file_type",
"message": "Unsupported reference type"
}
}
{
"error": {
"code": "invalid_generation_request",
"message": "Invalid 3D generation request"
}
}
{
"error": {
"code": "invalid_multi_view_images",
"message": "Request body validation failed",
"details": [
{
"field": "/multi_view_images",
"rule": "custom",
"message": "Views must include front and back without duplicates"
}
]
}
}
{
"error": {
"code": "invalid_prompt",
"message": "Request body validation failed",
"details": [
{
"field": "/prompt",
"rule": "too_small",
"message": "String must contain at least 1 character(s)"
}
]
}
}
{
"error": {
"code": "invalid_reference_source",
"message": "Request body validation failed",
"details": [
{
"field": "/input_references/0",
"rule": "custom",
"message": "Provide exactly one of file_id or url"
}
]
}
}
{
"error": {
"code": "invalid_reference_url",
"message": "Request body validation failed",
"details": [
{
"field": "/input_references/0/url",
"rule": "custom",
"message": "url must be an HTTPS URL without embedded credentials"
}
]
}
}
{
"error": {
"code": "invalid_request",
"message": "Request body validation failed",
"details": [
{
"field": "/model",
"rule": "invalid_enum_value",
"message": "Invalid enum value. Expected 'dreamtech/neural4d-2.5', received 'unsupported-model'"
}
]
}
}
{
"error": {
"code": "invalid_target_polycount",
"message": "target_polycount must be between 100000 and 500000 in steps of 1000"
}
}
{
"error": {
"code": "unsafe_reference_url",
"message": "Reference URL is not allowed"
}
}
{
"error": {
"code": "invalid_api_key",
"message": "A Bearer API key is required"
}
}
{
"error": {
"code": "insufficient_credits",
"message": "User insufficient points, only have 0 now"
}
}
{
"error": {
"code": "subscription_required",
"message": "OpenAPI v1 is available to subscribed users only"
}
}
{
"error": {
"code": "reference_fetch_timeout",
"message": "Reference host resolution timed out"
}
}
{
"error": {
"code": "reference_too_large",
"message": "Reference file must not exceed 20 MB"
}
}
{
"error": {
"code": "invalid_reference_file",
"message": "Reference file is empty"
}
}
{
"error": {
"code": "invalid_reference_file_type",
"message": "Reference response Content-Type does not match its file content"
}
}
{
"error": {
"code": "reference_fetch_failed",
"message": "Reference host could not be resolved"
}
}
{
"error": {
"code": "reference_redirect_limit",
"message": "Reference URL redirected too many times"
}
}
{
"error": {
"code": "generation_limit_exceeded",
"message": "Generation limit exceeded"
}
}
{
"error": {
"code": "rate_limit_exceeded",
"message": "Too many requests. Retry after the indicated interval."
}
}
{
"error": {
"code": "reference_import_busy",
"message": "Too many reference files are being imported"
}
}
{
"error": {
"code": "internal_error",
"message": "An internal error occurred"
}
}
{
"error": {
"code": "file_moderation_unavailable",
"message": "An internal error occurred"
}
}
{
"error": {
"code": "rate_limit_unavailable",
"message": "An internal error occurred"
}
}
{
"error": {
"code": "reference_too_large",
"message": "Reference file must not exceed 10 MB"
}
}
授权
string
默认值:"Bearer ${YOUR_API_KEY}"
必填
使用 Bearer 方式发送的 Neural4D API 密钥。
请求体 application/json
- 文生 3D
- 单图生 3D
- 批量图生 3D
- 多视图生 3D
enum<string>
必填
公开模型标识。可选值:
dreamtech/neural4d-2.5。string
必填
描述待生成模型的文本提示词。不能为空,最多 500 个字符。
boolean
默认值:false
是否生成纹理。设为
false 时仅生成网格。boolean
默认值:false
是否生成 PBR 材质。为
true 时,with_texture 必须为 true。enum<string>
默认值:"standard"
网格质量:
standard、high 或 extra_high。enum<string>
默认值:"triangle"
网格拓扑:
triangle 或 quad。integer
默认值:500000
目标面数。三角面
standard 为 100,000–500,000,默认 500,000;三角面 high、extra_high 为 500,000–1,000,000,默认 1,000,000;四边面为 1,000–100,000,默认 50,000。三角面以 1,000 递增,四边面以 100 递增。enum<string>
默认值:"auto"
角色姿态:
auto、A-pose 或 T-pose。integer
默认值:1
生成的模型数量,范围为 1–4。
enum<string>
必填
公开模型标识。可选值:
dreamtech/neural4d-2.5。object[]
必填
参考图片数组,长度必须为
1。图片仅支持 JPG、JPEG、PNG、WEBP,每张大小不超过 20 MiB。元素只能提供 file_id 或 url 中的一个。不能与 multi_view_images 同时使用。大小限制同时适用于 file_id 和 url。boolean
默认值:false
是否在生成 3D 模型前增强输入图片,帮助改善生成效果。设为
true 时开启,默认关闭。boolean
默认值:false
是否生成纹理。设为
false 时仅生成网格。boolean
默认值:false
是否生成 PBR 材质。为
true 时,with_texture 必须为 true。enum<string>
默认值:"standard"
网格质量:
standard、high 或 extra_high。enum<string>
默认值:"triangle"
网格拓扑:
triangle 或 quad。integer
默认值:500000
目标面数。三角面
standard 为 100,000–500,000,默认 500,000;三角面 high、extra_high 为 500,000–1,000,000,默认 1,000,000;四边面为 1,000–100,000,默认 50,000。三角面以 1,000 递增,四边面以 100 递增。enum<string>
默认值:"auto"
角色姿态:
auto、A-pose 或 T-pose。integer
默认值:1
根据这一张参考图片生成的模型数量,范围为 1–4。
enum<string>
必填
公开模型标识。可选值:
dreamtech/neural4d-2.5。object[]
必填
参考图片数组,长度为
2–10。图片仅支持 JPG、JPEG、PNG、WEBP,每张大小不超过 20 MiB。每张图片分别生成一个模型。每个元素只能提供 file_id 或 url 中的一个。不能与 multi_view_images 同时使用。大小限制同时适用于 file_id 和 url。boolean
默认值:false
是否在生成 3D 模型前增强批次中的每张输入图片,帮助改善生成效果。设为
true 时开启,默认关闭。boolean
默认值:false
是否生成纹理。设为
false 时仅生成网格。boolean
默认值:false
是否生成 PBR 材质。为
true 时,with_texture 必须为 true。enum<string>
默认值:"standard"
网格质量:
standard、high 或 extra_high。enum<string>
默认值:"triangle"
网格拓扑:
triangle 或 quad。integer
默认值:500000
目标面数。三角面
standard 为 100,000–500,000,默认 500,000;三角面 high、extra_high 为 500,000–1,000,000,默认 1,000,000;四边面为 1,000–100,000,默认 50,000。三角面以 1,000 递增,四边面以 100 递增。enum<string>
必填
公开模型标识。可选值:
dreamtech/neural4d-2.5。object[]
必填
多视图参考图片数组,长度为
2–6。图片支持 JPG、JPEG、PNG、WEBP,每张大小不超过 10 MiB。必须包含 front 和 back;其余视角可选,同一视角最多出现一次。每个元素只能提供 file_id 或 url 中的一个。不能与 input_references 同时使用。大小限制同时适用于 file_id 和 url。此模式固定使用 high 质量的三角网格,不能传入 mesh_quality、topology 或 pose。boolean
默认值:false
是否生成纹理。设为
false 时仅生成网格。boolean
默认值:false
是否生成 PBR 材质。为
true 时,with_texture 必须为 true。integer
默认值:500000
目标面数。多视图使用
high 质量的三角网格,可设为 500,000–1,000,000,默认 500,000,以 1,000 递增。integer
默认值:1
生成的模型数量,范围为 1–4。
{
"model": "dreamtech/neural4d-2.5",
"prompt": "白色摄影棚背景中的陶瓷茶壶",
"mesh_quality": "standard",
"topology": "triangle",
"target_polycount": 500000,
"with_texture": false,
"with_pbr": false,
"n": 1
}
{
"model": "dreamtech/neural4d-2.5",
"input_references": [
{ "type": "image", "file_id": "550e8400-e29b-41d4-a716-446655440000" }
],
"image_enhancement": true,
"pose": "T-pose",
"mesh_quality": "standard",
"n": 2
}
{
"model": "dreamtech/neural4d-2.5",
"input_references": [
{ "type": "image", "file_id": "550e8400-e29b-41d4-a716-446655440000" },
{ "type": "image", "file_id": "550e8400-e29b-41d4-a716-446655440001" }
],
"image_enhancement": true,
"mesh_quality": "standard",
"target_polycount": 500000
}
{
"model": "dreamtech/neural4d-2.5",
"multi_view_images": [
{ "view_type": "front", "file_id": "550e8400-e29b-41d4-a716-446655440001" },
{ "view_type": "back", "file_id": "550e8400-e29b-41d4-a716-446655440002" },
{ "view_type": "left", "file_id": "550e8400-e29b-41d4-a716-446655440003" },
{ "view_type": "right", "file_id": "550e8400-e29b-41d4-a716-446655440004" },
{ "view_type": "top", "file_id": "550e8400-e29b-41d4-a716-446655440005" },
{ "view_type": "bottom", "file_id": "550e8400-e29b-41d4-a716-446655440006" }
],
"target_polycount": 500000,
"with_texture": false,
"with_pbr": false,
"n": 1
}
响应
请通过error.code 判断错误原因。
- 202
- 400
- 401
- 403
- 408
- 413
- 415
- 422
- 429
- 500
- 503
成功请求返回
202 Accepted、批次任务 ID 和生成结果子项。批量图片请求会为每张图片创建一个子任务;例如传入 2 张图片,data 中返回 2 个子项。string
必填
本次生成请求的批次任务 ID,可用于查询任务状态。
enum<string>
必填
批次任务状态。可选值:
queued、processing、succeeded、failed。integer<int64>
必填
批次任务创建时间的 Unix 时间戳,单位为秒。
enum<string>
必填
生成模式。可选值:
text_to_3d(文生)、image_to_3d(单图生)、batch_image_to_3d(批量图生)、multi_view_to_3d(多视图生)。string
必填
本次生成使用的公开模型标识。
object[]
必填
本次请求创建的生成结果子项。
隐藏 子属性
隐藏 子属性
生成结果子项 UUID。
子任务状态。可选值:
queued、processing、succeeded、failed。子任务创建时间的 Unix 时间戳,单位为秒。
子任务更新时间的 Unix 时间戳,单位为秒。
请求无效。
object
必填
结构化错误详情。
隐藏 子属性
隐藏 子属性
稳定且可供程序读取的错误码。
file_rejected: 参考图片未通过内容校验。invalid_content_type: Content-Type 必须为 application/json。invalid_file_id: 上传文件 ID 无效或不可用。invalid_file_type: 上传文件不是受支持的参考图片。invalid_generation_request: 不支持当前 3D 生成请求。invalid_multi_view_images: 多视图必须包含正面和背面,且视角不能重复。invalid_prompt: 提示词为空、超过 500 个字符或未通过内容校验。invalid_reference_source: 每个参考素材必须且只能提供 file_id 或 url 中的一个。invalid_reference_url: 参考素材 URL 的格式或长度无效。invalid_request: 请求参数无效。invalid_target_polycount: 目标面数不满足允许的范围或步长。unsafe_reference_url: 参考素材 URL 或重定向目标不被允许。
便于阅读的错误说明,请通过 error.code 区分原因。
可用时返回参数校验问题,每项包含 field、rule 和 message。
鉴权失败。
订阅或积分要求未满足。
参考素材下载超时。
参考图片过大。
参考图片无效或不受支持。
参考素材下载失败。
超过限制。响应包含
Retry-After 时,请按该请求头指定的秒数等待后再重试。内部错误。当
error.details.registration_failed 为 true 时,任务已经入队,但任务登记失败;完整提交返回 task_registration_failed,3D 部分提交保留原错误码。
error.details.task 保留任务 ID、UUID 和已知积分;submission_accepted 为 true,retryable 为 false。
不要重新提交生成请求,以免重复扣费。登记恢复前,任务查询可能返回 404。{
"id": "normal-3d-c50fe63e-699d-4d61-93f5-2099ab159d6d",
"status": "queued",
"created_at": 1784044800,
"mode": "batch_image_to_3d",
"model": "dreamtech/neural4d-2.5",
"data": [
{
"uuid": "72e30159-a242-4491-a67c-2ad0cfc9efb6",
"status": "queued",
"created_at": 1784044800
},
{
"uuid": "72e30159-a242-4491-a67c-2ad0cfc9efb7",
"status": "queued",
"created_at": 1784044800
}
],
"usage": {
"credits": 60
}
}
{
"error": {
"code": "file_rejected",
"message": "The uploaded image did not pass content validation"
}
}
{
"error": {
"code": "invalid_content_type",
"message": "Content-Type must be application/json"
}
}
{
"error": {
"code": "invalid_file_id",
"message": "Request body validation failed"
}
}
{
"error": {
"code": "invalid_file_type",
"message": "Unsupported reference type"
}
}
{
"error": {
"code": "invalid_generation_request",
"message": "Invalid 3D generation request"
}
}
{
"error": {
"code": "invalid_multi_view_images",
"message": "Request body validation failed",
"details": [
{
"field": "/multi_view_images",
"rule": "custom",
"message": "Views must include front and back without duplicates"
}
]
}
}
{
"error": {
"code": "invalid_prompt",
"message": "Request body validation failed",
"details": [
{
"field": "/prompt",
"rule": "too_small",
"message": "String must contain at least 1 character(s)"
}
]
}
}
{
"error": {
"code": "invalid_reference_source",
"message": "Request body validation failed",
"details": [
{
"field": "/input_references/0",
"rule": "custom",
"message": "Provide exactly one of file_id or url"
}
]
}
}
{
"error": {
"code": "invalid_reference_url",
"message": "Request body validation failed",
"details": [
{
"field": "/input_references/0/url",
"rule": "custom",
"message": "url must be an HTTPS URL without embedded credentials"
}
]
}
}
{
"error": {
"code": "invalid_request",
"message": "Request body validation failed",
"details": [
{
"field": "/model",
"rule": "invalid_enum_value",
"message": "Invalid enum value. Expected 'dreamtech/neural4d-2.5', received 'unsupported-model'"
}
]
}
}
{
"error": {
"code": "invalid_target_polycount",
"message": "target_polycount must be between 100000 and 500000 in steps of 1000"
}
}
{
"error": {
"code": "unsafe_reference_url",
"message": "Reference URL is not allowed"
}
}
{
"error": {
"code": "invalid_api_key",
"message": "A Bearer API key is required"
}
}
{
"error": {
"code": "insufficient_credits",
"message": "User insufficient points, only have 0 now"
}
}
{
"error": {
"code": "subscription_required",
"message": "OpenAPI v1 is available to subscribed users only"
}
}
{
"error": {
"code": "reference_fetch_timeout",
"message": "Reference host resolution timed out"
}
}
{
"error": {
"code": "reference_too_large",
"message": "Reference file must not exceed 20 MB"
}
}
{
"error": {
"code": "invalid_reference_file",
"message": "Reference file is empty"
}
}
{
"error": {
"code": "invalid_reference_file_type",
"message": "Reference response Content-Type does not match its file content"
}
}
{
"error": {
"code": "reference_fetch_failed",
"message": "Reference host could not be resolved"
}
}
{
"error": {
"code": "reference_redirect_limit",
"message": "Reference URL redirected too many times"
}
}
{
"error": {
"code": "generation_limit_exceeded",
"message": "Generation limit exceeded"
}
}
{
"error": {
"code": "rate_limit_exceeded",
"message": "Too many requests. Retry after the indicated interval."
}
}
{
"error": {
"code": "reference_import_busy",
"message": "Too many reference files are being imported"
}
}
{
"error": {
"code": "internal_error",
"message": "An internal error occurred"
}
}
{
"error": {
"code": "file_moderation_unavailable",
"message": "An internal error occurred"
}
}
{
"error": {
"code": "rate_limit_unavailable",
"message": "An internal error occurred"
}
}
{
"error": {
"code": "reference_too_large",
"message": "Reference file must not exceed 10 MB"
}
}
⌘I
{
"model": "dreamtech/neural4d-2.5",
"prompt": "白色摄影棚背景中的陶瓷茶壶",
"mesh_quality": "standard",
"topology": "triangle",
"target_polycount": 500000,
"with_texture": false,
"with_pbr": false,
"n": 1
}
{
"model": "dreamtech/neural4d-2.5",
"input_references": [
{ "type": "image", "file_id": "550e8400-e29b-41d4-a716-446655440000" }
],
"image_enhancement": true,
"pose": "T-pose",
"mesh_quality": "standard",
"n": 2
}
{
"model": "dreamtech/neural4d-2.5",
"input_references": [
{ "type": "image", "file_id": "550e8400-e29b-41d4-a716-446655440000" },
{ "type": "image", "file_id": "550e8400-e29b-41d4-a716-446655440001" }
],
"image_enhancement": true,
"mesh_quality": "standard",
"target_polycount": 500000
}
{
"model": "dreamtech/neural4d-2.5",
"multi_view_images": [
{ "view_type": "front", "file_id": "550e8400-e29b-41d4-a716-446655440001" },
{ "view_type": "back", "file_id": "550e8400-e29b-41d4-a716-446655440002" },
{ "view_type": "left", "file_id": "550e8400-e29b-41d4-a716-446655440003" },
{ "view_type": "right", "file_id": "550e8400-e29b-41d4-a716-446655440004" },
{ "view_type": "top", "file_id": "550e8400-e29b-41d4-a716-446655440005" },
{ "view_type": "bottom", "file_id": "550e8400-e29b-41d4-a716-446655440006" }
],
"target_polycount": 500000,
"with_texture": false,
"with_pbr": false,
"n": 1
}
{
"id": "normal-3d-c50fe63e-699d-4d61-93f5-2099ab159d6d",
"status": "queued",
"created_at": 1784044800,
"mode": "batch_image_to_3d",
"model": "dreamtech/neural4d-2.5",
"data": [
{
"uuid": "72e30159-a242-4491-a67c-2ad0cfc9efb6",
"status": "queued",
"created_at": 1784044800
},
{
"uuid": "72e30159-a242-4491-a67c-2ad0cfc9efb7",
"status": "queued",
"created_at": 1784044800
}
],
"usage": {
"credits": 60
}
}
{
"error": {
"code": "file_rejected",
"message": "The uploaded image did not pass content validation"
}
}
{
"error": {
"code": "invalid_content_type",
"message": "Content-Type must be application/json"
}
}
{
"error": {
"code": "invalid_file_id",
"message": "Request body validation failed"
}
}
{
"error": {
"code": "invalid_file_type",
"message": "Unsupported reference type"
}
}
{
"error": {
"code": "invalid_generation_request",
"message": "Invalid 3D generation request"
}
}
{
"error": {
"code": "invalid_multi_view_images",
"message": "Request body validation failed",
"details": [
{
"field": "/multi_view_images",
"rule": "custom",
"message": "Views must include front and back without duplicates"
}
]
}
}
{
"error": {
"code": "invalid_prompt",
"message": "Request body validation failed",
"details": [
{
"field": "/prompt",
"rule": "too_small",
"message": "String must contain at least 1 character(s)"
}
]
}
}
{
"error": {
"code": "invalid_reference_source",
"message": "Request body validation failed",
"details": [
{
"field": "/input_references/0",
"rule": "custom",
"message": "Provide exactly one of file_id or url"
}
]
}
}
{
"error": {
"code": "invalid_reference_url",
"message": "Request body validation failed",
"details": [
{
"field": "/input_references/0/url",
"rule": "custom",
"message": "url must be an HTTPS URL without embedded credentials"
}
]
}
}
{
"error": {
"code": "invalid_request",
"message": "Request body validation failed",
"details": [
{
"field": "/model",
"rule": "invalid_enum_value",
"message": "Invalid enum value. Expected 'dreamtech/neural4d-2.5', received 'unsupported-model'"
}
]
}
}
{
"error": {
"code": "invalid_target_polycount",
"message": "target_polycount must be between 100000 and 500000 in steps of 1000"
}
}
{
"error": {
"code": "unsafe_reference_url",
"message": "Reference URL is not allowed"
}
}
{
"error": {
"code": "invalid_api_key",
"message": "A Bearer API key is required"
}
}
{
"error": {
"code": "insufficient_credits",
"message": "User insufficient points, only have 0 now"
}
}
{
"error": {
"code": "subscription_required",
"message": "OpenAPI v1 is available to subscribed users only"
}
}
{
"error": {
"code": "reference_fetch_timeout",
"message": "Reference host resolution timed out"
}
}
{
"error": {
"code": "reference_too_large",
"message": "Reference file must not exceed 20 MB"
}
}
{
"error": {
"code": "invalid_reference_file",
"message": "Reference file is empty"
}
}
{
"error": {
"code": "invalid_reference_file_type",
"message": "Reference response Content-Type does not match its file content"
}
}
{
"error": {
"code": "reference_fetch_failed",
"message": "Reference host could not be resolved"
}
}
{
"error": {
"code": "reference_redirect_limit",
"message": "Reference URL redirected too many times"
}
}
{
"error": {
"code": "generation_limit_exceeded",
"message": "Generation limit exceeded"
}
}
{
"error": {
"code": "rate_limit_exceeded",
"message": "Too many requests. Retry after the indicated interval."
}
}
{
"error": {
"code": "reference_import_busy",
"message": "Too many reference files are being imported"
}
}
{
"error": {
"code": "internal_error",
"message": "An internal error occurred"
}
}
{
"error": {
"code": "file_moderation_unavailable",
"message": "An internal error occurred"
}
}
{
"error": {
"code": "rate_limit_unavailable",
"message": "An internal error occurred"
}
}
{
"error": {
"code": "reference_too_large",
"message": "Reference file must not exceed 10 MB"
}
}