# 标签增强
> 把简短的风格标签扩写成更丰富的组合，异步任务
> 结果在 `data.result.upsampled_tags`
> 扩写后的标签可直接喂给「生成音乐」
`POST /v1/music/generations/upsampleTags`
## 认证
- `Authorization` (string / 必填) — 所有接口均使用 Bearer Token 进行认证。 获取 API Key：[访问控制台](https://api.oairoute.com/keys) 创建。 请求时在请求头中添加： ```http Authorization: Bearer YOUR_OAIRoute_KEY ```
## 请求参数
- `model` (string / 可选) — 音频模型，当前只支持 `suno`，不传时也默认 `suno`。
- `tags` (string / 必填) — 待增强的风格标签，例如 `pop`。 缺失时提交阶段直接返回 400，且不扣费。
> **Note:** 
> 本端点没有版本维度。传 `version` 会被丢弃，且不影响计费。
## 响应
- `code` (integer) — 响应状态码，成功为 200。
- `data[].status` (string) — 任务状态，提交后为 `submitted`。
- `data[].task_id` (string) — 任务唯一标识，用于轮询。
## 取结果
用 `GET /v1/music/tasks/{task_id}` 查询，增强后的标签在 `data.result.upsampled_tags`。
> **Note:** 
> 提交成功只代表任务已被受理。增强结果**必须**通过查询接口取回，不能指望提交响应里直接带。
## 为什么需要这一步
风格标签写得太短，模型能发挥的空间反而小。比如只写 `pop`，生成结果可能偏任何一种流行乐。扩写成 `pop, female vocal, bright piano, 120 bpm, radio-ready` 之后，方向就明确得多。
典型用法是把它当成「先把想法写具体」的助手：
1. 你有模糊的方向，写一个词
2. 调本接口扩写
3. 把扩写结果粘进「生成音乐」的 `tags` 或 `style`
## 什么时候不用它
如果你已经能写出三个以上的具体标签，直接生成就行，不用多这一步。这个接口的价值在于「把模糊变具体」，不是「把具体变更多」。
| 情况 | 建议 |
|---|---|
| 只想到一个词 | 先扩写 |
| 已能写 3 到 5 个标签 | 直接用 |
| 想要特定风格 | 直接写，别让模型猜 |
> **Note:** 
> 扩写结果不一定完全符合你的意图，加了太多你没想到的元素是常见情况。拿到结果后先看一眼，把不想要的标签删掉再用于生成。
## 错误码
错误响应的格式、状态码与重试建议见[错误码与限流](../../../support/errors.html)，常见报错的排查步骤见[常见问题](../../../support/faq.html)。
## 使用示例
提交一个任务并拿到 `task_id`：
> **Note:** 
> 提交成功只表示任务已受理。真正的产物要拿返回的 `task_id` 去任务查询接口轮询，`status` 变成 `completed` 之后才有结果。
**标签增强{Enhance tags}::cURL**
```
curl --request POST \
  --url 'https://api.oairoute.com/v1/music/generations/upsampleTags' \
  --header 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "suno",
    "tags": "pop"
  }'
```
**标签增强{Enhance tags}::Python**
```
import requests
res = requests.post(
    "https://api.oairoute.com/v1/music/generations/upsampleTags",
    headers={
        "Authorization": "Bearer YOUR_OAIRoute_KEY",
        "Content-Type": "application/json",
    },
    json={"model": "suno", "tags": "pop"},
)
print(res.json()["data"][0]["task_id"])
```
**标签增强{Enhance tags}::JavaScript**
```
const url = "https://api.oairoute.com/v1/music/generations/upsampleTags";
const options = {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "model": "suno",
    "tags": "pop"
  }),
};
fetch(url, options)
  .then((res) => res.json())
  .then((json) => console.log(json))
  .catch((err) => console.error(err));
```
**200 标签增强{Enhance tags}**
```
{
  "code": 200,
  "data": {
    "id": "task_01K8C55M0HP1GJWBJYZMKX1XS1",
    "status": "completed",
    "progress": 100,
    "created": 1763088289,
    "completed": 1763088303,
    "actual_time": 14,
    "cost": 0.006,
    "credits_cost": 0.06,
    "result": {
      "upsampled_tags": "pop, female vocal, bright piano, uplifting, 120 bpm, radio-ready production"
    }
  }
}
```