主题模式

图像生成 API - 供应商调度参数说明 ​

图像生成 API 中的 extra_body.provider 参数支持供应商选择、过滤和排序等调度功能。

参数概览 ​

provider 对象包含两类参数：

  1. 图像生成特有参数：仅用于图像生成 API
  2. 供应商调度参数：与其他 API 接口（如 Chat、Embedding、Reranker）通用

图像生成特有参数 ​

参数名类型必填默认值说明
enable_image_base64bool否false是否在响应数据的 data 字段中同时返回图像的 Base64 编码。设置为 true 时，响应中的每个图像对象会包含 b64_json 字段
enable_image_origin_databool否false是否在响应中包含原始响应数据。设置为 true 时，响应中会包含 origin_data 字段，包含供应商 API 的完整原始响应

供应商调度参数 ​

以下参数与其他 API 接口通用，用于控制供应商的选择、过滤和排序策略：

供应商选择 ​

参数名类型必填默认值说明
onlyarray否[]白名单；仅在该集合内挑选供应商
ignorearray否[]黑名单；从候选中排除
orderarray否[]供应商排序，优先级按顺序降低

排序策略 ​

参数名类型必填默认值说明
sortstring/array否-排序策略，支持以下值：
- output_price：输出价格优先
- latency：延迟优先

支持多关键字排序，优先级按顺序降低。例如：["output_price", "latency"] 表示优先考虑输出价格，在价格相同的情况下选择延迟更低的供应商

范围过滤 ​

参数名类型必填默认值说明
output_price_rangearray否[]限制输出价格范围，单位：¥ / 张
latency_rangearray否[]限制延迟范围，单位：s，基于实时的延迟数据调度

其他控制参数 ​

参数名类型必填默认值说明
allow_fallbacksbool否true是否允许降级。当主供应商不可用时，是否尝试其他供应商。设置为 false 时，如果按照指定筛选策略无法找到合适的供应商，将直接返回错误

策略应用顺序 ​

调度策略的应用顺序为：

  1. only（白名单筛选）
  2. ignore（黑名单排除）
  3. 各种范围过滤（价格、延迟）
  4. order（供应商排序）
  5. sort（排序策略）

详细文档 ​

关于供应商调度参数的详细说明、使用示例和最佳实践，请参考：

使用示例 ​

示例 1：使用白名单和排序策略 ​

json
{
  "model": "Doubao-Seedream-4.0",
  "input": {
    "prompt": "一只可爱的猫咪在花园里玩耍"
  },
  "extra_body": {
    "provider": {
      "only": ["火山方舟"],
      "sort": ["output_price", "latency"],
      "enable_image_base64": false,
      "enable_image_origin_data": true
    }
  }
}

示例 2：使用价格范围过滤 ​

json
{
  "model": "Doubao-Seedream-4.0",
  "input": {
    "prompt": "美丽的日落景色"
  },
  "extra_body": {
    "provider": {
      "output_price_range": [0, 5],
      "sort": "output_price",
      "enable_image_base64": true,
      "enable_image_origin_data": true
    }
  }
}

示例 3：使用延迟过滤 ​

json
{
  "model": "Doubao-Seedream-4.0",
  "input": {
    "prompt": "现代城市建筑"
  },
  "extra_body": {
    "provider": {
      "latency_range": [0, 5],
      "sort": "latency",
      "allow_fallbacks": false,
      "enable_image_base64": false,
      "enable_image_origin_data": false
    }
  }
}

示例 4：仅使用图像特有参数 ​

json
{
  "model": "Doubao-Seedream-4.0",
  "input": {
    "prompt": "抽象艺术画"
  },
  "extra_body": {
    "provider": {
      "enable_image_base64": true,
      "enable_image_origin_data": true
    }
  }
}

注意事项 ​

  1. 参数冲突：only 与 ignore 不可交叉包含相同供应商，否则将返回 422 错误
  2. 指标依赖：范围过滤和排序策略依赖实时指标（时延、价格）；无指标时可能跳过范围过滤或降级排序
  3. 失败重试：当 allow_fallbacks 为 true 时，如果按照指定筛选策略无法找到合适的供应商，系统会自动按照排序策略尝试其他供应商，最多重试两次
  4. 供应商列表：供应商名称列表见 https://aiping.cn/supplierList，使用时大小写敏感