人像素材与参考视频接入流程

本页给出一条可以直接落地的服务端调用顺序。每一步的字段、示例和错误码在接口页里，这里只演示先后关系与完整代码：

素材库相关接口见素材库接口概览；
视频任务相关接口见创建视频任务。

https://locopalai.com
Authorization: Bearer <API_KEY>
Content-Type: application/json

调用顺序

虚拟素材

POST /api/v1/materials/groups
  → POST /api/v1/materials/assets
  → GET  /api/v1/materials/assets/{asset_id}   轮询到 status 为 Active
  → POST /v1/video/generations
  → GET  /v1/video/generations/{task_id}

真人素材

POST /api/v1/materials/groups {"type":"real"}
  → POST /api/v1/materials/portrait/sessions   拿到二维码链接
  → 真人本人扫码并完成手机采集
  → POST /api/v1/materials/portrait/resolve
  → POST /api/v1/materials/sync
  → GET  /api/v1/materials/assets?group_id=...
  → POST /v1/video/generations

创建 real 分组不代表平台代替真人本人完成授权；涉及真人本人时，仍必须由本人完成采集和授权。

一、虚拟人像入库

创建分组：POST /api/v1/materials/groups，type 传 virtual，保存响应里的 data.group.id。字段与示例见素材分组。
提交图片：POST /api/v1/materials/assets，用 group_id + image_url（或 data_url），保存 data.asset_id。title 可以留空，平台会按文件名自动命名。
轮询状态：GET /api/v1/materials/assets/{asset_id}，建议 5～10 秒查一次，只查同一个素材 ID。

`data.asset.status`	处理方式
`Processing`	稍后查询同一个 `asset_id`
`Active`	可以在视频请求里使用 `asset://asset-id`
`Failed`	读取 `error_message`，修正图片后创建新的素材

二、真人素材扫码授权

POST /api/v1/materials/portrait/sessions 拿到 authorization_url 和 session_token，把地址转成二维码交给真人本人扫码。
本人完成采集后调用 POST /api/v1/materials/portrait/resolve（带 session_token），拿到真人分组 group.id。
POST /api/v1/materials/sync 同步一次，再查询素材列表读取真人素材的 asset_id 与 status。

参数、响应和错误码见真人素材授权。

三、多图 + 参考视频提交

「多图 + 深度视频」在公开接口里的格式是：每张图片各占一个 content 元素，参考视频使用 video_url 和 role: "reference_video"，没有单独的 deep_video 字段。

export LOCOPAL_API_KEY="sk-你的APIKey"
export LOCOPAL_VIDEO_MODEL_ID="从 /v1/models 返回的视频模型 ID"
export LOCOPAL_PERSON_IMAGE_URL="https://你的对象存储域名/person.png"
export LOCOPAL_PRODUCT_IMAGE_URL="https://你的对象存储域名/product.png"
export LOCOPAL_REFERENCE_VIDEO_URL="https://你的对象存储域名/motion.mp4"

const origin = 'https://locopalai.com'
const apiKey = process.env.LOCOPAL_API_KEY!
const model = process.env.LOCOPAL_VIDEO_MODEL_ID!
const personImage = process.env.LOCOPAL_PERSON_IMAGE_URL!
const productImage = process.env.LOCOPAL_PRODUCT_IMAGE_URL!
const referenceVideo = process.env.LOCOPAL_REFERENCE_VIDEO_URL!

