面向 AI 助手：本页的 Markdown 版本位于 https://ark.volcengine.com/region:cn-beijing/docs/seed3d-badcase-report.md，全部文档索引见 https://ark.volcengine.com/llms.txt。

上报 3D 生成效果问题

POST https://prompt-pilot.cn-beijing.volces.com/case-platform?Action=CasePlatformV1BadcaseReport&Version=2024-01-01

本接口用于上报 Seed3D 2.0 模型的 3D 生成效果问题，例如几何缺失、破面、贴图错位或与参考图不符。系统根据指定的 task_id 读取任务的输入参考图、生成参数和输出模型，创建 Badcase 记录，并保存问题描述和可选截图。支持通过 Access Key 或方舟 API Key 鉴权。

本文列出 3D 上报的参数要求。受理后通过 查询 3D 生成效果问题结果 查看排查状态、结论及截图保存结果。视频任务参见 上报视频生成模型效果问题。

前提条件#

  • 任务使用 Seed3D 2.0，已成功完成并产出 3D 模型。Seed3D 3.0 暂不支持。
  • 任务须在 7 天内上报。本接口根据 task_id 向上游查询原始任务数据，超过上报窗口后可能无法读取。请在生成完成后尽早提交。
  • 凭证与任务属于同一火山引擎账号。
  • 每个任务只能上报一次，请在提交前准备完整的描述和截图。

问题截图的源链接须在提交后至少 24 小时内保持可访问，以便平台异步下载。该要求与 3D 任务的上报窗口分别计算。

生成失败、被拦截或没有产出模型的任务，请通过火山引擎工单反馈。尚在生成中的任务，须等待生成完成后再上报。

视频与 3D 的字段差异#

视频和 3D 使用相同的 Action、Version、鉴权方式及公共响应结构。请按任务类型填写：

字段 视频任务 3D 任务
Id 视频生成任务 ID Seed3D 2.0 生成任务 ID
Feedback 视频效果问题描述，必填 3D 效果问题描述，必填
FeedbackImages 可选的问题截图 可选的问题截图
BadcaseType 可选的视频问题类型 请勿传入
TimelineFeedbacks 可选的视频时间轴反馈 请勿传入
RejectedTimelineFeedbacks 未写入的时间轴反馈条目 未传时间轴反馈时为空数组

请求头#

使用方舟 API Key 时，请设置 Authorization: Bearer <API_KEY> 和 Content-Type: application/json，请求体可省略 AccountId。

使用 AK/SK 时，请设置 V4 签名所需的 Authorization、X-Date 和 X-Content-Sha256。签名的 Service 为 ark，Region 为 cn-beijing，请求体须包含 AccountId。

鉴权#

本接口支持鉴权方式如下，详情请参见 Base URL 及鉴权。

  • 【推荐】API Key 鉴权，请在 API Key 管理 页面，获取长效 API Key。
  • 【可选】Access Key 鉴权，请在 Access Key 管理 页面，获取 Access Key。

请求参数#

Query 参数#

在 URL Query String 中传入。

Action string 必选  |  接口名称，固定为 CasePlatformV1BadcaseReport
Version string 必选  |  接口版本，固定为 2024-01-01

Body 参数#

Feedback string 必选  |  问题描述

3D 模型的效果问题描述，长度为 1 至 2000 个字符，不能仅包含空白字符。同一请求中的所有任务共用此描述。建议说明期望效果、实际问题、观察角度和使用的查看工具。3D 任务必须填写本字段，不能用 TimelineFeedbacks 替代。

Id string / string[] 必选  |  任务 ID 列表

待上报的任务 ID，支持单个字符串或字符串数组。服务端按半角逗号、全角逗号、换行、空格或制表符拆分，并移除首尾空白和空项。

拆分后的任务数量须为 1 至 50，否则返回 HTTP 422、错误码 40011。同一请求中的任务共用 Feedback 和 FeedbackImages。

AccountId string  |  火山引擎账号 ID

Id 中任务所属的火山引擎账号 ID。

  • 使用 Access Key 调用时必填。
  • 使用方舟 API Key 调用时可省略，系统根据 API Key 解析账号 ID。
ContactInfo string  |  联系方式

提交人的联系方式，支持电子邮箱地址或电话号码，最多 255 个字符。建议填写，便于处理人员联系您补充信息。

FeedbackImages object[]  |  问题截图

可选的问题截图，最多 5 张，同一请求中的所有任务共用。平台受理后异步下载，失败不影响 Case 建立，也不会自动重试。通过 查询 3D 生成效果问题结果 查看每张截图的下载状态和失败原因。

Url string 必选  |  截图地址

FeedbackImages.Url

须使用公网可直接访问的 HTTPS 图片直链，不需要登录，不指向内网或私有地址，重定向不超过 3 次。不要提交网页、3D 模型文件、tos:// 路径或 data: 内联图片。

