OpenAPI 接入说明

DAMODEL OpenAPI 允许您通过 API Key 管理账号下的云资源。本文档主要介绍规格查询、实例、云磁盘和镜像管理接口。

配置	值
API 地址	`https://www.damodel.com`
API Key	前往控制台 - 管理 - API 密钥创建
请求格式	`application/json`
时间戳	Unix 秒级时间戳

需重点关注

API Key 具有账号资源操作权限，请仅在服务端保存和使用，不要放入网页、客户端安装包、公开代码仓库或日志中。

鉴权方式

每次请求都必须携带以下两个 HTTP Header：

Header	必填	说明
`X-Damodel-Token`	是	控制台创建的 API Key，直接填写，不要添加 `Bearer` 前缀
`X-Damodel-Timestamp`	是	发起请求时的 Unix 秒级时间戳，与服务端时间偏差不能超过 300 秒

示例：

shell

export DAMODEL_API="https://www.damodel.com"
export DAMODEL_TOKEN="sk-your-api-key"

curl "$DAMODEL_API/api/spec/list?region=cn-north-a" \
  -H "X-Damodel-Token: $DAMODEL_TOKEN" \
  -H "X-Damodel-Timestamp: $(date +%s)"

需关注

X-Damodel-Timestamp 必须在每次请求前重新生成。不要传毫秒时间戳，也不要复用超过 5 分钟的时间戳。

如果请求同时携带 Authorization 和非空的 X-Damodel-Token，服务端会优先使用 X-Damodel-Token；API Key 鉴权失败时不会回退到 Authorization。

Python 请求示例

python

import os
import time
import requests

BASE_URL = "https://www.damodel.com"
API_KEY = os.environ["DAMODEL_TOKEN"]


def headers():
    return {
        "X-Damodel-Token": API_KEY,
        "X-Damodel-Timestamp": str(int(time.time())),
        "Content-Type": "application/json",
    }


response = requests.get(
    f"{BASE_URL}/api/spec/list",
    params={"region": "cn-north-a"},
    headers=headers(),
    timeout=30,
)
response.raise_for_status()
print(response.json())

通用响应格式

所有 JSON 接口都使用统一响应结构。请求成功时，response_metadata.error 为 null，业务数据位于 result。

json

{
  "result": {},
  "response_metadata": {
    "request_id": "afcb17f1-1b9e-42dd-9e7d-78c4482f49d2",
    "trace_id": "65ea5d78bdaf4a88b064cf8f58f590bc",
    "action": "",
    "version": "",
    "service": "",
    "error": null
  }
}

请求失败时，result 通常为 null，错误信息位于 response_metadata.error。

json

{
  "result": null,
  "response_metadata": {
    "request_id": "afcb17f1-1b9e-42dd-9e7d-78c4482f49d2",
    "trace_id": "65ea5d78bdaf4a88b064cf8f58f590bc",
    "action": "",
    "version": "",
    "service": "",
    "error": {
      "code_n": 100002,
      "code": "InvalidParameter",
      "message": "InvalidParameter: invalid request",
      "description": "参数错误"
    }
  }
}

字段	说明
`result`	接口业务数据；无返回数据或失败时通常为 `null`
`request_id`	请求编号，向客服或技术支持反馈问题时请提供
`trace_id`	链路追踪编号，排查跨服务问题时使用
`error.code_n`	数字错误码，程序应优先根据此字段判断错误
`error.code`	英文错误名称
`error.message`	本次请求的详细错误信息
`error.description`	面向用户的中文错误说明

HTTP 状态码和通用错误

不要只根据 HTTP 状态码判断业务结果；收到非 2xx 响应时，还应读取 response_metadata.error.code_n。

HTTP 状态码	`code_n`	`code`	说明
400	100002	`InvalidParameter`	缺少必填参数、参数格式或取值不正确
401	100006	`InvalidToken`	API Key 不存在、已删除、账号不可用，或时间戳缺失/过期
400	100042	`PermissionDenied`	API Key 所属子账号没有调用该接口的权限
429	100015	`TooManyRequests`	请求频率过高
500	100014	`InternalError`	服务内部错误，请保留 `request_id` 和 `trace_id` 后重试或联系技术支持

权限和资源归属

API Key 继承创建者当前的账号身份和权限。
主账号 API Key 可以操作主账号资源。
子账号 API Key 只能操作该子账号有权限访问的资源，计费仍归属主账号。
API Key 被删除、创建者被禁用或主账号被禁用后，后续请求会立即失败。

接口导航

分类	文档	主要接口
规格	规格查询	实例规格、云磁盘规格
实例	实例管理	创建、列表、详情、重命名、释放
云磁盘	云磁盘管理	创建、列表、重命名、扩容、释放
镜像	镜像管理	公共镜像、私有镜像、保存、重命名、删除

调用建议

创建资源前先调用规格和镜像查询接口，不要在程序中长期硬编码规格 ID 或镜像 ID。
创建、保存镜像等操作可能异步完成，请通过对应列表或详情接口轮询最终状态。
对创建、扩容、释放和删除等非幂等操作谨慎重试。网络超时时，应先查询资源状态再决定是否重试。
对 429 和临时性 500 错误使用指数退避；对参数、权限和余额错误不要自动重试。

OpenAPI 接入说明 ​

鉴权方式 ​

Python 请求示例 ​

通用响应格式 ​

HTTP 状态码和通用错误 ​

权限和资源归属 ​

接口导航 ​

调用建议 ​