pipeline_core/skills_library/all/uapi-module/SKILL.md

name	description
vidu-ref2video-example	Complete worked example of integrating Vidu v2 reference-to-video API into Sage

Vidu Reference-to-Video API Integration Example

Overview

Complete example of integrating Vidu's v2 reference-to-video API into Sage's uapi/llmage system.

Source

API docs: https://platform.vidu.cn/docs/reference-to-video

Two Modes

1. Subject Mode: Uses subjects[] array with named subjects, referenced via @name in prompt
2. Non-Subject Mode: Direct images[] array without subject wrapper

ID Generation

Critical: All IDs must be ≤21 characters, matching the system's getID() format. Use random 21-char strings from [a-zA-Z0-9_-]. Never use readable names as IDs — they will fail with ERROR 1406: Data too long.

Example valid IDs: H_gY42bRRW2MnbTxxLjJY, m_r2v_q3turbo001

Configuration (SQL)

uapiio — Subject Mode

INSERT INTO uapiio (id, name, description, input_fields) VALUES (
  '<21-char-id>',
  '参考生视频v2(主体模式)',
  'Vidu参考生视频v2 API - 主体模式输入输出定义',
  '{"model": {"type": "string", "required": true, "title": "模型名称"}, "subjects": {"type": "array", "required": true, "title": "主体列表"}, "prompt": {"type": "string", "required": true, "title": "提示词"}, ...}'
);

uapiio — Non-Subject Mode

INSERT INTO uapiio (id, name, description, input_fields) VALUES (
  '<21-char-id>',
  '参考生视频v2(非主体模式)',
  'Vidu参考生视频v2 API - 非主体模式(直接图片参考)输入输出定义',
  '{"model": {"type": "string", "required": true, "title": "模型名称"}, "images": {"type": "array", "required": true, "title": "参考图片URL列表"}, "prompt": {"type": "string", "required": true, "title": "提示词"}, ...}'
);

uapi — Create Task (both modes)

INSERT INTO uapi (id, upappid, name, title, description, need_auth, stream, path, httpmethod, chunk_match, headers, params, data, response, ioid)
VALUES ('<21-char-id>', 'vidu', 'ref2video_v2_subjects', '参考生视频v2(主体模式)', '...', '0', 'async', '/ent/v2/reference2video', 'POST', 'task_id', '{"Content-Type": "application/json", "Authorization": "Token {{apikey}}"}', NULL, '{{jsondata}}', '{{response}}', '<uapiio-id>');

Auth approach: Use Token {{apikey}} directly in the headers JSON — no token() function needed. The {{apikey}} template variable is already available from upappkey and gets substituted with the actual key value at render time.

llm — 7 Model Variants

Each model gets its own record with a unique 21-char ID:

Model	apiname	Pricing Tier
viduq3-turbo	ref2video_v2_subjects	q3 tier
viduq3	ref2video_v2_subjects	q3 tier
viduq2-pro	ref2video_v2_subjects	q2 tier
viduq2	ref2video_v2_subjects	q2 tier
viduq1	ref2video_v2_subjects	q2 tier
vidu2.0	ref2video_v2_subjects	q2 tier
viduq3-mix	ref2video_v2_no_subjects	q3 tier

llm_api_map

Maps each llm to the appropriate uapi:

• Subject mode models → ref2video_v2_subjects
• viduq3-mix → ref2video_v2_no_subjects
• All use taskStatus for query
• query_period: 30 seconds

No Code Changes Required

The inline Token {{apikey}} approach in the headers JSON works without any code changes. The template engine renders {{apikey}} as the actual API key from upappkey, producing Token actual_key_value at runtime.

Model Comparison

Model	Duration	Special	Pricing
viduq3-mix	3-16s	Best quality, non-subject only	q3 tier
viduq3-turbo	3-16s	Fastest, cost-effective	q3 tier
viduq3	3-16s	Multi-camera consistency	q3 tier
viduq2-pro	0-10s	Video reference, editing	q2 tier
viduq2	1-10s	Rich details, good motion	q2 tier
viduq1	5s	Stable, smooth	q2 tier
vidu2.0	4s	Fast generation	q2 tier

Key API Parameters

• subjects[]: Max 7 subjects (q3/q2/q1/2.0), max 4 (q2-pro). Each subject max 3 images.
• images[]: 1-7 reference images for non-subject mode
• videos[]: Only viduq2-pro supports video subjects (max 2, or 1 temp)
• duration: Model-dependent (q3-turbo/q3: 3-16s, q2-pro: 0-10s, q2: 1-10s, q1: 5s, 2.0: 4s)
• audio: true enables audio+video output (default true for q3 models)
• off_peak: true for cheaper but slower generation (48h timeout)

uapiio input_fields — Bricks 格式 (≠ JSON Schema)

重要: input_fields 必须是 bricks 兼容的数组格式，不是 JSON Schema。参考 references/uapiio-bricks-format.md。