---
name: vidu-ref2video-example
description: 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

```sql
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

```sql
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)

```sql
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`。