人物素材と参照動画の連携フロー

本ページでは、そのまま実装できるサーバー側の呼び出し順序を示します。各ステップのフィールド、例、エラーコードは API ページにあり、ここでは順序関係と完全なコードのみを示します：

素材ライブラリ関連の API は素材ライブラリ API 概要を参照してください。
動画タスク関連の API は動画タスクの作成を参照してください。

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 秒に 1 回、同じ素材 ID のみを照会することをおすすめします。

`data.asset.status`	処理方法
`Processing`	後で同じ `asset_id` を照会する
`Active`	動画リクエストで `asset://asset-id` を使用できる
`Failed`	`error_message` を読み取り、画像を修正して新しい素材を作成する

二、実在人物素材の QR コード許諾

POST /api/v1/materials/portrait/sessions で authorization_url と session_token を取得し、アドレスを QR コードにして実在の人物本人に読み取ってもらいます。
本人が収集を完了したら POST /api/v1/materials/portrait/resolve を呼び出し（session_token を付与）、実在人物グループの group.id を取得します。
POST /api/v1/materials/sync で一度同期し、素材一覧を照会して実在人物素材の asset_id と status を読み取ります。

パラメータ、レスポンス、エラーコードは実在人物素材の肖像権許諾を参照してください。

三、複数画像＋参照動画の送信

「複数画像＋深度動画」の公開エンドポイントでの形式は次のとおりです。各画像がそれぞれ 1 つの 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> に置き換えるだけです。各画像は引き続き個別に 1 つの content 要素を占める必要があります。参照画像の枚数、参照動画の機能、解像度、長さ、音声機能は、/v1/models が返すモデル能力と実際のエラーに準じます。

四、完全な Node.js の例

下のコードは「グループ作成 → 画像送信 → ステータスのポーリング → 動画送信」をつなぐもので、API キーは環境変数から読み取ります。

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 キーが欠落、誤り、または失効していないか確認します。
400：リクエストボディのフィールドとセッショントークンが完全か確認します。
404：素材 ID、グループ ID が現在のアカウントに属しているか確認します。
503：素材または実在人物許諾サービスが一時的に利用できません。リクエスト情報を保持してからプラットフォームサポートに連絡してください。
Processing：同じ素材 ID の照会を続け、重複して登録しないでください。
Failed：error_message を読み取り、元のファイルを修正して新しい素材を作成してください。

このページの目次