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

查询 3D 生成效果问题结果

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

本接口用于查询 Seed3D 2.0 生成效果问题的处理状态、问题标签、解决方案说明，以及上报时附带截图的保存结果。先通过 上报 3D 生成效果问题 提交反馈，再使用生成任务的 task_id 查询。只能查询当前账号已上报的任务，支持通过 Access Key 或方舟 API Key 鉴权。

Status 为 processing 时表示排查中，为 done 时表示处理完成。截图的下载状态与排查状态相互独立。视频任务参见 查询视频生成模型效果问题结果。

上报窗口与查询时机#

请先在 7 天内通过 上报 3D 生成效果问题 提交火山方舟的 3D 任务反馈。上报接口需要根据 task_id 查询上游原始任务数据，因此有上报窗口。

7 天是上报窗口。本接口查询已上报 Case 的处理状态和结果。Status 为 processing 时，排查尚未完成，ProblemLabel 和 SolutionNote 尚未产出，请稍后再次查询；为 done 时，可读取处理结论。截图下载状态与排查状态相互独立。

链接有效期#

  • FeedbackImages[].Url 为截图的预签名链接，有效期约 10 分钟，具体过期时间见 ExpiresAt。每次查询会重新生成链接，过期后请重新调用本接口。
  • SolutionNote.Attachments[].Url 为解决方案附件链接，每次查询会重新签名。请使用最新响应中的链接，过期后重新查询。

以上是返回链接的有效期，不代表 Case 记录的保留期。

请求头#

使用方舟 API Key 时，设置 Authorization: Bearer <API_KEY> 和 Content-Type: application/json，账号身份从 API Key 解析。

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

鉴权#

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

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

请求参数#

Query 参数#

在 URL Query String 中传入。

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

Body 参数#

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

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

标准化后的任务数量须为 1 至 50，否则返回 HTTP 422、错误码 40011。只能查询当前账号已上报过的任务。

3D 响应中的视频兼容字段#

视频和 3D 使用相同的 Action、Version、鉴权方式及公共响应结构。Accepted 条目中的 BadcaseType 和 TimelineFeedbacks 仅供视频任务使用；3D 任务返回空数组，可忽略。

截图下载失败原因#

截图下载失败不影响 Case 建立，也不会自动重试。同一任务无法再次上报；需要补充截图时，请提供 SubmissionId 和任务 ID 联系技术支持。下表用于定位当前失败及检查后续上报的截图来源。

ErrorCode ErrorReason 含义及处理方法
40020 blocked_address 链接或重定向目标不是公网地址，检查截图来源。
40020 timeout 下载超过 60 秒，检查图片大小和源站响应速度。
40020 http_error 源站返回错误状态码，如 403、404；确认链接未过期且无需登录。
40020 fetch_failed 连接失败、响应为空或重定向超过 3 次，检查图片直链。
40020 not_image 实际内容不是 PNG、JPEG 或 WebP，检查是否提交了网页或其他文件。
40023 too_large 图片超过 10 MB，后续上报前压缩图片。
50010 storage_failed 平台存储失败，提供任务 ID 联系技术支持。

错误码#

HTTP 4xx 或 5xx 时，错误在 ResponseMetadata.Error 中；HTTP 200 时仍需检查 Result.Accepted 与 Result.Rejected，逐个确认查询结果。

HTTP 错误码 含义及处理方法
422 40011 Id 标准化后为空或超过 50 个任务，修正任务列表。
400 100023 请求参数校验失败，按 Message 检查 JSON 和字段类型。
503 100050 平台查询任务资料繁忙或超时，稍后重试。
200 40002 任务不存在或不属于当前账号，检查任务 ID 和鉴权账号。
200 40012 任务尚未上报过 Badcase，先调用上报接口。

查询接口的 40012 表示「尚未上报过」，与上报接口的 40012（任务 ID 格式不合法）含义不同。错误信息可能返回中文或英文，程序应按错误码判断。

响应参数#

Total integer  |  任务总数

本次查询的任务 ID 数量，重复的任务 ID 只计一次。与上报接口按去重前数量统计的 Total 不同。

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

命中且归属当前账号的 task_id 列表，返回提交快照和处理结果。

