主题模式

图像生成 API - 服务商调度参数说明 ​

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

请求格式 ​

图像生成 API 支持 OpenAI 标准格式（推荐），同时也支持嵌套格式。嵌套格式的详细说明请参见文档末尾。

参数概览 ​

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",
  "prompt": "一只可爱的猫咪在花园里玩耍",
  "provider": {
    "only": ["火山方舟"],
    "sort": ["output_price", "latency"],
    "enable_image_base64": false,
    "enable_image_origin_data": true
  }
}

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

json
{
  "model": "Doubao-Seedream-4.0",
  "prompt": "美丽的日落景色",
  "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",
  "prompt": "现代城市建筑",
  "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",
  "prompt": "抽象艺术画",
  "provider": {
    "enable_image_base64": true,
    "enable_image_origin_data": true
  }
}

示例 5：完整参数示例 ​

json
{
  "model": "Doubao-Seedream-4.0",
  "prompt": "一只可爱的猫咪在花园里玩耍",
  "n": 1,
  "size": "1024x1024",
  "quality": "standard",
  "response_format": "url",
  "provider": {
    "only": ["火山方舟"],
    "sort": ["output_price", "latency"],
    "enable_image_base64": false,
    "enable_image_origin_data": true
  }
}

嵌套格式（备选） ​

除了 OpenAI 标准格式，API 也支持嵌套格式。如果使用嵌套格式，参数分配规则如下：

  • 放入 input 对象的参数：prompt、negative_prompt、image、image2、image3 等图片相关输入参数
  • 放入 extra_body 对象的参数：n、size、quality、response_format 等生成参数，以及 provider 对象

嵌套格式完整示例 ​

json
{
  "model": "Doubao-Seedream-4.0",
  "input": {
    "prompt": "一只可爱的猫咪在花园里玩耍",
    "negative_prompt": "低质量、模糊"
  },
  "extra_body": {
    "n": 1,
    "size": "1024x1024",
    "quality": "standard",
    "enable_image_base64": false,
    "provider": {
      "only": ["火山方舟"],
      "sort": ["output_price", "latency"],
      "enable_image_origin_data": true
    }
  }
}

注意：嵌套格式与 OpenAI 标准格式功能完全等价，系统会自动检测并处理。推荐使用 OpenAI 标准格式以获得更好的兼容性。

注意事项 ​

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