# 查询 3D 生成效果问题结果 > 全部文档的索引见 [llms.txt](https://ark.volcengine.com/llms.txt)；在任一文档页面地址后追加 `.md` 可获取该页的 Markdown 版本。 `POST https://prompt-pilot.cn-beijing.volces.com/case-platform?Action=CasePlatformV1BadcaseQuery&Version=2024-01-01` 本接口用于查询 Seed3D 2.0 生成效果问题的处理状态、问题标签、解决方案说明，以及上报时附带截图的保存结果。先通过 [上报 3D 生成效果问题](/docs/seed3d-badcase-report) 提交反馈，再使用生成任务的 `task_id` 查询。只能查询当前账号已上报的任务，支持通过 Access Key 或方舟 API Key 鉴权。 `Status` 为 `processing` 时表示排查中，为 `done` 时表示处理完成。截图的下载状态与排查状态相互独立。视频任务参见 [查询视频生成模型效果问题结果](/docs/case-platform-v1-badcase-query-api)。 > **注意** > > 本接口及文档仅支持中国大陆火山方舟服务，不支持非中国大陆地区（如 BytePlus 等）。 ### 上报窗口与查询时机 请先在 **7 天内**通过 [上报 3D 生成效果问题](/docs/seed3d-badcase-report) 提交火山方舟的 3D 任务反馈。上报接口需要根据 `task_id` 查询上游原始任务数据，因此有上报窗口。 7 天是上报窗口。本接口查询已上报 Case 的处理状态和结果。`Status` 为 `processing` 时，排查尚未完成，`ProblemLabel` 和 `SolutionNote` 尚未产出，请稍后再次查询；为 `done` 时，可读取处理结论。截图下载状态与排查状态相互独立。 ### 链接有效期 - `FeedbackImages[].Url` 为截图的预签名链接，有效期约 **10 分钟**，具体过期时间见 `ExpiresAt`。每次查询会重新生成链接，过期后请重新调用本接口。 - `SolutionNote.Attachments[].Url` 为解决方案附件链接，每次查询会重新签名。请使用最新响应中的链接，过期后重新查询。 以上是返回链接的有效期，不代表 Case 记录的保留期。 ### 请求头 使用方舟 API Key 时，设置 `Authorization: Bearer ` 和 `Content-Type: application/json`，账号身份从 API Key 解析。 使用 AK/SK 时，设置 V4 签名所需的 `Authorization`、`X-Date` 和 `X-Content-Sha256`，签名的 `Service` 为 `ark`、`Region` 为 `cn-beijing`。 ## 鉴权 本接口支持鉴权方式如下，详情请参见 [Base URL 及鉴权](/docs/base-url-and-authentication)。 * 【推荐】API Key 鉴权，请在 [API Key 管理](https://ark.volcengine.com/region:cn-beijing/apiKey) 页面，获取长效 API Key。 * 【可选】Access Key 鉴权，请在 [Access Key 管理](https://console.volcengine.com/iam/keymanage) 页面，获取 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`。 ## 代码示例 ## API Key 鉴权 ### cURL #### Request ```bash curl "https://prompt-pilot.cn-beijing.volces.com/case-platform?Action=CasePlatformV1BadcaseQuery&Version=2024-01-01" \ -H "Authorization: Bearer $ARK_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "Id": "cgt-20260501132104-tfm9v" }' ``` #### Response ``` { "ResponseMetadata": { "RequestId": "20261015081714000000000000000000", "Action": "CasePlatformV1BadcaseQuery", "Version": "2024-01-01", "Service": "ark", "Region": "cn-beijing" }, "Result": { "Total": 1, "Accepted": [ { "TaskId": "cgt-20260501132104-tfm9v", "BadcaseType": [], "Feedback": "生成的 glb 模型背面有破面，头发贴图错位到脸部。使用 Blender 4.2，从正后方观察。", "FeedbackImages": [ { "Url": "https://case-platform-files-cn-beijing.tos-cn-beijing.volces.com/.../back-view.png?X-Tos-Algorithm=...", "MimeType": "image/png", "Status": "ok", "ErrorCode": null, "ErrorReason": null, "ErrorMessage": null, "MediaKey": "...", "ExpiresAt": "2026-10-15T08:27:14Z" }, { "Url": null, "MimeType": null, "Status": "failed", "ErrorCode": 40020, "ErrorReason": "http_error", "ErrorMessage": "The image host responded with HTTP 404", "MediaKey": null, "ExpiresAt": null } ], "TimelineFeedbacks": [], "SubmitTime": "2026-10-15T07:19:22Z", "Status": "processing", "ProblemLabel": "", "SolutionNote": null } ], "Rejected": [] } } ``` ## Access Key 鉴权 ### cURL #### Request ```bash curl 'https://ark.cn-beijing.volcengineapi.com/?Action=CasePlatformV1BadcaseQuery&Version=2024-01-01' \ -H 'Content-Type: application/json' \ -H 'X-Date: ' \ -H 'X-Content-Sha256: ' \ -H 'Authorization: HMAC-SHA256 Credential=//cn-beijing/ark/request, SignedHeaders=content-type;host;x-content-sha256;x-date, Signature=' \ -d '{ "Id": "cgt-20260501132104-tfm9v" }' ``` #### Response ``` { "ResponseMetadata": { "RequestId": "20261015101714000000000000000000", "Action": "CasePlatformV1BadcaseQuery", "Version": "2024-01-01", "Service": "ark", "Region": "cn-beijing" }, "Result": { "Total": 1, "Accepted": [ { "TaskId": "cgt-20260501132104-tfm9v", "BadcaseType": [], "Feedback": "生成的 glb 模型背面有破面，头发贴图错位到脸部。使用 Blender 4.2，从正后方观察。", "FeedbackImages": [], "TimelineFeedbacks": [], "SubmitTime": "2026-10-15T07:19:22Z", "Status": "done", "ProblemLabel": "几何缺失", "SolutionNote": { "Text": "建议补充能完整展示背面轮廓的参考图后重新生成。", "Attachments": [ { "Type": "image", "Url": "https://case-platform-files-cn-beijing.tos-cn-beijing.volces.com/.../reference.png?X-Tos-Algorithm=...", "MimeType": "image/png", "Name": "reference.png" } ] } } ], "Rejected": [] } } ```