# 错误码与重试

错误响应包括 code、message、data 和 requestId。客户端同时检查 HTTP 状态与 code。

| code | HTTP 状态 | 处理方式 |
| --- | --- | --- |
| invalid_api_key | 401 | 检查 Key 是否正确、撤销、过期或账户不可用 |
| invalid_parameters | 400 | 按 message 修正请求参数 |
| VIP_MODEL_REQUIRED | 403 | 使用有权限的模型或开通会员 |
| api_key_quota_exceeded | 402 | API Key 剩余积分额度不足，在开发者页面提高额度或使用其他密钥 |
| budget_exceeded | 400 | 预计积分超过 max_credits，调整参数或预算 |
| insufficient_credits | 402 | 充值并核对提交结果后再操作 |
| not_found | 404 | 检查任务 ID、媒体类型和账户 |
| idempotency_conflict | 409 | 同一幂等键使用了不同参数 |
| LOCKED | 409 | 同一请求正在提交，稍后原样重试 |
| submission_uncertain | 409 | 保留原 Key 和 requestId 联系平台核实，避免重复生成 |
| generation_failed | 400/500 | 生成校验或提交失败，查看 message 和任务信息 |
| VIDEO_REFERENCE_LIMIT_EXCEEDED | 400 | 素材数量超过本模型上限 |
| UNSUPPORTED_VIDEO_REFERENCE_MEDIA | 400 | 模型不支持该参考媒体 |
| UNRESOLVED_VIDEO_REFERENCE | 400 | 提示词引用没有对应素材 |
| service_unavailable | 500/503 | 服务暂不可用，退避后使用原幂等键重试 |

## 请求超时

生成提交超时不代表未入队；使用相同 Key 和请求参数重试。已获得 task_id 时继续查询。任务查询超时不会重新生成或额外扣费。

## 文件与代理错误

文件超过 100 MiB 返回 413；代理限制、无效 JSON 等错误可能返回纯文本或 HTML，客户端应保留 HTTP 状态与响应原文。

## 积分核对

失败后的退款按平台任务处理结果执行。任务 credits 是原记录金额，不是退款状态；需要核查可提供 task_id 和 requestId。

## 调用示例

设置环境变量 DRAMAGEN_API_KEY（用户密钥）。Python 需要 requests，JavaScript 使用 Node.js 20+。

### cURL

```bash
curl --request GET "https://api.storymo.art/v1/models" \
  --header "Authorization: Bearer $DRAMAGEN_API_KEY"
```

### Python

```python
import os
import requests

api_origin = "https://api.storymo.art"
headers = {
  "Authorization": "Bearer YOUR_API_KEY"
}
headers["Authorization"] = "Bearer " + os.environ["DRAMAGEN_API_KEY"]
response = requests.request("GET", api_origin + "/v1/models", headers=headers, timeout=360)
response.raise_for_status()
result = response.json()
if result["code"] != "ok":
    raise RuntimeError(result)
print(result["data"])
```

### JavaScript

```javascript
const apiOrigin = "https://api.storymo.art";
const headers = {
  "Authorization": "Bearer YOUR_API_KEY"
};
headers.Authorization = `Bearer ${process.env.DRAMAGEN_API_KEY}`;
const response = await fetch(apiOrigin + "/v1/models", {
  method: "GET",
  headers,
});
const result = await response.json();
if (!response.ok || result.code !== "ok") throw new Error(JSON.stringify(result));
console.log(result.data);
```