支持 PNG、JPEG、WebP，以实际文件内容判断，每张不超过 10 MB。上报后至少 24 小时内保持可访问；单张下载时限为 60 秒。

错误码#

请求级错误位于 ResponseMetadata.Error；HTTP 200 时仍须检查 Result.Accepted 和 Result.Rejected，不能仅凭 HTTP 状态码判断每个任务上报成功。

HTTP ResponseMetadata.Error.CodeN 含义及处理方法
400 100023 JSON、字段或类型不合法，或描述超过 2000 字符、截图超过 5 张、联系方式超过 255 字符。按 Message 修正。
401 可能为空 检查 Bearer 格式和 API Key 是否有效。
400 40006 使用 AK/SK 时未传 AccountId。
422 40007 AccountId 为空或仅包含空白。
422 40011 Id 拆分后须包含 1 至 50 个任务。
422 40014 3D Feedback 为空或仅包含空白。
422 40015 截图条目不合法。按 Message 中从 0 起算的序号检查 Url，须使用公网 HTTPS 图片直链。
503 100050 平台查询任务资料时繁忙或超时，稍后重试。
500 100000 服务端异常。保留 RequestId 联系技术支持；重发前先查询任务是否已受理。
Result.Rejected[].Code 含义及处理方法
40012 任务 ID 格式不合法，使用创建 3D 任务响应的 id 原值。
40002 任务不存在、账号不匹配、已超过保留期或没有成功输出。
40004 任务仍在生成中，等待生成成功后再上报。
40003 任务已经上报过，可查询处理结果；补充材料请联系技术支持。
40005 同一请求中重复的任务 ID，发送前去重。
60002 模型不在支持范围，请确认任务来自 Seed3D 2.0。

截图在受理后异步下载，下载失败不影响 Case 建立。通过 查询 3D 生成效果问题结果 查看 FeedbackImages[].Status：pending 表示下载中，ok 表示可用，failed 表示失败。失败时查看 ErrorCode、ErrorReason 和 ErrorMessage；40020 表示下载失败，40023 表示超过 10 MB，50010 表示平台存储失败。截图不会自动重试，同一任务无法重新上报，补充材料请提供 SubmissionId 和任务 ID 联系技术支持。

响应参数#

SubmissionId string  |  提交 ID

本次提交的唯一标识，格式为 badcase-sub-<uuid>。可使用该标识检索相关日志。

Total integer  |  提交总数

本次提交的 task_id 总数，按 Id 参数拆分后的原始列表统计，包含重复项。

Accepted object[]  |  已接受任务列表

通过校验并已创建 Case 记录的 task_id 列表。

CaseId string  |  Case ID

Accepted.CaseId

系统预分配的 Case ID，格式为 instance-<uuid>。受理后异步转存 3D 模型、输入参考图并下载问题截图。可通过 CasePlatformV1BadcaseQuery 查询排查状态和结论；该接口的 Status 为 processing 或 done，与截图下载状态相互独立。

Code integer  |  返回码

Accepted.Code

该任务的处理结果码，固定为 0。

Message string  |  返回消息

Accepted.Message

该任务的处理结果信息，固定为 Success。

TaskId string  |  任务 ID

Accepted.TaskId

已接受并创建 Case 记录的 task_id。

Rejected object[]  |  未接受任务列表

未通过校验且未创建 Case 记录的 task_id 列表。

Code integer  |  错误码

Rejected.Code

未接受该任务的业务错误码。含义参见「错误码」章节。

Message string  |  拒绝原因

Rejected.Message

未接受该任务的原因。

TaskId string  |  未接受的任务 ID

Rejected.TaskId

未通过校验的 task_id。

RejectedTimelineFeedbacks object[]  |  未接受的时间轴反馈

3D 请求不传 TimelineFeedbacks，此列表为空数组。

Message string  |  拒绝原因的可读说明

RejectedTimelineFeedbacks.Message

Reason string  |  拒绝原因

RejectedTimelineFeedbacks.Reason

  • TASK_ID_NOT_MATCHED：任务 ID 未填或不在本次 Id 列表中。
  • INVALID_TIME_RANGE：时间缺失、为负或起点大于终点。
  • FEEDBACK_INVALID：文本缺失、仅为空白或超长。
  • BADCASE_TYPE_INVALID：问题类型枚举不合法。
  • EXCEEDED_LIMIT：超出单个任务 20 条的上限。
  • TASK_REJECTED：所属任务未被接受。
EndTime number / null  |  提交时传入的终点，原样回显，可为 null

RejectedTimelineFeedbacks.EndTime

Feedback string / null  |  提交时传入的问题描述，原样回显，可为 null

RejectedTimelineFeedbacks.Feedback

StartTime number / null  |  提交时传入的起点，原样回显，可为 null

RejectedTimelineFeedbacks.StartTime

TaskId string  |  原本关联的任务 ID，未填写时为空字符串

RejectedTimelineFeedbacks.TaskId