公共参数与 storage

Base:https://<域名>/api/v1

鉴权:Authorization: Bearer <API_KEY>;JSON 请求加 Content-Type: application/json。

响应:{ "code": 1|0, "msg": "…", "data": … }。成功 code=1,失败 code=0 看 msg。

支持在 POST /tasks、POST /chat/completions、应用中心(ANY /apps/{app_code}/{api_code})等与业务 JSON 同级传下列公共字段;具体业务参数以各模型/应用文档为准。


一、公共参数

字段说明
model模型编码;POST /tasks 必填,/chat 必填
channel选填,渠道/线路,不传由平台解析
callback_url选填,异步终态时向该地址 POST JSON(POST /tasks、部分应用可传)
storage选填,见第二节;AK/SK 不落库,按任务短期缓存
stream选填,仅 /chat/completions 流式
smart_route选填,智能路由控制:on 强制进入编排,auto 按当前配置决策,off 关闭;仅已标记支持且绑定已发布策略的接口生效
params仅 POST /tasks 旧写法:有非空 params 对象时,仅其内为业务体;model 等仍在根级

应用请求里会去掉与路由同名的 app_code/api_code 和 callback_url,storage 也不参与与接口默认参数合并(解析后移除)。

智能路由参数(smart_route)

智能路由将多模型能力组织为可感知、可编排、可追溯的智能执行网络:当当前线路发生可降级故障时,平台按已发布策略在候选节点间继续尝试,并在节点切换时完成必要的参数适配;最终响应保持当前接口格式。仅文档或模型列表中标记为支持智能路由的接口可使用该参数。

值行为
on本次请求必须进入智能编排;接口不支持、未绑定已发布策略或策略不可执行时返回 smart_route_unavailable。
auto按当前租户与用户配置决定是否进入编排。
off本次请求关闭智能编排,沿用常规调用;若租户或用户已开启全局“智能路由”开关,则全局开关优先。

例如,在模型或应用 API 的业务 JSON 同级传入:

{
  "model": "your-model-code",
  "prompt": "生成一张产品海报",
  "smart_route": "on"
}

平台会在路由日志中记录每个节点的尝试、结果与失败分类,便于追溯实际执行路径。计费按最终成功节点对应的模型规则结算;所有候选节点均失败时,任务仍会失败。


二、用户相关查询接口

API说明
GET /tasks/{task_id}查询异步模型任务或异步应用任务的状态与结果;详见 [通用任务查询](api-task-query.md)。
GET /user/balance查询当前 API Key 对应用户余额/点数。
GET /user/usage查询当前 API Key 对应用户使用量。
GET /pricing查询模型 API 或应用 API 的当前有效价格规则。
POST /pricing/batch批量查询模型 API 或应用 API 的当前有效价格规则。

价格查询只返回规则与可读说明,不计算单次调用预计扣点;完整字段说明见仓库 [api-common-parameters.md](api-common-parameters.md)。


三、storage:对象转存

任务或对话产出媒体后,平台可拉取源 URL 再上传到你方桶。一次请求只能选一种云。传参两种写法(二选一):

  • 子对象:"storage": { "oss" | "cos" | "kodo": { … } }(三键只能有一个有内容)
  • 平铺:"storage": { "provider": "oss"|"cos"|"kodo"|"ftp", … }

主密钥可用多组键名(与代码 firstNonEmpty 一致),下表以常用名为主。


3.1 阿里云 OSS(oss / aliyun)

入参必填说明
bucket是桶名
access_key / access_key_id 等是访问主键(见上「别名」)
secret_key / access_key_secret 等是访问密钥
endpoint 或 domain 或 internal_endpoint是OSS 访问域名,如 oss-cn-hangzhou.aliyuncs.com(作为 SDK endpoint)
public_domain / cdn_domain / domain_url / url_domain否有则返回的 stored_url 以该域为基
path_rule / key_prefix / path否对象键,默认 ai-api/{date}/{task_id}_{index}.{ext},可含 {task_id} 等占位符

无 public_domain 时,默认 stored_url 形态:https://<bucket>.<endpoint>/<key>(有 endpoint 时)。


3.2 腾讯云 COS(cos / qcloud)

入参必填说明
bucket是桶名(含 appid 的桶名按 COS 要求)
access_key / secret_id 等是对应腾讯云 SecretId
secret_key 等是对应腾讯云 SecretKey
region是地域,如 ap-guangzhou(平台归一必须能取到 region)
public_domain / cdn_domain / domain_url / url_domain否对外访问基域,用于 stored_url
path_rule / key_prefix / path否同 OSS,默认与占位符一致

无 public_domain 时,默认 stored_url:https://<bucket>.cos.<region>.myqcloud.com/<key>(有 region 时)。


3.3 七牛 Kodo(kodo / qiniu)

入参必填说明
bucket是空间名(bucket)
access_key 等是AccessKey
secret_key 等是SecretKey
public_domain / cdn_domain / domain_url / url_domain强烈建议绑定域名/ CDN;不归一则 stored_url 可能无完整 http 前缀(仅 key)
path_rule / key_prefix / path否对象键,默认同前

转存用七牛 fetch 到指定空间/Key;无在配置校验里与 OSS 同级的「endpoint 必传」,但线上访问需你配置好域名或自行拼 URL。


3.4 响应中的 storage / storage_error

  • 转存成功且任务完成:可能多 data.storage(provider、bucket、files 含 stored_path、stored_url 等)。
  • 转存失败:可能多 data.storage_error(provider、code、message)。
  • 配置在本次请求解析阶段不通过:通常 code=0,以 msg 为准。

四、(仓库内备查)

更长的参数手册仍保留在仓库 [api-common-parameters.md](api-common-parameters.md),不在开发者中心菜单中单独展示;需要字段级全表时自行打开。

同类文章