自定义生图

接口说明

基于提示词和可选的姿势、背景、服装素材选项，生成自定义 AI 图片。

INFO

此接口与 /v1/chat/image 是完全独立的业务，不共享会话，无需 conversationId。

WARNING

该接口为同步阻塞接口，图片生成期间连接保持。生成过程通常需要 30～120 秒，请设置足够长的超时时间（建议 ≥ 150 秒）。

基本信息

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

请求体

{
  "agentId": "a36b6b38-e94d-ad19-c170-ad8de3a1a018",
  "text": "sitting on a bench in a park",
  "language": "en",
  "gender": "female",
  "pose": "sitting",
  "background": "park",
  "outfit": "casual dress",
  "refImageId": "550e8400-e29b-41d4-a716-446655440000",
  "metadata": {}
}

字段	类型	必填	说明
agentId	string	✅	智能体 ID
text	string	✅	图片描述，用于引导生图风格和场景
language	string	✅	语言代码，如 en、zh、ja
gender	string	❌	性别过滤：male 或 female
pose	string	❌	姿势选项 code，来自 /v1/config/options
background	string	❌	背景选项 code，来自 /v1/config/options
outfit	string	❌	服装选项 code，来自 /v1/config/options
refImageId	string	❌	参考图 ID，由上传参考图接口返回的 imageId
metadata	object	❌	扩展字段，可传空对象 {}

TIP

pose、background、outfit 的可选值请通过 POST /v1/config/options 接口查询，传入 namespace: "custom_image"。

响应格式

成功响应

{
  "code": 10200,
  "success": true,
  "message": "OK",
  "data": {
    "imageData": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
  },
  "traceId": "xEo3sQwB6KRuwFfG2BxNWwlLQhKrvg38",
  "timestamp": "1773298769366"
}

字段	类型	说明
data.imageData	string	生成的图片，格式为 data:image/png;base64,<数据>

错误响应

HTTP 状态码	说明
401	认证失败
400	请求参数缺失或格式错误
404	智能体不存在或未配置 comfy 工作流
500	Dify 或 RunPod 内部服务错误

业务错误（HTTP 200）：

message	说明
Invalid API key	API Key 无效或已禁用
Too many requests, please try again later	触发频率限制
API key usage limit reached	达到总调用次数上限
Agent not found	智能体不存在
Agent missing comfy prompt config	智能体未配置 ComfyUI 工作流

客户端示例

async function generateCustomImage(apiKey, apiSecret, userId, params) {
  const { agentId, text, language = 'en', gender, pose, background, outfit, refImageId } = params

  const body = Object.fromEntries(
    Object.entries({ agentId, text, language, gender, pose, background, outfit, refImageId })
      .filter(([, v]) => v != null && String(v).trim() !== '')
  )

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

  const controller = new AbortController()
  const timeoutId = setTimeout(() => controller.abort(), 150000) // 150s 超时

  try {
    const response = await fetch('/v1/image/generate', {
      method: 'POST',
      headers,
      body: JSON.stringify(body),
      signal: controller.signal,
    })

    const result = await response.json()
    if (!result.success) { console.error('生成失败：', result.message); return null }
    return result.data.imageData // "data:image/png;base64,..."
  } finally {
    clearTimeout(timeoutId)
  }
}

两步调用流程（含参考图）

// 第一步（可选）：上传参考人脸图
const refImageId = await uploadRefImage(apiKey, apiSecret, userId, imageFile)

// 第二步：生成图片
const imageData = await generateCustomImage(apiKey, apiSecret, userId, {
  agentId: 'xxx',
  text: 'sitting on a bench in a park',
  language: 'en',
  refImageId,
})

素材选项查询

const response = await fetch('/v1/config/options', {
  method: 'POST',
  headers: await buildAuthHeaders(apiKey, apiSecret, userId, { namespace: 'custom_image', language: 'en' }),
  body: JSON.stringify({ namespace: 'custom_image', gender: 'female', language: 'en' }),
})

const { data } = await response.json()
// data 结构：{ "Pose": [{code, label, previewUrl}, ...], "Background": [...], "Outfit": [...] }
// 返回的 code 字段即为传入 pose/background/outfit 的值