> ## Documentation Index
> Fetch the complete documentation index at: https://docs.phanedge.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# 阿里百炼 API 调用

> 通过 phanedge 统一 OpenAI 与 Anthropic 兼容接口调用阿里百炼模型

本文面向平台开发者，说明阿里百炼北京站渠道在 phanedge 中暴露的 API 契约。开发者只需要使用 phanedge Token 和模型名；百炼 API Key、DashScope BaseURL、渠道路由和成本对账由平台管理员维护。

<Note>
  本文描述的是 phanedge 对外接口，不是阿里云控制台直连接口。默认服务地址示例为 `https://models.phanedge.cloud`，请替换为你的平台实际域名。
</Note>

## 读者范围

| 角色    | 需要关心                                       | 不需要关心                                            |
| ----- | ------------------------------------------ | ------------------------------------------------ |
| 平台开发者 | phanedge Token、模型名、对外路径、请求/响应格式、错误码和异步任务状态 | 阿里云控制台登录、百炼 API Key、DashScope 原生签名、渠道 `base_url` |
| 平台管理员 | 渠道 Key、模型权限、默认模型、价格、日志和消费对账                | 业务服务里的 SDK 代码                                    |
| 业务应用  | OpenAI SDK、Anthropic SDK 或 HTTP 请求         | 百炼账号区域、内部计费 SKU                                  |

<Warning>
  业务服务不要保存或透传阿里云百炼 API Key。平台开发者只使用 phanedge Token；百炼 Key 仅配置在后台渠道中。
</Warning>

## 开发者接入路径

| 步骤 | Action                       | Expected                                                         |
| -- | ---------------------------- | ---------------------------------------------------------------- |
| 1  | 从平台获取 phanedge 模型调用 Token    | 业务服务只保存 phanedge Token，不保存百炼 API Key                             |
| 2  | 调用 `GET $BASE_URL/v1/models` | 能看到目标模型，例如 `qwen3.7-plus`、`qwen3-vl-plus`、`wan2.7-t2v`           |
| 3  | 按 SDK 类型设置 `base_url`        | OpenAI SDK 填 `$BASE_URL/v1`；Anthropic SDK 填 `$BASE_URL`          |
| 4  | 先跑最小探针                       | model list、非流式 chat、流式 chat、Responses、Anthropic Messages 至少各成功一次 |
| 5  | 保存请求 ID                      | 记录 `X-Oneapi-Request-Id` 或错误体 `request_id`，便于平台排查和对账             |

## 认证

```bash theme={null}
export BASE_URL="https://models.phanedge.cloud"
export TOKEN="your-api-token"
```

所有接口统一使用 Bearer Token：

```http theme={null}
Authorization: Bearer $TOKEN
```

建议先调用模型列表确认当前 Token 可见模型：

```bash theme={null}
curl "$BASE_URL/v1/models" \
  -H "Authorization: Bearer $TOKEN"
```

## Base URL 与 SDK

| 调用方式                             | SDK `base_url`                     | 实际对外路径         | 说明                                                                         |
| -------------------------------- | ---------------------------------- | -------------- | -------------------------------------------------------------------------- |
| OpenAI SDK 文本/视觉/Embedding/图像/视频 | `https://models.phanedge.cloud/v1` | `/v1/...`      | 适合 `chat.completions`、`responses`、`embeddings`、`images` 以及支持自定义 HTTP 的视频任务 |
| Anthropic SDK                    | `https://models.phanedge.cloud`    | `/v1/messages` | Anthropic SDK 会拼接 `/v1/messages`，不要把 base URL 写成百炼 `/apps/anthropic`       |
| curl / 原始 HTTP                   | `https://models.phanedge.cloud`    | 手动填写完整路径       | 示例均以 `$BASE_URL/v1/...` 展示                                                 |

<Tip>
  如果你在业务侧把 `base_url` 写成 `https://dashscope.aliyuncs.com`，请求会绕过 phanedge，无法获得平台路由、统一计费、请求 ID、错误清洗和审计日志。
</Tip>

## 最小验收探针

