文档中心

火山方舟

效果上报

上报 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 生成效果问题结果查看排查状态、结论及截图保存结果。视频任务参见上报视频生成模型效果问题。

注意

本接口及文档仅支持中国大陆火山方舟服务，不支持非中国大陆地区（如 BytePlus 等）。

前提条件

任务使用 Seed3D 2.0，已成功完成并产出 3D 模型。

任务须在 7 天内上报。本接口根据 task_id 向上游查询原始任务数据，超过上报窗口后可能无法读取。请在生成完成后尽早提交。

凭证与任务属于同一火山引擎账号。

每个任务只能上报一次，请在提交前准备完整的描述和截图。

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

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

请求头

使用方舟 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 必选 | 问题描述

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

AccountId string | 火山引擎账号 ID

ContactInfo string | 联系方式

FeedbackImages object[] | 问题截图

错误码

请求级错误位于 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

Total integer | 提交总数

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

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

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

API Key 鉴权

Request

# Use an Ark API Key from the account that owns these completed Seed3D 2.0 tasks.
# Replace task IDs, public HTTPS screenshot URLs, and contact information.
curl 'https://prompt-pilot.cn-beijing.volces.com/case-platform?Action=CasePlatformV1BadcaseReport&Version=2024-01-01' \
  -H "Authorization: Bearer $ARK_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "Id": ["<TASK_ID_1>", "<TASK_ID_2>"],
    "Feedback": "输入正面人物参考图后，生成的 glb 模型背面出现破面，头发贴图错位到脸部。在 Blender 中使用默认光照，从正后方观察可复现。",
    "FeedbackImages": [
      {"Url": "<SCREENSHOT_URL_1>"},
      {"Url": "<SCREENSHOT_URL_2>"}
    ],
    "ContactInfo": "<CONTACT_INFO>"
  }'

Response

{
  "ResponseMetadata": {
    "RequestId": "2026101512000000000000000000000000",
    "Action": "CasePlatformV1BadcaseReport",
    "Version": "2024-01-01",
    "Service": "case-platform",
    "Region": "cn-beijing",
    "Error": null
  },
  "Result": {
    "SubmissionId": "badcase-sub-6f1c2a9e-0b7d-4c3e-9a1f-2d5e8b7c4a10",
    "Total": 2,
    "Accepted": [
      {
        "TaskId": "<TASK_ID_1>",
        "CaseId": "instance-3b9d2f8a-5c1e-4d7b-8e2a-1f6c9a0b4d3e",
        "Code": 0,
        "Message": "Success"
      }
    ],
    "Rejected": [
      {
        "TaskId": "<TASK_ID_2>",
        "Code": 40003,
        "Message": "task_id 已经提交过 badcase"
      }
    ],
    "RejectedTimelineFeedbacks": []
  }
}

最近更新时间：2026.10.28 22:45:06

这个页面对您有帮助吗？

有用

无用