You need to enable JavaScript to run this app.
文档中心
火山方舟

火山方舟

复制全文
下载 pdf
效果上报
查询 3D 生成效果问题结果
复制全文
下载 pdf
查询 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 时表示处理完成。截图的下载状态与排查状态相互独立。视频任务参见 查询视频生成模型效果问题结果。​
注意​
本接口及文档仅支持中国大陆火山方舟服务,不支持非中国大陆地区(如 BytePlus 等)。​
上报窗口与查询时机​
请先在 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 列表​
​
​
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 | 任务总数​
​
Accepted object[] | 已接受任务列表​
​
Rejected object[] | 未接受任务列表​
​
​

Request

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": []
  }
}
最近更新时间:2026.10.28 16:13:24
这个页面对您有帮助吗?
有用
有用
无用
无用