查询素材选项

接口说明

按命名空间查询素材选项列表，用于自定义生图时获取可选的姿势（Pose）、背景（Background）、服装（Outfit）等素材 code 及展示标签。

TIP

查询返回的 code 字段即为调用 生成图片 接口时 pose、background、outfit 参数的传入值。

基本信息

项目	说明
接口路径	POST /v1/config/options
响应类型	application/json
认证方式	API Key + 请求签名（认证说明）

请求体

{
  "namespace": "custom_image",
  "gender": "female",
  "language": "en"
}

字段	类型	必填	说明
namespace	string	✅	素材命名空间，见下方说明
gender	string	❌	性别过滤：male 或 female；不传则返回全部（含通用素材）
language	string	❌	语言代码，如 en、zh、ja；默认 en

namespace 说明

namespace	说明
custom_image	自定义生图素材（Pose / Background / Outfit）

INFO

language 字段支持多语言 fallback：优先返回指定语言的标签，若无则退回 en，若仍无则使用 code 本身。

响应格式

成功响应

返回按分类（category）分组的素材选项 Map，key 为分类名称，value 为选项列表。

{
  "code": 10200,
  "success": true,
  "message": "OK",
  "data": {
    "Pose": [
      {
        "code": "standing",
        "label": "Standing",
        "previewUrl": "https://cdn.example.com/pose/standing.jpg"
      },
      {
        "code": "sitting",
        "label": "Sitting",
        "previewUrl": "https://cdn.example.com/pose/sitting.jpg"
      }
    ],
    "Background": [
      {
        "code": "park",
        "label": "Park",
        "previewUrl": "https://cdn.example.com/bg/park.jpg"
      },
      {
        "code": "office",
        "label": "Office",
        "previewUrl": "https://cdn.example.com/bg/office.jpg"
      }
    ],
    "Outfit": [
      {
        "code": "casual_dress",
        "label": "Casual Dress",
        "previewUrl": "https://cdn.example.com/outfit/casual_dress.jpg"
      }
    ]
  },
  "traceId": "xEo3sQwB6KRuwFfG2BxNWwlLQhKrvg38",
  "timestamp": "1773298769366"
}

响应字段说明

data 为 Map<category, List<OptionItem>>，每个 OptionItem 包含：

字段	类型	说明
code	string	选项值，调用生成接口时传入此值
label	string	多语言展示标签
previewUrl	string | null	缩略图 URL，无缩略图时不返回该字段
text	string | null	Dify 提示词扩展文本（自定义角色类使用），通常不返回

错误响应

HTTP 状态码	说明
401	认证失败
400	namespace 缺失

客户端示例

async function fetchMaterialOptions(apiKey, apiSecret, userId, { namespace, gender, language = 'en' }) {
  const body = { namespace, language }
  if (gender) body.gender = gender

  const headers = await buildAuthHeaders(apiKey, apiSecret, userId, body)

  const response = await fetch('/v1/config/options', {
    method: 'POST',
    headers,
    body: JSON.stringify(body),
  })

  const result = await response.json()
  if (!result.success) throw new Error(result.message)

  return result.data
  // 返回结构：
  // {
  //   "Pose":       [{ code, label, previewUrl }, ...],
  //   "Background": [{ code, label, previewUrl }, ...],
  //   "Outfit":     [{ code, label, previewUrl }, ...]
  // }
}

// 使用示例
const options = await fetchMaterialOptions(apiKey, apiSecret, userId, {
  namespace: 'custom_image',
  gender: 'female',
  language: 'en',
})

// 渲染 Pose 选项
options.Pose.forEach(item => {
  console.log(item.code, item.label, item.previewUrl)
})

// 将用户选择的 code 传给生成接口
const imageData = await generateCustomImage(apiKey, apiSecret, userId, {
  agentId: 'xxx',
  text: 'sitting on a bench',
  language: 'en',
  pose: options.Pose[0].code,        // e.g. "sitting"
  background: options.Background[0].code, // e.g. "park"
  outfit: options.Outfit[0].code,    // e.g. "casual_dress"
})

与生成图片的完整调用流程

1. POST /v1/config/options  →  获取素材 code 列表
           ↓
2. 用户从 UI 中选择 Pose / Background / Outfit
           ↓
3. （可选）POST /v1/image/upload  →  上传参考图，获取 refImageId
           ↓
4. POST /v1/image/generate  →  传入选中的 code 生成图片