Status string  |  处理状态

Accepted.Status

badcase 的处理状态。可选值：processing（处理中）、done（处理完成）。

TaskId string  |  任务 ID

Accepted.TaskId

通过校验且归属当前账号的 task_id。

Feedback string  |  问题描述

Accepted.Feedback

用户提交 badcase 时填写的效果问题描述。

FeedbackImages object[]  |  问题截图

Accepted.FeedbackImages

上报时附带的截图，按上报顺序返回。没有截图时为空数组。截图下载状态与 Case 排查状态相互独立，链接和失败原因见子字段。

ErrorCode integer / null  |  截图错误码

Accepted.FeedbackImages.ErrorCode

下载失败时的错误码：40020 为下载失败，40023 为超过 10 MB，50010 为平台存储失败；未发生错误时为 null。

ErrorMessage string / null  |  截图失败说明

Accepted.FeedbackImages.ErrorMessage

下载失败原因的英文说明，例如源站返回的 HTTP 状态码；未发生错误时为 null。

ErrorReason string / null  |  截图失败原因

Accepted.FeedbackImages.ErrorReason

下载失败时的细分原因，取值及处理方法见「截图下载失败原因」。没有失败或历史截图未记录此字段时为 null。

ExpiresAt string / null  |  链接过期时间

Accepted.FeedbackImages.ExpiresAt

Url 的过期时间，ISO 8601 UTC 格式；没有可用链接时为 null。

MediaKey string / null  |  内部媒资标识

Accepted.FeedbackImages.MediaKey

平台内部用于链接续签的标识，可忽略；可为 null。

MimeType string / null  |  图片类型

Accepted.FeedbackImages.MimeType

按文件实际内容识别的 MIME 类型，例如 image/png；尚未取得时为 null。

Status string  |  截图下载状态

Accepted.FeedbackImages.Status

  • ok：截图已保存，可使用 Url 查看。
  • pending：平台仍在下载。
  • failed：下载失败，查看 ErrorCode、ErrorReason 和 ErrorMessage。

此状态与 Accepted[].Status 的排查状态相互独立。

Url string / null  |  截图链接

Accepted.FeedbackImages.Url

截图的预签名链接，每次查询重新生成，有效期约 10 分钟。下载中或下载失败时为 null；过期后请重新调用本接口获取新链接。

ProblemLabel string  |  问题标签

Accepted.ProblemLabel

处理完成后返回的问题标签，由支持人员根据 Case 分析结果标注。Status 为 processing 时尚未产出，通常为空字符串。

SolutionNote object / null  |  解决方案

Accepted.SolutionNote

解决方案说明，包含文本说明和附件列表。Status 为 processing 时尚未产出，值为 null；处理完成后返回对象。

object object
Attachments object[] / null  |  解决方案附件列表，可为 null

Accepted.SolutionNote.Attachments

附件可为图片、视频或音频；链接每次查询都会重新生成，请从最新响应取得，不要长期保存。

Attachment[] object[]
Type string  |  文件类型

Accepted.SolutionNote.Attachments.Type

文件类型。可选值：image、video、audio。

Url string  |  文件链接

Accepted.SolutionNote.Attachments.Url

文件链接。读取时，TOS URL 会自动重新签名。

MimeType string / null  |  MIME 类型

Accepted.SolutionNote.Attachments.MimeType

多用途互联网邮件扩展类型（MIME Type），可为 null。

Name string / null  |  文件名称

Accepted.SolutionNote.Attachments.Name

文件名称，可为 null。

null null
Text string / null  |  解决方案说明文本，可为 null

Accepted.SolutionNote.Text

null null
SubmitTime string / null  |  提交时间

Accepted.SubmitTime

Badcase 的提交时间，ISO 8601 UTC 格式；未取得时间时可为 null。

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

未命中、不归属当前账号或未提交过 badcase 的 task_id 列表。

Code integer  |  错误码

Rejected.Code

未接受该 task_id 的业务错误码。

Message string  |  拒绝原因

Rejected.Message

未接受该 task_id 的原因说明。

TaskId string  |  任务 ID

Rejected.TaskId

未接受的 task_id。