Skip to content

armgit / hypit

Public Imported from GitHub
0

Clone any viral video with AI agents. Not just a script, the whole workflow: swap the face, the words, the B-roll, ship 100 variants in one command, and get your 100M views.

fix(seedance): require visual reference classification for 0.2.8

kashorin168c537c4f48
diff --git a/docs/quickstart/composition.md b/docs/quickstart/composition.md
index d4f29fef..969fff21 100644
--- a/docs/quickstart/composition.md
+++ b/docs/quickstart/composition.md
@@ -179,11 +179,11 @@ illustration. The complete runnable project is `examples/podcast/`; the commands
<gpt:Image id="studio-scene" prompt={scene-look} aspect-ratio="9:16" resolution="2K"/>
<seedance:ReferenceVideo id="take" model="mini"
prompt={direction} duration="5" generate-audio="true">
- <seedance:Reference image={studio-scene.image}/>
+ <seedance:Reference image={studio-scene.image} person-reference="true"/>
</seedance:ReferenceVideo>
<seedance:ReferenceVideo id="motion" model="mini"
prompt={direction} duration="5">
- <seedance:Reference image={studio-scene.image}/>
+ <seedance:Reference image={studio-scene.image} person-reference="true"/>
</seedance:ReferenceVideo>
<space:Canvas id="vertical" width="1080" height="1920"/>
diff --git a/docs/quickstart/generation.md b/docs/quickstart/generation.md
index f91a2a72..0ec04292 100644
--- a/docs/quickstart/generation.md
+++ b/docs/quickstart/generation.md
@@ -130,7 +130,8 @@ First-frame generation with an optional last frame:
```svml
<seedance:FrameVideo id="transition" model="fast"
prompt={transition-direction} duration="5"
- first-frame={opening-image} last-frame={closing-image}/>
+ first-frame={opening-image} first-frame-person-reference="false"
+ last-frame={closing-image} last-frame-person-reference="false"/>
```
### seedance:ReferenceVideo
@@ -148,10 +149,10 @@ video and audio references within the model's declared limits.
</seedance:ReferenceVideo>
```
-On an image or video reference, `person-reference="true"` declares a person/avatar in the supplied
-material, including a generated human likeness. Use false for a reference without that content;
-omission leaves the classification unspecified. Audio references do not use this visual flag.
-Frame mode provides `first-frame-person-reference` and `last-frame-person-reference`. The selected
+Every image/video reference requires `person-reference="true|false"`: true if the supplied material
+contains a person, false otherwise. Omission is an error;
+audio must omit the field. Frame mode requires `first-frame-person-reference` and, when a last frame
+is supplied, `last-frame-person-reference`. The selected
Provider carries this fact through the service's media preparation; a service without such a field
accepts the declaration without transmitting it.
@@ -221,8 +222,8 @@ language for the selected model, keeping dialogue in the language it should be s
resolution="720p"
aspect-ratio="9:16"
generate-audio="false">
- <seedance:Reference image={scene}/>
- <seedance:Reference image={product}/>
+ <seedance:Reference image={scene} person-reference="false"/>
+ <seedance:Reference image={product} person-reference="false"/>
</seedance:ReferenceVideo>
```
diff --git a/docs/quickstart/tracks.md b/docs/quickstart/tracks.md
index a12fd360..2b012a92 100644
--- a/docs/quickstart/tracks.md
+++ b/docs/quickstart/tracks.md
@@ -157,7 +157,7 @@ Placement is an explicit Spatial Frame edge; appearance and motion remain reusab
<seedance:ReferenceVideo id="product-motion" model="mini"
prompt={product-direction} duration="5">
- <seedance:Reference image={product-reference}/>
+ <seedance:Reference image={product-reference} person-reference="false"/>
</seedance:ReferenceVideo>
<space:Frame id="product-frame" within={vertical}
diff --git a/docs/zh/quickstart/composition.md b/docs/zh/quickstart/composition.md
index 26fe10a8..2df82ed0 100644
--- a/docs/zh/quickstart/composition.md
+++ b/docs/zh/quickstart/composition.md
@@ -173,11 +173,11 @@ Build Target,也可以直接接到媒体裁切、音频/帧提取或模型参
<gpt:Image id="studio-scene" prompt={scene-look} aspect-ratio="9:16" resolution="2K"/>
<seedance:ReferenceVideo id="take" model="mini"
prompt={direction} duration="5" generate-audio="true">
- <seedance:Reference image={studio-scene.image}/>
+ <seedance:Reference image={studio-scene.image} person-reference="true"/>
</seedance:ReferenceVideo>
<seedance:ReferenceVideo id="motion" model="mini"
prompt={direction} duration="5">
- <seedance:Reference image={studio-scene.image}/>
+ <seedance:Reference image={studio-scene.image} person-reference="true"/>
</seedance:ReferenceVideo>
<space:Canvas id="vertical" width="1080" height="1920"/>
diff --git a/docs/zh/quickstart/generation.md b/docs/zh/quickstart/generation.md
index 6bd141be..ab32e608 100644
--- a/docs/zh/quickstart/generation.md
+++ b/docs/zh/quickstart/generation.md
@@ -116,7 +116,8 @@ Seedance 2.5 复用同样的 Surface,而不是由 Runtime 把别的模型偷
```svml
<seedance:FrameVideo id="transition" model="fast"
prompt={transition-direction} duration="5"
- first-frame={opening-image} last-frame={closing-image}/>
+ first-frame={opening-image} first-frame-person-reference="false"
+ last-frame={closing-image} last-frame-person-reference="false"/>
```
### seedance:ReferenceVideo
@@ -133,9 +134,8 @@ Seedance 2.5 复用同样的 Surface,而不是由 Runtime 把别的模型偷
</seedance:ReferenceVideo>
```
-图片或视频参考上的 `person-reference="true"` 声明素材中含有人物/数字人形象,AI 生成的人像也适用。
-没有这类内容时可写 false;省略表示没有提供分类。音频参考不使用这个视觉标记。
-首尾帧模式提供 `first-frame-person-reference` 和 `last-frame-person-reference`。
+每个参考图片/视频必须填写 `person-reference="true|false"`:参考素材含人物填 true,不含填 false。
+漏填会报错,音频不得填写。首帧必须填写 `first-frame-person-reference`,提供尾帧时还须填写 `last-frame-person-reference`。
选定的 Provider 负责把这项事实交给服务的素材准备流程;服务 API 没有对应字段时,Provider 接受这项声明但不传输。
舞蹈、身体动作或运镜可以由参考视频提供运动依据,再用参考图指定新的形象与场景。
@@ -189,8 +189,8 @@ Source Closure 沿着这个显式包导入读取内容。如果共享措辞不
<seedance:ReferenceVideo id="demo" model="mini"
prompt={demo-prompt} duration="5"
resolution="720p" aspect-ratio="9:16" generate-audio="false">
- <seedance:Reference image={scene}/>
- <seedance:Reference image={product}/>
+ <seedance:Reference image={scene} person-reference="false"/>
+ <seedance:Reference image={product} person-reference="false"/>
</seedance:ReferenceVideo>
```
diff --git a/docs/zh/quickstart/tracks.md b/docs/zh/quickstart/tracks.md
index 303c6555..900264bf 100644
--- a/docs/zh/quickstart/tracks.md
+++ b/docs/zh/quickstart/tracks.md
@@ -111,7 +111,7 @@ B-roll 是通用 Media Track 的一种剪辑用途,不是独立 Track 家族
<seedance:ReferenceVideo id="product-motion" model="mini"
prompt={product-direction} duration="5">
- <seedance:Reference image={product-reference}/>
+ <seedance:Reference image={product-reference} person-reference="false"/>
</seedance:ReferenceVideo>
<space:Frame id="product-frame" within={vertical}
diff --git a/examples/interview/reference.svml b/examples/interview/reference.svml
index ca0d6799..ef019f94 100644
--- a/examples/interview/reference.svml
+++ b/examples/interview/reference.svml
@@ -197,9 +197,9 @@
model="mini" prompt={manifest-rule-prompt}
duration="11"
resolution="720p" aspect-ratio="9:16" generate-audio="true">
- <seedance:Reference image={interviewer-view.image}/>
- <seedance:Reference image={guest-view.image}/>
- <seedance:Reference image={shared-view.image}/>
+ <seedance:Reference image={interviewer-view.image} person-reference="true"/>
+ <seedance:Reference image={guest-view.image} person-reference="true"/>
+ <seedance:Reference image={shared-view.image} person-reference="true"/>
<seedance:Reference audio={boy-voice.reference}/>
<seedance:Reference audio={wife-voice.reference}/>
</seedance:ReferenceVideo>
@@ -208,9 +208,9 @@
model="mini" prompt={real-estate-rule-prompt}
duration="8"
resolution="720p" aspect-ratio="9:16" generate-audio="true">
- <seedance:Reference image={interviewer-view.image}/>
- <seedance:Reference image={guest-view.image}/>
- <seedance:Reference image={shared-view.image}/>
+ <seedance:Reference image={interviewer-view.image} person-reference="true"/>
+ <seedance:Reference image={guest-view.image} person-reference="true"/>
+ <seedance:Reference image={shared-view.image} person-reference="true"/>
<seedance:Reference audio={boy-voice.reference}/>
<seedance:Reference audio={wife-voice.reference}/>
</seedance:ReferenceVideo>
@@ -219,9 +219,9 @@
model="mini" prompt={bitcoin-rule-prompt}
duration="8"
resolution="720p" aspect-ratio="9:16" generate-audio="true">
- <seedance:Reference image={interviewer-view.image}/>
- <seedance:Reference image={guest-view.image}/>
- <seedance:Reference image={shared-view.image}/>
+ <seedance:Reference image={interviewer-view.image} person-reference="true"/>
+ <seedance:Reference image={guest-view.image} person-reference="true"/>
+ <seedance:Reference image={shared-view.image} person-reference="true"/>
<seedance:Reference audio={boy-voice.reference}/>
<seedance:Reference audio={wife-voice.reference}/>
</seedance:ReferenceVideo>
diff --git a/examples/interview/swap-host.svml b/examples/interview/swap-host.svml
index e4ba8043..4160e276 100644
--- a/examples/interview/swap-host.svml
+++ b/examples/interview/swap-host.svml
@@ -126,9 +126,9 @@
model="mini" prompt={manifest-rule-prompt}
duration="10"
resolution="720p" aspect-ratio="9:16" generate-audio="true">
- <seedance:Reference image={interviewer-view.image}/>
- <seedance:Reference image={guest-view.image}/>
- <seedance:Reference image={shared-view.image}/>
+ <seedance:Reference image={interviewer-view.image} person-reference="true"/>
+ <seedance:Reference image={guest-view.image} person-reference="true"/>
+ <seedance:Reference image={shared-view.image} person-reference="true"/>
<seedance:Reference audio={chad-voice}/>
<seedance:Reference audio={wojak-voice}/>
</seedance:ReferenceVideo>
@@ -137,9 +137,9 @@
model="mini" prompt={real-estate-rule-prompt}
duration="8"
resolution="720p" aspect-ratio="9:16" generate-audio="true">
- <seedance:Reference image={interviewer-view.image}/>
- <seedance:Reference image={guest-view.image}/>
- <seedance:Reference image={shared-view.image}/>
+ <seedance:Reference image={interviewer-view.image} person-reference="true"/>
+ <seedance:Reference image={guest-view.image} person-reference="true"/>
+ <seedance:Reference image={shared-view.image} person-reference="true"/>
<seedance:Reference audio={chad-voice}/>
<seedance:Reference audio={wojak-voice}/>
</seedance:ReferenceVideo>
@@ -148,9 +148,9 @@
model="mini" prompt={bitcoin-rule-prompt}
duration="8"
resolution="720p" aspect-ratio="9:16" generate-audio="true">
- <seedance:Reference image={interviewer-view.image}/>
- <seedance:Reference image={guest-view.image}/>
- <seedance:Reference image={shared-view.image}/>
+ <seedance:Reference image={interviewer-view.image} person-reference="true"/>
+ <seedance:Reference image={guest-view.image} person-reference="true"/>
+ <seedance:Reference image={shared-view.image} person-reference="true"/>
<seedance:Reference audio={chad-voice}/>
<seedance:Reference audio={wojak-voice}/>
</seedance:ReferenceVideo>
diff --git a/examples/interview/swap-lang.svml b/examples/interview/swap-lang.svml
index 8779f507..df7c8bac 100644
--- a/examples/interview/swap-lang.svml
+++ b/examples/interview/swap-lang.svml
@@ -126,9 +126,9 @@
model="mini" prompt={manifest-rule-prompt}
duration="10"
resolution="720p" aspect-ratio="9:16" generate-audio="true">
- <seedance:Reference image={interviewer-view.image}/>
- <seedance:Reference image={guest-view.image}/>
- <seedance:Reference image={shared-view.image}/>
+ <seedance:Reference image={interviewer-view.image} person-reference="true"/>
+ <seedance:Reference image={guest-view.image} person-reference="true"/>
+ <seedance:Reference image={shared-view.image} person-reference="true"/>
<seedance:Reference audio={boy-voice}/>
<seedance:Reference audio={wife-voice}/>
</seedance:ReferenceVideo>
@@ -137,9 +137,9 @@
model="mini" prompt={real-estate-rule-prompt}
duration="8"
resolution="720p" aspect-ratio="9:16" generate-audio="true">
- <seedance:Reference image={interviewer-view.image}/>
- <seedance:Reference image={guest-view.image}/>
- <seedance:Reference image={shared-view.image}/>
+ <seedance:Reference image={interviewer-view.image} person-reference="true"/>
+ <seedance:Reference image={guest-view.image} person-reference="true"/>
+ <seedance:Reference image={shared-view.image} person-reference="true"/>
<seedance:Reference audio={boy-voice}/>
<seedance:Reference audio={wife-voice}/>
</seedance:ReferenceVideo>
@@ -148,9 +148,9 @@
model="mini" prompt={bitcoin-rule-prompt}
duration="8"
resolution="720p" aspect-ratio="9:16" generate-audio="true">
- <seedance:Reference image={interviewer-view.image}/>
- <seedance:Reference image={guest-view.image}/>
- <seedance:Reference image={shared-view.image}/>
+ <seedance:Reference image={interviewer-view.image} person-reference="true"/>
+ <seedance:Reference image={guest-view.image} person-reference="true"/>
+ <seedance:Reference image={shared-view.image} person-reference="true"/>
<seedance:Reference audio={boy-voice}/>
<seedance:Reference audio={wife-voice}/>
</seedance:ReferenceVideo>
diff --git a/examples/interview/swap-ride.svml b/examples/interview/swap-ride.svml
index e21694fb..5d3485bd 100644
--- a/examples/interview/swap-ride.svml
+++ b/examples/interview/swap-ride.svml
@@ -133,9 +133,9 @@
model="mini" prompt={uber-rule-prompt}
duration="9"
resolution="720p" aspect-ratio="9:16" generate-audio="true">
- <seedance:Reference image={interviewer-view.image}/>
- <seedance:Reference image={guest-view.image}/>
- <seedance:Reference image={shared-view.image}/>
+ <seedance:Reference image={interviewer-view.image} person-reference="true"/>
+ <seedance:Reference image={guest-view.image} person-reference="true"/>
+ <seedance:Reference image={shared-view.image} person-reference="true"/>
<seedance:Reference audio={leon-voice}/>
<seedance:Reference audio={ada-voice}/>
</seedance:ReferenceVideo>
@@ -144,9 +144,9 @@
model="mini" prompt={shortcuts-rule-prompt}
duration="11"
resolution="720p" aspect-ratio="9:16" generate-audio="true">
- <seedance:Reference image={interviewer-view.image}/>
- <seedance:Reference image={guest-view.image}/>
- <seedance:Reference image={shared-view.image}/>
+ <seedance:Reference image={interviewer-view.image} person-reference="true"/>
+ <seedance:Reference image={guest-view.image} person-reference="true"/>
+ <seedance:Reference image={shared-view.image} person-reference="true"/>
<seedance:Reference audio={leon-voice}/>
<seedance:Reference audio={ada-voice}/>
</seedance:ReferenceVideo>
@@ -155,9 +155,9 @@
model="mini" prompt={first-place-rule-prompt}
duration="6"
resolution="720p" aspect-ratio="9:16" generate-audio="true">
- <seedance:Reference image={interviewer-view.image}/>
- <seedance:Reference image={guest-view.image}/>
- <seedance:Reference image={shared-view.image}/>
+ <seedance:Reference image={interviewer-view.image} person-reference="true"/>
+ <seedance:Reference image={guest-view.image} person-reference="true"/>
+ <seedance:Reference image={shared-view.image} person-reference="true"/>
<seedance:Reference audio={leon-voice}/>
<seedance:Reference audio={ada-voice}/>
</seedance:ReferenceVideo>
diff --git a/examples/podcast/reference.svml b/examples/podcast/reference.svml
index 0e7ebda6..96acbd15 100644
--- a/examples/podcast/reference.svml
+++ b/examples/podcast/reference.svml
@@ -308,9 +308,9 @@
<seedance:ReferenceVideo id="lifestyle-montage" model="mini"
prompt={lifestyle-montage-prompt} duration="5"
resolution="720p" aspect-ratio="9:16" generate-audio="false">
- <seedance:Reference image={coffee.image}/>
- <seedance:Reference image={smoothie.image}/>
- <seedance:Reference image={pasta.image}/>
+ <seedance:Reference image={coffee.image} person-reference="true"/>
+ <seedance:Reference image={smoothie.image} person-reference="true"/>
+ <seedance:Reference image={pasta.image} person-reference="true"/>
</seedance:ReferenceVideo>
<text:Render id="daily-creatine-take-prompt"
@@ -328,15 +328,15 @@
<seedance:ReferenceVideo id="opening-take" model="mini"
prompt={opening-take-prompt} duration="5"
resolution="720p" aspect-ratio="9:16" generate-audio="true">
- <seedance:Reference image={split.image}/>
+ <seedance:Reference image={split.image} person-reference="true"/>
<seedance:Reference audio={guy-voice.reference}/>
</seedance:ReferenceVideo>
<seedance:ReferenceVideo id="daily-creatine-take" model="mini"
prompt={daily-creatine-take-prompt} duration="8"
resolution="720p" aspect-ratio="9:16" generate-audio="true">
- <seedance:Reference image={girl-hold.image}/>
- <seedance:Reference image={guy.image}/>
+ <seedance:Reference image={girl-hold.image} person-reference="true"/>
+ <seedance:Reference image={guy.image} person-reference="true"/>
<seedance:Reference audio={girl-voice.reference}/>
<seedance:Reference audio={guy-voice.reference}/>
</seedance:ReferenceVideo>
@@ -344,8 +344,8 @@
<seedance:ReferenceVideo id="arms-are-asking-take" model="mini"
prompt={arms-are-asking-take-prompt} duration="6"
resolution="720p" aspect-ratio="9:16" generate-audio="true">
- <seedance:Reference image={girl-hold.image}/>
- <seedance:Reference image={guy-hold.image}/>
+ <seedance:Reference image={girl-hold.image} person-reference="true"/>
+ <seedance:Reference image={guy-hold.image} person-reference="true"/>
<seedance:Reference audio={girl-voice.reference}/>
<seedance:Reference audio={guy-voice.reference}/>
</seedance:ReferenceVideo>
diff --git a/examples/podcast/swap-app.svml b/examples/podcast/swap-app.svml
index bcea63f3..49edce07 100644
--- a/examples/podcast/swap-app.svml
+++ b/examples/podcast/swap-app.svml
@@ -136,23 +136,23 @@
<seedance:ReferenceVideo id="opening-take" model="mini"
prompt={opening-take-prompt} duration="4"
resolution="720p" aspect-ratio="9:16" generate-audio="true">
- <seedance:Reference image={jocknerd.image}/>
+ <seedance:Reference image={jocknerd.image} person-reference="true"/>
<seedance:Reference audio={nerd-voice}/>
</seedance:ReferenceVideo>
<seedance:ReferenceVideo id="lifestyle-montage" model="mini"
prompt={lifestyle-montage-prompt} duration="4"
resolution="720p" aspect-ratio="9:16" generate-audio="false">
- <seedance:Reference image={classroom-selfie.image}/>
- <seedance:Reference image={library-study.image}/>
- <seedance:Reference image={wedding-vows.image}/>
+ <seedance:Reference image={classroom-selfie.image} person-reference="true"/>
+ <seedance:Reference image={library-study.image} person-reference="true"/>
+ <seedance:Reference image={wedding-vows.image} person-reference="true"/>
</seedance:ReferenceVideo>
<seedance:ReferenceVideo id="daily-cheatgpt-take" model="mini"
prompt={daily-cheatgpt-take-prompt} duration="7"
resolution="720p" aspect-ratio="9:16" generate-audio="true">
- <seedance:Reference image={jock-hold.image}/>
- <seedance:Reference image={nerd.image}/>
+ <seedance:Reference image={jock-hold.image} person-reference="true"/>
+ <seedance:Reference image={nerd.image} person-reference="true"/>
<seedance:Reference audio={jock-voice}/>
<seedance:Reference audio={nerd-voice}/>
</seedance:ReferenceVideo>
@@ -160,8 +160,8 @@
<seedance:ReferenceVideo id="brain-is-asking-take" model="mini"
prompt={brain-is-asking-take-prompt} duration="7"
resolution="720p" aspect-ratio="9:16" generate-audio="true">
- <seedance:Reference image={jock-hold.image}/>
- <seedance:Reference image={nerd.image}/>
+ <seedance:Reference image={jock-hold.image} person-reference="true"/>
+ <seedance:Reference image={nerd.image} person-reference="true"/>
<seedance:Reference audio={jock-voice}/>
<seedance:Reference audio={nerd-voice}/>
</seedance:ReferenceVideo>
diff --git a/examples/podcast/swap-host.svml b/examples/podcast/swap-host.svml
index df1aa3ef..b204a98d 100644
--- a/examples/podcast/swap-host.svml
+++ b/examples/podcast/swap-host.svml
@@ -131,9 +131,9 @@
<seedance:ReferenceVideo id="lifestyle-montage" model="mini"
prompt={lifestyle-montage-prompt} duration="4"
resolution="720p" aspect-ratio="9:16" generate-audio="false">
- <seedance:Reference image={before.image}/>
- <seedance:Reference image={after.image}/>
- <seedance:Reference image={during.image}/>
+ <seedance:Reference image={before.image} person-reference="false"/>
+ <seedance:Reference image={after.image} person-reference="false"/>
+ <seedance:Reference image={during.image} person-reference="false"/>
</seedance:ReferenceVideo>
<text:Render id="daily-creatine-take-prompt"
@@ -151,15 +151,15 @@
<seedance:ReferenceVideo id="opening-take" model="mini"
prompt={opening-take-prompt} duration="4"
resolution="720p" aspect-ratio="9:16" generate-audio="true">
- <seedance:Reference image={pepedoge.image}/>
+ <seedance:Reference image={pepedoge.image} person-reference="false"/>
<seedance:Reference audio={doge-voice}/>
</seedance:ReferenceVideo>
<seedance:ReferenceVideo id="daily-creatine-take" model="mini"
prompt={daily-creatine-take-prompt} duration="7"
resolution="720p" aspect-ratio="9:16" generate-audio="true">
- <seedance:Reference image={pepe-hold.image}/>
- <seedance:Reference image={doge.image}/>
+ <seedance:Reference image={pepe-hold.image} person-reference="false"/>
+ <seedance:Reference image={doge.image} person-reference="false"/>
<seedance:Reference audio={pepe-voice}/>
<seedance:Reference audio={doge-voice}/>
</seedance:ReferenceVideo>
@@ -167,8 +167,8 @@
<seedance:ReferenceVideo id="arms-are-asking-take" model="mini"
prompt={arms-are-asking-take-prompt} duration="7"
resolution="720p" aspect-ratio="9:16" generate-audio="true">
- <seedance:Reference image={pepe-hold.image}/>
- <seedance:Reference image={doge-hold.image}/>
+ <seedance:Reference image={pepe-hold.image} person-reference="false"/>
+ <seedance:Reference image={doge-hold.image} person-reference="false"/>
<seedance:Reference audio={pepe-voice}/>
<seedance:Reference audio={doge-voice}/>
</seedance:ReferenceVideo>
diff --git a/examples/podcast/swap-item.svml b/examples/podcast/swap-item.svml
index 7c3cd897..d5281d68 100644
--- a/examples/podcast/swap-item.svml
+++ b/examples/podcast/swap-item.svml
@@ -143,23 +143,23 @@
<seedance:ReferenceVideo id="opening-take" model="mini"
prompt={opening-take-prompt} duration="4"
resolution="720p" aspect-ratio="9:16" generate-audio="true">
- <seedance:Reference image={idoltboy.image}/>
+ <seedance:Reference image={idoltboy.image} person-reference="true"/>
<seedance:Reference audio={tboy-voice}/>
</seedance:ReferenceVideo>
<seedance:ReferenceVideo id="lifestyle-montage" model="mini"
prompt={lifestyle-montage-prompt} duration="4"
resolution="720p" aspect-ratio="9:16" generate-audio="false">
- <seedance:Reference image={cleanser.image}/>
- <seedance:Reference image={mask-selfie.image}/>
- <seedance:Reference image={alarm-phone.image}/>
+ <seedance:Reference image={cleanser.image} person-reference="true"/>
+ <seedance:Reference image={mask-selfie.image} person-reference="true"/>
+ <seedance:Reference image={alarm-phone.image} person-reference="true"/>
</seedance:ReferenceVideo>
<seedance:ReferenceVideo id="daily-retinol-take" model="mini"
prompt={daily-retinol-take-prompt} duration="8"
resolution="720p" aspect-ratio="9:16" generate-audio="true">
- <seedance:Reference image={idol-hold.image}/>
- <seedance:Reference image={tboy.image}/>
+ <seedance:Reference image={idol-hold.image} person-reference="true"/>
+ <seedance:Reference image={tboy.image} person-reference="true"/>
<seedance:Reference audio={idol-voice}/>
<seedance:Reference audio={tboy-voice}/>
</seedance:ReferenceVideo>
@@ -167,8 +167,8 @@
<seedance:ReferenceVideo id="skin-is-asking-take" model="mini"
prompt={skin-is-asking-take-prompt} duration="6"
resolution="720p" aspect-ratio="9:16" generate-audio="true">
- <seedance:Reference image={idol-hold.image}/>
- <seedance:Reference image={tboy-hold.image}/>
+ <seedance:Reference image={idol-hold.image} person-reference="true"/>
+ <seedance:Reference image={tboy-hold.image} person-reference="true"/>
<seedance:Reference audio={idol-voice}/>
<seedance:Reference audio={tboy-voice}/>
</seedance:ReferenceVideo>
diff --git a/examples/provider-package/README.md b/examples/provider-package/README.md
index 99ae5cea..31122a37 100644
--- a/examples/provider-package/README.md
+++ b/examples/provider-package/README.md
@@ -68,7 +68,7 @@ differ from the image example, and each is the reason the video example exists.
**The reference vocabulary is wider, and each role maps to its own field.** The Model declares
`referenceImage`, `referenceVideo` and `referenceAudio` as separate ports precisely so each can map
to one wire field — a service that mixes them into one array cannot tell the roles apart. An image
-reference also carries an optional `personReference` classification, which is why those ports use
+reference also requires a boolean `personReference` classification, which is why those ports use
`itemObject` rather than `urlArray`: the item field travels with the URL it belongs to.
```json
@@ -76,7 +76,7 @@ reference also carries an optional `personReference` classification, which is wh
```
`firstFrame` and `lastFrame` accept at most one item each, so their body fields are URLs.
-This illustrative service accepts their optional person classification on `POST /uploads` through
+This illustrative service accepts their required visual-reference person classification on `POST /uploads` through
`x-person-reference: true` or `false`. Their mappings declare `resourceFields: ["personReference"]`,
and the URL resolver sends that header when supplied. Replace this with the real service’s
documented transport; a field that the service cannot carry must be refused, never discarded.
diff --git a/examples/ranking-football/reference-banana-from-swap/reference-banana-from-swap.svml b/examples/ranking-football/reference-banana-from-swap/reference-banana-from-swap.svml
index 65816545..bb753a45 100644
--- a/examples/ranking-football/reference-banana-from-swap/reference-banana-from-swap.svml
+++ b/examples/ranking-football/reference-banana-from-swap/reference-banana-from-swap.svml
@@ -133,13 +133,13 @@
<seedance:ReferenceVideo id="ronaldo-take" model="mini"
prompt={ronaldo-prompt} duration="10"
resolution="720p" aspect-ratio="9:16" generate-audio="true">
- <seedance:Reference image={presenter.image}/>
+ <seedance:Reference image={presenter.image} person-reference="true"/>
<seedance:Reference audio={presenter-voice}/>
</seedance:ReferenceVideo>
<seedance:ReferenceVideo id="messi-take" model="mini"
prompt={messi-prompt} duration="10"
resolution="720p" aspect-ratio="9:16" generate-audio="true">
- <seedance:Reference image={presenter.image}/>
+ <seedance:Reference image={presenter.image} person-reference="true"/>
<seedance:Reference audio={presenter-voice}/>
</seedance:ReferenceVideo>
diff --git a/examples/ranking-football/reference-banana/reference-banana.svml b/examples/ranking-football/reference-banana/reference-banana.svml
index 65816545..bb753a45 100644
--- a/examples/ranking-football/reference-banana/reference-banana.svml
+++ b/examples/ranking-football/reference-banana/reference-banana.svml
@@ -133,13 +133,13 @@
<seedance:ReferenceVideo id="ronaldo-take" model="mini"
prompt={ronaldo-prompt} duration="10"
resolution="720p" aspect-ratio="9:16" generate-audio="true">
- <seedance:Reference image={presenter.image}/>
+ <seedance:Reference image={presenter.image} person-reference="true"/>
<seedance:Reference audio={presenter-voice}/>
</seedance:ReferenceVideo>
<seedance:ReferenceVideo id="messi-take" model="mini"
prompt={messi-prompt} duration="10"
resolution="720p" aspect-ratio="9:16" generate-audio="true">
- <seedance:Reference image={presenter.image}/>
+ <seedance:Reference image={presenter.image} person-reference="true"/>
<seedance:Reference audio={presenter-voice}/>
</seedance:ReferenceVideo>
diff --git a/examples/ranking-football/reference-gpt.svml b/examples/ranking-football/reference-gpt.svml
index 53a26252..72e72617 100644
--- a/examples/ranking-football/reference-gpt.svml
+++ b/examples/ranking-football/reference-gpt.svml
@@ -133,13 +133,13 @@
<seedance:ReferenceVideo id="ronaldo-take" model="mini"
prompt={ronaldo-prompt} duration="10"
resolution="720p" aspect-ratio="9:16" generate-audio="true">
- <seedance:Reference image={presenter.image}/>
+ <seedance:Reference image={presenter.image} person-reference="true"/>
<seedance:Reference audio={presenter-voice}/>
</seedance:ReferenceVideo>
<seedance:ReferenceVideo id="messi-take" model="mini"
prompt={messi-prompt} duration="10"
resolution="720p" aspect-ratio="9:16" generate-audio="true">
- <seedance:Reference image={presenter.image}/>
+ <seedance:Reference image={presenter.image} person-reference="true"/>
<seedance:Reference audio={presenter-voice}/>
</seedance:ReferenceVideo>
diff --git a/examples/ranking-football/reference.svml b/examples/ranking-football/reference.svml
index 873bfeec..64756c4c 100644
--- a/examples/ranking-football/reference.svml
+++ b/examples/ranking-football/reference.svml
@@ -164,13 +164,13 @@
<seedance:ReferenceVideo id="ronaldo-take" model="mini"
prompt={ronaldo-prompt} duration="10"
resolution="720p" aspect-ratio="9:16" generate-audio="true">
- <seedance:Reference image={presenter.image}/>
+ <seedance:Reference image={presenter.image} person-reference="true"/>
<seedance:Reference audio={presenter-voice.reference}/>
</seedance:ReferenceVideo>
<seedance:ReferenceVideo id="messi-take" model="mini"
prompt={messi-prompt} duration="10"
resolution="720p" aspect-ratio="9:16" generate-audio="true">
- <seedance:Reference image={presenter.image}/>
+ <seedance:Reference image={presenter.image} person-reference="true"/>
<seedance:Reference audio={presenter-voice.reference}/>
</seedance:ReferenceVideo>
diff --git a/examples/ranking-football/swap-effect-banana-reference-sync/swap-effect-banana-reference-sync.svml b/examples/ranking-football/swap-effect-banana-reference-sync/swap-effect-banana-reference-sync.svml
index 10781c60..88b9b3a3 100644
--- a/examples/ranking-football/swap-effect-banana-reference-sync/swap-effect-banana-reference-sync.svml
+++ b/examples/ranking-football/swap-effect-banana-reference-sync/swap-effect-banana-reference-sync.svml
@@ -133,13 +133,13 @@
<seedance:ReferenceVideo id="ronaldo-take" model="mini"
prompt={ronaldo-prompt} duration="10"
resolution="720p" aspect-ratio="9:16" generate-audio="true">
- <seedance:Reference image={presenter.image}/>
+ <seedance:Reference image={presenter.image} person-reference="true"/>
<seedance:Reference audio={presenter-voice}/>
</seedance:ReferenceVideo>
<seedance:ReferenceVideo id="messi-take" model="mini"
prompt={messi-prompt} duration="10"
resolution="720p" aspect-ratio="9:16" generate-audio="true">
- <seedance:Reference image={presenter.image}/>
+ <seedance:Reference image={presenter.image} person-reference="true"/>
<seedance:Reference audio={presenter-voice}/>
</seedance:ReferenceVideo>
diff --git a/examples/ranking-football/swap-effect-banana/swap-effect-banana.svml b/examples/ranking-football/swap-effect-banana/swap-effect-banana.svml
index 10391668..da3ab81b 100644
--- a/examples/ranking-football/swap-effect-banana/swap-effect-banana.svml
+++ b/examples/ranking-football/swap-effect-banana/swap-effect-banana.svml
@@ -121,13 +121,13 @@
<seedance:ReferenceVideo id="messi-take" model="mini"
prompt={messi-prompt} duration="10"
resolution="720p" aspect-ratio="9:16" generate-audio="true">
- <seedance:Reference image={presenter.image}/>
+ <seedance:Reference image={presenter.image} person-reference="true"/>
<seedance:Reference audio={presenter-voice}/>
</seedance:ReferenceVideo>
<seedance:ReferenceVideo id="ronaldo-take" model="mini"
prompt={ronaldo-prompt} duration="10"
resolution="720p" aspect-ratio="9:16" generate-audio="true">
- <seedance:Reference image={presenter.image}/>
+ <seedance:Reference image={presenter.image} person-reference="true"/>
<seedance:Reference audio={presenter-voice}/>
</seedance:ReferenceVideo>
diff --git a/examples/ranking-football/swap-effect.svml b/examples/ranking-football/swap-effect.svml
index bc9c6db4..590c704d 100644
--- a/examples/ranking-football/swap-effect.svml
+++ b/examples/ranking-football/swap-effect.svml
@@ -121,13 +121,13 @@
<seedance:ReferenceVideo id="messi-take" model="mini"
prompt={messi-prompt} duration="10"
resolution="720p" aspect-ratio="9:16" generate-audio="true">
- <seedance:Reference image={presenter.image}/>
+ <seedance:Reference image={presenter.image} person-reference="true"/>
<seedance:Reference audio={presenter-voice}/>
</seedance:ReferenceVideo>
<seedance:ReferenceVideo id="ronaldo-take" model="mini"
prompt={ronaldo-prompt} duration="10"
resolution="720p" aspect-ratio="9:16" generate-audio="true">
- <seedance:Reference image={presenter.image}/>
+ <seedance:Reference image={presenter.image} person-reference="true"/>
<seedance:Reference audio={presenter-voice}/>
</seedance:ReferenceVideo>
diff --git a/examples/ranking-football/swap-host.svml b/examples/ranking-football/swap-host.svml
index 2367856d..db5afafb 100644
--- a/examples/ranking-football/swap-host.svml
+++ b/examples/ranking-football/swap-host.svml
@@ -133,13 +133,13 @@
<seedance:ReferenceVideo id="ronaldo-take" model="mini"
prompt={ronaldo-prompt} duration="10"
resolution="720p" aspect-ratio="9:16" generate-audio="true">
- <seedance:Reference image={presenter.image}/>
+ <seedance:Reference image={presenter.image} person-reference="true"/>
<seedance:Reference audio={presenter-voice}/>
</seedance:ReferenceVideo>
<seedance:ReferenceVideo id="messi-take" model="mini"
prompt={messi-prompt} duration="10"
resolution="720p" aspect-ratio="9:16" generate-audio="true">
- <seedance:Reference image={presenter.image}/>
+ <seedance:Reference image={presenter.image} person-reference="true"/>
<seedance:Reference audio={presenter-voice}/>
</seedance:ReferenceVideo>
diff --git a/examples/ranking-football/swap-topic.svml b/examples/ranking-football/swap-topic.svml
index dc5ce52e..abcea8ed 100644
--- a/examples/ranking-football/swap-topic.svml
+++ b/examples/ranking-football/swap-topic.svml
@@ -148,13 +148,13 @@
<seedance:ReferenceVideo id="elon-take" model="mini"
prompt={elon-prompt} duration="10"
resolution="720p" aspect-ratio="9:16" generate-audio="true">
- <seedance:Reference image={presenter.image}/>
+ <seedance:Reference image={presenter.image} person-reference="true"/>
<seedance:Reference audio={presenter-voice}/>
</seedance:ReferenceVideo>
<seedance:ReferenceVideo id="sam-take" model="mini"
prompt={sam-prompt} duration="10"
resolution="720p" aspect-ratio="9:16" generate-audio="true">
- <seedance:Reference image={presenter.image}/>
+ <seedance:Reference image={presenter.image} person-reference="true"/>
<seedance:Reference audio={presenter-voice}/>
</seedance:ReferenceVideo>
diff --git a/package.json b/package.json
index dba9d5c2..e1ecb605 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "@hypit/hypit",
- "version": "0.2.7",
+ "version": "0.2.8",
"homepage": "https://hypit.ai",
"repository": {
"type": "git",
diff --git a/packages/gpt-image/test/broll-graph.test.ts b/packages/gpt-image/test/broll-graph.test.ts
index faa08280..47d1508d 100644
--- a/packages/gpt-image/test/broll-graph.test.ts
+++ b/packages/gpt-image/test/broll-graph.test.ts
@@ -121,7 +121,7 @@ function fixture() {
});
for (const name of ["holding", "walking", "interview"]) add(`montage.${name}.binding`, seedance.mediaBindings.referenceImage!.type, {
kind: "inline",
- value: sealGenerationMediaBinding(seedanceBindingPort as never, { role: "image" }) as unknown as CanonicalValue,
+ value: sealGenerationMediaBinding(seedanceBindingPort as never, { role: "image", fields: { personReference: true } }) as unknown as CanonicalValue,
});
const componentInputs = (
diff --git a/packages/provider-hiapi/README.md b/packages/provider-hiapi/README.md
index 548d553c..1880af76 100644
--- a/packages/provider-hiapi/README.md
+++ b/packages/provider-hiapi/README.md
@@ -37,7 +37,7 @@ Service limits this Provider reports as unsupported before submitting:
`1:3`, `9:21`; 4K excludes `1:1`, `3:1`, `1:3`, `9:21`; image-to-image takes up to six references.
- Grok Imagine renders 480p or 720p; `grok-imagine-1.5/image-to-video` animates exactly one image.
-Seedance visual references may carry `person-reference`; the Provider accepts the declaration and
+Seedance visual references require `person-reference`; the Provider accepts the declaration and
transmits nothing for it, since HiAPI has no field for it. Seedance rejects reference images and
videos that contain a real human face; HiAPI offers no way to register authorized portrait material,
so such a request fails with the service's moderation error.
diff --git a/packages/provider-hiapi/test/routes.test.ts b/packages/provider-hiapi/test/routes.test.ts
index e7b89c71..7b085951 100644
--- a/packages/provider-hiapi/test/routes.test.ts
+++ b/packages/provider-hiapi/test/routes.test.ts
@@ -42,11 +42,11 @@ test("Seedance 2.5 selects the HiAPI model from the request shape", async () =>
input: { prompt: "go", resolution: "720p", duration: 5, generate_audio: true, web_search: false, aspect_ratio: "adaptive", first_frame_url: "https://example.test/reference" },
});
const references = sealSeedanceRequest("seedance-2.5", {
- ...base, aspectRatio: ["16:9"], referenceVideo: [{ role: "video", artifact: video }],
+ ...base, aspectRatio: ["16:9"], referenceVideo: [{ role: "video", artifact: video, fields: { personReference: false } }],
});
assert.equal(seedance.prepare(constraints(references)).model, "seedance-2.5/reference-to-video");
const framed = seedance.supports({ capability: seedance.capability, returns: seedance.returns,
- constraints: constraints(sealSeedanceRequest("seedance-2.5", { ...base, aspectRatio: ["16:9"], firstFrame: [{ role: "image", artifact: image }] })) });
+ constraints: constraints(sealSeedanceRequest("seedance-2.5", { ...base, aspectRatio: ["16:9"], firstFrame: [{ role: "image", artifact: image, fields: { personReference: true } }] })) });
assert.equal(framed.status, "unsupported");
});
diff --git a/packages/provider-hypihub/README.md b/packages/provider-hypihub/README.md
index f9a6c7e4..b9a00e93 100644
--- a/packages/provider-hypihub/README.md
+++ b/packages/provider-hypihub/README.md
@@ -123,12 +123,11 @@ size and part concurrency, retries a failed part with a fresh signed URL, comple
one upload, and then passes the returned HTTPS URL to generation or transcription. Signing requests
contain at most the service's 128-part limit; all batches belong to the same upload. One
Resource identity with the same declared person-reference classification is uploaded once within one Runtime operation. Hypit keeps no upload catalog or
-cross-Build cache. Seedance visual references can carry `personReference` in their media fields;
+cross-Build cache. Seedance visual references require boolean `personReference` in their media fields;
the mapping declares it as a resource-transport field and the upload session receives
-`is_person_reference`, preserving true, false and omission. It stays out of the generation body.
+`is_person_reference`, preserving true and false. It stays out of the generation body.
This covers reference images, reference videos, and first/last frames for every declared Seedance
-variant. Omission remains absent on the wire; HypiHub's upload API currently defaults it to false,
-so omission does not enable detection or person-reference preparation.
+variant. Seedance rejects omission before upload; no automatic face detection is requested.
HypiHub stores the authored classification and prepares the applicable upstream person reference;
this Provider does not detect faces or select an upstream private-avatar group.
diff --git a/packages/provider-hypihub/test/provider.test.ts b/packages/provider-hypihub/test/provider.test.ts
index 5f09b753..b8bb3b03 100644
--- a/packages/provider-hypihub/test/provider.test.ts
+++ b/packages/provider-hypihub/test/provider.test.ts
@@ -604,7 +604,7 @@ test("HypiHub stops before paid submission when a reference upload fails", async
const reference = await resources.put(new Uint8Array([1, 2, 3]), "image/png");
const request = need(sealSeedanceRequest("seedance-2-mini", {
prompt: ["A presenter turns toward camera."],
- referenceImage: [{ role: "image", artifact: reference }],
+ referenceImage: [{ role: "image", artifact: reference, fields: { personReference: true } }],
resolution: ["720p"], aspectRatio: ["16:9"], duration: [5],
generateAudio: [false], webSearch: [false],
}) as unknown as CanonicalValue);
@@ -815,12 +815,12 @@ test("HypiHub polling errors and operation deadlines fail without settlement pol
test("reference URL reuse includes its authored classification and forwards it to custom transport", async () => {
const resources = new MemoryResourceStore();
const reference = await resources.put(new Uint8Array([1, 2, 3]), "image/png");
- const flags = [true, false, undefined, true];
+ const flags = [true, false, true];
const request = need(sealSeedanceRequest("seedance-2-mini", {
prompt: ["A person waves."], resolution: ["720p"], aspectRatio: ["9:16"],
duration: [5], generateAudio: [false], webSearch: [false],
referenceImage: flags.map((flag) => ({ role: "image", artifact: reference,
- ...(flag === undefined ? {} : { fields: { personReference: flag } }) })),
+ fields: { personReference: flag } })),
}) as unknown as CanonicalValue);
const seen: unknown[] = [];
const provider = createHypiHubProvider({
@@ -842,7 +842,7 @@ test("reference URL reuse includes its authored classification and forwards it t
const started = await resolved.registration.endpoint.start({ command: { kind: "fulfill-need", id: "classified", need: request }, need: request, resources,
credentials: { apiKey: { secret: "test-key" } }, operation: "classified" });
assert.equal(started.status, "pending");
- assert.deepEqual(seen, [{ personReference: true }, { personReference: false }, {}]);
+ assert.deepEqual(seen, [{ personReference: true }, { personReference: false }]);
});
test("generation and voice cloning check their exact catalogue operation before resolving references", async () => {
@@ -853,7 +853,7 @@ test("generation and voice cloning check their exact catalogue operation before
{
endpoint: seedanceEndpoints.mini!, model: "seedance-2-mini", operation: "videos", path: "/videos",
constraints: sealSeedanceRequest("seedance-2-mini", {
- prompt: ["A presenter speaks."], referenceImage: [{ role: "image", artifact: image }],
+ prompt: ["A presenter speaks."], referenceImage: [{ role: "image", artifact: image, fields: { personReference: true } }],
resolution: ["720p"], aspectRatio: ["9:16"], duration: [5], generateAudio: [true], webSearch: [false],
}),
references: true,
diff --git a/packages/provider-hypihub/test/routes.test.ts b/packages/provider-hypihub/test/routes.test.ts
index 3fde808a..991a92f0 100644
--- a/packages/provider-hypihub/test/routes.test.ts
+++ b/packages/provider-hypihub/test/routes.test.ts
@@ -147,8 +147,8 @@ test("HypiHub Seedance sends reference images through the public top-level field
generateAudio: [true],
webSearch: [false],
referenceImage: [
- { role: "image", artifact: image },
- { role: "image", artifact: { ...image, resource: "res_hypihub-route-2" } },
+ { role: "image", artifact: image, fields: { personReference: true } },
+ { role: "image", artifact: { ...image, resource: "res_hypihub-route-2" }, fields: { personReference: false } },
],
},
}, resolve);
@@ -236,8 +236,8 @@ test("HypiHub MiMo Speech mappings use the public audio speech fields", async ()
test("Seedance person metadata reaches resource transport without changing video request fields", async () => {
for (const route of hypiHubRoutes.filter((item) => item.capability.module.name === "@hypit/seedance")) {
for (const port of ["referenceImage", "referenceVideo", "firstFrame", "lastFrame"] as const) {
- for (const flag of [true, false, undefined]) {
- const fields = flag === undefined ? {} : { personReference: flag };
+ for (const flag of [true, false]) {
+ const fields = { personReference: flag };
const seen: unknown[] = [];
const result = await compile(route, { ports: {
prompt: ["animate"], duration: [5],
diff --git a/packages/provider-monid/README.md b/packages/provider-monid/README.md
index 45a2879f..0c4193f1 100644
--- a/packages/provider-monid/README.md
+++ b/packages/provider-monid/README.md
@@ -25,7 +25,7 @@ each media input as a typed item with its `role` (`first_frame`, `last_frame`, `
The Seedance endpoints add `generate_audio`. Monid documents no web search field for them, so
`web-search="true"` is unsupported, and Seedance 2.5 frame mode (`first-frame` present) requires
-`aspect-ratio="adaptive"`. Seedance visual references may carry `person-reference`; the Provider
+`aspect-ratio="adaptive"`. Seedance visual references require `person-reference`; the Provider
accepts the declaration and transmits nothing for it, since the endpoint has no field for it.
Seedance rejects reference images and videos that contain a real human face; Monid offers no way to
register authorized portrait material, so such a request fails with the upstream moderation error.
diff --git a/packages/provider-tokendance/README.md b/packages/provider-tokendance/README.md
index 82f25aa2..2137a225 100644
--- a/packages/provider-tokendance/README.md
+++ b/packages/provider-tokendance/README.md
@@ -19,7 +19,7 @@ the models the Distribution already describes.
Video requests write the prompt and each media input as one item of the protocol's `content`
array with its `role` (`first_frame`, `last_frame`, `reference_image`, `reference_video`,
`reference_audio`), then `resolution`, `ratio`, `duration` and, for Seedance, `generate_audio`;
-`web-search="true"` adds `tools: [{ "type": "web_search" }]`. Seedance visual references may carry
+`web-search="true"` adds `tools: [{ "type": "web_search" }]`. Seedance visual references require
`person-reference`; the Provider accepts the declaration and transmits nothing for it, since the Ark
protocol has no such field. Seedance 2.0 and 2.5 reject reference images and videos that contain a
real human face; TokenDance offers no way to register authorized portrait material, so such a request
diff --git a/packages/seedance-kits/README.md b/packages/seedance-kits/README.md
index b2023be2..724fb44e 100644
--- a/packages/seedance-kits/README.md
+++ b/packages/seedance-kits/README.md
@@ -23,8 +23,8 @@ ordinary explicit graph edges:
<seedance:ReferenceVideo id="broll" model="mini" prompt={broll-prompt}
duration="5" resolution="720p" aspect-ratio="9:16">
- <seedance:Reference image={scene}/>
- <seedance:Reference image={product}/>
+ <seedance:Reference image={scene} person-reference="false"/>
+ <seedance:Reference image={product} person-reference="false"/>
</seedance:ReferenceVideo>
```
@@ -154,7 +154,8 @@ For a multi-scene B-roll montage, `story` can name the references in scene order
action. Choose an edit language compatible with cuts. “Continuous within each scene” and “one
continuous shot for the whole montage” ask for different results.
-Visual input classification belongs to the Seedance Reference, separately from Kit text. The
+Every Seedance image/video Reference requires `person-reference="true|false"`: true if the supplied
+material contains a person, false otherwise. Audio must omit it. The
[Seedance author package](../seedance/README.md#visual-reference-metadata) explains `person-reference`
and its frame variants. The Kit supplies direction; the actual reference edges supply media and
metadata. For movement-led work, a reference video can carry the motion while the text explains what
diff --git a/packages/seedance/README.md b/packages/seedance/README.md
index 64378910..e386dcaa 100644
--- a/packages/seedance/README.md
+++ b/packages/seedance/README.md
@@ -34,22 +34,20 @@ responsible for any additional service-specific input limits.
## Visual reference metadata
-Declare whether each image or video contains a person/avatar reference, including an AI-generated
-human likeness. This describes the supplied material, independently of the prompt's requested action:
+Every supplied image or video must explicitly declare `person-reference`: `true` if it contains
+a person, `false` otherwise. Classify the supplied material, not the requested result.
```xml
-<seedance:ReferenceVideo id="dance" model="mini" prompt={direction} duration="8">
+<seedance:ReferenceVideo id="take" model="mini" prompt={direction} duration="8">
<seedance:Reference image={presenter.image} person-reference="true"/>
- <seedance:Reference video={motion.video} person-reference="true"/>
+ <seedance:Reference video={presenter.video} person-reference="true"/>
<seedance:Reference image={room.image} person-reference="false"/>
</seedance:ReferenceVideo>
```
-`person-reference` is optional, accepts literal `true` or `false`, and applies to image/video, not
-voice audio. Omission carries no classification; it is distinct from explicitly declaring false.
-Inspect the actual reference when deciding the value. For `FrameVideo`, use
-`first-frame-person-reference` and `last-frame-person-reference` beside their respective frame
-inputs. A last-frame classification requires a last-frame input.
+Missing or non-boolean declarations are rejected; there is no default or automatic face detection.
+Audio must omit this field. `FrameVideo` requires `first-frame-person-reference` and, when a last
+frame is supplied, `last-frame-person-reference`. A last-frame classification requires a last frame.
| Supplied visual input | Authored attribute | Request port |
| --- | --- | --- |
@@ -66,23 +64,18 @@ These forms apply to `standard`, `fast`, `mini` and `2.5`. For example:
last-frame={empty-room.image} last-frame-person-reference="false"/>
```
-Classify the material supplied to this request, not the intended result. A dance video with a person
-still needs `true` when used only for motion, even if the prompt asks for a different performer.
-An empty room stays `false` when the prompt asks to add a person. Inspect video across the selected
-excerpt, not only its opening frame. This flag neither detects faces nor locks or names an identity.
-Identity and action direction remain in the prompt and references.
+Inspect the selected video excerpt, not only its opening frame. An empty room stays `false` when
+the prompt asks to add a person. The flag does not lock identity; direction and references own that.
The SVML author declares this parameter on each reference input. Admitted files, generated
images/videos and reused Results use the same attributes. For a future output, declare the intended
reference classification explicitly; if its contents are uncertain, generate and inspect that
material before using it downstream.
-The model's media ports carry this as `fields.personReference`. Providers interpret it through their
-service's media handling; it is not a prompt sentence or a Core-level identity. HypiHub sends it as
+Direct requests require the same boolean in `fields.personReference`. Providers interpret it through
+their service's media handling; it is not a prompt sentence or a Core-level identity. HypiHub sends it as
`is_person_reference` when uploading the file, then uses the returned URL in the ordinary video
request. A project Provider maps it according to its own API.
-Omission does not request automatic face detection. HypiHub currently treats omitted upload flags
-as unmarked (`false`); declare `true` explicitly for a person reference that needs its preparation.
Video references can carry motion or camera behavior while image references carry the target
appearance. Request duration and reference-clip duration are different limits. Check the selected
diff --git a/packages/seedance/src/index.ts b/packages/seedance/src/index.ts
index 2b045bd7..85abc979 100644
--- a/packages/seedance/src/index.ts
+++ b/packages/seedance/src/index.ts
@@ -17,7 +17,7 @@ export type SeedanceModel = typeof seedanceModels[number];
const ASPECT_RATIOS = ["1:1", "4:3", "3:4", "16:9", "9:16", "21:9", "adaptive"] as const;
-const PERSON_REFERENCE_FIELDS = [{ name: "personReference", value: { kind: "boolean" }, optional: true }] as const;
+const PERSON_REFERENCE_FIELDS = [{ name: "personReference", value: { kind: "boolean" } }] as const;
const SEEDANCE_25_DURATIONS = [-1, ...Array.from({ length: 27 }, (_item, index) => index + 4)] as const;
@@ -175,9 +175,9 @@ const seedanceCommonAttributes: readonly SurfaceAttributeVocabulary[] = [
},
];
-const personReferenceAttribute = (name: string): SurfaceAttributeVocabulary => ({
- name, kind: "literal", required: false, values: ["true", "false"],
- summary: "Declares whether this visual input contains a person/avatar reference, including an AI-generated human likeness. Omission leaves it unclassified.",
+const personReferenceAttribute = (name: string, required = false): SurfaceAttributeVocabulary => ({
+ name, kind: "literal", required, values: ["true", "false"],
+ summary: "Required for each supplied image/video, including first/last frames: true if it contains a person, false otherwise. Audio must omit it.",
});
const seedanceVideoPort: readonly SurfacePortVocabulary[] = [{
@@ -235,7 +235,7 @@ export const seedanceMarkupSurfaces = [
summary: "Generates one video with an exact Seedance model from a Text prompt and the images the video opens and closes on.",
attributes: [
...seedanceCommonAttributes,
- personReferenceAttribute("first-frame-person-reference"),
+ personReferenceAttribute("first-frame-person-reference", true),
personReferenceAttribute("last-frame-person-reference"),
{
name: "first-frame",
@@ -253,7 +253,7 @@ export const seedanceMarkupSurfaces = [
},
],
ports: seedanceVideoPort,
- example: '<seedance:FrameVideo id="bridge" model="fast" prompt={direction} duration="5" first-frame={first.image} last-frame={last.image}/>',
+ example: '<seedance:FrameVideo id="bridge" model="fast" prompt={direction} duration="5" first-frame={first.image} first-frame-person-reference="true" last-frame={last.image} last-frame-person-reference="false"/>',
notes: [
...seedanceSettingNotes,
"Both frames are ordinary image Artifact edges; the Surface copies no runtime media into request metadata.",
@@ -316,7 +316,7 @@ export const seedanceMarkupSurfaces = [
notes: [
...seedanceSettingNotes,
"The element requires at least one `Reference` child, and the model's port limits cap how many of each role it accepts.",
- "`person-reference` applies to image/video references; voice audio carries no visual classification. The Provider transports the declared fact according to its API.",
+ "Every image/video Reference requires `person-reference=\"true|false\"`. Classify the supplied material; audio must omit the field. The Provider transports it according to its API.",
"A `Reference` carries exactly one of `image`, `video` or `audio`, and is empty.",
],
},
diff --git a/packages/seedance/src/surface.ts b/packages/seedance/src/surface.ts
index 1ac3cbc1..3eb1d74d 100644
--- a/packages/seedance/src/surface.ts
+++ b/packages/seedance/src/surface.ts
@@ -146,8 +146,10 @@ function booleanAttribute(element: StructuredElement, name: string, fallback: bo
}
function personReferenceFields(element: StructuredElement, name: string) {
- return element.attributes[name] === undefined ? undefined
- : { personReference: booleanAttribute(element, name, false) };
+ if (element.attributes[name] === undefined) {
+ throw new Error(`${element.name}.${name} is required for this visual reference; set true if it contains a person, false otherwise`);
+ }
+ return { personReference: booleanAttribute(element, name, false) };
}
function enumeratedPort(table: GenerationPortTable, name: string): readonly (string | number)[] {
@@ -217,8 +219,8 @@ function referenceInputs(
const kinds = accepted.filter((kind) => child.attributes[kind] !== undefined);
if (kinds.length !== 1) throw new Error(`${child.name} requires exactly one of ${accepted.join(", ")}`);
const role = kinds[0]!;
- const fields = personReferenceFields(child, "person-reference");
- if (role === "audio" && fields !== undefined) throw new Error(`${child.name}.person-reference applies to image or video, not audio`);
+ if (role === "audio" && child.attributes["person-reference"] !== undefined) throw new Error(`${child.name}.person-reference applies to image or video, not audio`);
+ const fields = role === "audio" ? undefined : personReferenceFields(child, "person-reference");
result.push({
...(fields === undefined ? {} : { fields }),
role,
@@ -242,13 +244,12 @@ function frameInputs(
): MediaInput[] {
const first = mediaReference(resolved(element, "first-frame", resolveReference), "image", `${element.name}.first-frame`);
const firstFields = personReferenceFields(element, "first-frame-person-reference");
- const result: MediaInput[] = [{ port: "firstFrame", role: "image", source: first, ...(firstFields === undefined ? {} : { fields: firstFields }) }];
- const lastFields = personReferenceFields(element, "last-frame-person-reference");
- if (lastFields !== undefined && element.attributes["last-frame"] === undefined) throw new Error(`${element.name}.last-frame-person-reference requires last-frame`);
+ const result: MediaInput[] = [{ port: "firstFrame", role: "image", source: first, fields: firstFields }];
+ if (element.attributes["last-frame-person-reference"] !== undefined && element.attributes["last-frame"] === undefined) throw new Error(`${element.name}.last-frame-person-reference requires last-frame`);
if (element.attributes["last-frame"] !== undefined) {
result.push({
port: "lastFrame",
- ...(lastFields === undefined ? {} : { fields: lastFields }),
+ fields: personReferenceFields(element, "last-frame-person-reference"),
role: "image",
source: mediaReference(resolved(element, "last-frame", resolveReference), "image", `${element.name}.last-frame`),
});
diff --git a/packages/seedance/test/surface.test.ts b/packages/seedance/test/surface.test.ts
index 2c886761..2f44affa 100644
--- a/packages/seedance/test/surface.test.ts
+++ b/packages/seedance/test/surface.test.ts
@@ -49,7 +49,7 @@ test("TextVideo exposes prompt-only generation without inventing a usage", async
});
test("admitted M4A audio is rejected at decode while future audio remains a graph reference", async () => {
- const source = '<seedance:ReferenceVideo id="speaker" model="mini" prompt={direction} duration="6"><seedance:Reference image={generated.image}/><seedance:Reference audio={voice.audio}/></seedance:ReferenceVideo>';
+ const source = '<seedance:ReferenceVideo id="speaker" model="mini" prompt={direction} duration="6"><seedance:Reference image={generated.image} person-reference="true"/><seedance:Reference audio={voice.audio}/></seedance:ReferenceVideo>';
for (const mediaType of ["audio/mp4", "audio/x-m4a", "audio/wav", "audio/mpeg"]) {
const admitted = new Map(refs);
admitted.set("voice.audio", {
@@ -86,7 +86,7 @@ test("Seedance 2.5 is an exact model with 1080p and auto or 4-30 second duration
test("FrameVideo exposes first-frame and optional last-frame as exact model ports", async () => {
const result = await decode(
- '<seedance:FrameVideo id="bridge" model="fast" prompt={direction} duration="5" first-frame={first.image} last-frame={last.image}/>',
+ '<seedance:FrameVideo id="bridge" model="fast" prompt={direction} duration="5" first-frame={first.image} first-frame-person-reference="true" last-frame={last.image} last-frame-person-reference="false"/>',
decodeSeedanceFrameVideoSurface,
);
const component = result.components[0]!;
@@ -104,7 +104,7 @@ test("FrameVideo exposes first-frame and optional last-frame as exact model port
test("ReferenceVideo keeps generated Text and heterogeneous references on explicit graph edges", async () => {
const result = await decode(
`<seedance:ReferenceVideo id="speaker" model="mini" prompt={direction} duration="6" generate-audio="true">
- <seedance:Reference image={generated.image}/>
+ <seedance:Reference image={generated.image} person-reference="true"/>
<seedance:Reference audio={voice.audio}/>
</seedance:ReferenceVideo>`,
decodeSeedanceReferenceVideoSurface,
@@ -135,7 +135,7 @@ test("the three Surfaces make incompatible invocation shapes unrepresentable", a
);
await assert.rejects(
async () => await decode(
- '<seedance:ReferenceVideo id="search" model="mini" prompt={direction} duration="5" web-search="true"><seedance:Reference image={generated.image}/></seedance:ReferenceVideo>',
+ '<seedance:ReferenceVideo id="search" model="mini" prompt={direction} duration="5" web-search="true"><seedance:Reference image={generated.image} person-reference="true"/></seedance:ReferenceVideo>',
decodeSeedanceReferenceVideoSurface,
),
/requires/u,
@@ -146,13 +146,13 @@ test("visual reference classification survives authoring as per-input metadata",
const result = await decode(`<seedance:ReferenceVideo id="motion" model="mini" prompt={direction} duration="6">
<seedance:Reference image={generated.image} person-reference="true"/>
<seedance:Reference video={first.image} person-reference="false"/>
- <seedance:Reference image={last.image}/>
+ <seedance:Reference image={last.image} person-reference="false"/>
</seedance:ReferenceVideo>`, decodeSeedanceReferenceVideoSurface);
const bindings = result.records.filter((record) => record.id.endsWith(".binding"));
assert.deepEqual(bindings.map((record) => record.value.kind === "inline" ? record.value.value : null), [
{ role: "image", fields: { personReference: true } },
{ role: "video", fields: { personReference: false } },
- { role: "image" },
+ { role: "image", fields: { personReference: false } },
]);
const frames = await decode('<seedance:FrameVideo id="frames" model="fast" prompt={direction} duration="5" first-frame={first.image} first-frame-person-reference="true" last-frame={last.image} last-frame-person-reference="false"/>', decodeSeedanceFrameVideoSurface);
const frameBindings = frames.records.filter((record) => record.id.endsWith(".binding"));
@@ -162,5 +162,18 @@ test("visual reference classification survives authoring as per-input metadata",
]);
await assert.rejects(decode('<seedance:ReferenceVideo id="bad" model="mini" prompt={direction} duration="6"><seedance:Reference audio={voice.audio} person-reference="true"/></seedance:ReferenceVideo>', decodeSeedanceReferenceVideoSurface), /applies to image or video/);
await assert.rejects(decode('<seedance:ReferenceVideo id="bad" model="mini" prompt={direction} duration="6"><seedance:Reference image={generated.image} person-reference="maybe"/></seedance:ReferenceVideo>', decodeSeedanceReferenceVideoSurface), /must be true or false/);
- await assert.rejects(decode('<seedance:FrameVideo id="bad" model="mini" prompt={direction} duration="6" first-frame={first.image} last-frame-person-reference="true"/>', decodeSeedanceFrameVideoSurface), /requires last-frame/);
+ await assert.rejects(decode('<seedance:FrameVideo id="bad" model="mini" prompt={direction} duration="6" first-frame={first.image} first-frame-person-reference="true" last-frame-person-reference="true"/>', decodeSeedanceFrameVideoSurface), /requires last-frame/);
+});
+
+test("every supplied visual requires classification, while absent frames and audio do not", async () => {
+ for (const kind of ["image", "video"]) {
+ await assert.rejects(decode(`<seedance:ReferenceVideo id="bad" model="mini" prompt={direction} duration="6"><seedance:Reference ${kind}={generated.image}/></seedance:ReferenceVideo>`, decodeSeedanceReferenceVideoSurface), /person-reference is required/);
+ }
+ await assert.rejects(decode('<seedance:FrameVideo id="bad" model="fast" prompt={direction} duration="5" first-frame={first.image}/>', decodeSeedanceFrameVideoSurface), /first-frame-person-reference is required/);
+ await assert.rejects(decode('<seedance:FrameVideo id="bad" model="fast" prompt={direction} duration="5" first-frame={first.image} first-frame-person-reference="false" last-frame={last.image}/>', decodeSeedanceFrameVideoSurface), /last-frame-person-reference is required/);
+ const firstOnly = await decode('<seedance:FrameVideo id="first" model="fast" prompt={direction} duration="5" first-frame={first.image} first-frame-person-reference="false"/>', decodeSeedanceFrameVideoSurface);
+ assert.equal(firstOnly.records.filter((record) => record.id.endsWith(".binding")).length, 1);
+ const audioOnly = await decode('<seedance:ReferenceVideo id="voice" model="2.5" prompt={direction} duration="5"><seedance:Reference audio={voice.audio}/></seedance:ReferenceVideo>', decodeSeedanceReferenceVideoSurface);
+ const binding = audioOnly.records.find((record) => record.id.endsWith(".binding"))!;
+ assert.deepEqual(binding.value.kind === "inline" ? binding.value.value : null, { role: "audio" });
});
diff --git a/packages/seedance/test/validation.test.ts b/packages/seedance/test/validation.test.ts
index 8264bbfe..cb2ff171 100644
--- a/packages/seedance/test/validation.test.ts
+++ b/packages/seedance/test/validation.test.ts
@@ -17,7 +17,7 @@ const audio = (mediaType: string): BlobRef => ({
const settings = {
prompt: ["A presenter explains the scene"], resolution: ["720p"], aspectRatio: ["9:16"],
duration: [5], generateAudio: [true], webSearch: [false],
- referenceImage: [{ role: "image" as const, artifact: {
+ referenceImage: [{ role: "image" as const, fields: { personReference: true }, artifact: {
kind: "blob" as const, resource: fixtureResource("reference-image"), size: 4, mediaType: "image/png",
} }],
};
@@ -57,8 +57,16 @@ for (const [model, endpoint] of Object.entries(seedanceEndpointsByModel)) {
const role = port === "referenceVideo" ? "video" : "image";
const artifact = { ...referenceImage[0]!.artifact, mediaType: role === "video" ? "video/mp4" : "image/png" };
const initial = { ...scalars, ...(port === "lastFrame" ? { firstFrame: referenceImage } : {}) };
- for (const flag of [true, false, undefined]) {
- const binding = { role, ...(flag === undefined ? {} : { fields: { personReference: flag } }) };
+ for (const fields of [undefined, {}, { personReference: "true" }]) {
+ const binding = { role, ...(fields === undefined ? {} : { fields }) };
+ assert.throws(() => endpoint.sealRequest({ ...initial, [port]: [{ ...binding, artifact }] }), /personReference/);
+ await assert.rejects(produce(endpoint.mediaBindings[port]!.producer, {
+ draft: input(inline(sealGenerationRequestDraft(endpoint.ports, initial))),
+ binding: input(inline(binding)), artifact: input(artifact),
+ }), /personReference/);
+ }
+ for (const flag of [true, false]) {
+ const binding = { role, fields: { personReference: flag } };
const bound = await produce(endpoint.mediaBindings[port]!.producer, {
draft: input(inline(sealGenerationRequestDraft(endpoint.ports, initial))),
binding: input(inline(binding)), artifact: input(artifact),
diff --git a/skills/hypit/references/environment/model-and-provider.md b/skills/hypit/references/environment/model-and-provider.md
index e3842829..9f4dac30 100644
--- a/skills/hypit/references/environment/model-and-provider.md
+++ b/skills/hypit/references/environment/model-and-provider.md
@@ -232,7 +232,7 @@ Follow one actual request:
Locate the complete `examples/provider-package/README.md` through `hypit paths`. Use its
`provider-images` or `provider-videos` package according to the request shape. The video example
-covers image/video/audio references, first/last frames, optional person classification and separate
+covers image/video/audio references, first/last frames, required visual-reference person classification and separate
result collection. Its mappings, limits and transport are examples to adapt, not a new shared API.
Implement only the service capabilities this work needs.
diff --git a/skills/hypit/references/playbooks/craft/video-direction.md b/skills/hypit/references/playbooks/craft/video-direction.md
index c3bd48a2..2d80a5a9 100644
--- a/skills/hypit/references/playbooks/craft/video-direction.md
+++ b/skills/hypit/references/playbooks/craft/video-direction.md
@@ -35,7 +35,10 @@ Its range follows the relationship to preserve, the intended new duration and th
reference limits. Connect the actual footage in Source; describing it in prose does not supply
its temporal behavior to the model. The selected model and Provider determine supported combinations
and media requirements; read their installed vocabulary and package documentation for the exact
-request, including any person-reference metadata.
+request. Seedance requires `person-reference="true|false"` on each image/video reference: true if
+the supplied material contains a person, false otherwise.
+Inspect the selected excerpt, not just its first frame. Audio must omit the field; the installed
+Seedance README owns the corresponding required first/last-frame attributes.
For a longer action, distinguish the duration of source footage the model can accept from the
duration it can produce in one request. Use one request when the model's capability and the work's
diff --git a/skills/hypit/references/production/vocabulary.md b/skills/hypit/references/production/vocabulary.md
index 7f96fc4d..70f91da0 100644
--- a/skills/hypit/references/production/vocabulary.md
+++ b/skills/hypit/references/production/vocabulary.md
@@ -44,9 +44,9 @@ package-local Fragment documentation for those inputs and exports.
Read the model Surface's reference roles and per-input metadata as well as its prompt parameters.
The prompt gives direction; the actual edges supply media and the declared facts needed to use it.
-For example, Seedance's `person-reference="true"` identifies a supplied image/video containing a
-person or generated human likeness; false describes a reference without it, and audio has no such
-visual field. Its installed README owns the exact Reference and frame-mode forms. The
+Seedance requires `person-reference="true|false"` on every image/video reference: true if the supplied
+material contains a person, false otherwise. Audio must omit it. Its installed README owns the required
+first/last-frame forms. The
[Provider](../environment/model-and-provider.md) translates these facts into the selected service's
media preparation without adding service instructions to the creative prompt.