const response = await fetch(`${origin}/v1/video/generations`, {
  method: 'POST',
  headers: { Authorization: `Bearer ${apiKey}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    model,
    content: [
      { type: 'text', text: '以图片1的人物为主体，参考图片2的产品外观，按照参考视频的动作节奏和运镜生成视频。' },
      { type: 'image_url', role: 'reference_image', image_url: { url: personImage } },
      { type: 'image_url', role: 'reference_image', image_url: { url: productImage } },
      { type: 'video_url', role: 'reference_video', video_url: { url: referenceVideo } },
    ],
    resolution: '720p',
    ratio: '16:9',
    duration: 5,
    generate_audio: true,
    watermark: false,
  }),
})

const created = (await response.json()) as { id?: string; error?: { message?: string } }
if (!response.ok || !created.id) throw new Error(created.error?.message ?? `创建视频失败：HTTP ${response.status}`)

// 保存 created.id。网络中断后只查询这个 ID，不要重复创建。
const query = await fetch(`${origin}/v1/video/generations/${encodeURIComponent(created.id)}`, {
  headers: { Authorization: `Bearer ${apiKey}` },
})
if (!query.ok) throw new Error(await query.text())
console.log(await query.json())

如果图片已经通过素材库审核，把图片 URL 换成 asset://<asset_id> 即可，每张图片仍然要单独占用一个 content 元素。参考图片数量、参考视频能力、清晰度、时长和音频能力以 /v1/models 返回的模型能力和实际报错为准。

四、完整 Node.js 示例

下面的代码串起「创建分组 → 提交图片 → 轮询状态 → 提交视频」，API Key 从环境变量读取。

const origin = process.env.LOCOPAL_API_ORIGIN ?? 'https://locopalai.com'
const apiKey = process.env.LOCOPAL_API_KEY
const imageUrl = process.env.LOCOPAL_IMAGE_URL
const videoModelId = process.env.LOCOPAL_VIDEO_MODEL_ID

if (!apiKey || !imageUrl || !videoModelId) {
  throw new Error('请设置 LOCOPAL_API_KEY、LOCOPAL_IMAGE_URL、LOCOPAL_VIDEO_MODEL_ID')
}

async function locopal<T>(path: string, init: RequestInit = {}) {
  const response = await fetch(`${origin}${path}`, {
    ...init,
    headers: {
      Authorization: `Bearer ${apiKey}`,
      'Content-Type': 'application/json',
      ...init.headers,
    },
  })
  const payload = (await response.json()) as { code?: number; data?: T; msg?: string }
  if (!response.ok || payload.code !== 0) throw new Error(payload.msg ?? `请求失败：HTTP ${response.status}`)
  return payload.data as T
}

const group = await locopal<{ group: { id: string } }>('/api/v1/materials/groups', {
  method: 'POST',
  body: JSON.stringify({ name: 'API 人像参考素材', description: '虚拟素材分组', type: 'virtual' }),
})

const asset = await locopal<{ asset_id: string }>('/api/v1/materials/assets', {
  method: 'POST',
  body: JSON.stringify({ group_id: group.group.id, title: '人物参考图', image_url: imageUrl }),
})

const state = await locopal<{ asset: { status: string; error_message?: string | null } }>(
  `/api/v1/materials/assets/${encodeURIComponent(asset.asset_id)}`,
)
if (state.asset.status !== 'Active') {
  throw new Error(state.asset.error_message ?? '素材尚未可用')
}

const video = await fetch(`${origin}/v1/video/generations`, {
  method: 'POST',
  headers: { Authorization: `Bearer ${apiKey}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    model: videoModelId,
    content: [
      { type: 'text', text: '让人物自然转身，保持人物外观一致。' },
      { type: 'image_url', role: 'reference_image', image_url: { url: `asset://${asset.asset_id}` } },
    ],
    resolution: '720p',
    ratio: '16:9',
    duration: 5,
  }),
})
if (!video.ok) throw new Error(await video.text())
console.log(await video.json())

五、完整 Node.js 真人授权示例

const origin = 'https://locopalai.com'
const apiKey = process.env.LOCOPAL_API_KEY!

async function api<T>(path: string, init: RequestInit = {}) {
  const response = await fetch(`${origin}${path}`, {
    ...init,
    headers: { Authorization: `Bearer ${apiKey}`, 'Content-Type': 'application/json', ...init.headers },
  })
  const payload = (await response.json()) as { code?: number; data?: T; msg?: string }
  if (!response.ok || payload.code !== 0) throw new Error(payload.msg ?? `请求失败：HTTP ${response.status}`)
  return payload.data as T
}

const created = await api<{ session: { authorization_url: string; session_token: string } }>(
  '/api/v1/materials/portrait/sessions',
  { method: 'POST', body: JSON.stringify({ continuous_create: false }) },
)

// 把 authorization_url 转成二维码展示给真人本人。
// 等用户在手机端完成采集后，再执行下面的解析请求。
const resolved = await api<{ group: { id: string; type: string } }>('/api/v1/materials/portrait/resolve', {
  method: 'POST',
  body: JSON.stringify({ session_token: created.session.session_token }),
})

await api('/api/v1/materials/sync', { method: 'POST', body: '{}' })
const assets = await api<{ assets: Array<{ id: string; status: string }> }>(
  `/api/v1/materials/assets?group_id=${encodeURIComponent(resolved.group.id)}&page=1&page_size=20`,
)
console.log({ group: resolved.group, assets })

六、模型切换与错误处理

虚拟素材继续使用同一个 asset://<asset_id>，换模型时只改 model 字段。真人素材只能提交到支持真人素材库的模型；当前模型不支持时接口会返回可读错误，不能把真人素材改成普通图片 URL 绕过限制。

401：检查 API Key 是否缺失、错误或失效；
400：检查请求体字段和会话 Token 是否完整；
404：检查素材 ID、分组 ID 是否属于当前账号；
503：素材或真人授权服务暂时不可用，保留请求信息后联系平台支持；
Processing：继续查询同一个素材 ID，不要重复入库；
Failed：读取 error_message，修正源文件后创建新的素材。

本页目录