# 上报 3D 生成效果问题

> 全部文档的索引见 [llms.txt](https://ark.volcengine.com/llms.txt)；在任一文档页面地址后追加 `.md` 可获取该页的 Markdown 版本。

`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 生成效果问题结果](/docs/seed3d-badcase-query) 查看排查状态、结论及截图保存结果。视频任务参见 [上报视频生成模型效果问题](/docs/case-platform-v1-badcase-report-api)。

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

### 前提条件

- 任务使用 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 及鉴权](/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。

---

<span id="request-parameters"></span>
## 请求参数

### 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 生成效果问题结果](/docs/seed3d-badcase-query) 查看每张截图的下载状态和失败原因。

**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 生成效果问题结果](/docs/seed3d-badcase-query) 查看 `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`


## 代码示例

## API Key 鉴权

### cURL

#### Request

```bash
# 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": []
  }
}
```