查询素材选项

接口说明

按命名空间查询素材选项列表，用于自定义生图时获取可选的姿势（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）
custom_agent	自定义角色素材（Ethnicity / Age / BodyType / HairColor / HairStyle / BreastSize / ButtSize / Voice 等）

INFO

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

category（参数分类）说明

接口返回的 data 为 Map<category, List<OptionItem>>，其中 key 就是参数分类（category）名称。不同 namespace 下常见的分类如下（以接口实时返回为准，后续可能新增分类，客户端建议按返回内容动态渲染而不是写死列表）。

custom_image 分类

category	说明
Pose	姿势
Background	背景
Outfit	服装

custom_agent 分类

category	说明	备注
Ethnicity	种族	生成封面必填
Age	年龄段	生成封面必填
BodyType	体型	生成封面必填，受 gender 过滤
BreastSize	胸部大小	仅 female 需要（生成封面必填）
ButtSize	臀部大小	仅 female 需要（生成封面必填）
HairColor	发色	生成封面必填
HairStyle	发型	生成封面必填，受 gender 过滤
Voice	声音	创建角色必填（作为 voiceId 传入），受 gender 过滤
Personality	性格	可选
Occupation	职业	可选
Relationship	关系定位	可选
Fetish	个性化偏好	可选

TIP

OptionItem.text 为扩展字段：部分分类可能用于后端提示词拼接，也可能用于 UI 展示（例如 HairColor.text 可能存放颜色 hex，某些标签类可能用 text 存放 emoji）。

响应格式

成功响应

返回按分类（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	选项的扩展描述文本（自定义角色类使用），通常不返回

错误响应

HTTP 状态码	说明
401	鉴权失败（缺少请求头、时间戳过期、API Key 无效或签名错误）
200	参数校验失败等业务错误：success=false，code=10400，错误原因见 message

客户端示例

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, {
    url: '/v1/config/options',
  })

  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 生成图片