| 能力                 | 请求                                                        | 通过标准                                                            |
| ------------------ | --------------------------------------------------------- | --------------------------------------------------------------- |
| 模型列表               | `GET $BASE_URL/v1/models`                                 | 返回 200，响应中包含计划使用的模型                                             |
| Chat 非流式           | `POST $BASE_URL/v1/chat/completions`，`stream=false` 或不传   | 返回一条完整 assistant 消息和 usage                                      |
| Chat 流式            | `POST $BASE_URL/v1/chat/completions`，`stream=true`        | 返回 SSE chunk，最终包含结束事件或完整收敛状态                                    |
| Responses          | `POST $BASE_URL/v1/responses`                             | 返回 OpenAI Responses 兼容对象；如启用缓存，usage 中保留缓存字段                    |
| Anthropic Messages | `POST $BASE_URL/v1/messages`                              | 返回 Anthropic Messages 兼容对象，业务侧 SDK 不需要知道百炼 `/apps/anthropic` 路径 |
| 图像/视频              | `POST $BASE_URL/v1/images/*` 或 `POST $BASE_URL/v1/videos` | 图像按成功张数返回；视频创建后需要继续查询终态                                         |

## 接口矩阵

| 能力                 | phanedge 接口                         | 百炼上游路径                                                                                                                                                | 说明                                    |
| ------------------ | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- |
| 模型列表               | `GET /v1/models`                    | `compatible-mode/v1/models`                                                                                                                           | 返回当前 Token 与渠道配置可见模型                  |
| Chat Completions   | `POST /v1/chat/completions`         | `compatible-mode/v1/chat/completions` 或 `/api/v1/services/aigc/text-generation/generation` / `/api/v1/services/aigc/multimodal-generation/generation` | 支持非流式、流式、文本和图像理解                      |
| Responses          | `POST /v1/responses`                | `compatible-mode/v1/responses`                                                                                                                        | 支持 OpenAI Responses 非流式与流式            |
| Anthropic Messages | `POST /v1/messages`                 | `/apps/anthropic/v1/messages`                                                                                                                         | 支持 Anthropic Messages 非流式、流式和官方高级字段透传 |
| Embeddings         | `POST /v1/embeddings`               | `/api/v1/services/embeddings/text-embedding/text-embedding`；OpenAI API 模式为 `compatible-mode/v1/embeddings`                                            | 文本向量                                  |
| 图像生成               | `POST /v1/images/generations`       | `/api/v1/services/aigc/multimodal-generation/generation`                                                                                              | 文生图，按成功图片数计费                          |
| 图像编辑               | `POST /v1/images/edits`             | `/api/v1/services/aigc/multimodal-generation/generation`                                                                                              | 改图，建议传公网可访问 URL                       |
| 视频创建               | `POST /v1/videos`                   | `/api/v1/services/aigc/video-generation/video-synthesis`                                                                                              | 文生视频、图生视频、参考视频、视频编辑                   |
| 视频查询               | `GET /v1/videos/{video_id}`         | `/api/v1/tasks/{task_id}`                                                                                                                             | 查询异步任务状态与结果 URL                       |
| 视频下载               | `GET /v1/videos/{video_id}/content` | 结果 URL 代理下载                                                                                                                                           | 完成后下载视频文件                             |

## 与百炼官方入口的关系

本文档中的 `phanedge 接口` 是平台开发者使用的稳定契约；`百炼上游路径` 只用于解释后台渠道如何转发和排障。业务代码不要直接拼接百炼上游路径，也不要把百炼 API Key 放入业务服务。

| 官方百炼能力                  | 百炼官方接入信息                                                                                      | phanedge 对外契约                                                           |
| ----------------------- | --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| OpenAI Chat Completions | 北京兼容端点为 `https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions`                  | 使用 `POST $BASE_URL/v1/chat/completions`，SDK `base_url` 填 `$BASE_URL/v1` |
| OpenAI Responses        | 北京兼容端点为 `https://dashscope.aliyuncs.com/compatible-mode/v1/responses`                         | 使用 `POST $BASE_URL/v1/responses`                                        |
| Anthropic Messages      | 北京兼容端点为 `https://dashscope.aliyuncs.com/apps/anthropic/v1/messages`                           | 使用 `POST $BASE_URL/v1/messages`，SDK `base_url` 填 `$BASE_URL`            |
| DashScope 原生文本          | `POST /api/v1/services/aigc/text-generation/generation`                                       | 业务侧仍使用 OpenAI Chat Completions 形态，平台按模型和输入自动选择上游协议                      |
| DashScope 原生多模态         | `POST /api/v1/services/aigc/multimodal-generation/generation`                                 | 图像理解、图像生成和图像编辑由平台转换为百炼原生多模态请求                                           |
| DashScope 视频任务          | `POST /api/v1/services/aigc/video-generation/video-synthesis` + `GET /api/v1/tasks/{task_id}` | 使用 `POST /v1/videos` 创建任务，使用 `GET /v1/videos/{video_id}` 查询终态           |

<Tip>
  百炼官方文档会按模型和地域更新参数。业务开发者优先遵循本页的 phanedge 对外契约；需要确认某个模型的上游特性时，再参考百炼官方文档并通过平台验收。
</Tip>

## 官方文档核对

以下链接用于解释 phanedge 后台为什么采用对应上游协议。平台开发者的业务代码仍以本页的 phanedge 对外契约为准。

| 主题                      | 官方文档                                                                                               |
| ----------------------- | -------------------------------------------------------------------------------------------------- |
| OpenAI Chat Completions | [OpenAI 兼容 Chat](https://help.aliyun.com/zh/model-studio/qwen-api-via-openai-chat-completions)     |
| OpenAI Responses        | [创建响应](https://help.aliyun.com/zh/model-studio/qwen-api-via-openai-responses)                      |
| Anthropic Messages      | [Anthropic 兼容 Messages](https://help.aliyun.com/zh/model-studio/anthropic-api-messages)            |
| DashScope 文本与多模态        | [DashScope API 参考](https://help.aliyun.com/zh/model-studio/qwen-api-via-dashscope)                 |
| 万相 2.7 文生视频             | [万相 2.7 文生视频 API 参考](https://help.aliyun.com/zh/model-studio/text-to-video-api-reference)          |
| 万相 2.7 图生视频             | [万相 2.7 图生视频 API 参考](https://help.aliyun.com/zh/model-studio/image-to-video-general-api-reference) |
| 上下文缓存                   | [上下文缓存 Context Cache](https://help.aliyun.com/zh/model-studio/context-cache)                       |
| 显式缓存实践                  | [百炼显式缓存最佳实践](https://help.aliyun.com/zh/model-studio/explicit-cache-best-practice)                 |

最后核查日期：2026-06-15。

## 平台开发者契约

| 项目    | 约定                                                                     |
| ----- | ---------------------------------------------------------------------- |
| 服务地址  | 使用平台域名，例如 `https://models.phanedge.cloud`；SDK `base_url` 通常填写到 `/v1`   |
| 认证    | 只使用 phanedge Token；不要在业务服务中保存阿里云百炼 API Key                             |
| 模型名   | 请求体里的 `model` 使用平台公开模型名，例如 `qwen3.7-plus`、`qwen3-vl-plus`、`wan2.7-t2v` |
| 可见性   | 以 `GET /v1/models` 返回为准；模型可能因 Token 权限、渠道模型配置或百炼账号权益不可见                |
| 区域    | 当前文档只描述北京站渠道；不要把国际站 workspace endpoint 或 Key 混入北京站渠道                   |
| 请求 ID | 平台会返回 `X-Oneapi-Request-Id` 和错误体里的 `error.request_id`，排查工单优先提供该 ID     |
| 计费    | 文本/视觉/Embedding 按 token 计量；图片按成功图片张数；视频按成功输出秒数与分辨率档位                   |
| 上游透传  | 百炼上游错误会保留可读语义，但平台会清理密钥、内部 URL 等敏感信息                                    |

## Usage 与缓存计费字段

文本、视觉理解和 Embedding 响应会尽量保留 OpenAI 兼容 usage 字段。百炼缓存相关字段主要影响输入 token 的计费方式，开发者可以把它们用于成本解释和对账，不应自行按这些字段扣费。

| 字段                                                  | 出现位置                          | 含义                        | 平台计费语义                     |
| --------------------------------------------------- | ----------------------------- | ------------------------- | -------------------------- |
| `prompt_tokens` / `input_tokens`                    | OpenAI 兼容或 DashScope 原生 usage | 输入 token 总量               | 基础输入 token                 |
| `completion_tokens` / `output_tokens`               | OpenAI 兼容或 DashScope 原生 usage | 输出 token 总量               | 基础输出 token                 |
| `prompt_tokens_details.cached_tokens`               | OpenAI 兼容 usage               | 命中缓存的输入 token             | 按模型缓存命中比例折算，显式缓存命中通常低于隐式缓存 |
| `prompt_tokens_details.cache_creation_input_tokens` | OpenAI 兼容 usage               | 本次新创建显式缓存的 token          | 按显式缓存写入比例折算，通常高于标准输入价      |
| `usage.cache_read_input_tokens`                     | Anthropic Messages usage      | Anthropic 兼容入口命中缓存的 token | 按百炼 Anthropic 缓存命中规则折算     |
| `usage.cache_creation_input_tokens`                 | Anthropic Messages usage      | Anthropic 兼容入口创建缓存的 token | 按显式缓存写入比例折算                |

<Warning>
  缓存字段是上游返回的用量信号。最终消费以平台日志和账单为准；如果响应 usage 与消费记录不一致，请带上 `X-Oneapi-Request-Id` 或错误体中的 `request_id` 排查。
</Warning>

## 协议兼容边界

| 协议                      | 当前支持                                                                                                                       | 需要单独验收                                  |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
| OpenAI Chat Completions | 文本、流式、图像理解输入、基础 usage                                                                                                      | 模型专属工具调用细节、超长上下文、特殊采样参数                 |
| OpenAI Responses        | 非流式、流式、文本 input 形态                                                                                                         | 复杂工具、文件输入、Responses 高级内置工具              |
| Anthropic Messages      | 非流式、流式、`anthropic-version` / `anthropic-beta` header 透传、thinking、tool、图片/视频理解、`cache_control` 字段透传和 Anthropic usage 缓存字段映射 | 复杂 tool 结果、多轮 thinking、媒体输入与缓存组合的真实上游抽样 |
| DashScope 原生文本/多模态      | 由渠道内部转换，开发者仍使用 OpenAI 形态                                                                                                   | 直接发送 DashScope 原生请求体                    |
| 图像                      | 文生图、改图、URL 或 base64 结果转换                                                                                                   | 本地文件直传、不可公网访问图片 URL                     |
| 视频                      | 创建、查询、下载、参考图片/视频映射                                                                                                         | 上游未开通模型、过期结果 URL 续期                     |

<Warning>
  本页描述的是 phanedge 对外 API 契约。不要把 DashScope 原生请求体直接发送到 phanedge，除非对应字段已经在本文或通用 OpenAI/Claude 文档中声明。
</Warning>

## SDK 接入

### OpenAI SDK

```python theme={null}
from openai import OpenAI

client = OpenAI(
    api_key="your-api-token",
    base_url="https://models.phanedge.cloud/v1",
)

resp = client.chat.completions.create(
    model="qwen3.7-plus",
    messages=[{"role": "user", "content": "用一句话说明百炼接入方式。"}],
)

print(resp.choices[0].message.content)
```

Responses、Embeddings、Images 和 Videos 入口也使用同一个 `base_url` 与 Token。不同 SDK 对非官方视频扩展字段的支持不完全一致；如果 SDK 类型不接受扩展字段，可以改用原始 HTTP 请求。

### Anthropic SDK

```python theme={null}
import anthropic

client = anthropic.Anthropic(
    api_key="your-api-token",
    base_url="https://models.phanedge.cloud",
)

message = client.messages.create(
    model="qwen3.7-plus",
    max_tokens=1024,
    messages=[{"role": "user", "content": "用 Anthropic Messages 格式回复一句话。"}],
)

print(message.content[0].text)
```

百炼 Anthropic 入口会透传 `anthropic-version`、`anthropic-beta`、thinking、tool、媒体输入和 `cache_control` 等 Messages 字段，并保留上游返回的缓存 usage 字段。复杂 tool 结果、多轮 thinking、媒体输入与缓存组合仍建议按模型做真实上游抽样。

## Chat Completions

### 非流式

```bash theme={null}
curl -X POST "$BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.7-plus",
    "messages": [
      {"role": "system", "content": "你是一个简洁的中文助手。"},
      {"role": "user", "content": "给我三个 API 接入验收点。"}
    ]
  }'
```

### 流式

```bash theme={null}
curl -N -X POST "$BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.7-plus",
    "stream": true,
    "messages": [
      {"role": "user", "content": "用 30 字说明统一网关的价值。"}
    ]
  }'
```

### 图像理解

```bash theme={null}
curl -X POST "$BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3-vl-plus",
    "messages": [
      {
        "role": "user",
        "content": [
          {"type": "text", "text": "描述这张图片的主体和风格。"},
          {"type": "image_url", "image_url": {"url": "https://example.com/image.jpg"}}
        ]
      }
    ]
  }'
```

## Responses

```bash theme={null}
curl -X POST "$BASE_URL/v1/responses" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.7-plus",
    "input": [
      {
        "role": "user",
        "content": [
          {"type": "input_text", "text": "把这段需求整理成验收标准。"}
        ]
      }
    ]
  }'
```

流式调用时加入 `"stream": true`。

## Anthropic Messages

```bash theme={null}
curl -X POST "$BASE_URL/v1/messages" \
  -H "Authorization: Bearer $TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.7-plus",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "用 Anthropic Messages 格式返回一句问候。"}
    ]
  }'
```

<Warning>
  该入口透传 Anthropic Messages 字段，但最终可用性仍取决于百炼账号权限和具体模型。涉及 thinking、tool、媒体输入与缓存组合时，请保留请求 ID 并按模型抽样验收。
</Warning>

## Embeddings

```bash theme={null}
curl -X POST "$BASE_URL/v1/embeddings" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-v4",
    "input": ["阿里百炼模型接入", "统一网关与计费"]
  }'
```

## 图像生成

```bash theme={null}
curl -X POST "$BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-2.0-pro",
    "prompt": "干净的 SaaS 控制台产品宣传图，真实屏幕，浅色背景",
    "size": "1024x1024",
    "response_format": "url",
    "n": 1
  }'
```

百炼图像结果支持 `url` 与 `b64_json`。当请求 `b64_json` 但上游只返回 URL 时，平台会尝试下载结果并转成 base64。

## 图像编辑

```bash theme={null}
curl -X POST "$BASE_URL/v1/images/edits" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-edit-plus",
    "prompt": "保持主体不变，替换为干净的电商白底图",
    "images": [
      {"image_url": "https://example.com/product.png"}
    ],
    "size": "1024x1024",
    "response_format": "url",
    "n": 1
  }'
```

## 视频生成

百炼视频为异步任务。创建任务返回 `video_id` 后，需要查询任务状态，完成后再下载文件。

<Note>
  HappyHorse 1.1 系列包含 `happyhorse-1.1-t2v`、`happyhorse-1.1-i2v` 和 `happyhorse-1.1-r2v`。官方参数默认 `1080P`，国内默认价为 720P ￥0.90 / 秒、1080P ￥1.20 / 秒；如需按 720P 成本生成，请显式传入 `"resolution": "720p"`。
</Note>

<Note>
  如果模型支持固定随机种子，请将 `seed` 作为 JSON 数字传入，例如 `"seed": 12345`。不要传字符串形式的 `"12345"`；平台会拒绝非数字或超出 `0-2147483647` 范围的 `seed`。
</Note>

### 文生视频

```bash theme={null}
curl -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.7-t2v",
    "prompt": "城市夜景中的新能源车广告片，电影感镜头，平稳推进",
    "seconds": 5,
    "resolution": "720p"
  }'
```

### 图生视频

```bash theme={null}
curl -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.7-i2v",
    "prompt": "让画面中的人物自然转身微笑，镜头轻微推进",
    "input_reference": {"image_url": "https://example.com/first-frame.jpg"},
    "seconds": 5,
    "resolution": "720p"
  }'
```

### 参考视频生成

```bash theme={null}
curl -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.7-r2v",
    "prompt": "参考视频运动节奏，生成同风格产品展示短片",
    "references": {
      "video": ["https://example.com/reference.mp4"]
    },
    "input_reference": {"image_url": "https://example.com/product.png"},
    "seconds": 5,
    "resolution": "720p"
  }'
```

### 查询与下载

```bash theme={null}
curl "$BASE_URL/v1/videos/$VIDEO_ID" \
  -H "Authorization: Bearer $TOKEN"
```

任务成功后通常返回 `completed`，结果 URL 会带 `expires_at` 过期信号。客户端也建议兼容本地异步任务口径中的 `success`。

```bash theme={null}
curl -L "$BASE_URL/v1/videos/$VIDEO_ID/content" \
  -H "Authorization: Bearer $TOKEN" \
  --output "$VIDEO_ID.mp4"
```

### 异步任务状态

| 平台状态                                    | 含义              | 客户端建议                               |
| --------------------------------------- | --------------- | ----------------------------------- |
| `queued` / `in_progress` / `processing` | 任务已创建或正在执行      | 继续轮询，建议指数退避                         |
| `completed` / `success`                 | 任务成功，通常包含结果 URL | 可以调用下载接口或读取结果 URL                   |
| `failed`                                | 上游任务失败          | 记录 `video_id`、`request_id` 和错误信息后排查 |
| `cancelled`                             | 任务取消或上游未继续执行    | 视业务需要重新创建任务                         |

视频任务创建阶段只代表上游接受任务，不代表最终成功。对账和扣费应以终态成功结果为准。

## 视频参考输入规则

| 模型类型                        | 推荐字段                                                              | 平台映射到百炼                                                        |
| --------------------------- | ----------------------------------------------------------------- | -------------------------------------------------------------- |
| `happyhorse-1.1-i2v`        | `input_reference` 或 `input_image`，仅单张首帧图                          | `input.media[].type=first_frame`                               |
| `happyhorse-1.1-r2v`        | `input_reference` 图片 URL 或图片对象数组，建议 1-9 张参考图                      | `input.media[].type=reference_image`                           |
| `happyhorse-1.0-i2v`        | `input_reference` 或 `input_image`                                 | 原生 `img_url`                                                   |
| `happyhorse-1.0-r2v`        | `input_reference` 图片 URL；公开 JSON 示例优先使用 `{"image_url": "..."}` 对象 | `input.media[].type=reference_image`                           |
| `wan2.7-i2v`                | `input_reference` 图片或视频 URL                                       | 第一项视频映射为 `first_clip`，图片映射为 `first_frame`，后续图片映射为 `last_frame` |
| `wan2.7-r2v`                | `references.video[]` + 可选 `input_reference` 图片对象                  | 视频映射为 `reference_video`，图片映射为 `reference_image`                |
| `happyhorse-1.0-video-edit` | 图片 `input_reference` 或 `references.video[]`                       | 图片输入兼容 `img_url`；`references.video[]` 映射为 `reference_video`    |
| `wan2.7-videoedit`          | `references.video[]` + 可选图片 `input_reference` 对象                  | 源视频映射为 `video`，图片映射为 `reference_image`                         |

<Tip>
  参考素材 URL 需要能被百炼上游访问。视频 URL 建议使用 `.mp4` 或 `.mov` 后缀；图片 URL 建议使用公开 HTTPS 地址。
</Tip>

## 失败与排查

| 现象                          | 建议处理                                           |
| --------------------------- | ---------------------------------------------- |
| `model_not_found` 或模型不可见    | 先调用 `GET /v1/models`，确认 Token 权限、渠道模型配置和百炼账号权益 |
| 百炼上游返回权限错误                  | 联系平台管理员检查百炼模型开通、API Key 权限和账号额度                |
| 图像编辑无产物                     | 确认 `images[].image_url` 可公网访问，并且模型属于图像编辑分类     |
| 视频创建返回 `invalid_duration`   | 百炼视频当前支持 2-15 秒；HappyHorse 系列最短 3 秒            |
| 视频创建返回 `invalid_resolution` | 百炼视频当前只接受 `720p` 或 `1080p`                     |
| 视频下载返回未就绪                   | 先查询任务状态，等待 `completed` 后再下载                    |

错误响应遵循平台统一格式，常见字段如下：

```json theme={null}
{
  "error": {
    "message": "model not found (request id: 20260615120000abcdef)",
    "type": "invalid_request_error",
    "code": "model_not_found",
    "request_id": "20260615120000abcdef",
    "upstream_request_id": "dashscope-request-id"
  }
}
```

更多错误格式、请求 ID 和对账说明请参考 [错误处理](/guide/errors)、[请求 ID](/guide/request-id) 与 [账单对账](/guide/billing-reconciliation)。