zyc/video-shuoshan
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Compare commits

base: zyc:main
Branches Tags
zyc:main
zyc:dev
zyc:master
zyc:temp4.17
zyc:temptudou
zyc:v1.2.0
zyc:v1.0.0
zyc:tempTest
..
compare: zyc:temptudou
Branches Tags
zyc:dev
zyc:main
zyc:master
zyc:temp4.17
zyc:temptudou
zyc:v1.2.0
zyc:v1.0.0
zyc:tempTest

No commits in common. "main" and "temptudou" have entirely different histories.
main ... temptudou

49 changed files with 534 additions and 34829 deletions
Show Stats Expand all files Collapse all files

210
.gitea/workflows/deploy.yaml
View File

@ -3,172 +3,102 @@ name: Build and Deploy
on:
push:
branches:
- main
- master
- dev
jobs:
build-and-deploy:
runs-on: ubuntu-latest
steps:
- name: Checkout
run: |
git clone --depth=1 --branch=${{ github.ref_name }} https://gitea.airlabs.art/${{ github.repository }}.git .
uses: actions/checkout@v3
- name: Set environment by branch
run: |
SHORT_SHA=$(echo "${{ github.sha }}" | cut -c1-7)
BUILD_DATE=$(date +%Y%m%d)
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v2
with:
config-inline: |
[registry."docker.io"]
mirrors = ["https://docker.m.daocloud.io", "https://docker.1panel.live", "https://hub.rat.dev"]
if [[ "${{ github.ref_name }}" == "master" ]]; then
echo "IMAGE_TAG=prod-${BUILD_DATE}-${SHORT_SHA}" >> $GITHUB_ENV
echo "CR_SERVER_ACTIVE=gitea-prod-cn-shanghai.cr.volces.com" >> $GITHUB_ENV
echo "CR_USERNAME_ACTIVE=seaislee@76339115" >> $GITHUB_ENV
echo "CR_PASSWORD_ACTIVE=${{ secrets.CR_PROD_PASSWORD }}" >> $GITHUB_ENV
echo "CR_ORG=prod" >> $GITHUB_ENV
echo "DEPLOY_ENV=production" >> $GITHUB_ENV
echo "DOMAIN_API=airflow-studio-api.airlabs.art" >> $GITHUB_ENV
echo "DOMAIN_WEB=airflow-studio.airlabs.art" >> $GITHUB_ENV
echo "REDIS_URL=redis://zyc:Zyc188208@redis-shzlf5t46gjvow7ua.redis.ivolces.com:6379/0" >> $GITHUB_ENV
elif [[ "${{ github.ref_name }}" == "dev" ]]; then
echo "IMAGE_TAG=dev-${BUILD_DATE}-${SHORT_SHA}" >> $GITHUB_ENV
echo "CR_SERVER_ACTIVE=${{ secrets.CR_SERVER }}" >> $GITHUB_ENV
echo "CR_USERNAME_ACTIVE=${{ secrets.CR_USERNAME }}" >> $GITHUB_ENV
echo "CR_PASSWORD_ACTIVE=${{ secrets.CR_PASSWORD }}" >> $GITHUB_ENV
echo "CR_ORG=dev" >> $GITHUB_ENV
echo "DEPLOY_ENV=development" >> $GITHUB_ENV
echo "DOMAIN_API=airflow-studio-api.test.airlabs.art" >> $GITHUB_ENV
echo "DOMAIN_WEB=airflow-studio.test.airlabs.art" >> $GITHUB_ENV
echo "REDIS_URL=redis://zyc:Zyc188208@redis-shzlsczo52dft8mia.redis.ivolces.com:6379/0" >> $GITHUB_ENV
fi
- name: Login to Volcano Engine CR
run: |
echo "${{ env.CR_PASSWORD_ACTIVE }}" | docker login --username "${{ env.CR_USERNAME_ACTIVE }}" --password-stdin ${{ env.CR_SERVER_ACTIVE }}
- name: Login to Huawei Cloud SWR
uses: docker/login-action@v2
with:
registry: ${{ secrets.SWR_SERVER }}
username: ${{ secrets.SWR_USERNAME }}
password: ${{ secrets.SWR_PASSWORD }}
- name: Build and Push Backend
id: build_backend
run: |
set -o pipefail
for attempt in 1 2 3; do
echo "Build backend attempt $attempt/3..."
DOCKER_BUILDKIT=0 docker build \
--tag ${{ env.CR_SERVER_ACTIVE }}/${{ env.CR_ORG }}/video-backend:${{ env.IMAGE_TAG }} \
--tag ${{ env.CR_SERVER_ACTIVE }}/${{ env.CR_ORG }}/video-backend:latest \
./backend 2>&1 | tee /tmp/build.log && break
echo "Attempt $attempt failed, retrying in 10s..." && sleep 10
done
for attempt in 1 2 3; do
docker push ${{ env.CR_SERVER_ACTIVE }}/${{ env.CR_ORG }}/video-backend:${{ env.IMAGE_TAG }} && \
docker push ${{ env.CR_SERVER_ACTIVE }}/${{ env.CR_ORG }}/video-backend:latest && break
echo "Push attempt $attempt failed, retrying in 10s..." && sleep 10
done
docker buildx build \
--push \
--no-cache \
--provenance=false \
--tag ${{ secrets.SWR_SERVER }}/${{ secrets.SWR_ORG }}/video-backend:latest \
./backend 2>&1 | tee /tmp/build.log
- name: Build and Push Web
id: build_web
run: |
set -o pipefail
for attempt in 1 2 3; do
echo "Build web attempt $attempt/3..."
DOCKER_BUILDKIT=0 docker build \
--tag ${{ env.CR_SERVER_ACTIVE }}/${{ env.CR_ORG }}/video-web:${{ env.IMAGE_TAG }} \
--tag ${{ env.CR_SERVER_ACTIVE }}/${{ env.CR_ORG }}/video-web:latest \
./web 2>&1 | tee -a /tmp/build.log && break
echo "Attempt $attempt failed, retrying in 10s..." && sleep 10
done
for attempt in 1 2 3; do
docker push ${{ env.CR_SERVER_ACTIVE }}/${{ env.CR_ORG }}/video-web:${{ env.IMAGE_TAG }} && \
docker push ${{ env.CR_SERVER_ACTIVE }}/${{ env.CR_ORG }}/video-web:latest && break
echo "Push attempt $attempt failed, retrying in 10s..." && sleep 10
done
docker buildx build \
--push \
--provenance=false \
--tag ${{ secrets.SWR_SERVER }}/${{ secrets.SWR_ORG }}/video-web:latest \
./web 2>&1 | tee -a /tmp/build.log
- name: Setup Kubectl
- name: Setup SSH
run: |
if ! command -v kubectl &>/dev/null; then
for attempt in 1 2 3; do
curl -LO "https://files.m.daocloud.io/dl.k8s.io/release/v1.28.0/bin/linux/amd64/kubectl" && break
echo "Download attempt $attempt failed, retrying in 5s..." && sleep 5
done
chmod +x kubectl && mv kubectl /usr/bin/kubectl
fi
kubectl version --client
mkdir -p ~/.ssh
echo "${{ secrets.K3S_SSH_KEY }}" > ~/.ssh/id_rsa
chmod 600 ~/.ssh/id_rsa
ssh-keyscan -H ${{ secrets.K3S_HOST }} >> ~/.ssh/known_hosts 2>/dev/null
- name: Set kubeconfig
run: |
mkdir -p $HOME/.kube
if [[ "${{ github.ref_name }}" == "master" ]]; then
printf '%s\n' '${{ secrets.VOLCANO_PROD_KUBE_CONFIG }}' > $HOME/.kube/config
elif [[ "${{ github.ref_name }}" == "dev" ]]; then
printf '%s\n' '${{ secrets.VOLCANO_TEST_KUBE_CONFIG }}' > $HOME/.kube/config
fi
chmod 600 $HOME/.kube/config
echo "kubeconfig lines: $(wc -l < $HOME/.kube/config)"
grep server $HOME/.kube/config || echo "WARNING: no server found in kubeconfig"
- name: Deploy to K3s
- name: Deploy to K3s via SSH
id: deploy
run: |
echo "Environment: ${{ env.DEPLOY_ENV }}"
CR_IMAGE="${{ env.CR_SERVER_ACTIVE }}/${{ env.CR_ORG }}"
SWR_IMAGE="${{ secrets.SWR_SERVER }}/${{ secrets.SWR_ORG }}"
# Replace image placeholders
sed -i "s|\${CI_REGISTRY_IMAGE}/video-backend:latest|${CR_IMAGE}/video-backend:${{ env.IMAGE_TAG }}|g" k8s/backend-deployment.yaml
sed -i "s|\${CI_REGISTRY_IMAGE}/video-backend:latest|${CR_IMAGE}/video-backend:${{ env.IMAGE_TAG }}|g" k8s/celery-deployment.yaml
sed -i "s|\${CI_REGISTRY_IMAGE}/video-web:latest|${CR_IMAGE}/video-web:${{ env.IMAGE_TAG }}|g" k8s/web-deployment.yaml
# Replace image placeholders in yaml files
sed -i "s|\${CI_REGISTRY_IMAGE}/video-backend:latest|${SWR_IMAGE}/video-backend:latest|g" k8s/backend-deployment.yaml
sed -i "s|\${CI_REGISTRY_IMAGE}/video-backend:latest|${SWR_IMAGE}/video-backend:latest|g" k8s/celery-deployment.yaml
sed -i "s|\${CI_REGISTRY_IMAGE}/video-web:latest|${SWR_IMAGE}/video-web:latest|g" k8s/web-deployment.yaml
# Replace domain placeholders in ingress
sed -i "s|airflow-studio-api.airlabs.art|${{ env.DOMAIN_API }}|g" k8s/ingress.yaml
sed -i "s|airflow-studio.airlabs.art|${{ env.DOMAIN_WEB }}|g" k8s/ingress.yaml
# Copy k8s manifests to server
scp -o StrictHostKeyChecking=no k8s/backend-deployment.yaml k8s/web-deployment.yaml k8s/ingress.yaml k8s/celery-deployment.yaml root@${{ secrets.K3S_HOST }}:/tmp/
# Replace DB config for production
if [[ "${{ env.DEPLOY_ENV }}" == "production" ]]; then
sed -i "s|mysql8351f937d637.rds.ivolces.com|mysqld9bb4e81696d.rds.ivolces.com|g" k8s/backend-deployment.yaml
sed -i "s|mysql8351f937d637.rds.ivolces.com|mysqld9bb4e81696d.rds.ivolces.com|g" k8s/celery-deployment.yaml
fi
# Create/update secrets and apply manifests on server
set -o pipefail
ssh -o StrictHostKeyChecking=no root@${{ secrets.K3S_HOST }} << ENDSSH
export KUBECONFIG=/etc/rancher/k3s/k3s.yaml
# Replace CORS origin
sed -i "s|https://airflow-studio.airlabs.art|https://${{ env.DOMAIN_WEB }}|g" k8s/backend-deployment.yaml
kubectl create secret generic video-backend-secrets \
--from-literal=ARK_API_KEY='${{ secrets.ARK_API_KEY }}' \
--from-literal=TOS_ACCESS_KEY='${{ secrets.TOS_ACCESS_KEY }}' \
--from-literal=TOS_SECRET_KEY='${{ secrets.TOS_SECRET_KEY }}' \
--from-literal=DJANGO_SECRET_KEY='${{ secrets.DJANGO_SECRET_KEY }}' \
--from-literal=DB_HOST='${{ secrets.DB_HOST }}' \
--from-literal=DB_USER='${{ secrets.DB_USER }}' \
--from-literal=DB_PASSWORD='${{ secrets.DB_PASSWORD }}' \
--from-literal=ALIYUN_SMS_ACCESS_KEY='${{ secrets.ALIYUN_SMS_ACCESS_KEY }}' \
--from-literal=ALIYUN_SMS_ACCESS_SECRET='${{ secrets.ALIYUN_SMS_ACCESS_SECRET }}' \
--dry-run=client -o yaml | kubectl apply -f -
# Replace Redis URL by environment
sed -i "s|redis://zyc:Zyc188208@redis-shzlsczo52dft8mia.redis.ivolces.com:6379/0|${{ env.REDIS_URL }}|g" k8s/backend-deployment.yaml
sed -i "s|redis://zyc:Zyc188208@redis-shzlsczo52dft8mia.redis.ivolces.com:6379/0|${{ env.REDIS_URL }}|g" k8s/celery-deployment.yaml
kubectl apply -f /tmp/backend-deployment.yaml
kubectl apply -f /tmp/celery-deployment.yaml
kubectl apply -f /tmp/web-deployment.yaml
kubectl apply -f /tmp/ingress.yaml
# All kubectl operations with retry (K3s 内网连接可能抖动)
for attempt in 1 2 3; do
echo "Deploy attempt $attempt/3..."
{
# Create/update image pull secret for CR
kubectl create secret docker-registry cr-pull-secret \
--docker-server="${{ env.CR_SERVER_ACTIVE }}" \
--docker-username="${{ env.CR_USERNAME_ACTIVE }}" \
--docker-password="${{ env.CR_PASSWORD_ACTIVE }}" \
--dry-run=client -o yaml | kubectl apply -f -
# Preserve real client IP: disable SNAT on Traefik
kubectl patch svc traefik -n kube-system -p '{"spec":{"externalTrafficPolicy":"Local"}}' 2>/dev/null || true
# Create/update secrets (业务密钥，DB 已写在 yaml 里)
kubectl create secret generic video-backend-secrets \
--from-literal=ARK_API_KEY='${{ secrets.ARK_API_KEY }}' \
--from-literal=TOS_ACCESS_KEY='${{ secrets.TOS_ACCESS_KEY }}' \
--from-literal=TOS_SECRET_KEY='${{ secrets.TOS_SECRET_KEY }}' \
--from-literal=DJANGO_SECRET_KEY='${{ secrets.DJANGO_SECRET_KEY }}' \
--from-literal=ALIYUN_SMS_ACCESS_KEY='${{ secrets.ALIYUN_SMS_ACCESS_KEY }}' \
--from-literal=ALIYUN_SMS_ACCESS_SECRET='${{ secrets.ALIYUN_SMS_ACCESS_SECRET }}' \
--dry-run=client -o yaml | kubectl apply -f -
kubectl rollout restart deployment/video-backend
kubectl rollout restart deployment/celery-worker
kubectl rollout restart deployment/video-web
# Apply manifests
kubectl apply -f k8s/backend-deployment.yaml
kubectl apply -f k8s/celery-deployment.yaml
kubectl apply -f k8s/web-deployment.yaml
kubectl apply -f k8s/ingress.yaml
# Preserve real client IP
kubectl patch svc traefik -n kube-system -p '{"spec":{"externalTrafficPolicy":"Local"}}' 2>/dev/null || true
kubectl rollout restart deployment/video-backend
kubectl rollout restart deployment/celery-worker
kubectl rollout restart deployment/video-web
} 2>&1 | tee /tmp/deploy.log && break
echo "Attempt $attempt failed, retrying in 10s..."
sleep 10
done
rm -f /tmp/backend-deployment.yaml /tmp/web-deployment.yaml /tmp/ingress.yaml /tmp/celery-deployment.yaml
ENDSSH
# ===== Log Center: failure reporting =====
- name: Report failure to Log Center
@ -207,7 +137,7 @@ jobs:
-H "Content-Type: application/json" \
-d "{
\"project_id\": \"video_backend\",
\"environment\": \"${{ env.DEPLOY_ENV }}\",
\"environment\": \"${{ github.ref_name }}\",
\"level\": \"ERROR\",
\"source\": \"${SOURCE}\",
\"commit_hash\": \"${{ github.sha }}\",
@ -228,13 +158,3 @@ jobs:
\"run_url\": \"https://gitea.airlabs.art/${{ github.repository }}/actions/runs/${{ github.run_number }}\"
}
}" || true
# ===== Cleanup: remove unused Docker resources =====
- name: Docker Cleanup
if: always()
run: |
docker container prune -f
docker image prune -a -f
docker builder prune -a -f
echo "Disk usage after cleanup:"
df -h / | tail -1

5
backend/Dockerfile
View File

@ -1,4 +1,4 @@
FROM docker.m.daocloud.io/python:3.12-slim
FROM python:3.12-slim
ENV PYTHONDONTWRITEBYTECODE=1
ENV PYTHONUNBUFFERED=1
@ -11,7 +11,6 @@ RUN sed -i 's/deb.debian.org/mirrors.aliyun.com/g' /etc/apt/sources.list.d/debia
gcc \
default-libmysqlclient-dev \
pkg-config \
ffmpeg \
&& rm -rf /var/lib/apt/lists/*
# Python dependencies
@ -30,4 +29,4 @@ RUN chmod +x /app/entrypoint.sh
EXPOSE 8000
ENTRYPOINT ["/app/entrypoint.sh"]
CMD ["gunicorn", "--bind", "0.0.0.0:8000", "--workers", "2", "--worker-class", "gevent", "--worker-connections", "200", "--timeout", "120", "--access-logfile", "-", "--error-logfile", "-", "config.wsgi:application"]
CMD ["gunicorn", "--bind", "0.0.0.0:8000", "--workers", "2", "--timeout", "120", "--access-logfile", "-", "--error-logfile", "-", "config.wsgi:application"]

23
backend/apps/generation/migrations/0017_add_asset_type.py
View File

@ -1,23 +0,0 @@
# Generated by Django 4.2.29 on 2026-04-04 05:39
from django.db import migrations, models
class Migration(migrations.Migration):
dependencies = [
('generation', '0016_add_is_deleted_to_generationrecord'),
]
operations = [
migrations.AddField(
model_name='asset',
name='asset_type',
field=models.CharField(choices=[('Image', '图像'), ('Video', '视频'), ('Audio', '音频')], default='Image', max_length=10, verbose_name='素材类型'),
),
migrations.AlterField(
model_name='asset',
name='url',
field=models.CharField(blank=True, default='', max_length=1000, verbose_name='素材URL'),
),
]

28
backend/apps/generation/migrations/0018_add_thumbnail_and_duration.py
View File

@ -1,28 +0,0 @@
# Generated by Django 4.2.29 on 2026-04-04 09:02
from django.db import migrations, models
class Migration(migrations.Migration):
dependencies = [
('generation', '0017_add_asset_type'),
]
operations = [
migrations.AddField(
model_name='asset',
name='duration',
field=models.FloatField(default=0, verbose_name='时长（秒）'),
),
migrations.AddField(
model_name='asset',
name='thumbnail_url',
field=models.CharField(blank=True, default='', max_length=1000, verbose_name='缩略图URL'),
),
migrations.AddField(
model_name='generationrecord',
name='thumbnail_url',
field=models.CharField(blank=True, default='', max_length=1000, verbose_name='视频缩略图URL'),
),
]

18
backend/apps/generation/migrations/0019_duration_nullable.py
View File

@ -1,18 +0,0 @@
# Generated by Django 4.2.29 on 2026-04-04 17:59
from django.db import migrations, models
class Migration(migrations.Migration):
dependencies = [
('generation', '0018_add_thumbnail_and_duration'),
]
operations = [
migrations.AlterField(
model_name='asset',
name='duration',
field=models.FloatField(default=None, null=True, verbose_name='时长（秒）'),
),
]

13
backend/apps/generation/models.py
View File

@ -42,7 +42,6 @@ class GenerationRecord(models.Model):
resolution = models.CharField(max_length=10, blank=True, default='', verbose_name='分辨率')
status = models.CharField(max_length=20, choices=STATUS_CHOICES, default='queued', verbose_name='状态')
result_url = models.CharField(max_length=1000, blank=True, default='', verbose_name='生成结果URL')
thumbnail_url = models.CharField(max_length=1000, blank=True, default='', verbose_name='视频缩略图URL')
error_message = models.TextField(blank=True, default='', verbose_name='错误信息')
raw_error = models.TextField(blank=True, default='', verbose_name='原始错误信息')
reference_urls = models.JSONField(default=list, blank=True, verbose_name='参考素材信息')
@ -137,17 +136,12 @@ class AssetGroup(models.Model):
class Asset(models.Model):
"""虚拟人像素材 — 图片/视频/音频。"""
"""虚拟人像素材 — 单张图片。"""
STATUS_CHOICES = [
('processing', '处理中'),
('active', '可用'),
('failed', '失败'),
]
ASSET_TYPE_CHOICES = [
('Image', '图像'),
('Video', '视频'),
('Audio', '音频'),
]
group = models.ForeignKey(
AssetGroup, on_delete=models.CASCADE,
@ -155,10 +149,7 @@ class Asset(models.Model):
)
remote_asset_id = models.CharField(max_length=100, default='', verbose_name='火山Asset ID')
name = models.CharField(max_length=100, default='', verbose_name='素材名称')
url = models.CharField(max_length=1000, blank=True, default='', verbose_name='素材URL')
asset_type = models.CharField(max_length=10, choices=ASSET_TYPE_CHOICES, default='Image', verbose_name='素材类型')
thumbnail_url = models.CharField(max_length=1000, blank=True, default='', verbose_name='缩略图URL')
duration = models.FloatField(null=True, default=None, verbose_name='时长（秒）')
url = models.CharField(max_length=1000, blank=True, default='', verbose_name='图片URL')
status = models.CharField(max_length=20, choices=STATUS_CHOICES, default='processing', verbose_name='状态')
error_message = models.CharField(max_length=500, blank=True, default='', verbose_name='错误信息')
created_at = models.DateTimeField(auto_now_add=True, verbose_name='创建时间')

216
backend/apps/generation/tasks.py
View File

@ -1,40 +1,27 @@
"""Celery tasks for async video generation polling."""
import logging
import time
from celery import shared_task
logger = logging.getLogger(__name__)
# 固定轮询间隔：全程每 5 秒（RPM 12000 足够，400 并发仅用 40%）
POLL_INTERVAL = 5
@shared_task(ignore_result=True)
def poll_video_task(record_id):
"""Poll Volcano API once for a video generation task.
一次性任务：查一次 API，更新 DB，结束。
由 recover_stuck_tasks（beat 每10秒调度）统一驱动，不再自己 retry。
用 Redis 锁防止 _handle_completed 期间被重复 dispatch。
@shared_task(bind=True, max_retries=0, ignore_result=True)
def poll_video_task(self, record_id):
"""Poll Volcano API for a video generation task until it reaches a terminal state.
This is the server-side counterpart to the frontend polling.
It runs independently of the browser — even if the user closes the page,
this task keeps polling until Volcano returns completed or failed.
"""
from django.core.cache import cache
# Redis 锁：防止同一 record 被并发处理（_handle_completed 耗时较长）
lock_key = f'poll_lock:{record_id}'
if not cache.add(lock_key, '1', timeout=120):
return
try:
_do_poll(record_id)
except Exception:
logger.exception('poll_video_task: unexpected error for record=%s', record_id)
finally:
cache.delete(lock_key)
def _do_poll(record_id):
"""实际轮询逻辑，由 poll_video_task 调用。"""
from django.utils import timezone
from apps.generation.models import GenerationRecord
from utils.airdrama_client import query_task, map_status
from utils.airdrama_client import query_task, map_status, extract_video_url, ERROR_MESSAGES
try:
record = GenerationRecord.objects.get(pk=record_id)
@ -42,81 +29,85 @@ def _do_poll(record_id):
logger.warning('poll_video_task: record %s not found', record_id)
return
if record.status not in ('queued', 'processing'):
return
ark_task_id = record.ark_task_id
if not ark_task_id:
logger.warning('poll_video_task: record %s has no ark_task_id', record_id)
return
# Poll Volcano API
try:
ark_resp = query_task(ark_task_id)
new_status = map_status(ark_resp.get('status', ''))
except Exception:
logger.exception('poll_video_task: API query failed for record=%s ark=%s', record_id, ark_task_id)
if record.status not in ('queued', 'processing'):
logger.info('poll_video_task: record %s already in terminal state: %s', record_id, record.status)
return
if new_status in ('queued', 'processing'):
elapsed = 0
logger.info('poll_video_task: start polling record=%s ark=%s', record_id, ark_task_id)
while True:
time.sleep(POLL_INTERVAL)
elapsed += POLL_INTERVAL
# Re-fetch record to check if frontend already updated it
try:
record.refresh_from_db()
except GenerationRecord.DoesNotExist:
logger.info('poll_video_task: record %s deleted during polling', record_id)
return
if record.status not in ('queued', 'processing'):
logger.info('poll_video_task: record %s resolved by frontend: %s', record_id, record.status)
return
# Poll Volcano API
try:
ark_resp = query_task(ark_task_id)
new_status = map_status(ark_resp.get('status', ''))
except Exception:
logger.exception('poll_video_task: API query failed for %s, will retry', ark_task_id)
continue # retry on next interval
if new_status in ('queued', 'processing'):
# Still running, update status and touch updated_at
record.status = new_status
record.save(update_fields=['status', 'updated_at'])
continue
# Terminal state reached — process result
record.status = new_status
record.save(update_fields=['status', 'updated_at'])
# Save seed
returned_seed = ark_resp.get('seed')
if returned_seed is not None:
record.seed = returned_seed
if new_status == 'completed':
_handle_completed(record, ark_resp)
elif new_status == 'failed':
_handle_failed(record, ark_resp)
record.completed_at = timezone.now()
record.save(update_fields=[
'status', 'result_url', 'error_message', 'raw_error',
'seed', 'completed_at',
])
logger.info(
'poll_video_task: record=%s ark=%s final_status=%s elapsed=%ds',
record_id, ark_task_id, new_status, elapsed,
)
return
# Terminal state reached — process result
record.status = new_status
returned_seed = ark_resp.get('seed')
if returned_seed is not None:
record.seed = returned_seed
if new_status == 'completed':
_handle_completed(record, ark_resp)
elif new_status == 'failed':
_handle_failed(record, ark_resp)
record.completed_at = timezone.now()
record.save(update_fields=[
'status', 'result_url', 'thumbnail_url', 'error_message', 'raw_error',
'seed', 'completed_at',
])
logger.info(
'poll_video_task: record=%s ark=%s final_status=%s',
record_id, ark_task_id, new_status,
)
def _handle_completed(record, ark_resp):
"""Process a completed task: persist video to TOS, extract thumbnail, settle payment."""
import os
"""Process a completed task: persist video to TOS and settle payment."""
from utils.airdrama_client import extract_video_url
video_url = extract_video_url(ark_resp)
if video_url:
# Download once to temp file, reuse for TOS upload + thumbnail extraction
tmp_path = None
try:
from utils.media_utils import download_to_temp, extract_video_info_from_file
from utils.tos_client import upload_from_file_path, upload_file
tmp_path = download_to_temp(video_url, '.mp4')
# Upload video to TOS from file (streaming, no full memory load)
record.result_url = upload_from_file_path(tmp_path, folder='results', content_type='video/mp4')
# Extract thumbnail from the same local file (no second download)
thumb_file, _ = extract_video_info_from_file(tmp_path)
if thumb_file:
record.thumbnail_url = upload_file(thumb_file, folder='thumbnails')
from utils.tos_client import upload_from_url
record.result_url = upload_from_url(video_url, folder='results')
except Exception:
logger.exception('poll_video_task: failed to persist video / extract thumbnail')
if not record.result_url:
record.result_url = video_url
record.error_message = '视频保存失败，临时链接将在24小时后过期，请联系管理员'
finally:
if tmp_path and os.path.exists(tmp_path):
os.unlink(tmp_path)
logger.exception('poll_video_task: failed to persist video to TOS')
record.result_url = video_url
# 结算：按实际 tokens 扣费
usage = ark_resp.get('usage', {})
@ -131,27 +122,29 @@ def _handle_completed(record, ark_resp):
@shared_task(ignore_result=True)
def recover_stuck_tasks():
"""每30秒扫一次所有进行中的任务，统一派发轮询。
poll_video_task 是一次性任务，不再自己 retry，由这里统一驱动。
"""
"""定时扫描卡在 processing/queued 超过 10 分钟的任务，重新派发轮询。"""
from datetime import timedelta
from django.utils import timezone
from apps.generation.models import GenerationRecord
active_records = GenerationRecord.objects.filter(
cutoff = timezone.now() - timedelta(minutes=10)
stuck_records = GenerationRecord.objects.filter(
status__in=('queued', 'processing'),
ark_task_id__isnull=False,
).exclude(ark_task_id='').values_list('id', flat=True)
updated_at__lt=cutoff, # updated_at 超过 10 分钟没更新，说明没有 worker 在轮询
).exclude(ark_task_id='')
count = 0
for record_id in active_records:
for record in stuck_records:
logger.warning('recover_stuck_tasks: re-dispatching record=%s ark=%s', record.id, record.ark_task_id)
try:
poll_video_task.delay(record_id)
poll_video_task.delay(record.id)
count += 1
except Exception:
logger.error('recover_stuck_tasks: failed to dispatch record=%s', record_id)
logger.error('recover_stuck_tasks: failed to dispatch record=%s', record.id)
if count:
logger.info('recover_stuck_tasks: dispatched %d active tasks', count)
logger.info('recover_stuck_tasks: re-dispatched %d stuck tasks', count)
def _handle_failed(record, ark_resp):
@ -172,44 +165,3 @@ def _handle_failed(record, ark_resp):
else:
from apps.generation.views import _release_freeze
_release_freeze(record)
@shared_task(ignore_result=True)
def process_asset_media(asset_id):
"""Extract thumbnail + duration for video/audio assets asynchronously."""
from apps.generation.models import Asset
try:
asset = Asset.objects.select_related('group').get(pk=asset_id)
except Asset.DoesNotExist:
logger.warning('process_asset_media: asset %s not found', asset_id)
return
from utils.media_utils import extract_video_info, get_audio_duration
from utils.tos_client import upload_file
if asset.asset_type == 'Video':
thumb_file, dur = extract_video_info(asset.url)
if thumb_file:
try:
asset.thumbnail_url = upload_file(thumb_file, folder='thumbnails')
except Exception:
logger.exception('process_asset_media: thumbnail upload failed for asset %s', asset_id)
asset.duration = dur if dur > 0 else None # None = ffprobe failed, frontend skips duration check
asset.save(update_fields=['thumbnail_url', 'duration'])
# Atomic update: only set group thumbnail if still empty (concurrent-safe)
from apps.generation.models import AssetGroup
from django.db import transaction
try:
with transaction.atomic():
group = AssetGroup.objects.select_for_update().get(pk=asset.group_id)
if not group.thumbnail_url and asset.thumbnail_url:
group.thumbnail_url = asset.thumbnail_url
group.save(update_fields=['thumbnail_url'])
except AssetGroup.DoesNotExist:
logger.warning('process_asset_media: group %s deleted, skipping thumbnail update', asset.group_id)
elif asset.asset_type == 'Audio':
dur = get_audio_duration(asset.url)
asset.duration = dur if dur > 0 else None
asset.save(update_fields=['duration'])
logger.info('process_asset_media: asset %s done (type=%s, dur=%s)', asset_id, asset.asset_type, asset.duration)

440
backend/apps/generation/views.py
View File

@ -32,7 +32,7 @@ User = get_user_model()
logger = logging.getLogger(__name__)
# File validation constants
ALLOWED_IMAGE_EXTS = {'jpeg', 'jpg', 'png', 'webp', 'bmp', 'tiff', 'gif', 'heic', 'heif'}
ALLOWED_IMAGE_EXTS = {'jpeg', 'jpg', 'png', 'webp', 'bmp', 'tiff', 'gif'}
ALLOWED_VIDEO_EXTS = {'mp4', 'mov'}
ALLOWED_AUDIO_EXTS = {'mp3', 'wav'}
MAX_IMAGE_SIZE = 30 * 1024 * 1024 # 30MB
@ -287,39 +287,37 @@ def video_generate_view(request):
reference_snapshots = []
content_items = []
seen_urls = set() # 去重：同一个素材只引用一次
_asset_cache = {} # group_id → [(asset_url, asset_type), ...]，避免同一素材组重复查询
_asset_cache = {} # group_id → resolved_url，避免同一素材组重复查询
from .models import Asset as AssetModel
def _resolve_asset_group_all(gid, lbl):
"""查询本地 DB 获取组内所有 active 素材，返回 [(asset_url, asset_type), ...] 列表。
processing 的素材会尝试实时刷新状态。"""
assets = list(AssetModel.objects.filter(
group_id=gid, group__team=team, status__in=['active', 'processing']
).exclude(remote_asset_id='').order_by('created_at'))
if not assets:
logger.warning('No assets found for group %s (label=%s)', gid, lbl)
return []
resolved_list = []
for asset in assets:
# 本地 processing → 实时查火山刷新
if asset.status == 'processing':
result, _ = _assets_api_call(assets_client.get_asset, asset.remote_asset_id)
if result and result.get('Status') == 'Active':
asset.status = 'active'
asset.url = result.get('Url', asset.url)
asset.save(update_fields=['status', 'url'])
logger.info('Asset %s refreshed to active from Volcano', asset.remote_asset_id)
else:
logger.warning('Asset %s still processing, skipped', asset.remote_asset_id)
continue # 跳过未就绪的素材
aid = asset.remote_asset_id
if aid.startswith('Asset-'):
aid = 'asset-' + aid[6:]
resolved_url = f'asset://{aid}'
resolved_list.append((resolved_url, asset.asset_type))
logger.info('Asset group %s resolved: %d assets', gid, len(resolved_list))
return resolved_list
def _resolve_asset_group(gid, lbl):
"""查询本地 DB + 必要时刷新火山状态，返回 Asset://xxx 或原始 asset:// URL。"""
asset = AssetModel.objects.filter(
group_id=gid, status__in=['active', 'processing']
).order_by(
Case(When(status='active', then=0), default=1)
).first()
if not asset or not asset.remote_asset_id:
logger.warning('No asset found for group %s (label=%s)', gid, lbl)
return f'asset://group-{gid}'
# 本地 processing → 实时查火山刷新
if asset.status == 'processing':
result, _ = _assets_api_call(assets_client.get_asset, asset.remote_asset_id)
if result and result.get('Status') == 'Active':
asset.status = 'active'
asset.url = result.get('Url', asset.url)
asset.save(update_fields=['status', 'url'])
logger.info('Asset %s refreshed to active from Volcano', asset.remote_asset_id)
else:
logger.warning('Asset %s still processing on Volcano', asset.remote_asset_id)
return f'asset://group-{gid}'
aid = asset.remote_asset_id
if aid.startswith('asset-'):
aid = 'Asset-' + aid[6:]
resolved = f'Asset://{aid}'
logger.info('Asset resolved: group=%s -> %s', gid, resolved)
return resolved
from utils import assets_client
@ -349,75 +347,30 @@ def video_generate_view(request):
snap['thumb_url'] = thumb_url
reference_snapshots.append(snap)
# 单素材引用：asset://local-{id} → 查 Asset 表 → 单个 content_item
if url.startswith('asset://local-'):
try:
asset_local_id = int(url.replace('asset://local-', ''))
asset_obj = AssetModel.objects.get(pk=asset_local_id, group__team=team)
if asset_obj.status != 'active':
return Response({
'error': 'asset_not_ready',
'message': f'素材「{label}」尚在处理中，请稍后重试',
}, status=status.HTTP_400_BAD_REQUEST)
if not asset_obj.remote_asset_id:
return Response({
'error': 'asset_not_ready',
'message': f'素材「{label}」尚未就绪，请稍后重试',
}, status=status.HTTP_400_BAD_REQUEST)
aid = asset_obj.remote_asset_id
if aid.startswith('Asset-'):
aid = 'asset-' + aid[6:]
resolved_asset_url = f'asset://{aid}'
if asset_obj.asset_type == 'Video':
content_items.append({'type': 'video_url', 'video_url': {'url': resolved_asset_url}, 'role': 'reference_video'})
elif asset_obj.asset_type == 'Audio':
content_items.append({'type': 'audio_url', 'audio_url': {'url': resolved_asset_url}, 'role': 'reference_audio'})
else:
content_items.append({'type': 'image_url', 'image_url': {'url': resolved_asset_url}, 'role': 'reference_image'})
except AssetModel.DoesNotExist:
return Response({
'error': 'asset_not_found',
'message': f'素材「{label}」不存在或已被删除',
}, status=status.HTTP_400_BAD_REQUEST)
except Exception as e:
logger.warning('Failed to resolve asset URL %s: %s', url, e)
return Response({
'error': 'asset_not_ready',
'message': f'素材「{label}」解析失败，请重试',
}, status=status.HTTP_400_BAD_REQUEST)
continue
# 向后兼容：asset://group-{id} → 展开为组内所有 active 素材
# 转换 asset://group-{id} 为火山 Asset://Asset-xxx 格式（仅用于 content_items）
resolved_url = url
if url.startswith('asset://group-'):
try:
group_id = int(url.replace('asset://group-', ''))
# 跨迭代缓存：同一 group_id 不重复查询/刷新
if group_id in _asset_cache:
asset_list = _asset_cache[group_id]
resolved_url = _asset_cache[group_id]
else:
asset_list = _resolve_asset_group_all(group_id, label)
_asset_cache[group_id] = asset_list
if not asset_list:
return Response({
'error': 'asset_not_ready',
'message': f'素材「{label}」尚未就绪，请在素材库中确认状态为"可用"后重试',
}, status=status.HTTP_400_BAD_REQUEST)
for asset_url, asset_type in asset_list:
if asset_type == 'Video':
content_items.append({'type': 'video_url', 'video_url': {'url': asset_url}, 'role': 'reference_video'})
elif asset_type == 'Audio':
content_items.append({'type': 'audio_url', 'audio_url': {'url': asset_url}, 'role': 'reference_audio'})
else:
content_items.append({'type': 'image_url', 'image_url': {'url': asset_url}, 'role': 'reference_image'})
resolved_url = _resolve_asset_group(group_id, label)
_asset_cache[group_id] = resolved_url
except Exception as e:
logger.warning('Failed to resolve asset group URL %s: %s', url, e)
return Response({
'error': 'asset_not_ready',
'message': f'素材「{label}」解析失败，请重试',
}, status=status.HTTP_400_BAD_REQUEST)
continue # 素材组已展开为多个 content_items，跳过下面的单项处理
# 未解析成功的 asset URL → 返回明确错误，不再静默跳过
if resolved_url.startswith('asset://'):
logger.error('Unresolved asset URL: %s (label=%s)', resolved_url, label)
return Response({
'error': 'asset_not_ready',
'message': f'素材「{label}」尚未就绪，请在素材库中确认状态为"可用"后重试',
}, status=status.HTTP_400_BAD_REQUEST)
if ref_type == 'image':
item = {'type': 'image_url', 'image_url': {'url': url}}
item = {'type': 'image_url', 'image_url': {'url': resolved_url}}
# API 文档要求：参考图模式下所有图片的 role 必须为 reference_image
if mode == 'universal':
item['role'] = 'reference_image'
@ -425,12 +378,12 @@ def video_generate_view(request):
item['role'] = role
content_items.append(item)
elif ref_type == 'video':
item = {'type': 'video_url', 'video_url': {'url': url}}
item = {'type': 'video_url', 'video_url': {'url': resolved_url}}
if role:
item['role'] = role
content_items.append(item)
elif ref_type == 'audio':
item = {'type': 'audio_url', 'audio_url': {'url': url}}
item = {'type': 'audio_url', 'audio_url': {'url': resolved_url}}
if role:
item['role'] = role
content_items.append(item)
@ -641,7 +594,6 @@ def _serialize_task(record):
'base_cost_amount': float(record.base_cost_amount),
'status': record.status,
'result_url': d.get('result_url', ''),
'thumbnail_url': d.get('thumbnail_url', ''),
'error_message': d.get('error_message', ''),
'reference_urls': d.get('reference_urls') or [],
'is_favorited': record.is_favorited,
@ -2971,36 +2923,12 @@ def _assets_api_call(func, *args, **kwargs):
)
def _detect_asset_type(file):
"""Detect asset type from file content_type. Returns ('Image'|'Video'|'Audio', error_response|None)."""
ct = (file.content_type or '').lower()
if ct.startswith('video/'):
if ct not in ('video/mp4', 'video/quicktime'):
return None, Response({'error': '仅支持 MP4 和 MOV 格式的视频'}, status=status.HTTP_400_BAD_REQUEST)
if file.size > MAX_VIDEO_SIZE:
return None, Response({'error': '视频文件不能超过 50MB'}, status=status.HTTP_400_BAD_REQUEST)
return 'Video', None
elif ct.startswith('audio/'):
if ct not in ('audio/mpeg', 'audio/wav'):
return None, Response({'error': '仅支持 MP3 和 WAV 格式的音频'}, status=status.HTTP_400_BAD_REQUEST)
if file.size > MAX_AUDIO_SIZE:
return None, Response({'error': '音频文件不能超过 15MB'}, status=status.HTTP_400_BAD_REQUEST)
return 'Audio', None
else:
ext = file.name.rsplit('.', 1)[-1].lower() if '.' in file.name else ''
if ext and ext not in ALLOWED_IMAGE_EXTS:
return None, Response({'error': f'不支持的图片格式: {ext}'}, status=status.HTTP_400_BAD_REQUEST)
if file.size > MAX_IMAGE_SIZE:
return None, Response({'error': '图片文件不能超过 30MB'}, status=status.HTTP_400_BAD_REQUEST)
return 'Image', None
@api_view(['GET', 'POST'])
@permission_classes([IsTeamMember])
@parser_classes([MultiPartParser, JSONParser])
def asset_groups_view(request):
"""GET /api/v1/assets/groups — list groups for current team.
POST /api/v1/assets/groups — create a group with an initial asset (image/video/audio).
POST /api/v1/assets/groups — create a group with an initial image.
"""
team = request.user.team
@ -3046,33 +2974,39 @@ def asset_groups_view(request):
return Response({'error': '请输入角色名称'}, status=status.HTTP_400_BAD_REQUEST)
file = request.FILES.get('file')
if not file:
return Response({'error': '请上传一张素材图片'}, status=status.HTTP_400_BAD_REQUEST)
# Validate file BEFORE creating group (prevent orphan records)
asset_type = None
if file:
asset_type, err = _detect_asset_type(file)
if err:
return err
if asset_type == 'Image':
try:
from PIL import Image
img = Image.open(file)
w, h = img.size
if w < 300 or h < 300:
return Response(
{'error': f'图片太小了（当前 {w}x{h}），宽高需在 300~6000 像素之间'},
status=status.HTTP_400_BAD_REQUEST,
)
if w > 6000 or h > 6000:
return Response(
{'error': f'图片太大了（当前 {w}x{h}），宽高需在 300~6000 像素之间'},
status=status.HTTP_400_BAD_REQUEST,
)
file.seek(0)
except ImportError:
pass
except Exception:
pass
# Validate image dimensions (Volcano Assets API requires 300-6000px)
try:
from PIL import Image
img = Image.open(file)
w, h = img.size
if w < 300 or h < 300:
return Response(
{'error': f'图片太小了，请上传更大的图片（当前 {w}x{h}，最小要求 300x300）'},
status=status.HTTP_400_BAD_REQUEST,
)
if w > 6000 or h > 6000:
return Response(
{'error': f'图片太大了，请压缩后重试（当前 {w}x{h}，最大支持 6000x6000）'},
status=status.HTTP_400_BAD_REQUEST,
)
file.seek(0) # Reset after PIL read
except ImportError:
pass # Pillow not installed, skip validation
except Exception:
pass # Not an image or corrupted, let TOS handle it
# Upload to TOS
try:
tos_url = tos_upload(file, folder='assets')
except Exception as e:
logger.exception('TOS upload failed for asset')
return Response(
{'error': f'文件上传失败: {e}'},
status=status.HTTP_500_INTERNAL_SERVER_ERROR,
)
# Create remote group
from utils import assets_client
@ -3083,71 +3017,49 @@ def asset_groups_view(request):
if result is not None:
remote_group_id = result
# Local DB group
# Create remote asset
remote_asset_id = ''
if remote_group_id:
result, err = _assets_api_call(assets_client.create_asset, remote_group_id, tos_url, name)
if err:
return err
if result is not None:
remote_asset_id = result
# Local DB records
group = AssetGroup.objects.create(
team=team,
remote_group_id=remote_group_id,
name=name,
description='',
thumbnail_url='',
thumbnail_url=tos_url,
created_by=request.user,
)
# If file provided, create first asset (validation already done above)
if file and asset_type:
folder = 'assets' if asset_type == 'Image' else asset_type.lower()
try:
tos_url = tos_upload(file, folder=folder)
except Exception as e:
logger.exception('TOS upload failed for asset')
return Response(
{'error': '文件上传失败，请稍后重试'},
status=status.HTTP_500_INTERNAL_SERVER_ERROR,
)
remote_asset_id = ''
if remote_group_id:
result, err = _assets_api_call(assets_client.create_asset, remote_group_id, tos_url, name, asset_type=asset_type)
if err:
return err
if result is not None:
remote_asset_id = result
asset_obj = Asset.objects.create(
group=group,
remote_asset_id=remote_asset_id,
name=name,
url=tos_url,
asset_type=asset_type,
status='processing' if remote_asset_id else 'active',
error_message='',
)
# Set group thumbnail for images; video/audio thumbnails extracted async
if asset_type == 'Image':
group.thumbnail_url = tos_url
group.save(update_fields=['thumbnail_url'])
# Async: extract thumbnail + duration for video/audio
if asset_type in ('Video', 'Audio'):
from apps.generation.tasks import process_asset_media
process_asset_media.delay(asset_obj.id)
Asset.objects.create(
group=group,
remote_asset_id=remote_asset_id,
name=name,
url=tos_url,
status='processing' if remote_asset_id else 'active',
error_message='',
)
return Response({
'id': group.id,
'name': group.name,
'thumbnail_url': group.thumbnail_url,
'remote_group_id': group.remote_group_id,
'asset_count': Asset.objects.filter(group=group).count(),
'asset_count': 1,
'created_at': group.created_at.isoformat(),
}, status=status.HTTP_201_CREATED)
@api_view(['GET', 'PUT', 'DELETE'])
@api_view(['GET', 'PUT'])
@permission_classes([IsTeamMember])
@parser_classes([JSONParser])
def asset_group_detail_view(request, group_id):
"""GET /api/v1/assets/groups/<id> — group info + assets.
PUT /api/v1/assets/groups/<id> — update name/description.
DELETE /api/v1/assets/groups/<id> — delete entire group + all assets.
"""
team = request.user.team
try:
@ -3155,20 +3067,6 @@ def asset_group_detail_view(request, group_id):
except AssetGroup.DoesNotExist:
return Response({'error': '素材组不存在'}, status=status.HTTP_404_NOT_FOUND)
if request.method == 'DELETE':
# Delete all remote assets in this group
from utils import assets_client
for asset in Asset.objects.filter(group=group):
if asset.remote_asset_id:
try:
assets_client.delete_asset(asset.remote_asset_id)
except Exception as e:
logger.warning('Failed to delete remote asset %s: %s', asset.remote_asset_id, e)
# Delete local records
Asset.objects.filter(group=group).delete()
group.delete()
return Response({'message': '素材组已删除'})
if request.method == 'GET':
# 同步火山端的素材组名字
if group.remote_group_id:
@ -3189,9 +3087,6 @@ def asset_group_detail_view(request, group_id):
'id': a.id,
'name': a.name,
'url': a.url,
'asset_type': a.asset_type,
'thumbnail_url': a.thumbnail_url,
'duration': a.duration,
'status': a.status,
'remote_asset_id': a.remote_asset_id,
'error_message': a.error_message,
@ -3246,7 +3141,7 @@ def asset_group_detail_view(request, group_id):
@permission_classes([IsTeamMember])
@parser_classes([MultiPartParser])
def asset_group_add_asset_view(request, group_id):
"""POST /api/v1/assets/groups/<id>/assets — add an asset (image/video/audio) to a group."""
"""POST /api/v1/assets/groups/<id>/assets — add an image to a group."""
team = request.user.team
try:
group = AssetGroup.objects.get(pk=group_id, team=team)
@ -3257,43 +3152,36 @@ def asset_group_add_asset_view(request, group_id):
if not file:
return Response({'error': '请上传文件'}, status=status.HTTP_400_BAD_REQUEST)
# Detect asset type and validate format/size
asset_type, err = _detect_asset_type(file)
if err:
return err
# Validate image dimensions (only for images)
if asset_type == 'Image':
try:
from PIL import Image
img = Image.open(file)
w, h = img.size
if w < 300 or h < 300:
return Response(
{'error': f'图片太小了（当前 {w}x{h}），宽高需在 300~6000 像素之间'},
status=status.HTTP_400_BAD_REQUEST,
)
if w > 6000 or h > 6000:
return Response(
{'error': f'图片太大了（当前 {w}x{h}），宽高需在 300~6000 像素之间'},
status=status.HTTP_400_BAD_REQUEST,
)
file.seek(0)
except ImportError:
pass
except Exception:
pass
# Validate image dimensions (Volcano Assets API requires 300-6000px)
try:
from PIL import Image
img = Image.open(file)
w, h = img.size
if w < 300 or h < 300:
return Response(
{'error': f'图片太小了，请上传更大的图片（当前 {w}x{h}，最小要求 300x300）'},
status=status.HTTP_400_BAD_REQUEST,
)
if w > 6000 or h > 6000:
return Response(
{'error': f'图片太大了，请压缩后重试（当前 {w}x{h}，最大支持 6000x6000）'},
status=status.HTTP_400_BAD_REQUEST,
)
file.seek(0)
except ImportError:
pass
except Exception:
pass
name = request.data.get('name', '').strip() or file.name
# Upload to TOS
folder = 'assets' if asset_type == 'Image' else asset_type.lower()
try:
tos_url = tos_upload(file, folder=folder)
tos_url = tos_upload(file, folder='assets')
except Exception as e:
logger.exception('TOS upload failed for asset')
return Response(
{'error': '文件上传失败，请稍后重试'},
{'error': f'文件上传失败: {e}'},
status=status.HTTP_500_INTERNAL_SERVER_ERROR,
)
@ -3302,7 +3190,7 @@ def asset_group_add_asset_view(request, group_id):
remote_asset_id = ''
if group.remote_group_id:
result, err = _assets_api_call(
assets_client.create_asset, group.remote_group_id, tos_url, name, asset_type=asset_type,
assets_client.create_asset, group.remote_group_id, tos_url, name,
)
if err:
return err
@ -3314,77 +3202,36 @@ def asset_group_add_asset_view(request, group_id):
remote_asset_id=remote_asset_id,
name=name,
url=tos_url,
asset_type=asset_type,
status='processing' if remote_asset_id else 'active',
error_message='',
)
# Atomic: set group thumbnail only if still empty (concurrent-safe)
if asset_type == 'Image':
from django.db import transaction
with transaction.atomic():
locked_group = AssetGroup.objects.select_for_update().get(pk=group.id)
if not locked_group.thumbnail_url:
locked_group.thumbnail_url = tos_url
locked_group.save(update_fields=['thumbnail_url'])
# Async: extract thumbnail + duration for video/audio
if asset_type in ('Video', 'Audio'):
from apps.generation.tasks import process_asset_media
process_asset_media.delay(asset.id)
# If first asset, set thumbnail
if not group.thumbnail_url:
group.thumbnail_url = tos_url
group.save(update_fields=['thumbnail_url'])
return Response({
'id': asset.id,
'name': asset.name,
'url': asset.url,
'asset_type': asset.asset_type,
'thumbnail_url': asset.thumbnail_url,
'duration': asset.duration,
'status': asset.status,
'remote_asset_id': asset.remote_asset_id,
'created_at': asset.created_at.isoformat(),
}, status=status.HTTP_201_CREATED)
@api_view(['PUT', 'DELETE'])
@api_view(['PUT'])
@permission_classes([IsTeamMember])
@parser_classes([JSONParser])
def asset_update_view(request, asset_id):
"""PUT /api/v1/assets/<id> — rename an asset. DELETE — delete an asset."""
"""PUT /api/v1/assets/<id> — rename an asset."""
team = request.user.team
try:
asset = Asset.objects.select_related('group').get(pk=asset_id, group__team=team)
except Asset.DoesNotExist:
return Response({'error': '素材不存在'}, status=status.HTTP_404_NOT_FOUND)
if request.method == 'DELETE':
# Delete from Volcano first
if asset.remote_asset_id:
from utils import assets_client
try:
assets_client.delete_asset(asset.remote_asset_id)
except Exception as e:
logger.warning('Failed to delete remote asset %s: %s', asset.remote_asset_id, e)
group = asset.group
asset.delete()
# Update group thumbnail: prefer Image > Video (with thumbnail) > empty
remaining_img = Asset.objects.filter(group=group, asset_type='Image').exclude(status='failed').first()
remaining_vid = Asset.objects.filter(group=group, asset_type='Video').exclude(status='failed').exclude(thumbnail_url='').first()
if remaining_img:
new_thumb = remaining_img.url
elif remaining_vid:
new_thumb = remaining_vid.thumbnail_url
else:
new_thumb = ''
if group.thumbnail_url != new_thumb:
group.thumbnail_url = new_thumb
group.save(update_fields=['thumbnail_url'])
return Response({'message': '素材已删除'})
# PUT — rename
new_name = request.data.get('name')
if not new_name:
return Response({'error': '请提供素材名称'}, status=status.HTTP_400_BAD_REQUEST)
@ -3409,29 +3256,26 @@ def asset_update_view(request, asset_id):
@api_view(['GET'])
@permission_classes([IsTeamMember])
def asset_search_view(request):
"""GET /api/v1/assets/search?q=... — search individual assets for @ popup."""
"""GET /api/v1/assets/search?q=... — fast search for @ popup."""
team = request.user.team
q = request.query_params.get('q', '').strip()[:100] # 限制搜索长度
q = request.query_params.get('q', '').strip()
if not q:
return Response({'results': []})
assets = (
Asset.objects
.filter(group__team=team, name__icontains=q, status='active')
.select_related('group')
groups = (
AssetGroup.objects
.filter(team=team, name__icontains=q)
.annotate(asset_count=Count('assets'))
.order_by('-created_at')[:20]
)
results = []
for a in assets:
for g in groups:
results.append({
'id': a.id,
'name': a.name,
'url': a.url,
'asset_type': a.asset_type,
'group_name': a.group.name,
'remote_asset_id': a.remote_asset_id,
'thumbnail_url': a.thumbnail_url,
'duration': a.duration,
'id': g.id,
'name': g.name,
'thumbnail_url': g.thumbnail_url if g.asset_count > 0 else '',
'asset_count': g.asset_count,
'remote_group_id': g.remote_group_id,
})
return Response({'results': results})

4
backend/config/settings.py
View File

@ -182,14 +182,14 @@ CELERY_TIMEZONE = 'Asia/Shanghai'
CELERY_BEAT_SCHEDULE = {
'recover-stuck-tasks': {
'task': 'apps.generation.tasks.recover_stuck_tasks',
'schedule': 10, # 每 10 秒
'schedule': 600, # 每 10 分钟
},
}
LANGUAGE_CODE = 'zh-hans'
TIME_ZONE = 'Asia/Shanghai'
USE_I18N = True
USE_TZ = False
USE_TZ = True
STATIC_URL = 'static/'
STATIC_ROOT = BASE_DIR / 'staticfiles'

1
backend/requirements.txt
View File

@ -10,5 +10,4 @@ ip-region>=1.0
volcengine>=1.0.218
Pillow>=10.0
celery>=5.3,<6.0
gevent>=24.2
redis>=5.0,<6.0

71
backend/tests/mock_airdrama.py
View File

@ -1,71 +0,0 @@
"""
临时替换 airdrama_client，让 query_task 始终返回 running。
worker 启动时会 import 这个 mock 版本。
"""
import os
import time
import redis
# 用 Redis 做跨进程计数器
_redis_url = os.environ.get('REDIS_URL', 'redis://localhost:6379/1')
_r = redis.from_url(_redis_url)
COUNTER_KEY = 'bench:poll_count'
ACTIVE_KEY = 'bench:active'
PEAK_KEY = 'bench:peak'
TASKS_KEY = 'bench:tasks_seen'
def query_task(task_id):
"""始终返回 running，通过 Redis 统计并发"""
pipe = _r.pipeline()
pipe.incr(COUNTER_KEY)
pipe.incr(ACTIVE_KEY)
pipe.sadd(TASKS_KEY, task_id)
pipe.execute()
# 检查并更新峰值
active = int(_r.get(ACTIVE_KEY) or 0)
peak = int(_r.get(PEAK_KEY) or 0)
if active > peak:
_r.set(PEAK_KEY, active)
time.sleep(0.2) # 模拟 200ms 网络延迟
_r.decr(ACTIVE_KEY)
return {'status': 'running'}
def map_status(ark_status):
mapping = {
'running': 'processing',
'submitted': 'queued',
'queued': 'queued',
'succeeded': 'completed',
'failed': 'failed',
}
return mapping.get(ark_status, 'processing')
def extract_video_url(resp):
return None
class AirDramaAPIError(Exception):
def __init__(self, code, message, status_code=400):
self.code = code
self.api_message = message
self.user_message = message
super().__init__(f'{code}: {message}')
ERROR_MESSAGES = {}
def create_task(**kwargs):
"""mock create_task"""
return {'id': 'mock-task-id'}
def download_video(url):
return b''

179
backend/tests/poll_concurrency_report.md
View File

@ -1,179 +0,0 @@
# Celery 轮询并发测试报告
> 测试日期：2026-04-04
> 测试环境：本地 macOS → 火山云外网 Redis + MySQL
---
## 一、测试目的
验证 `poll_video_task` 从 `while True` + `time.sleep` 改为 `self.retry(countdown=5)` + gevent 协程池后，并发轮询能力的提升，目标支撑 1000 并发。
## 二、测试环境
| 项目 | 配置 |
|------|------|
| 本地机器 | Mac Studio, Apple Silicon |
| Python | 3.14 |
| Celery | 5.6.2 |
| Worker 模式 | gevent, concurrency=200 |
| Redis | 火山云外网 `redis-shzlsczo52dft8mia.redis.volces.com:6379/1` |
| MySQL | 火山云外网 `mysql-8351f937d637-public.rds.volces.com:3306` |
| 火山 API | Mock（始终返回 `running`，模拟 200ms 网络延迟） |
**注意**：本地通过公网访问火山云 Redis/MySQL，延迟较线上内网环境高约 30-50ms/次，实际线上性能会显著更好。
## 三、测试方法
1. 启动 mock worker：替换 `utils.airdrama_client` 为 mock 模块，`query_task` 始终返回 `running`
2. 在 MySQL 中创建 N 条 `status=processing` 的测试记录
3. 批量派发 `poll_video_task.delay(record.id)` 到 Redis
4. 通过 Redis 计数器实时统计：总查询次数、当前并发、峰值并发、任务覆盖率
5. 观察指定时长后输出结果
## 四、测试结果
### 测试 1：100 个并发任务（30 秒）
```
时间 总查询 当前并发 峰值并发 QPS 任务覆盖
------ -------- -------- -------- -------- ----------
1s 44 3 6 44 45/100
2s 52 2 6 8 53/100
3s 63 3 6 11 64/100
4s 86 5 8 23 70/100
5s 101 4 8 15 80/100
6s 115 4 8 14 91/100
7s 129 4 8 14 100/100
...
30s 450 3 8 14 100/100
```
| 指标 | 结果 |
|------|------|
| 总查询次数 | 451 |
| 平均 QPS | 15.0 |
| 峰值并发 | 8 |
| 任务覆盖率 | **100/100 (100%)** |
| 全覆盖耗时 | **7 秒** |
| 结果 | **PASS** |
### 测试 2：500 个并发任务（30 秒）
```
时间 总查询 当前并发 峰值并发 QPS 任务覆盖
------ -------- -------- -------- -------- ----------
1s 180 -1 2 180 139/500
5s 234 -1 2 14 182/500
10s 300 -1 2 13 232/500
15s 368 -1 2 13 279/500
20s 436 -1 2 13 331/500
25s 504 0 2 14 381/500
30s 572 -1 2 14 432/500
```
| 指标 | 结果 |
|------|------|
| 总查询次数 | 573 |
| 平均 QPS | 19.1 |
| 峰值并发 | 2 |
| 任务覆盖率 | **432/500 (86%)** |
| 预估全覆盖 | ~35 秒 |
| 结果 | **PASS** |
### 测试 3：1000 个并发任务（60 秒）
```
时间 总查询 当前并发 峰值并发 QPS 任务覆盖
------ -------- -------- -------- -------- ----------
1s 323 0 3 323 254/1000
5s 375 1 3 14 291/1000
10s 439 -1 3 13 337/1000
15s 504 1 3 13 387/1000
20s 569 1 3 13 437/1000
25s 632 0 3 12 485/1000
30s 697 0 3 14 534/1000
35s 761 -1 3 13 584/1000
40s 826 1 3 13 634/1000
45s 891 0 3 13 683/1000
50s 955 0 3 12 732/1000
55s 1020 1 3 13 782/1000
60s 1085 0 3 14 830/1000
```
| 指标 | 结果 |
|------|------|
| 总查询次数 | 1086 |
| 平均 QPS | 18.1 |
| 峰值并发 | 3 |
| 任务覆盖率 | **831/1000 (83%)** |
| 预估全覆盖 | ~75 秒（受公网延迟限制） |
| 协程利用率 | 3/200 (1.5%) |
| 结果 | **PASS**（稳定运行，无异常，无 OOM） |
**关键发现**：200 个协程峰值只用了 3 个，说明瓶颈完全在公网网络延迟，不在资源。
## 五、性能对比
| 指标 | 旧方案（while True + fork） | 新方案（self.retry + gevent） | 提升 |
|------|---|---|---|
| 最大并发轮询数 | **4**（= concurrency） | **1000+**（已验证） | **250x** |
| Worker 占用方式 | 持续占用（sleep 期间不释放） | 每次查询仅占用毫秒级 | - |
| Worker 重启后 | 任务丢失 | Redis 中自动恢复 | - |
| 内存模式 | 4 进程常驻 ~280Mi | 1 进程 + 200 协程 ~100Mi | 节省 64% |
| 最坏恢复时间 | ~20 分钟 | ~6 分钟（3 分钟 beat + 3 分钟门槛） | **3x** |
## 六、线上性能预估
本次测试受公网延迟影响，QPS 约 14-19。线上内网环境预估：
| 因素 | 本地测试（公网） | 线上预估（内网） |
|------|---------|---------|
| Redis RTT | ~30ms | ~1ms |
| MySQL RTT | ~30ms | ~1ms |
| 火山 API 延迟 | 200ms（mock） | 200-300ms（真实） |
| 单次查询总耗时 | ~260ms | ~202ms |
| 预估 QPS | 14-19 | **40-60** |
| 1000 任务全覆盖 | ~75 秒 | **~20 秒** |
### 资源需求验证
```
1000 任务 × 每 5 秒查一次 = 需要 200 QPS
200 协程 × (1000ms / 202ms) = 可提供 990 QPS
990 >> 200 → 当前配置绰绰有余
```
| 项目 | 当前值 | 1000 并发是否足够 |
|------|--------|-----------------|
| gevent concurrency | 200 | 足够（只用了 1.5%） |
| 内存 | 1Gi | 足够 |
| CPU | 1000m | 足够 |
| retry countdown | 5 秒 | 合适 |
## 七、测试文件
| 文件 | 说明 |
|------|------|
| `tests/test_poll_concurrency.py` | 测试脚本（worker + bench 两步执行） |
| `tests/mock_airdrama.py` | Mock 火山 API 模块（通过 Redis 跨进程计数） |
### 运行方式
```bash
cd backend && source venv/bin/activate
# 终端 1：启动 mock worker
python tests/test_poll_concurrency.py worker --concurrency 200
# 终端 2：派发任务 + 监控（可调整 --tasks 和 --duration）
python tests/test_poll_concurrency.py bench --tasks 1000 --duration 60
```
## 八、结论
1. 新方案在 **1000 个并发任务**下稳定运行 60 秒，无异常、无 OOM、无任务丢失
2. 相比旧方案最大并发从 4 提升到 1000+，**提升 250 倍**
3. 200 个协程峰值只用了 3 个，**当前配置无需加资源**即可支撑 1000 并发
4. Worker 重启不再丢失任务，通过 Redis 队列自动恢复
5. 公网测试 QPS 受延迟限制（~18），线上内网预估可达 40-60 QPS，1000 任务约 20 秒全覆盖

183
backend/tests/test_poll_concurrency.py
View File

@ -1,183 +0,0 @@
"""
Celery poll_video_task 并发压测（两步执行）
步骤 1：启动 worker（mock 火山 API）
步骤 2：派发任务 + 监控
用法：
cd backend && source venv/bin/activate
# 终端 1：启动 mock worker
python tests/test_poll_concurrency.py worker
# 终端 2：派发 + 监控
python tests/test_poll_concurrency.py bench --tasks 100 --duration 30
"""
import argparse
import os
import sys
import time
# 公共环境变量
REDIS_URL = os.environ.get('REDIS_URL',
'redis://zyc:Zyc188208@redis-shzlsczo52dft8mia.redis.volces.com:6379/1')
os.environ['REDIS_URL'] = REDIS_URL
os.environ['USE_MYSQL'] = 'true'
os.environ.setdefault('DB_HOST', 'mysql-8351f937d637-public.rds.volces.com')
os.environ.setdefault('DB_NAME', 'video_auto')
os.environ.setdefault('DB_USER', 'zyc')
os.environ.setdefault('DB_PASSWORD', 'Zyc188208')
os.environ.setdefault('DB_PORT', '3306')
sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'config.settings')
def cmd_worker(args):
"""启动 worker，用 mock 替换真实 airdrama_client"""
# gevent monkey-patch 必须在所有 import 之前
from gevent import monkey
monkey.patch_all()
# 用 mock 模块替换真实 airdrama_client
sys.path.insert(0, os.path.join(os.path.dirname(__file__)))
import mock_airdrama
sys.modules['utils.airdrama_client'] = mock_airdrama
import django
django.setup()
print(f'[worker] 启动中... (mock 火山 API, concurrency={args.concurrency})')
print(f'[worker] Redis: {REDIS_URL}')
from config.celery import app
app.Worker(
pool='gevent',
concurrency=args.concurrency,
loglevel='INFO',
without_heartbeat=True,
without_mingle=True,
without_gossip=True,
).start()
def cmd_bench(args):
"""派发任务 + 监控"""
import django
django.setup()
import redis as redis_lib
r = redis_lib.from_url(REDIS_URL)
from apps.accounts.models import User, Team
from apps.generation.models import GenerationRecord
from apps.generation.tasks import poll_video_task
num_tasks = args.tasks
duration = args.duration
print(f'\n{"="*60}')
print(f' Celery gevent 轮询并发压测')
print(f' 任务数: {num_tasks}')
print(f' 观察时长: {duration} 秒')
print(f' Redis: {REDIS_URL}')
print(f'{"="*60}\n')
# 清空计数器
for key in ['bench:poll_count', 'bench:active', 'bench:peak', 'bench:tasks_seen']:
r.delete(key)
# 准备测试数据
team, _ = Team.objects.get_or_create(name='压测团队', defaults={'total_seconds_pool': 999999})
user, _ = User.objects.get_or_create(username='bench_user', defaults={
'email': 'bench@test.com', 'team': team,
})
GenerationRecord.objects.filter(prompt__startswith='压测任务').delete()
records = []
for i in range(num_tasks):
record = GenerationRecord.objects.create(
user=user,
prompt=f'压测任务 {i}',
mode='universal',
model='seedance_2.0',
aspect_ratio='16:9',
duration=5,
status='processing',
ark_task_id=f'bench-{i:04d}',
)
records.append(record)
print(f'[准备] 已创建 {num_tasks} 个测试记录')
# 清空队列
r.delete('celery')
print(f'[准备] 已清空 Redis 队列\n')
# 派发
print(f'[派发] 正在派发 {num_tasks} 个轮询任务...')
t0 = time.time()
for record in records:
poll_video_task.delay(record.id)
print(f'[派发] 完成，耗时 {time.time()-t0:.1f} 秒\n')
# 监控
print(f'[监控] 开始观察 {duration} 秒...\n')
print(f' {"时间":>6s} {"总查询":>8s} {"当前并发":>8s} {"峰值并发":>8s} {"QPS":>8s} {"任务覆盖":>10s}')
print(f' {"-"*6} {"-"*8} {"-"*8} {"-"*8} {"-"*8} {"-"*10}')
last_count = 0
for sec in range(1, duration + 1):
time.sleep(1)
ct = int(r.get('bench:poll_count') or 0)
ca = int(r.get('bench:active') or 0)
cp = int(r.get('bench:peak') or 0)
tp = r.scard('bench:tasks_seen')
qps = ct - last_count
last_count = ct
print(f' {sec:>5d}s {ct:>8d} {ca:>8d} {cp:>8d} {qps:>8d} {tp:>9d}/{num_tasks}')
# 结果
ft = int(r.get('bench:poll_count') or 0)
fp = int(r.get('bench:peak') or 0)
tp = r.scard('bench:tasks_seen')
print(f'\n{"="*60}')
print(f' 测试结果')
print(f'{"="*60}')
print(f' 总查询次数: {ft}')
print(f' 平均 QPS: {ft / duration:.1f}')
print(f' 峰值并发查询: {fp}')
print(f' 任务覆盖率: {tp}/{num_tasks} ({tp*100//num_tasks}%)')
print(f'{"="*60}\n')
if tp == num_tasks:
print(f' PASS: 所有 {num_tasks} 个任务都被成功轮询')
else:
print(f' WARNING: 只有 {tp}/{num_tasks} 个任务被轮询到')
# 清理（只清 Redis 计数器，DB 记录保留给 worker 查询）
# 测试结束后手动清理：
# python -c "import os,django;os.environ['DJANGO_SETTINGS_MODULE']='config.settings';os.environ['USE_MYSQL']='true';os.environ['DB_HOST']='mysql-8351f937d637-public.rds.volces.com';os.environ['DB_NAME']='video_auto';os.environ['DB_USER']='zyc';os.environ['DB_PASSWORD']='Zyc188208';django.setup();from apps.generation.models import GenerationRecord;print(GenerationRecord.objects.filter(prompt__startswith='压测任务').delete())"
for key in ['bench:poll_count', 'bench:active', 'bench:peak', 'bench:tasks_seen']:
r.delete(key)
print(f' 已清理 Redis 计数器（DB 记录保留给 worker）')
if __name__ == '__main__':
parser = argparse.ArgumentParser(description='Celery 轮询并发压测')
sub = parser.add_subparsers(dest='cmd')
p_worker = sub.add_parser('worker', help='启动 mock worker')
p_worker.add_argument('--concurrency', type=int, default=200)
p_bench = sub.add_parser('bench', help='派发任务 + 监控')
p_bench.add_argument('--tasks', type=int, default=100)
p_bench.add_argument('--duration', type=int, default=30)
args = parser.parse_args()
if args.cmd == 'worker':
cmd_worker(args)
elif args.cmd == 'bench':
cmd_bench(args)
else:
parser.print_help()

134
backend/utils/media_utils.py
View File

@ -1,134 +0,0 @@
"""Media utilities: extract video thumbnails and durations using ffmpeg/ffprobe.
WARNING: These functions download files and run subprocess commands.
They MUST only be called from Celery tasks, NEVER from HTTP request handlers.
Calling from gunicorn (especially with gevent workers) will block the worker pool.
"""
import logging
import subprocess
import tempfile
import os
import requests
from django.core.files.uploadedfile import SimpleUploadedFile
logger = logging.getLogger(__name__)
MAX_DOWNLOAD_SIZE = 100 * 1024 * 1024 # 100MB safety limit
def download_to_temp(url: str, suffix: str) -> str:
"""Download a URL to a temporary file. Returns the temp file path.
Only accepts http/https URLs to prevent SSRF.
"""
if not url.startswith(('http://', 'https://')):
raise ValueError(f'Invalid URL scheme: {url[:30]}')
resp = requests.get(url, timeout=30, stream=True)
resp.raise_for_status()
tmp = tempfile.NamedTemporaryFile(suffix=suffix, delete=False)
downloaded = 0
try:
for chunk in resp.iter_content(8192):
downloaded += len(chunk)
if downloaded > MAX_DOWNLOAD_SIZE:
tmp.close()
os.unlink(tmp.name)
raise ValueError(f'File too large: {downloaded} bytes')
tmp.write(chunk)
tmp.close()
except Exception:
tmp.close()
if os.path.exists(tmp.name):
os.unlink(tmp.name)
raise
return tmp.name
def _get_duration_ffprobe(file_path: str) -> float:
"""Get media duration in seconds using ffprobe."""
try:
result = subprocess.run(
['ffprobe', '-v', 'quiet', '-show_entries', 'format=duration',
'-of', 'default=noprint_wrappers=1:nokey=1', file_path],
capture_output=True, text=True, timeout=15,
)
return float(result.stdout.strip())
except Exception as e:
logger.warning('ffprobe duration failed: %s', e)
return 0
def _extract_first_frame(video_path: str, output_path: str) -> bool:
"""Extract the first frame of a video as JPEG using ffmpeg."""
try:
subprocess.run(
['ffmpeg', '-y', '-i', video_path, '-vframes', '1',
'-f', 'image2', '-q:v', '2', output_path],
capture_output=True, timeout=15,
)
return os.path.exists(output_path) and os.path.getsize(output_path) > 0
except Exception as e:
logger.warning('ffmpeg frame extraction failed: %s', e)
return False
def extract_video_info_from_file(video_path: str) -> tuple:
"""Extract first frame thumbnail + duration from a local video file.
Returns (thumbnail_file: SimpleUploadedFile | None, duration: float).
Does NOT delete the input file — caller is responsible for cleanup.
"""
tmp_thumb = None
try:
duration = _get_duration_ffprobe(video_path)
tmp_thumb = video_path + '_thumb.jpg'
if _extract_first_frame(video_path, tmp_thumb):
with open(tmp_thumb, 'rb') as f:
thumb_file = SimpleUploadedFile(
'thumbnail.jpg', f.read(), content_type='image/jpeg'
)
return thumb_file, duration
return None, duration
except Exception as e:
logger.warning('extract_video_info_from_file failed: %s', e)
return None, 0
finally:
if tmp_thumb and os.path.exists(tmp_thumb):
os.unlink(tmp_thumb)
def extract_video_info(video_url: str) -> tuple:
"""Extract first frame thumbnail + duration from a video URL.
Returns (thumbnail_file: SimpleUploadedFile | None, duration: float).
NOTE: This function downloads the full video. For large files, call from
Celery tasks only — never from HTTP request handlers.
"""
tmp_video = None
try:
suffix = '.mp4'
if '.mov' in video_url.lower():
suffix = '.mov'
tmp_video = download_to_temp(video_url, suffix)
return extract_video_info_from_file(tmp_video)
except Exception as e:
logger.warning('extract_video_info failed for %s: %s', video_url, e)
return None, 0
finally:
if tmp_video and os.path.exists(tmp_video):
os.unlink(tmp_video)
def get_audio_duration(audio_url: str) -> float:
"""Get audio duration in seconds from a URL."""
tmp_audio = None
try:
suffix = '.wav' if '.wav' in audio_url.lower() else '.mp3'
tmp_audio = download_to_temp(audio_url, suffix)
return _get_duration_ffprobe(tmp_audio)
except Exception as e:
logger.warning('get_audio_duration failed for %s: %s', audio_url, e)
return 0
finally:
if tmp_audio and os.path.exists(tmp_audio):
os.unlink(tmp_audio)

44
backend/utils/tos_client.py
View File

@ -56,10 +56,8 @@ def upload_file(file_obj, folder='uploads'):
client.head_object(bucket=settings.TOS_BUCKET, key=key)
logger.info('TOS dedup hit: %s', key)
return url
except Exception as e:
err_str = str(e).lower()
if '404' not in err_str and 'not found' not in err_str and 'nosuchkey' not in err_str:
logger.warning('TOS head_object unexpected error (proceeding with upload): %s', e)
except Exception:
pass # Object doesn't exist, proceed with upload
client.put_object(
bucket=settings.TOS_BUCKET,
@ -71,44 +69,6 @@ def upload_file(file_obj, folder='uploads'):
return url
def upload_from_file_path(file_path, folder='uploads', content_type=None):
"""Upload a local file to TOS by path (streaming, no full memory load).
Returns the permanent CDN URL.
"""
ext = file_path.rsplit('.', 1)[-1].lower() if '.' in file_path else 'bin'
if not content_type:
content_type = CONTENT_TYPE_MAP.get(ext, 'application/octet-stream')
# Use content hash for dedup
h = hashlib.sha256()
with open(file_path, 'rb') as f:
for chunk in iter(lambda: f.read(8192), b''):
h.update(chunk)
content_hash = h.hexdigest()
key = f'{folder}/{content_hash}.{ext}'
url = f'{settings.TOS_CDN_DOMAIN}/{key}'
client = get_tos_client()
try:
client.head_object(bucket=settings.TOS_BUCKET, key=key)
logger.info('TOS dedup hit: %s', key)
return url
except Exception as e:
# Only proceed if object not found (404). Re-raise on auth/config errors.
err_str = str(e).lower()
if '404' not in err_str and 'not found' not in err_str and 'nosuchkey' not in err_str:
logger.warning('TOS head_object unexpected error (proceeding with upload): %s', e)
with open(file_path, 'rb') as f:
client.put_object(
bucket=settings.TOS_BUCKET,
key=key,
content=f,
content_type=content_type,
)
return url
def upload_from_url(source_url, folder='results'):
"""Download a file from a URL and upload to TOS, return permanent CDN URL."""
import requests as req

961
docs/API文档/3-28-【申请权限填客户名称】Seedance 2.0 & 2.0 fast API文档（邀测用户版）.md
View File

@ -1,961 +0,0 @@
# 【申请权限填客户名称】Seedance 2.0 & 2.0 fast API文档（邀测用户版）
该文档目前仅限开白客户使用，发送前请和销管确认客户是否在开白名单内
***【❗️❗️❗️】该文档限制客户申请权限，只有返回了服务协议的客户方可申请***
本文介绍 Seedance 2.0 & 2.0 fast 模型相较于存量模型 **新增/配置有区别&#x20;**&#x7684; API 参数介绍，存量 API 参数的完整介绍参见 [视频生成 API](https://www.volcengine.com/docs/82379/1520758?lang=zh)。
> 本文档仅限预览及邀测用户使用：
>
> * 不承诺正式API上线100%一致。
>
> * 仅限邀测用户阅读，请勿截图/分享给其他人员。
>
> * 您上传的内容请确保由您原创或已取得授权。
# 模型能力
> **Seedance 2.0 和 Seedance 2.0 fast 提供的模型能力一致，**&#x8FFD;求最高生成品质，推荐使用 **Seedance 2.0**；更注重成本与生成速度，不要求极限品质，推荐使用 **Seedance 2.0 fast**。
**Seedance 2.0 & 2.0 fast (有声视频/无声视频)**
* **多模态参考生视频**：输入参考图片（0\~9）+参考视频（0\~3）+ 参考音频（0\~3）+ 文本提示词（可选）生成 1 个目标视频。支持生成全新视频、编辑视频、延长视频。
> **注意：不可单独输入音频，应至少包含 1 个参考视频或图片。**
* **图生视频-首尾帧**：输入首帧图片+尾帧图片+文本提示词（可选）生成 1 个目标视频。
* **图生视频-首帧**：输入首帧图片+文本提示词（可选）生成 1 个目标视频。
* **文生视频**：输入文本提示词生成 1 个目标视频。
**模型能力对比表：**
| 模型名称 | | [Seedance 2.0](https://console.volcengine.com/ark/region:ark+cn-beijing/model/detail?Id=doubao-seedance-2-0) | [Seedance 2.0 fast](https://console.volcengine.com/ark/region:ark+cn-beijing/model/detail?Id=doubao-seedance-2-0-fast\&projectName=default) | [Seedance 1.5 pro](https://console.volcengine.com/ark/region:ark+cn-beijing/model/detail?Id=doubao-seedance-1-5-pro\&projectName=default) | [Seedance 1.0 pro ](https://console.volcengine.com/ark/region:ark+cn-beijing/model/detail?Id=doubao-seedance-1-0-pro\&projectName=default) | [Seedance 1.0 pro fast ](https://console.volcengine.com/ark/region:ark+cn-beijing/model/detail?Id=doubao-seedance-1-0-pro-fast\&projectName=default) | [Seedance 1.0 lite i2v](https://console.volcengine.com/ark/region:ark+cn-beijing/model/detail?Id=doubao-seedance-1-0-lite-i2v\&projectName=default) | [Seedance-1.0 lite t2v ](https://console.volcengine.com/ark/region:ark+cn-beijing/model/detail?Id=doubao-seedance-1-0-lite-t2v) |
| ------------ | -------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| Model ID | | doubao-seedance-2-0-260128 | doubao-seedance-2-0-fast-260128 | doubao-seedance-1-5-pro-251215 | doubao-seedance-1-0-pro-250528 | doubao-seedance-1-0-pro-fast-251015 | doubao-seedance-1-0-lite-i2v-250428 | doubao-seedance-1-0-lite-t2v-250428 |
| 文生视频 | | ✅ | | ✅ | ✅ | ✅ | ✅ | ✅ |
| 图生视频-首帧 | | ✅ | | ✅ | ✅ | ✅ | ✅ | ❌ |
| 图生视频-首尾帧 | | ✅ | | ✅ | ✅ | ❌ | ✅ | ❌ |
| 多模态参考【New】 | 图片参考 | ✅ | | ❌ | ❌ | ❌ | ✅ | ❌ |
| | 视频参考 | ✅ | | ❌ | ❌ | ❌ | ❌ | ❌ |
| | 组合参考 | ✅ | | ❌ | ❌ | ❌ | ❌ | ❌ |
| 编辑视频【New】 | | ✅ | | ❌ | ❌ | ❌ | ❌ | ❌ |
| 延长视频【New】 | | ✅ | | ❌ | ❌ | ❌ | ❌ | ❌ |
| 生成有声视频 | | ✅ | | ✅ | ❌ | ❌ | ❌ | ❌ |
| 联网搜索增强【New】 | | ✅ | | ❌ | [❌](https://p9-arcosite.byteimg.com/obj/tos-cn-i-goo7wpa0wc/f359753773c94d97885008ca1223c9bc) | ❌ | ❌ | ❌ |
| 样片模式 | | ❌ | | ✅ | ❌ | ❌ | ❌ | ❌ |
| 返回视频尾帧 | | ✅ | | ✅ | ✅ | ✅ | ✅ | ✅ |
| 输出视频规格 | 输出分辨率 | 480p, 720p | | 480p, 720p, 1080p | 480p, 720p, 1080p | 480p, 720p, 1080p | 480p, 720p, 1080p | 480p, 720p, 1080p |
| | 输出宽高比 | 21:9, 16:9, 4:3, 1:1, 3:4, 9:16 | | | | | | |
| | 输出时长 | 4\~15 秒 | | 4\~12 秒 | 2\~12 秒 | 2\~12 秒 | 2\~12 秒 | 2\~12 秒 |
| | 输出视频格式 | mp4 | | mp4 | mp4 | mp4 | mp4 | mp4 |
| 离线推理 | | [❌](https://p9-arcosite.byteimg.com/obj/tos-cn-i-goo7wpa0wc/f359753773c94d97885008ca1223c9bc) | | ✅ | ✅ | ✅ | ✅ | ✅ |
| 在线推理限流 | RPM | 600 | | 600 | 600 | 600 | 300 | 300 |
| | 并发数 | 10 | | 10 | 10 | 10 | 5 | 5 |
| 离线推理限流 | TPD | - | | 5000亿 | 5000亿 | 5000亿 | 2500亿 | 2500亿 |
# Creat-创建视频生成任务
> POST https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks
## 请求参数
#### **content** `object[]` `必选`
输入给模型，生成视频的信息，支持文本、图片、音频、视频、样片任务 ID。支持以下几种组合：
* **文本**
* **文本（可选）+ 图片**
* **文本（可选）+ 视频**
* **文本（可选）+ 图片 + 音频**
* **文本（可选）+ 图片 + 视频**
* **文本（可选）+ 视频 + 音频**
* **文本（可选）+ 图片 + 视频 + 音频**
***
**信息类型：**
* **文本信息**`object`
输入给模型的提示词信息。
***
content.**type&#x20;**`string` `必选`
输入内容的类型，此处应为 **text**。
***
content.**text&#x20;**`string` `必选`
输入给模型的文本提示词，描述期望生成的视频。
支持中英文。建议中文不超过500字，英文不超过1000词。字数过多信息容易分散，模型可能因此忽略细节，只关注重点，造成视频缺失部分元素。提示词的更多使用技巧请参见 [Seedance 提示词指南](https://www.volcengine.com/docs/82379/1587797)。
* **图片信息** `object`
输入给模型的图片信息。
***
content.**type&#x20;**`string` `必选`
输入内容的类型，此处应为 **image\_url**。
***
content.**image\_url&#x20;**`object` `必选`
输入给模型的图片对象。
***
content.image\_url.**url&#x20;**`string` `必选`
图片 URL 、图片 Base64 编码、素材 ID。
* 图片 URL：填入图片的公网 URL。
* Base64 编码：将本地文件转换为 Base64 编码字符串，然后提交给大模型。遵循格式：data:image/<图片格式>;base64,\<Base64编码>，注意 <图片格式> 需小写，如 data:image/png;base64,{base64\_image}。
* 素材 ID：用于视频生成的预置素材及虚拟人像的 ID，遵循格式：asset://\<ASSET\_ID>，可从 [素材&虚拟人像库](https://console.volcengine.com/ark-stg/region:ark-stg+cn-beijing/experience/vision?modelId=doubao-seedance-2-0-260128) 获取，详细使用请参见[文档](https://www.volcengine.com/docs/82379/2223965?lang=zh)。
> **传入单张图片要求**
>
> * 格式：jpeg、png、webp、bmp、tiff、gif
>
> * 宽高比（宽/高）： (0.4, 2.5)&#x20;
>
> * 宽高长度（px）：(300, 6000)
>
> * 大小：单张图片小于 30 MB。请求体大小不超过 64 MB。大文件请勿使用Base64编码。
>
> * 图片数量：
>
> * 图生视频-首帧：1 张
>
> * 图生视频-首尾帧：2 张
>
> * Seedance 2.0 & 2.0 fast 多模态参考生视频：1\~9 张
***
content.**role&#x20;**`string` `条件必填`
图片的位置或用途。
> **注意**
>
> * **图生视频-首帧**、**图生视频-首尾帧**、**多模态参考生视频**（包括参考图、视频、音频）为 3 种互斥场景，**不可混用**。
>
> * **多模态参考生视频**可通过提示词指定参考图片作为首帧/尾帧，间接实现“首尾帧+多模态参考”效果。若需严格保障首尾帧和指定图片一致，**优先使用图生视频-首尾帧**（配置 role 为 **first\_frame / last\_frame**）。
***
**图生视频-首帧**
> 需要传入1个 image\_url 对象
* **字段role取值：**
* **first\_frame 或不填**
***
**图生视频-首尾帧**
> 需要传入2个 image\_url 对象
* **字段role取值：**
* 首帧图片对应的字段 role 为：**first\_frame**，必填
* 尾帧图片对应的字段 role 为：**last\_frame**，必填
***
**图生视频-参考图&#x20;**
> 可传入 1\~9 个 image\_url 对象
* **字段role取值**：
* 每张参考图对应的字段 role 均为：**reference\_image**，必填
* **视频信息** `object`&#x20;
输入给模型的视频信息。仅 Seedance 2.0 & 2.0 fast 支持输入视频。2026年3月11日起，支持使用本账号下 Seedance 2.0 & 2.0 fast 模型产出的视频作为输入素材，进行视频编辑或延长，其中的真人人脸可正常使用，不会触发审核拦截。
***
content.**type&#x20;**`string` `必选`
输入内容的类型，此处应为 **video\_url**。
***
content.**video\_url&#x20;**`object` `必选`
输入给模型的视频对象。
***
content.video\_url.**url&#x20;**`string` `必选`
视频URL、素材 ID。
* 视频 URL：填入视频的公网 URL。
* 素材 ID：用于视频生成的预置素材及虚拟人像视频的 ID，遵循格式：asset://\<ASSET\_ID>。可从[素材&虚拟人像库](https://console.volcengine.com/ark-stg/region:ark-stg+cn-beijing/experience/vision?modelId=doubao-seedance-2-0-260128)获取。
> **传入单个视频要求**
>
> * 视频格式：mp4、mov。
>
> * 分辨率：480p、720p
>
> * 时长：单个视频时长 \[2, 15] s，最多传入 3 个参考视频，所有视频总时长不超过 15s。
>
> * 尺寸：
>
> * 宽高比（宽/高）：\[0.4, 2.5]
>
> * 宽高长度（px）：\[300, 6000]
>
> * 画面像素（宽 × 高）：\[409600, 927408] ，示例：
>
> * 画面尺寸 640×640=409600 满足最小值 ；
>
> * 画面尺寸 834×1112=927408 满足最大值。
>
> * 大小：单个视频不超过 50 MB。
>
> * 帧率 (FPS)：\[24, 60]&#x20;
***
content.**role&#x20;**`string` `条件必填`
视频的位置或用途。当前仅支持 **reference\_video**。
* **音频信息&#x20;**`object`&#x20;
输入给模型的音频信息。仅 Seedance 2.0 & 2.0 fast 支持输入音频。注意不可单独输入音频，应至少包含 1 个参考视频或图片。
***
content.**type&#x20;**`string` `必选`
输入内容的类型，此处应为 **audio\_url**。
***
content.**audio\_url&#x20;**`object` `必选`
输入给模型的音频对象。
***
content.audio\_url.**url&#x20;**`string` `必选`
音频 URL 、音频 Base64 编码、素材 ID。
* 音频 URL：填入音频的公网 URL。
* Base64 编码：将本地文件转换为 Base64 编码字符串，然后提交给大模型。遵循格式：data:audio/<音频格式>;base64,\<Base64编码>，注意 <音频格式> 需小写，如 data:audio/wav;base64,{base64\_audio}。
* 素材 ID：用于视频生成的虚拟人的音频素材 ID，遵循格式：asset://\<ASSET\_ID>。可从[素材&虚拟人像库](https://console.volcengine.com/ark-stg/region:ark-stg+cn-beijing/experience/vision?modelId=doubao-seedance-2-0-260128)获取。
> **传入单个音频要求**
>
> * 格式：wav、mp3
>
> * 时长：单个音频时长 \[2, 15] s，最多传入 3 段参考音频，所有音频总时长不超过 15 s。
>
> * 大小：单个音频不超过 15 MB，请求体大小不超过 64 MB。大文件请勿使用Base64编码。
***
content.**role&#x20;**`string` `条件必填`
音频的位置或用途。当前仅支持 **reference\_audio** 。
#### **service\_tier** `string`
&#x20;Seedance 2.0 & 2.0 fast 暂不支持
#### **generate\_audio&#x20;**`boolean`&#x20;
> Seedance 2.0 & 2.0 fast 默认值： true
控制生成的视频是否包含与画面同步的声音。
* true：模型输出的视频包含同步音频。模型会基于文本提示词与视觉内容，自动生成与之匹配的人声、音效及背景音乐。建议将对话部分置于双引号内，以优化音频生成效果。例如：男人叫住女人说：“你记住，以后不可以用手指指月亮。”
* false：模型输出的视频为无声视频。
> **说明**
>
> 生成的有声视频均为单声道，和传入的音频声道数无关。
####
#### **draft&#x20;**`boolean`
&#x20;Seedance 2.0 & 2.0 fast 暂不支持
#### **tools&#x20;**`object[]`
> 仅 Seedance 2.0 & 2.0 fast 支持
配置模型要调用的工具。
***
tools.**type&#x20;**`string`
指定使用的工具类型。
* web\_search：联网搜索工具。当前仅文生视频支持。
> **说明**
>
> * 开启联网搜索后，模型会根据用户的提示词自主判断是否搜索互联网内容（如商品、天气等）。可提升生成视频的时效性，但也会增加一定的时延。
>
> * 实际搜索次数可通过 [查询视频生成任务 API](https://www.volcengine.com/docs/82379/1521309?lang=zh) 返回的 usage.tool\_usage.**web\_search** 字段获取，如果为 0 表示未搜索。
#### **resolution&#x20;**&#x20;`string`
> Seedance 2.0 & 2.0 fast 默认值：720p
视频分辨率，取值范围：
* 480p
* 720p
#### **ratio&#x20;**`string`&#x20;
> Seedance 2.0 & 2.0 fast 默认值： adaptive
生成视频的宽高比例。不同宽高比对应的宽高像素值见下方表格。
* 16:9&#x20;
* 4:3
* 1:1
* 3:4
* 9:16
* 21:9
* adaptive：根据输入自动选择最合适的宽高比
> **adaptive 适配规则**
>
> 当配置 **ratio** 为 adaptive 时，模型会根据生成场景自动适配宽高比；实际生成的视频宽高比可通过 [查询视频生成任务 API](https://www.volcengine.com/docs/82379/1521309?lang=zh) 返回的 **ratio** 字段获取。
>
> * 文生视频：根据输入的提示词，智能选择最合适的宽高比。
>
> * 首帧 / 首尾帧生视频：根据上传的首帧图片比例，自动选择最接近的宽高比。
>
> * 多模态参考生视频：根据用户提示词意图判断，如果是首帧生视频/编辑视频/延长视频，以该图片/视频为准选择最接近的宽高比；否则，以传入的第一个媒体文件为准（优先级：视频＞图片）选择最接近的宽高比。
***
**不同宽高比对应的宽高像素值：**
| 分辨率 | 宽高比 | 宽高像素值 |
| ---- | ---- | -------- |
| 480p | 16:9 | 864×496 |
| | 4:3 | 752×560 |
| | 1:1 | 640×640 |
| | 3:4 | 560×752 |
| | 9:16 | 496×864 |
| | 21:9 | 992×432 |
| 720p | 16:9 | 1280×720 |
| | 4:3 | 1112×834 |
| | 1:1 | 960×960 |
| | 3:4 | 834×1112 |
| | 9:16 | 720×1280 |
| | 21:9 | 1470×630 |
#### **duration** `integer`&#x20;
> Seedance 2.0 & 2.0 fast 默认值：5
生成视频时长，仅支持整数，单位：秒。
取值范围：
* \[4,15] 或设置为-1
> **配置方法**
>
> * 指定具体时长：支持有效范围内的任一整数。
>
> * 智能指定：设置为 -1，表示由模型在有效范围内自主选择合适的视频长度（整数秒）。实际生成视频的时长可通过 [查询视频生成任务 API](https://www.volcengine.com/docs/82379/1521309?lang=zh) 返回的 **duration** 字段获取。注意视频时长与计费相关，请谨慎设置。
#### **frames** `integer`&#x20;
Seedance 2.0 & 2.0 fast 暂不支持
#### **camera\_fixed** `boolean`
&#x20;Seedance 2.0 & 2.0 fast 暂不支持
# Get/List-查询视频生成任务/列表
> [查询视频生成任务](https://www.volcengine.com/docs/82379/1521309?lang=zh)：GET https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks/{id}
>
> [查询视频生成任务列表](https://www.volcengine.com/docs/82379/1521675?lang=zh)：GET https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks?page\_num={page\_num}\&page\_size={page\_size}\&filter.status={filter.status}\&filter.task\_ids={filter.task\_ids}\&filter.model={filter.model}
## 响应参数
#### **tools&#x20;**`object[]`&#x20;
> 仅 Seedance 2.0 & 2.0 fast 支持
配置模型要调用的工具。
***
tools.**type&#x20;**`string`
指定使用的工具类型。
* web\_search：联网搜索工具。
#### **usage** `object`
本次请求的 token 用量。
***
usage.**completion\_tokens** `integer`
模型输出视频花费的 token 数量。
***
usage.**total\_tokens** `integer`
本次请求消耗的总 token 数量。
***
usage.**tool\_usage&#x20;**`object`&#x20;
> 仅 Seedance 2.0 & 2.0 fast 支持
使用工具的用量信息。
***
usage.tool\_usage.**web\_search&#x20;**`integer`&#x20;
实际调用联网搜索工具的次数，仅开启联网搜索时返回。
# 调用简介及示例
## 流程简介
任务接口是异步接口，视频生成任务流程
1. 创建视频生成任务接口创建视频生成任务
2. 定时使用查询接口查询视频生成任务状态
1. 任务 running，过段时间再查询任务状态
2. 任务完成，返回视频链接，在24小时内下载生成的视频文件
## 1. 创建视频生成任务
> 以下示例仅展示 Seedance 2.0 & 2.0 fast 新增能力，更多视频生成示例详见 [创建视频生成任务 API](https://www.volcengine.com/docs/82379/1520757)。
### 多模态参考
```bash
curl https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ARK_API_KEY" \
-d '{
"model": "doubao-seedance-2-0-260128",
"content": [
{
"type": "text",
"text": "全程使用视频1的第一视角构图，全程使用音频1作为背景音乐。第一人称视角果茶宣传广告，seedance牌「苹苹安安」苹果果茶限定款；首帧为图片1，你的手摘下一颗带晨露的阿克苏红苹果，轻脆的苹果碰撞声；2-4 秒：快速切镜，你的手将苹果块投入雪克杯，加入冰块与茶底，用力摇晃，冰块碰撞声与摇晃声卡点轻快鼓点，背景音：「鲜切现摇」；4-6 秒：第一人称成品特写，分层果茶倒入透明杯，你的手轻挤奶盖在顶部铺展，在杯身贴上粉红包标，镜头拉近看奶盖与果茶的分层纹理；6-8 秒：第一人称手持举杯，你将图片2中的果茶举到镜头前（模拟递到观众面前的视角），杯身标签清晰可见，背景音「来一口鲜爽」，尾帧定格为图片2。背景声音统一为女生音色。"
},
{
"type": "image_url",
"image_url": {
"url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/r2v_tea_pic1.jpg"
},
"role": "reference_image"
},
{
"type": "image_url",
"image_url": {
"url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/r2v_tea_pic2.jpg"
},
"role": "reference_image"
},
{
"type": "video_url",
"video_url": {
"url": "https://ark-project.tos-cn-beijing.volces.com/doc_video/r2v_tea_video1.mp4"
},
"role": "reference_video"
},
{
"type": "audio_url",
"audio_url": {
"url": "https://ark-project.tos-cn-beijing.volces.com/doc_audio/r2v_tea_audio1.mp3"
},
"role": "reference_audio"
}
],
"generate_audio":true,
"ratio": "16:9",
"duration": 11,
"watermark": false
}'
```
### 编辑视频
```bash
curl https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ARK_API_KEY" \
-d '{
"model": "doubao-seedance-2-0-260128",
"content": [
{
"type": "text",
"text": "将视频1礼盒中的香水替换成图片1中的面霜，运镜不变"
},
{
"type": "image_url",
"image_url": {
"url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/r2v_edit_pic1.jpg"
},
"role": "reference_image"
},
{
"type": "video_url",
"video_url": {
"url": "https://ark-project.tos-cn-beijing.volces.com/doc_video/r2v_edit_video1.mp4"
},
"role": "reference_video"
}
],
"generate_audio": true,
"ratio": "16:9",
"duration": 5,
"watermark": true
}'
```
### 延长视频
```bash
curl https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ARK_API_KEY" \
-d '{
"model": "doubao-seedance-2-0-260128",
"content": [
{
"type": "text",
"text": "视频1中的拱形窗户打开，进入美术馆室内，接视频2，之后镜头进入画内，接视频3"
},
{
"type": "video_url",
"video_url": {
"url": "https://ark-project.tos-cn-beijing.volces.com/doc_video/r2v_extend_video1.mp4"
},
"role": "reference_video"
},
{
"type": "video_url",
"video_url": {
"url": "https://ark-project.tos-cn-beijing.volces.com/doc_video/r2v_extend_video2.mp4"
},
"role": "reference_video"
},
{
"type": "video_url",
"video_url": {
"url": "https://ark-project.tos-cn-beijing.volces.com/doc_video/r2v_extend_video3.mp4"
},
"role": "reference_video"
}
],
"generate_audio": true,
"ratio": "16:9",
"duration": 8,
"watermark": true
}'
```
### 使用联网搜索
仅支持文本生视频
```bash
curl https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ARK_API_KEY" \
-d '{
"model": "doubao-seedance-2-0-260128",
"content": [
{
"type": "text",
"text": "微距镜头对准叶片上翠绿的玻璃蛙。焦点逐渐从它光滑的皮肤，转移到它完全透明的腹部，一颗鲜红的心脏正在有力地、规律地收缩扩张。"
}
],
"generate_audio":true,
"ratio": "16:9",
"duration": 11,
"watermark": true,
"tools": [
{
"type": "web_search"
}
]
}'
```
## 2. 查询视频生成任务
```bash
//请将 cgt-2026****hzc2z 替换为创建视频生成任务时获得的任务ID
curl -X GET https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks/cgt-2026****hzc2z \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ARK_API_KEY"
```
# 最佳实践
## 使用公共虚拟人像生成视频
平台提供公共虚拟人像素材库，目前您可以使用其中的图像素材来创建一个统一、完备的视频主角。帮助您更好地控制主角，并确保其形象在多段视频中保持一致，避免因为真人人脸限制导致角色无法统一的问题。
素材模态目前包含图片，并提供人物背景描述。每个素材对应一个独立素材 ID (asset ID)，在体验中心的视频生成任务中，指定角色人脸生成视频。
1. 在浏览器中打开[体验中心](https://console.volcengine.com/ark/region:ark+cn-beijing/experience/vision?modelId=doubao-seedance-2-0-260128\&tab=GenVideo)，点击输入框下方的 **虚拟人像库** 页签。
2. 检索需要使用的人像，支持使用自然语言检索及筛选框组合筛选。
| 输入：文本 | 输入：虚拟人像、图片 | 输出 |
| ---------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -- |
| **图片1**中美妆博主用中文进行介绍，妆容改为明艳大气，去掉脸部反光，笑容甜美，近景镜头，手持**图片2**的面霜面向镜头展示，清新简约背景，元气甜美风格。博主台词：挖到本命面霜了！质地像云朵一样软糯，一抹就吸收，熬夜急救、补水保湿全搞定，素颜都自带柔光感。 | ![Image Token: HTf6bPRukoWaW4xnCSlcvKtUn7c](images/HTf6bPRukoWaW4xnCSlcvKtUn7c.png)![Image Token: YfCDbzJlqo4yzZxCmdscWdsInCf](images/YfCDbzJlqo4yzZxCmdscWdsInCf.jpeg) | |
在 [Video Generation API](https://www.volcengine.com/docs/82379/1520758) 的 **content.<模态>\_url.url** 字段中使用 素材 URI 生成视频。
> 输入的参考内容，包括人像素材，需符合视频生成限制，具体信息请查看使用限制。
>
> **注意**：
>
> * 首次在 API 中使用虚拟人像素材 Asset URI 前，需先在[方舟体验中心](https://console.volcengine.com/ark/region:ark+cn-beijing/experience/vision?modelId=doubao-seedance-2-0-260128\&tab=GenVideo)提交一次视频生成任务，阅读并同意弹出的 **虚拟人像库使用协议**。
>
> * 体验中心支持体验视频生成能力。默认单次生成 4 段视频，为节约成本，建议设置为每次生成 1 条，具体方式可参考[虚拟人像库](https://www.volcengine.com/docs/82379/2223965?lang=zh)。
同意协议的操作方式如下：
![Image Token: LK8ybUN9Ko2KkQxq2FdclVQtnkh](images/LK8ybUN9Ko2KkQxq2FdclVQtnkh.gif)
示例代码：
> **注意：**
> 在传入给模型的 Prompt 中，需要使用**图片 1**、**视频 1&#x20;**&#x7684;方式指代参考素材，素材序号为素材在请求体中的顺序。请勿直接在 Prompt 中直接使用 Asset ID。
> 例：“**图片1&#x20;**&#x91CC;的女孩身着**图片2**中的服装，正在整理柜台上的物品。**图片3**中的男孩是一位顾客，他走上前，想要向女孩索要联系方式。”&#x20;
>
> 调用示例请参考[常见问题 4](https://bytedance.larkoffice.com/wiki/RtHgwpJgviwFXLkQ9hLcRooEnVe#share-YOKvdYHjro8EjtxucWaczf6vneg)
```python
import os
import time
# Install SDK: pip install 'volcengine-python-sdk[ark]'
from volcenginesdkarkruntime import Ark
client = Ark(
# The base URL for model invocation
base_url='https://ark.cn-beijing.volces.com/api/v3',
# Get API Key：https://console.volcengine.com/ark/region:ark+cn-beijing/apikey
api_key=os.environ.get("ARK_API_KEY"),
)
if __name__ == "__main__":
print("----- create request -----")
create_result = client.content_generation.tasks.create(
model="doubao-seedance-2-0-260128", # Replace with Model ID
content=[
{
"type": "text",
# 注意：素材图片指代需使用“图片N”（ N 表示传入素材图片/图片的序号，如“图片1”、“图片2”）
"text": "图片1中美妆博主用中文进行介绍，妆容改为明艳大气，去掉脸部反光，笑容甜美，近景镜头，手持图片2的面霜面向镜头展示，清新简约背景，元气甜美风格。博主台词：挖到本命面霜了！质地像云朵一样软糯，一抹就吸收，熬夜急救、补水保湿全搞定，素颜都自带柔光感。"
},
{
"type": "image_url",
"image_url": {
"url": "asset://asset-20260224200602-qn7wr"
},
"role": "reference_image"
},
{
"type": "image_url",
"image_url": {
"url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/r2v_edit_pic1.jpg"
},
"role": "reference_image"
},
],
generate_audio=True,
ratio="16:9",
duration=11,
watermark=True,
)
print(create_result)
print("----- polling task status -----")
task_id = create_result.id
while True:
get_result = client.content_generation.tasks.get(task_id=task_id)
status = get_result.status
if status == "succeeded":
print("----- task succeeded -----")
print(get_result)
break
elif status == "failed":
print("----- task failed -----")
print(f"Error: {get_result.error}")
break
else:
print(f"Current status: {status}, Retrying after 30 seconds...")
time.sleep(30)
```
***
## 使用自有虚拟人像素材生成视频
Seedance 2.0 及 2.0 fast 模型具有完备的防范 Deepfake 和侵犯版权风险能力。在生成视频时，会对有风险的参考素材输入进行拦截，最大限度保证生成视频合规和安全性。
为确保创作者能充分利用 Seedance 2.0 系列模型强大的视频生成能力高效生成视频内容，同时规避 AI 生成内容的潜在风险，方舟推出了私域可信素材库，支持创作者自助上传虚拟人像素材。完成入库的可信素材将进入您的私域素材库，在视频生成中使用。
> 具体信息请参考文档：[ 「⚠️保密信息」【申请权限填客户名称】私域虚拟人像素材资产库使用指南（邀测用户版）](https://bytedance.larkoffice.com/wiki/RtHgwpJgviwFXLkQ9hLcRooEnVe)。
***
## 使用模型产物进行二创
Seedance 2.0 及 2.0 fast 模型生成的视频为受信素材。您可使用**本账号下**由上述模型生成的视频，进行视频编辑、视频延长等二次创作，素材中的人脸可正常参与生成，不会触发审核拦截。
> 2026年3月11日起，使用 Seedance 2.0 及 2.0 fast 模型生成的视频，支持二次创作。
| 输入：文本 | 输入：虚拟人像、图片 | 第一次输出视频 | 二次编辑后视频 |
| ---------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------- |
| **图片1**中美妆博主用中文进行介绍，妆容改为明艳大气，去掉脸部反光，笑容甜美，近景镜头，手持**图片2**的面霜面向镜头展示，清新简约背景，元气甜美风格。博主台词：挖到本命面霜了！质地像云朵一样软糯，一抹就吸收，熬夜急救、补水保湿全搞定，素颜都自带柔光感。 | ![Image Token: MbrRbjSSDoqaaKx3YmCcbVZUnud](images/MbrRbjSSDoqaaKx3YmCcbVZUnud.png)![Image Token: UGfibSj7soIYJMxoYpEcDBIcnkb](images/UGfibSj7soIYJMxoYpEcDBIcnkb.jpeg) | | |
1. 首次生视频，并获取视频 URL。
> **注意：**
> 在传入给模型的 Prompt 中，需要使用**图片 1**、**视频 1&#x20;**&#x7684;方式指代参考素材，素材序号为素材在请求体中的顺序。
>
> 请勿直接在 Prompt 中直接使用 Asset ID。
> 例：“**图片1&#x20;**&#x91CC;的女孩身着**图片2**中的服装，正在整理柜台上的物品。**图片3**中的男孩是一位顾客，他走上前，想要向女孩索要联系方式。”
```python
import os
import time
# Install SDK: pip install 'volcengine-python-sdk[ark]'
from volcenginesdkarkruntime import Ark
client = Ark(
# The base URL for model invocation
base_url='https://ark.cn-beijing.volces.com/api/v3',
# Get API Key：https://console.volcengine.com/ark/region:ark+cn-beijing/apikey
api_key=os.environ.get("ARK_API_KEY"),
)
if __name__ == "__main__":
print("----- create request -----")
create_result = client.content_generation.tasks.create(
model="doubao-seedance-2-0-260128", # Replace with Model ID
content=[
{
"type": "text",
# 注意：素材图片指代需使用“图片N”（ N 表示传入素材图片/图片的序号，如“图片1”、“图片2”）
"text": "图片1中美妆博主用中文进行介绍，妆容改为明艳大气，去掉脸部反光，笑容甜美，近景镜头，手持图片2的面霜面向镜头展示，清新简约背景，元气甜美风格。博主台词：挖到本命面霜了！质地像云朵一样软糯，一抹就吸收，熬夜急救、补水保湿全搞定，素颜都自带柔光感。"
},
{
"type": "image_url",
"image_url": {
"url": "asset://asset-20260224200602-qn7wr"
},
"role": "reference_image"
},
{
"type": "image_url",
"image_url": {
"url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/r2v_edit_pic1.jpg"
},
"role": "reference_image"
},
],
generate_audio=True,
ratio="16:9",
duration=11,
watermark=True,
)
print(create_result)
print("----- polling task status -----")
task_id = create_result.id
while True:
get_result = client.content_generation.tasks.get(task_id=task_id)
status = get_result.status
if status == "succeeded":
print("----- task succeeded -----")
print(get_result)
break
elif status == "failed":
print("----- task failed -----")
print(f"Error: {get_result.error}")
break
else:
print(f"Current status: {status}, Retrying after 30 seconds...")
time.sleep(30)
```
* 对首次生成的视频进行再次编辑。为直观展示效果，本示例中直接使用视频原始 URL。
> 视频原始 URL 的有效期仅 24 小时，实际使用时，建议您提前转存视频文件（例如上传至火山引擎TOS）。
```python
import os
import time
# Install SDK: pip install 'volcengine-python-sdk[ark]'
from volcenginesdkarkruntime import Ark
client = Ark(
# The base URL for model invocation
base_url='https://ark.cn-beijing.volces.com/api/v3',
# Get API Key：https://console.volcengine.com/ark/region:ark+cn-beijing/apikey
api_key=os.environ.get("ARK_API_KEY"),
)
if __name__ == "__main__":
print("----- create request -----")
create_result = client.content_generation.tasks.create(
model="doubao-seedance-2-0-260128", # Replace with Model ID
content=[
{
"type": "text",
"text": "将视频1中的背景修改为室内，房间布置温馨，包括白色的沙发，梳妆台和鲜花。"
},
{
"type": "video_url",
"video_url": {
"url": "https://ark-acg-cn-beijing.tos-cn-beijing.volces.com/doubao-seedance-2-0/02177390693606300000000000000000000ffffc0a88a7fb18e5d.mp4?X-Tos-Algorithm=TOS4-HMAC-SHA256&X-Tos-Credential=AKLTMjQyZTA4MzFjYTY0NGE5YzgzNTIzMTQzYWI5MmVjMDY%2F20260319%2Fcn-beijing%2Ftos%2Frequest&X-Tos-Date=20260319T075900Z&X-Tos-Expires=86400&X-Tos-Signature=204c1d922d7f563ab0fe2bdf28fe3764df52b3404827acf11c9f3dead82aa3db&X-Tos-SignedHeaders=host"
},
"role": "reference_video"
},
],
generate_audio=True,
ratio="16:9",
duration=11,
watermark=True,
)
print(create_result)
print("----- polling task status -----")
task_id = create_result.id
while True:
get_result = client.content_generation.tasks.get(task_id=task_id)
status = get_result.status
if status == "succeeded":
print("----- task succeeded -----")
print(get_result)
break
elif status == "failed":
print("----- task failed -----")
print(f"Error: {get_result.error}")
break
else:
print(f"Current status: {status}, Retrying after 30 seconds...")
time.sleep(30)
```
## 私域素材资产上传最佳案例
> 在上传素材资产时，**若将目标人脸图、全身参考图及细节参考图合并为同一张图片，可能导致各参考元素在画面中占比较小，从而增加模型识别难度**，造成生成视频中的人物形象与所上传素材资产出现偏差，或造成生成视频中素人脸被误识别为明星脸而触发风控拦截。
建议在上传素材资产时，将人物面部特写、服装细节等关键内容独立分割为单独的图片进行上传。具体可参考如下规则及示例：
| | 应该 | 不应该 | |
| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 输入内容 | 给出背景参考图、人物妆造三视图、人物面部无表情特写图、提示词![图片1-背景参考图 (Token: Hi55bqOYyoBWvSxMDjNcEuSJn7c)](images/Hi55bqOYyoBWvSxMDjNcEuSJn7c.png)![图片2-人物妆造三视图 (Token: XQE5bI0tJovdxmxf0qMcFCtEnoc)](images/XQE5bI0tJovdxmxf0qMcFCtEnoc.png)![图片3-人物面部特写图 (Token: BpkhbHY0Co0pB0xTgoRcLDOynGc)](images/BpkhbHY0Co0pB0xTgoRcLDOynGc.png) | 给出背景参考图、人物妆造三视图、提示词![图片1-背景参考图 (Token: T572bL5IGooP4HxogzGcwERRn5c)](images/T572bL5IGooP4HxogzGcwERRn5c.png)![图片2-人物妆造三视图 (Token: WZIcbGijXoOOZnxQRS9cA4kMndh)](images/WZIcbGijXoOOZnxQRS9cA4kMndh.png) | |
| 输出内容 | | | |
| 总结 | 同样是古风打斗剧情：左边输入内容包括：背景参考图、**人物妆造三视图**、**人物面部无表情特写图**、提示词；中间输入内容包括：背景参考图、人物妆造三视图、提示词；右边输入内容包括：背景参考图、人物妆造正视图、提示词。左边的输出视频更加还原人物面部特征；右边的人物面部特征一致性遵循不佳。 | | |
| 输入内容 | 给出背景参考图、人物妆造三视图、人物面部无表情特写图、提示词![图片1-背景参考图 (Token: JLD7bmUBYo7FpaxiAsicLkMQnKe)](images/JLD7bmUBYo7FpaxiAsicLkMQnKe.jpeg)![图片2-人物妆造三视图 (Token: Xj45b0L5uopyMqxTUOLcwn0ZnCc)](images/Xj45b0L5uopyMqxTUOLcwn0ZnCc.jpeg)![图片3-人物面部特写图 (Token: S7JRbu09Jo9OdkxHy7TcWTarnRh)](images/S7JRbu09Jo9OdkxHy7TcWTarnRh.png)![图片4-人物妆造三视图 (Token: KS5hb2DlCoLL6uxHnfdcl9konBe)](images/KS5hb2DlCoLL6uxHnfdcl9konBe.jpeg)![图片5-人物面部特写图 (Token: NtOnbySAHokJ4JxR4sdcu8oRnyh)](images/NtOnbySAHokJ4JxR4sdcu8oRnyh.jpeg) | 给出背景参考图、人物妆造三视图、提示词![图片1-背景参考图 (Token: I3ICbosi0oaR1LxcezKcYJWCnic)](images/I3ICbosi0oaR1LxcezKcYJWCnic.jpeg)![图片2-人物妆造三视图 (Token: JtOLbQ1iLoxTPUxXrkLcMcXknB8)](images/JtOLbQ1iLoxTPUxXrkLcMcXknB8.jpeg)![图片3-人物妆造三视图 (Token: RGoubMdjTokEK3xjJ3KcQqPtnuf)](images/RGoubMdjTokEK3xjJ3KcQqPtnuf.jpeg) | 给出背景参考图、人物妆造正视图、提示词![图片1-背景参考图 (Token: YCcmbhQVFoUcHcxExHfcSrSQnab)](images/YCcmbhQVFoUcHcxExHfcSrSQnab.jpeg)![图片2-人物妆造正视图 (Token: OoMFbcfBEoiqkCxOQJpcjgcAnzQ)](images/OoMFbcfBEoiqkCxOQJpcjgcAnzQ.png)![图片3-人物妆造正视图 (Token: ZAs6bIUkQooRUBxxe2EcHDQ2nug)](images/ZAs6bIUkQooRUBxxe2EcHDQ2nug.png) |
| 输出内容 | | | |
| 总结 | 同样是温馨亲子剧情：左边输入内容包括：背景参考图、**人物妆造三视图、人物面部无表情特写图**、提示词；中间输入内容包括：背景参考图、人物妆造三视图、提示词；右边输入内容包括：背景参考图、人物妆造正面图、提示词。左边的输出视频更加还原人物面部特征；中间的输出视频人物面部特征一致性遵循不佳；右边人物妆造、面部特征一致性遵循不佳。 | | |

1005
docs/API文档/3-31「保密信息」【申请权限填客户名称】Assets API 参考文档（邀测用户版）.md
View File

File diff suppressed because it is too large Load Diff

692
docs/API文档/old-Seedance 2.0 & 2.0 fast API文档（邀测用户版）.md
View File

@ -1,692 +0,0 @@
# 【申请权限填客户名称】Seedance 2.0 & 2.0 fast API文档（邀测用户版）
该文档目前仅限开白客户使用，发送前请和销管确认客户是否在开白名单内
***【❗️❗️❗️】该文档限制客户申请权限，只有返回了服务协议的客户方可申请***
本文介绍 Seedance 2.0 & 2.0 fast 模型相较于存量模型 **新增/配置有区别&#x20;**&#x7684; API 参数介绍，存量 API 参数的完整介绍参见 [视频生成 API](https://www.volcengine.com/docs/82379/1520758?lang=zh)。
> 本文档仅限预览及邀测用户使用：
>
> * 不承诺正式API上线100%一致。
>
> * 仅限邀测用户阅读，请勿截图/分享给其他人员。
>
> * 您上传的内容请确保由您原创或已取得授权。
# 模型能力
> **Seedance 2.0 和 Seedance 2.0 fast 提供的模型能力一致，**&#x8FFD;求最高生成品质，推荐使用 **Seedance 2.0**；更注重成本与生成速度，不要求极限品质，推荐使用 **Seedance 2.0 fast**。
**Seedance 2.0 & 2.0 fast (有声视频/无声视频)**
* **多模态参考生视频**：输入参考图片（0\~9）+参考视频（0\~3）+ 参考音频（0\~3）+ 文本提示词（可选）生成 1 个目标视频。支持生成全新视频、编辑视频、延长视频。
> **注意：不可单独输入音频，应至少包含 1 个参考视频或图片。**
* **图生视频-首尾帧**：输入首帧图片+尾帧图片+文本提示词（可选）生成 1 个目标视频。
* **图生视频-首帧**：输入首帧图片+文本提示词（可选）生成 1 个目标视频。
* **文生视频**：输入文本提示词生成 1 个目标视频。
**模型能力对比表：**
| 模型名称 | | [Seedance 2.0](https://console.volcengine.com/ark/region:ark+cn-beijing/model/detail?Id=doubao-seedance-2-0) | [Seedance 2.0 fast](https://console.volcengine.com/ark/region:ark+cn-beijing/model/detail?Id=doubao-seedance-2-0-fast\&projectName=default) | [Seedance 1.5 pro](https://console.volcengine.com/ark/region:ark+cn-beijing/model/detail?Id=doubao-seedance-1-5-pro\&projectName=default) | [Seedance 1.0 pro ](https://console.volcengine.com/ark/region:ark+cn-beijing/model/detail?Id=doubao-seedance-1-0-pro\&projectName=default) | [Seedance 1.0 pro fast ](https://console.volcengine.com/ark/region:ark+cn-beijing/model/detail?Id=doubao-seedance-1-0-pro-fast\&projectName=default) | [Seedance 1.0 lite i2v](https://console.volcengine.com/ark/region:ark+cn-beijing/model/detail?Id=doubao-seedance-1-0-lite-i2v\&projectName=default) | [Seedance-1.0 lite t2v ](https://console.volcengine.com/ark/region:ark+cn-beijing/model/detail?Id=doubao-seedance-1-0-lite-t2v) |
| ------------ | -------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| Model ID | | doubao-seedance-2-0-260128 | doubao-seedance-2-0-fast-260128 | doubao-seedance-1-5-pro-251215 | doubao-seedance-1-0-pro-250528 | doubao-seedance-1-0-pro-fast-251015 | doubao-seedance-1-0-lite-i2v-250428 | doubao-seedance-1-0-lite-t2v-250428 |
| 文生视频 | | ✅ | | ✅ | ✅ | ✅ | ✅ | ✅ |
| 图生视频-首帧 | | ✅ | | ✅ | ✅ | ✅ | ✅ | ❌ |
| 图生视频-首尾帧 | | ✅ | | ✅ | ✅ | ❌ | ✅ | ❌ |
| 多模态参考【New】 | 图片参考 | ✅ | | ❌ | ❌ | ❌ | ✅ | ❌ |
| | 视频参考 | ✅ | | ❌ | ❌ | ❌ | ❌ | ❌ |
| | 组合参考 | ✅ | | ❌ | ❌ | ❌ | ❌ | ❌ |
| 编辑视频【New】 | | ✅ | | ❌ | ❌ | ❌ | ❌ | ❌ |
| 延长视频【New】 | | ✅ | | ❌ | ❌ | ❌ | ❌ | ❌ |
| 生成有声视频 | | ✅ | | ✅ | ❌ | ❌ | ❌ | ❌ |
| 联网搜索增强【New】 | | ✅ | | ❌ | [❌](https://p9-arcosite.byteimg.com/obj/tos-cn-i-goo7wpa0wc/f359753773c94d97885008ca1223c9bc) | ❌ | ❌ | ❌ |
| 样片模式 | | ❌ | | ✅ | ❌ | ❌ | ❌ | ❌ |
| 返回视频尾帧 | | ✅ | | ✅ | ✅ | ✅ | ✅ | ✅ |
| 输出视频规格 | 输出分辨率 | 480p, 720p | | 480p, 720p, 1080p | 480p, 720p, 1080p | 480p, 720p, 1080p | 480p, 720p, 1080p | 480p, 720p, 1080p |
| | 输出宽高比 | 21:9, 16:9, 4:3, 1:1, 3:4, 9:16 | | | | | | |
| | 输出时长 | 4\~15 秒 | | 4\~12 秒 | 2\~12 秒 | 2\~12 秒 | 2\~12 秒 | 2\~12 秒 |
| | 输出视频格式 | mp4 | | mp4 | mp4 | mp4 | mp4 | mp4 |
| 离线推理 | | [❌](https://p9-arcosite.byteimg.com/obj/tos-cn-i-goo7wpa0wc/f359753773c94d97885008ca1223c9bc) | | ✅ | ✅ | ✅ | ✅ | ✅ |
| 在线推理限流 | RPM | 600 | | 600 | 600 | 600 | 300 | 300 |
| | 并发数 | 10 | | 10 | 10 | 10 | 5 | 5 |
| 离线推理限流 | TPD | - | | 5000亿 | 5000亿 | 5000亿 | 2500亿 | 2500亿 |
# Creat-创建视频生成任务
> POST https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks
## 请求参数
#### **content** `object[]` `必选`
输入给模型，生成视频的信息，支持文本、图片、音频、视频、样片任务 ID。支持以下几种组合：
* **文本**
* **文本（可选）+ 图片**
* **文本（可选）+ 视频**
* **文本（可选）+ 图片 + 音频**
* **文本（可选）+ 图片 + 视频**
* **文本（可选）+ 视频 + 音频**
* **文本（可选）+ 图片 + 视频 + 音频**
***
**信息类型：**
* **文本信息**`object`
输入给模型的提示词信息。
***
content.**type&#x20;**`string` `必选`
输入内容的类型，此处应为 **text**。
***
content.**text&#x20;**`string` `必选`
输入给模型的文本提示词，描述期望生成的视频。
支持中英文。建议中文不超过500字，英文不超过1000词。字数过多信息容易分散，模型可能因此忽略细节，只关注重点，造成视频缺失部分元素。提示词的更多使用技巧请参见 [Seedance 提示词指南](https://www.volcengine.com/docs/82379/1587797)。
* **图片信息** `object`
输入给模型的图片信息。
***
content.**type&#x20;**`string` `必选`
输入内容的类型，此处应为 **image\_url**。
***
content.**image\_url&#x20;**`object` `必选`
输入给模型的图片对象。
***
content.image\_url.**url&#x20;**`string` `必选`
图片 URL 、图片 Base64 编码、素材 ID。
* 图片 URL：填入图片的公网 URL。
* Base64 编码：将本地文件转换为 Base64 编码字符串，然后提交给大模型。遵循格式：data:image/<图片格式>;base64,\<Base64编码>，注意 <图片格式> 需小写，如 data:image/png;base64,{base64\_image}。
* 素材 ID：用于视频生成的预置素材及虚拟人像的 ID，遵循格式：asset://\<ASSET\_ID>，可从 [素材&虚拟人像库](https://console.volcengine.com/ark-stg/region:ark-stg+cn-beijing/experience/vision?modelId=doubao-seedance-2-0-260128) 获取，详细使用请参见[文档](https://www.volcengine.com/docs/82379/2223965?lang=zh)。
> **传入单张图片要求**
>
> * 格式：jpeg、png、webp、bmp、tiff、gif
>
> * 宽高比（宽/高）： (0.4, 2.5)&#x20;
>
> * 宽高长度（px）：(300, 6000)
>
> * 大小：单张图片小于 30 MB。请求体大小不超过 64 MB。大文件请勿使用Base64编码。
>
> * 图片数量：
>
> * 图生视频-首帧：1 张
>
> * 图生视频-首尾帧：2 张
>
> * Seedance 2.0 & 2.0 fast 多模态参考生视频：1\~9 张
***
content.**role&#x20;**`string` `条件必填`
图片的位置或用途。
> **注意**
>
> * **图生视频-首帧**、**图生视频-首尾帧**、**多模态参考生视频**（包括参考图、视频、音频）为 3 种互斥场景，**不可混用**。
>
> * **多模态参考生视频**可通过提示词指定参考图片作为首帧/尾帧，间接实现“首尾帧+多模态参考”效果。若需严格保障首尾帧和指定图片一致，**优先使用图生视频-首尾帧**（配置 role 为 **first\_frame / last\_frame**）。
***
**图生视频-首帧**
> 需要传入1个 image\_url 对象
* **字段role取值：**
* **first\_frame 或不填**
***
**图生视频-首尾帧**
> 需要传入2个 image\_url 对象
* **字段role取值：**
* 首帧图片对应的字段 role 为：**first\_frame**，必填
* 尾帧图片对应的字段 role 为：**last\_frame**，必填
***
**图生视频-参考图&#x20;**
> 可传入 1\~9 个 image\_url 对象
* **字段role取值**：
* 每张参考图对应的字段 role 均为：**reference\_image**，必填
* **视频信息** `object`&#x20;
输入给模型的视频信息。仅 Seedance 2.0 & 2.0 fast 支持输入视频。
***
content.**type&#x20;**`string` `必选`
输入内容的类型，此处应为 **video\_url**。
***
content.**video\_url&#x20;**`object` `必选`
输入给模型的视频对象。
***
content.video\_url.**url&#x20;**`string` `必选`
视频URL、素材 ID。
* 视频 URL：填入视频的公网 URL。
* 素材 ID：用于视频生成的预置素材及虚拟人像视频的 ID，遵循格式：asset://\<ASSET\_ID>。可从[素材&虚拟人像库](https://console.volcengine.com/ark-stg/region:ark-stg+cn-beijing/experience/vision?modelId=doubao-seedance-2-0-260128)获取。
> **传入单个视频要求**
>
> * 视频格式：mp4、mov。
>
> * 分辨率：480p、720p
>
> * 时长：单个视频时长 \[2, 15] s，最多传入 3 个参考视频，所有视频总时长不超过 15s。
>
> * 尺寸：
>
> * 宽高比（宽/高）：\[0.4, 2.5]
>
> * 宽高长度（px）：\[300, 6000]
>
> * 画面像素（宽 × 高）：\[409600, 927408] ，示例：
>
> * 画面尺寸 640×640=409600 满足最小值 ；
>
> * 画面尺寸 834×1112=927408 满足最大值。
>
> * 大小：单个视频不超过 50 MB。
>
> * 帧率 (FPS)：\[24, 60]&#x20;
***
content.**role&#x20;**`string` `条件必填`
视频的位置或用途。当前仅支持 **reference\_video**。
* **音频信息&#x20;**`object`&#x20;
输入给模型的音频信息。仅 Seedance 2.0 & 2.0 fast 支持输入音频。注意不可单独输入音频，应至少包含 1 个参考视频或图片。
***
content.**type&#x20;**`string` `必选`
输入内容的类型，此处应为 **audio\_url**。
***
content.**audio\_url&#x20;**`object` `必选`
输入给模型的音频对象。
***
content.audio\_url.**url&#x20;**`string` `必选`
音频 URL 、音频 Base64 编码、素材 ID。
* 音频 URL：填入音频的公网 URL。
* Base64 编码：将本地文件转换为 Base64 编码字符串，然后提交给大模型。遵循格式：data:audio/<音频格式>;base64,\<Base64编码>，注意 <音频格式> 需小写，如 data:audio/wav;base64,{base64\_audio}。
* 素材 ID：用于视频生成的虚拟人的音频素材 ID，遵循格式：asset://\<ASSET\_ID>。可从[素材&虚拟人像库](https://console.volcengine.com/ark-stg/region:ark-stg+cn-beijing/experience/vision?modelId=doubao-seedance-2-0-260128)获取。
> **传入单个音频要求**
>
> * 格式：wav、mp3
>
> * 时长：单个音频时长 \[2, 15] s，最多传入 3 段参考音频，所有音频总时长不超过 15 s。
>
> * 大小：单个音频不超过 15 MB，请求体大小不超过 64 MB。大文件请勿使用Base64编码。
***
content.**role&#x20;**`string` `条件必填`
音频的位置或用途。当前仅支持 **reference\_audio** 。
#### **service\_tier** `string`
&#x20;Seedance 2.0 & 2.0 fast 暂不支持
#### **generate\_audio&#x20;**`boolean`&#x20;
> Seedance 2.0 & 2.0 fast 默认值： true
控制生成的视频是否包含与画面同步的声音。
* true：模型输出的视频包含同步音频。模型会基于文本提示词与视觉内容，自动生成与之匹配的人声、音效及背景音乐。建议将对话部分置于双引号内，以优化音频生成效果。例如：男人叫住女人说：“你记住，以后不可以用手指指月亮。”
* false：模型输出的视频为无声视频。
> **说明**
>
> 生成的有声视频均为单声道，和传入的音频声道数无关。
####
#### **draft&#x20;**`boolean`
&#x20;Seedance 2.0 & 2.0 fast 暂不支持
#### **tools&#x20;**`object[]`
> 仅 Seedance 2.0 & 2.0 fast 支持
配置模型要调用的工具。
***
tools.**type&#x20;**`string`
指定使用的工具类型。
* web\_search：联网搜索工具。
> **说明**
>
> * 开启联网搜索后，模型会根据用户的提示词自主判断是否搜索互联网内容（如商品、天气等）。可提升生成视频的时效性，但也会增加一定的时延。
>
> * 实际搜索次数可通过 [查询视频生成任务 API](https://www.volcengine.com/docs/82379/1521309?lang=zh) 返回的 usage.tool\_usage.**web\_search** 字段获取，如果为 0 表示未搜索。
#### **resolution&#x20;**&#x20;`string`
> Seedance 2.0 & 2.0 fast 默认值：720p
视频分辨率，取值范围：
* 480p
* 720p
#### **ratio&#x20;**`string`&#x20;
> Seedance 2.0 & 2.0 fast 默认值： adaptive
生成视频的宽高比例。不同宽高比对应的宽高像素值见下方表格。
* 16:9&#x20;
* 4:3
* 1:1
* 3:4
* 9:16
* 21:9
* adaptive：根据输入自动选择最合适的宽高比
> **adaptive 适配规则**
>
> 当配置 **ratio** 为 adaptive 时，模型会根据生成场景自动适配宽高比；实际生成的视频宽高比可通过 [查询视频生成任务 API](https://www.volcengine.com/docs/82379/1521309?lang=zh) 返回的 **ratio** 字段获取。
>
> * 文生视频：根据输入的提示词，智能选择最合适的宽高比。
>
> * 首帧 / 首尾帧生视频：根据上传的首帧图片比例，自动选择最接近的宽高比。
>
> * 多模态参考生视频：根据用户提示词意图判断，如果是首帧生视频/编辑视频/延长视频，以该图片/视频为准选择最接近的宽高比；否则，以传入的第一个媒体文件为准（优先级：视频＞图片）选择最接近的宽高比。
***
**不同宽高比对应的宽高像素值：**
| 分辨率 | 宽高比 | 宽高像素值 |
| ---- | ---- | -------- |
| 480p | 16:9 | 864×496 |
| | 4:3 | 752×560 |
| | 1:1 | 640×640 |
| | 3:4 | 560×752 |
| | 9:16 | 496×864 |
| | 21:9 | 992×432 |
| 720p | 16:9 | 1280×720 |
| | 4:3 | 1112×834 |
| | 1:1 | 960×960 |
| | 3:4 | 834×1112 |
| | 9:16 | 720×1280 |
| | 21:9 | 1470×630 |
#### **duration** `integer`&#x20;
> Seedance 2.0 & 2.0 fast 默认值：5
生成视频时长，仅支持整数，单位：秒。
取值范围：
* \[4,15] 或设置为-1
> **配置方法**
>
> * 指定具体时长：支持有效范围内的任一整数。
>
> * 智能指定：设置为 -1，表示由模型在有效范围内自主选择合适的视频长度（整数秒）。实际生成视频的时长可通过 [查询视频生成任务 API](https://www.volcengine.com/docs/82379/1521309?lang=zh) 返回的 **duration** 字段获取。注意视频时长与计费相关，请谨慎设置。
#### **frames** `integer`&#x20;
Seedance 2.0 & 2.0 fast 暂不支持
#### **camera\_fixed** `boolean`
&#x20;Seedance 2.0 & 2.0 fast 暂不支持
# Get/List-查询视频生成任务/列表
> 查询视频生成任务：GET https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks/{id}
>
> 查询视频生成任务列表：GET https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks?page\_num={page\_num}\&page\_size={page\_size}\&filter.status={filter.status}\&filter.task\_ids={filter.task\_ids}\&filter.model={filter.model}
## 响应参数
#### **tools&#x20;**`object[]`&#x20;
> 仅 Seedance 2.0 & 2.0 fast 支持
配置模型要调用的工具。
***
tools.**type&#x20;**`string`
指定使用的工具类型。
* web\_search：联网搜索工具。
#### **usage** `object`
本次请求的 token 用量。
***
usage.**completion\_tokens** `integer`
模型输出视频花费的 token 数量。
***
usage.**total\_tokens** `integer`
本次请求消耗的总 token 数量。
***
usage.**tool\_usage&#x20;**`object`&#x20;
> 仅 Seedance 2.0 & 2.0 fast 支持
使用工具的用量信息。
***
usage.tool\_usage.**web\_search&#x20;**`integer`&#x20;
实际调用联网搜索工具的次数，仅开启联网搜索时返回。
# 调用简介及示例
## 流程简介
任务接口是异步接口，视频生成任务流程
1. 创建视频生成任务接口创建视频生成任务
2. 定时使用查询接口查询视频生成任务状态
1. 任务 running，过段时间再查询任务状态
2. 任务完成，返回视频链接，在24小时内下载生成的视频文件
## 1. 创建视频生成任务
> 以下示例仅展示 Seedance 2.0 & 2.0 fast 新增能力，更多视频生成示例详见 [创建视频生成任务 API](https://www.volcengine.com/docs/82379/1520757)。
### 多模态参考
### 编辑视频
### 延长视频
### 使用联网搜索
仅支持文本生视频
## 2. 查询视频生成任务
# 最佳实践-使用公共虚拟人像生成视频
平台提供公共虚拟人像素材库，目前您可以使用其中的图像素材来创建一个统一、完备的视频主角。帮助您更好地控制主角，并确保其形象在多段视频中保持一致，避免因为真人人脸限制导致角色无法统一的问题。
素材模态目前包含图片，并提供人物背景描述。每个素材对应一个独立素材 ID (asset ID)，在体验中心的视频生成任务中，指定角色人脸生成视频。
1. 在浏览器中打开[体验中心](https://console.volcengine.com/ark/region:ark+cn-beijing/experience/vision?modelId=doubao-seedance-2-0-260128\&tab=GenVideo)，点击输入框下方的 **虚拟人像库** 页签。
2. 检索需要使用的人像，支持使用自然语言检索及筛选框组合筛选。
| 输入：文本 | 输入：虚拟人像、图片 | 输出 |
| ---------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -- |
| **图片1**中美妆博主用中文进行介绍，妆容改为明艳大气，去掉脸部反光，笑容甜美，近景镜头，手持**图片2**的面霜面向镜头展示，清新简约背景，元气甜美风格。博主台词：挖到本命面霜了！质地像云朵一样软糯，一抹就吸收，熬夜急救、补水保湿全搞定，素颜都自带柔光感。 | ![Image Token: HTf6bPRukoWaW4xnCSlcvKtUn7c](images/HTf6bPRukoWaW4xnCSlcvKtUn7c.png)![Image Token: YfCDbzJlqo4yzZxCmdscWdsInCf](images/YfCDbzJlqo4yzZxCmdscWdsInCf.jpeg) | |
在 [Video Generation API](https://www.volcengine.com/docs/82379/1520758) 的 **content.<模态>\_url.url** 字段中使用 素材 URI 生成视频。
> 输入的参考内容，包括人像素材，需符合视频生成限制，具体信息请查看使用限制。
>
> **注意**：
>
> * 首次在 API 中使用虚拟人像素材 Asset URI 前，需先在[方舟体验中心](https://console.volcengine.com/ark/region:ark+cn-beijing/experience/vision?modelId=doubao-seedance-2-0-260128\&tab=GenVideo)提交一次视频生成任务，阅读并同意弹出的 **虚拟人像库使用协议**。
>
> * 体验中心支持体验视频生成能力。默认单次生成 4 段视频，为节约成本，建议设置为每次生成 1 条，具体方式可参考[虚拟人像库](https://www.volcengine.com/docs/82379/2223965?lang=zh)。
同意协议的操作方式如下：
![Image Token: LK8ybUN9Ko2KkQxq2FdclVQtnkh](images/LK8ybUN9Ko2KkQxq2FdclVQtnkh.gif)
示例代码：
# 使用自有虚拟人像素材生成视频（线下提交）
方舟提供私域人像素材库，您可在视频生成中使用自有虚拟人物或真人（仅限素人）素材，生成短剧等更定制化的视频内容。平台将对您提供的素材进行审核，规避可能产生的法律风险。
* 自有素材需入库后使用，您可将虚拟人像或真人素材发送给销售代表，同时完成合规承诺函及其他证明材料的准备。
* 入库后，您可使用素材的 Asset ID，在视频生成 API 中使用自有素材。
> **重要**：
>
> * 对虚拟人像素材，您需签署虚拟人像素材合规承诺函，并提供签署承诺函所需的材料。
>
> * 对真实人物素材，除承诺函外，您还需额外提供真人授权材料。
>
> * 具体流程及所需材料，请和您的销售代表确认。
提交自有人像素材时，需按人物将素材分组：
* 每个人物为一个素材组。
* 每组可包含多个素材文件，素材文件对应唯一 ID (asset ID)。
## 入库流程
提交自有虚拟人像素材方式大致如下，请联系您的销售代表了解详情。
1. 准备素材文件，完成承诺函签署，并准备其他证明材料。
2. 准备素材文件，完成承诺函签署，并准备其他证明材料。
* 每个人物素材需至少提供一张正面图片文件。此外，您可按需提供该人物的其他图片、视频素材。
* 需确保每个人物组中的素材与该正面图片为同一人物。
* 每个人物创建一个文件夹（命名：“*虚拟人像 1-<人像名>*”）
提交素材文件夹示例：
![Image Token: XMQ9bz6vhof7vxxsac8cqIZmneB](images/XMQ9bz6vhof7vxxsac8cqIZmneB.png)
> **注意**：
>
> * 以上示例仅供参考，您可根据视频创作需求，提交虚拟人物素材。
>
> * 您仅需上传视频生成任务中需要使用的素材。
* 素材文件需满足视频生成 API 对输入文件的要求：
> **传入单张图片要求**
>
> * 格式：jpeg、png、webp、bmp、tiff、gif
>
> * 宽高比（宽/高）： (0.4, 2.5)&#x20;
>
> * 宽高长度（px）：(300, 6000)
>
> * 大小：单张图片小于 30 MB。请求体大小不超过 64 MB。大文件请勿使用Base64编码。
> **传入单个视频要求**
>
> * 视频格式：mp4、mov。
>
> * 分辨率：480p、720p
>
> * 时长：单个视频时长 \[2, 15] s，最多传入 3 个参考视频，所有视频总时长不超过 15s。
>
> * 尺寸：
>
> * 宽高比（宽/高）：\[0.4, 2.5]
>
> * 宽高长度（px）：\[300, 6000]
>
> * 画面像素（宽 × 高）：\[409600, 927408] ，示例：
>
> * 画面尺寸 640×640=409600 满足最小值 ；
>
> * 画面尺寸 834×1112=927408 满足最大值。
>
> * 大小：单个视频不超过 50 MB。
>
> * 帧率 (FPS)：\[24, 60]&#x20;
> **注意**：
>
> 有关提交流程、承诺函签署所需材料的具体信息，请联系您的销售代表了解详情。
3. 方舟将对您提供的素材进行审核，通过审核的素材将被上传至虚拟人像库。
4. 入库后，每个人物组素材将通过以下示例中的形式返回，您可解压后查看：
![Image Token: PKu6b3391oUbVKxxEGjchxBVnbg](images/PKu6b3391oUbVKxxEGjchxBVnbg.png)
示例中：
* Andy 为您提交的人物名称
* group-20260310035119-9mzqn 为该人物组的 ID
* 解压后，可查看每张素材的 Asset ID，如：
![Image Token: VV0ybrxNfouEhZxTjqCcX1epnzb](images/VV0ybrxNfouEhZxTjqCcX1epnzb.png)
* 您可按 `asset: //<asset_id>` 规则拼接 URI，在 API 中使用对应素材生成视频：
具体调用方式请参考 [最佳实践-使用虚拟人像生成视频](https://bytedance.larkoffice.com/wiki/SANpwJ9bgiKgrykLaMTcAB0InWc#share-YurKdrLfAocLErxsTWDcKidPnGd)。
## **注意事项**
1. 首次在 API 中使用虚拟人像素材 Asset URI 前，需先在[方舟体验中心](https://console.volcengine.com/ark/region:ark+cn-beijing/experience/vision?modelId=doubao-seedance-2-0-260128\&tab=GenVideo)提交一次视频生成任务，阅读并同意弹出的 **虚拟人像库使用协议**，操作方式如下：
![Image Token: IFfPbDgceoFXZCxdriIcnwkPnUc](images/IFfPbDgceoFXZCxdriIcnwkPnUc.gif)
* 仅支持使用已入库素材生成视频。

1201
docs/API文档/old-「保密信息」【申请权限填客户名称】Assets API 参考文档（邀测用户版）.md
View File

File diff suppressed because it is too large Load Diff

128
docs/API文档/「保密信息」【申请权限填客户名称】控制台上传自有虚拟人像至素材资产库（邀测用户版）.md
View File

@ -1,128 +0,0 @@
# 「⚠️保密信息」【申请权限填客户名称】控制台上传自有虚拟人像至素材资产库（邀测用户版）
> 请注意，仅开白用户在控制台可&#x89C1;**《上传虚拟人像素材合规承诺函》**&#x7684;签署入口，若仅可&#x89C1;**《素材资产功能使用规则》**，则需申请开白
# 1. 介绍
3月19日起功能上线后，火山方舟会在控制台支持完成开白的B端客户批量上传和管理虚拟人资产，同时支持使用API创建、管理，允许企业上传**自有AIGC虚拟人**（含品牌定制 IP、自制数字人、采购的合规虚拟人等），在线勾选确&#x8BA4;**《上传虚拟人像素材合规承诺函》**，承诺上传的虚拟人像为企业合法所有、未侵犯任何第三方权益、不与任何自然人的肖像形象相同或相似、仅用于合规用途，即可完成确权，将虚拟人像上传入库，在推理中使用，仅可使用已入库的素材资产进行视频生成，未入库素材，即使为已入库同一角色的不同妆造，也无法使用。
# 2. 使用流程
![画板 1](images/whiteboard_1_1774075398978.png)
| | 释义 | 举例 |
| --------------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **素材资产（Asset）** | 一个素材文件（本期**仅支持图片**），是方舟Seedance系列模型可直接用于推理的可信资产 | ![Image Token: QwfCbg7HWodX84x6Jwdl8iWxg6d](images/QwfCbg7HWodX84x6Jwdl8iWxg6d.png) |
| **资产组合（Group）** | 将原子化的资产（Asset）组合起来，可以人物、工作室、项目组等维度将素材进行分组管理 | ![Image Token: KXmAbBvXTophYGxhUzulqOfWgab](images/KXmAbBvXTophYGxhUzulqOfWgab.png)![Image Token: S1KRbfaOzoyqNux7uh4laVqVgZc](images/S1KRbfaOzoyqNux7uh4laVqVgZc.png)![Image Token: YMKAbeeLpowghBxfQxmlzfPngAf](images/YMKAbeeLpowghBxfQxmlzfPngAf.png) |
## 2.1 方舟控制台
1. **首次使用签署使用承诺函**：开白用户可见**火山方舟体验中心-视觉模型-视频生成页面顶部【我的素材资产】**，点击进入素材资产管理界面，首次使用前需签署《上传虚拟人像素材合规承诺函》《素材资产功能使用规则》（仅需授权一次）
![Image Token: ZD36bcZEgo9FXnxm6lvlEX00gqY](images/ZD36bcZEgo9FXnxm6lvlEX00gqY.png)
![体验中心【我的资产】首次进入时，调起协议弹窗 (Token: EHCSbgUCyocNvdxn4Qql6nHfgab)](images/EHCSbgUCyocNvdxn4Qql6nHfgab.png)
* **创建素材资产组合（Group）**：可通过控制台上传单个或多个资产文件批量创建素材资产组合（Group），**当前仅支持上传的每个文件分别创建资产组，暂不支持创建一个资产组，同时注入多个资产**
![【我的素材资产】面板，右上角点击【添加素材资产组】 (Token: HfQvbsOknoJ2MfxVTuVlpKqjg0c)](images/HfQvbsOknoJ2MfxVTuVlpKqjg0c.png)
![Image Token: H7fabAsJSon7mqx0yzklmB20gXb](images/H7fabAsJSon7mqx0yzklmB20gXb.png)
![点击上传/拖拽上传文件 (Token: XNrTbx6f9onxK6xzEHmlpPApgNb)](images/XNrTbx6f9onxK6xzEHmlpPApgNb.png)
* 单次创建上限为**100个资产组合（Group）**，单账号允许的资产组合（Group）数量本期不设限
* 单个素材上传要求：
> - **图片格式**：控制台本期仅支持文件后缀为`.jpg`、`.jpeg`、`.png`（与API有差异）
>
> - **文件大小**：单张图片小于30M
>
> - **宽高比（宽/高）**：(0.4, 2.5)
>
> - **宽高长度（px）**：(300, 6000)
* 资产组合标题/描述/资产名称字段：
| **资产组合名称（Group Name）** | 必填，最大字符12（与API有差异） |
| ----------------------------- | ------------------- |
| **资产组合描述（Group Description）** | 选填，最大字符100（与API有差异） |
| **资产名称（Asset Name）** | 必填，最大字符12（与API有差异） |
![Image Token: OLX5bqDmuoFvScxMSjoldvMngcg](images/OLX5bqDmuoFvScxMSjoldvMngcg.png)
* 控制台上传时暂不支持直接编辑上述字段， 支持通过文件命名自动解析
> 命名规范：`{AssetName1}&&{GroupName1}&&{GroupDescription1(选填)}.jpg`
>
> 若无`&&`连接符，则文件名=`GroupName`=`AssetName`
* `GroupName`**或**`GroupDescription`**被审核拦截时，Group会创建失败**
* 创建完成后支持修改上述字段
![资产组合标题、描述修改 (Token: CpDGb1DkHoT0H7xymYXl0fl5gci)](images/CpDGb1DkHoT0H7xymYXl0fl5gci.png)
![资产名称修改 (Token: FGx3bIe8toKJVixJekllAYmXgsc)](images/FGx3bIe8toKJVixJekllAYmXgsc.png)
* **批量新增素材**：可点击进入某个资产组合（Group），在当前资产组合（Group）下新增资产（Asset）
![点击某一Group进入详情 (Token: J2bibWD6SoH170xehXWler3ugrg)](images/J2bibWD6SoH170xehXWler3ugrg.png)
![Image Token: NfxBbdQa9oXQpWxT1GoljirmgXe](images/NfxBbdQa9oXQpWxT1GoljirmgXe.png)
![点击右上角【添加素材资产】上传Asset (Token: CsgQbFnXOoTJACx2TeZlrQlHgrd)](images/CsgQbFnXOoTJACx2TeZlrQlHgrd.png)
* 单次新增素材上限为**500个资产**，单账号允许的资产（Asset）数量本期**不设限**
* 单个素材上传要求：
> - **图片格式**：控制台本期仅支持文件后缀为`.jpg`、`.jpeg`、`.png`（与API有差异）
>
> - **文件大小**：单张图片小于30M
>
> - **宽高比（宽/高）**：(0.4, 2.5)
>
> - **宽高长度（px）**：(300, 6000)
* 文件名会自动解析填入AssetName
| **资产名称（Asset Name）** | 必填，最大字符12（与API有差异） |
| -------------------- | ------------------ |
* **文件内容或**`AssetName`**被审核拦截时，Asset列表会展示失败状态，有对应报错信息。**
![报错示意 (Token: Bt9Vbf3ajohV07xVrK1lYKe2gOc)](images/Bt9Vbf3ajohV07xVrK1lYKe2gOc.png)
* **库内资产使用**：可在体验中心界面查看已上传的资产组合（Group）和对应组合下的资产（Asset），一键填入体验中心输入框，或一键复制URI通过API传入
![Image Token: Cv3AbbvFHoQuTcxacZclfNfggRc](images/Cv3AbbvFHoQuTcxacZclfNfggRc.png)
![Image Token: DuDib9l3Ao8NsTx8E0Fl9eQEglb](images/DuDib9l3Ao8NsTx8E0Fl9eQEglb.png)
![体验中心使用流程示意 (Token: YdKqbTI8fojMc5xAqAElrdOggff)](images/YdKqbTI8fojMc5xAqAElrdOggff.png)
## 2.2 API入库&#x20;
1. **首次使用签署使用承诺函**：通过火山方舟控制台开通管理，点击右上角的【开通素材资产库权限】，勾选同意协议，进行功能开通使用
![Image Token: Vvu2bZwhGoTs8MxPc9jlB1rigjh](images/Vvu2bZwhGoTs8MxPc9jlB1rigjh.png)
* **通过Asset API创建、管理素材资产：**
> **【对客材料】**
>
> * **素材资产库实践手册：**[ 【申请权限填客户名称】私域虚拟人像素材资产库（邀测用户版）](https://bytedance.larkoffice.com/wiki/RtHgwpJgviwFXLkQ9hLcRooEnVe)
>
> * **Asset API文档：**[ 【申请权限填客户名称】Asset API 参考文档（邀测用户版）](https://bytedance.larkoffice.com/wiki/FtqVwjinYisraGkT5uncWyd0nEb)

314
docs/API文档/「保密信息」【申请权限填客户名称】私域虚拟人像素材资产库使用指南（邀测用户版）.md
View File

@ -1,314 +0,0 @@
# 「⚠️保密信息」【申请权限填客户名称】私域虚拟人像素材资产库使用指南（邀测用户版）
> 本文档仅限预览及邀测用户使用：
>
> * 不承诺正式 API 上线100%一致。
>
> * 仅限邀测用户阅读，请勿截图/分享给其他人员。
>
> * 您需确保上传的虚拟人像符合以下条件：
>
> * 您合法拥有该素材，并享有完整的使用及处分权限。素材不包含未获授权的第三方商标、标识类内容。
>
> * 素材不得与任何自然人肖像或形象雷同，素材不存在抄袭、盗用情形，不会侵害任何第三方的人格权、知识产权等合法权益。
>
> * 素材不包含违反法规、违背公序良俗、危害国家安全的内容。
Seedance 2.0 系列模型具有完备的防范 Deepfake 和侵犯版权风险能力。在生成视频时，会对有风险的参考素材输入进行拦截，最大限度保证生成视频合规和安全性。
为确保创作者能充分利用 Seedance 2.0 强大的视频生成能力高效生成视频内容，同时规避 AI 生成内容的潜在风险，方舟推出了私域可信素材库。完成入库的可信素材将进入您的私域素材库，在视频生成中使用。
私域素材库使用流程如下：
![Image Token: CWyVbkJYSoxmeExAhjCcYDOOnPe](images/CWyVbkJYSoxmeExAhjCcYDOOnPe.png)
## 素材资产库结构说明
> 单个素材文件为一个 Asset（素材资产），每个 Asset 属于一个 Group（素材组合）。
>
> * 可使用素材组自由管理素材。例如，可将同一人物、工作室或项目组的素材放入一个素材组合进行管理。
>
> * **仅可使用已入库素材的 ID (Asset ID)进行视频生成，同一形象未入库素材无法使用。**
>
> * 仅需入库推理需使用的素材，不需使用的素材请勿入库。
以单人物形象为一素材组合为例：
* 素材资产：一个素材文件（图片），是方舟 Seedance 2.0 系列模型可直接用于推理的可信资产。
* 举例：一张人物装造。
* 文件类型：图片
> **单张图片要求**
>
> * 格式：jpeg、png、webp、bmp、tiff、gif、heic/heif
>
> * 宽高比（宽/高）： (0.4, 2.5)&#x20;
>
> * 宽高长度（px）：(300, 6000)
>
> * 大小：单张图片小于 30 MB。
* 资产 ID 示例：`asset-20260310035119-h8tq4`
![Image Token: NfNnbPdRUoLmRdxjoIUcwMvOnAf](images/NfNnbPdRUoLmRdxjoIUcwMvOnAf.png)
* 素材资产组：
* 可自由组合素材，以人物、工作室、项目组等维度将素材进行分组管理。
* Group ID 示例：`group-20260310035119-*****`
* 示例：
![Image Token: E58BbrAcoo1E68xdZPecGDQgn1c](images/E58BbrAcoo1E68xdZPecGDQgn1c.jpeg)
![Image Token: YX14bprrpoxvgXxHoABczW8EnNb](images/YX14bprrpoxvgXxHoABczW8EnNb.jpeg)
![Image Token: YoLEbaqR6oic3mx2Ow6cQ1j2nnf](images/YoLEbaqR6oic3mx2Ow6cQ1j2nnf.jpeg)
## 上传素材至私域虚拟人像库 （API & 控制台）
您可将自有的虚拟形象上传至私域虚拟人像库。
> **警告：**
>
> 您需确保上传的虚拟人像符合以下条件：
>
> * 您合法拥有该素材，并享有完整的使用及处分权限。素材不包含未获授权的第三方商标、标识类内容。
>
> * 素材不得与任何自然人肖像或形象雷同，素材不存在抄袭、盗用情形，不会侵害任何第三方的人格权、知识产权等合法权益。
>
> * 素材不包含违反法规、违背公序良俗、危害国家安全的内容。
方舟将对您上传的素材进行安全审核。审核通过后，即可在体验中心和 API 中使用素材生成视频。
您可使用 OpenAPI 或在体验中心上传虚拟素材。
### 阅读并同意协议
首次入库前，需打开 [控制台](https://console.volcengine.com/ark/region:ark+cn-beijing/overview?briefPage=0\&briefType=introduce\&type=new) > **开通管理** > **开通素材资产库权限，**&#x9605;读和同意相关规则和协议：
![Image Token: ZR4SbE6GColaYKxVTFZcSW1LnFc](images/ZR4SbE6GColaYKxVTFZcSW1LnFc.png)
先创建 Asset Group, 再向 Group 中添加虚拟人像素材。
> 素材格式的具体要求，请参考[素材库结构说明](https://bytedance.larkoffice.com/docx/MpHOdxYbwobmIWxk5rucBLranJb#share-V4mMdM92woylBlxML62c5Aelneh)。
### 使用控制台
1. 打开 [方舟控制台](https://console.volcengine.com/ark/region:ark+cn-beijing/experience/vision?modelId=doubao-seedance-2-0-260128\&tab=GenVideo) > **我的素材资产** > **我的虚拟人像 > 添加虚拟人像**，或左上方 **我的资产**。
![Image Token: VolnbkTKkoQ81kxcksWc3Ts6nDf](images/VolnbkTKkoQ81kxcksWc3Ts6nDf.png)
![Image Token: R5wRbFyexonHeRxbIK1cs3ScnAd](images/R5wRbFyexonHeRxbIK1cs3ScnAd.png)
2. 创建素材组合。
3. 向素材组合中上传素材。
### 使用 API
先使用 `CreateAssetGroup` API 创建素材组合，再使用 `CreateAsset` API 向组合中上传素材。请求示例：
1. **创建素材组合**
> **注意**：
>
> * 调用素材资产（Assets）API 接口需使用 Access Key 鉴权，详情参考 [API访问密钥管理](https://www.volcengine.com/docs/6257/64983?lang=zh)。
>
> * API 参数信息请参考[ Asset API 参考 （WIP） 副本](https://bytedance.larkoffice.com/wiki/FtqVwjinYisraGkT5uncWyd0nEb)。
使&#x7528;**&#x20;POST` `**`CreateAssetGroup` 接口创建素材组合。
在请求中传入：
* **Name**：素材组合的名称。
* **Description**: 素材组合的文字描述。
* **GroupType**: 选填，默认为 AIGC（虚拟人像素材）。
* **ProjectName**：选填，指定资源项目名称，默认为 default。一个项目中的资源仅可被该项目下的推理接入点使用，获取项目名称请参考[文档](https://www.volcengine.com/docs/82379/1359411?lang=zh#03ec4a65)。
> **注意**
>
> 如果请求中不指定 **ProjectName**，默认将创建素材组至 **default** 项目中。
请求示例：
**注意**：需使用 AK/SK 鉴权，详情参考 [API访问密钥管理](https://www.volcengine.com/docs/6257/64983?lang=zh)。
返回示例：
* **上传素材**
使用 **POST&#x20;**`CreateAsset`接口上传素材。
在请求中提供：
* **GroupId**：必填，素材组合 ID
* **URL**: 必填，图片可访问的 URL
* **AssetType**: 必填，仅支持上传图片类型素材，需指定为 **Image**
* **Name**: 选填，素材名称，可用于管理素材，如素材文件名。
* **ProjectName**：选填，指定资源项目名称，默认为 **default**。一个项目中的资源仅可被该项目下的推理接入点使用，获取项目名称请参考[文档](https://www.volcengine.com/docs/82379/1359411?lang=zh#03ec4a65)。
> **注意**
>
> 如果请求中不指定 **ProjectName**，则默认上传素材至 **default** 项目中。您需使用该字段确保将素材上传至对应的项目中。
**注意**：
* 每次请求上传一个素材文件。
* 该请求返回素材 ID，可使用 GetAsset API 查看是否上传成功。
返回示例：
## 检索虚拟人像资产 （API & 控制台）
您可使用以下方式检索虚拟人像资产。
* **控制台**：您可在 [方舟控制台](https://console.volcengine.com/ark/region:ark+cn-beijing/experience/vision?modelId=doubao-seedance-2-0-260128\&tab=GenVideo) >**&#x20;我的** > **我的虚拟人像&#x20;**&#x4E2D;搜索和查看已上传的虚拟人像资产。
* **API**：
* **POST&#x20;**`GetAsset `获取单个素材
* **POST&#x20;**`ListAssets` 查询素材
* **POST&#x20;**`ListAssetGroups` 查询素材组合信息
### 获取单个素材信息
可使用 **POST&#x20;**&#x47;etAsset 获取单个素材信息，指定素材资产 ID。
> **注意**：要获取完整的 API 参数、限流等信息，请查看[ Asset API 参考 （WIP） 副本](https://bytedance.larkoffice.com/docx/DZdUd9J3lo6JTGxDrjscv1g9nVg)。
返回示例：
### 查询素材资产
可使用 **POST&#x20;**&#x4C;istAssets 查询 Assets。
* 支持根据组合 ID (GroupId)、素材状态（Statuses）和素材名称（Name）查询。筛选出符合所有条件的素材。
* 支持使用 Name 进行模糊搜索，同时使用 GroupId 精确搜索，便于检索所需的素材。
支持使用 SortBy，SortOrder 对结果进行排序
> **注意**：获取完整的 API 参考文档，请查看[ Asset API 参考 （WIP） 副本](https://bytedance.larkoffice.com/docx/DZdUd9J3lo6JTGxDrjscv1g9nVg)。
返回示例：
### 查询素材组
使用 **POST&#x20;**&#x4C;istAssetGroups 查询素材组合信息。
支持模糊搜索素材组合名称（Name）或提供多个素材组合（GroupId）。
如有多个素材组，可使用 Name 字段进行模糊搜索。
> **注意**：要获取完整的 API 参考文档，请查看[ Asset API 参考 （WIP） 副本](https://bytedance.larkoffice.com/docx/DZdUd9J3lo6JTGxDrjscv1g9nVg)。
返回示例：
## 示例：上传素材并使用 GetAsset 获取素材信息
以下示例创建素材资产后，查询资产 Status 并根据状态，判断是否继续查询或返回对应结果。
代码执行以下逻辑：
1. createAsset： 上传资源，获取 AssetId
2. waitForAssetActive：开始查询，循环调用 getAssetStatus 查询当前资产状态
3. 根据 Status 判断
* Processing → 继续轮询
* Active → 返回 URL（结束）状态为 **Active** 后，可使用该素材 Asset ID (URI格式) 进行视频生成，如何使用人像素材生成视频，详见[下文](https://bytedance.larkoffice.com/wiki/RtHgwpJgviwFXLkQ9hLcRooEnVe#share-GrbXdVvYjonbMkxQWHEcGf2Inlf)。
* Failed → 返回错误（结束）
4. 返回结果并打印结果
查询结果示意如下：
## 使用人像素材生成视频
在获取素材 Asset ID后，可使用私域人像素材生成视频。效果预览及使用方式请参考下文。
### 效果预览
| 输入：文本 | 输入：虚拟人像、图片 | 输出 |
| ---------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -- |
| **图片1**中美妆博主用中文进行介绍，妆容改为明艳大气，去掉脸部反光，笑容甜美，近景镜头，手持**图片2**的面霜面向镜头展示，清新简约背景，元气甜美风格。博主台词：挖到本命面霜了！质地像云朵一样软糯，一抹就吸收，熬夜急救、补水保湿全搞定，素颜都自带柔光感。 | ![Image Token: HX4abuktdoOdZgxrqbxcNBlznSh](images/HX4abuktdoOdZgxrqbxcNBlznSh.png)![Image Token: MHRTb8420oORTqxTohYcrFkRnhc](images/MHRTb8420oORTqxTohYcrFkRnhc.jpeg) | |
### 视频生成
在 Video Generation API 的 **content.<模态>\_url.url** 字段中使用 素材 URI 生成视频。
> 资产 URI 拼接方式：`Asset://<asset_ID`**`>`**
具体方式请参考[ 【申请权限填客户名称】Seedance 2.0 & 2.0 fast API文档（邀测用户版）](https://bytedance.larkoffice.com/wiki/SANpwJ9bgiKgrykLaMTcAB0InWc#share-ONSwd51ezoXCJqxkAm2cIC61nMX)。
示例代码：
## 常见问题
### 1. 为什么素材上传成功后，无法使用素材生成视频或获取素材信息？
素材库&#x6309;**[项目](https://www.volcengine.com/docs/82379/1359411?lang=zh#03ec4a65)（Project）隔离**。
* 在视频生成时，必须使用**素材所在项目**中的推理接入点进行推理。
* 如果素材上传成功，但使用获取素材接口获取素材失败，可能是因为调用上传素材(CreateAsset)和获取素材接口时传入了不同的 **ProjectName**。
* **ProjectName** 默认值为 `default`，即如果不指定该字段，则默认将资源创建至 `default` 项目中。
* 建议在同一个项目中管理素材。
### 2. 怎样管理用户对素材库的权限？
您可使用[访问控制](https://console.volcengine.com/iam/identitymanage/user) （IAM）精细化管理用户操作素材库的权限。可按以下方式设置：
1. **创建自定义策略**
1. 打开[访问控制](https://console.volcengine.com/iam/policymanage) >**&#x20;新建自定义策略**
2. 输入策略名称。
3. 切换到 **JSON编辑器**，将下方自定义策略粘贴至编辑器中，点击 **提交** 保存。
![Image Token: F0bnb6AanolkCVxjbTdcKMOenkh](images/F0bnb6AanolkCVxjbTdcKMOenkh.png)
* **为用户/用户组赋权**
1. 点击 **用户管理** > **用户**/**用户组**，选择需要赋权的用户或用户组，点击右侧的 **添加权限。**
2. 在 **授权策略** 中选择**步骤 1** 中创建的策略。
3. （可选）在 **限制到项目资源&#x20;**&#x4E2D;选择策略应用的项目。
4. 点击 **提交。**
完成上述操作后，该用户/用户组即可在对应项目中管理素材。
关于 IAM 的更多信息，请参考[访问控制](http://volcengine.com/docs/6257?lang=zh)。

487
docs/API文档/关于种子值.md
View File

@ -1,487 +0,0 @@
`POST https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks` [ ](https://api.volcengine.com/api-explorer/?action=CreateContentsGenerationsTasks&data=%7B%7D&groupName=%E8%A7%86%E9%A2%91%E7%94%9F%E6%88%90API&query=%7B%7D&serviceCode=ark&version=2024-01-01)[运行](https://api.volcengine.com/api-explorer/?action=CreateContentsGenerationsTasks&data=%7B%7D&groupName=%E8%A7%86%E9%A2%91%E7%94%9F%E6%88%90API&query=%7B%7D&serviceCode=ark&version=2024-01-01)
本文介绍创建视频生成任务 API 的输入输出参数，供您使用接口时查阅字段含义。模型会依据传入的图片及文本信息生成视频，待生成完成后，您可以按条件查询任务并获取生成的视频。
:::warning
Seedance 2.0 模型目前仅支持 [控制台体验中心](https://console.volcengine.com/ark/region:ark+cn-beijing/experience/vision?modelId=doubao-seedance-2-0-260128&tab=GenVideo) 在免费额度内体验，暂不支持 API 调用，敬请期待。
:::
**不同模型支持的视频生成能力简介**
* **Seedance 1.5 pro==^new^==** ** ** **==^有声视频^==** **(自定义是否包含音频)**
* 图生视频\-首尾帧，根据您输入的++首帧图片+尾帧图片+文本提示词（可选）+参数（可选）++ 生成目标视频。
* 图生视频\-首帧，根据您输入的++首帧图片+文本提示词（可选）+参数（可选）++ 生成目标视频。
* 文生视频，根据您输入的++文本提示词+参数（可选）++ 生成目标视频。
* **Seedance 1.0 pro**
* 图生视频\-首尾帧，根据您输入的++首帧图片+尾帧图片+文本提示词（可选）+参数（可选）++ 生成目标视频。
* 图生视频\-首帧，根据您输入的++首帧图片+文本提示词（可选）+参数（可选）++ 生成目标视频。
* 文生视频，根据您输入的++文本提示词+参数（可选）++ 生成目标视频。
* **Seedance 1.0 pro fast**
* 图生视频\-首帧，根据您输入的++首帧图片+文本提示词（可选）+参数（可选）++ 生成目标视频。
* 文生视频，根据您输入的++文本提示词+参数（可选）++ 生成目标视频。
* **Seedance 1.0 lite**
* **doubao\-seedance\-1\-0\-lite\-t2v：** 文生视频，根据您输入的++文本提示词+参数（可选）++ 生成目标视频。
* **doubao\-seedance\-1\-0\-lite\-i2v：**
* 图生视频\-参考图，根据您输入的**++参考图片（1\-4张）++ ** +++文本提示词（可选）+ 参数（可选）++ 生成目标视频。
* 图生视频\-首尾帧，根据您输入的++首帧图片+尾帧图片+文本提示词（可选）+参数（可选）++ 生成目标视频。
* 图生视频\-首帧，根据您输入的++首帧图片+文本提示词（可选）+参数（可选）++ 生成目标视频。
Tips：一键展开折叠，快速检索内容
打开页面右上角开关，**ctrl ** + **f** 可检索页面内所有内容。
<span>![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_cae7ddb0e1977b68b353f17897b8574c.png) </span>
```mixin-react
return (<Tabs>
<Tabs.TabPane title="在线调试" key="cKmdyIjR"><RenderMd content={`<APILink link="https://api.volcengine.com/api-explorer/?action=CreateContentsGenerationsTasks&data=%7B%7D&groupName=%E8%A7%86%E9%A2%91%E7%94%9F%E6%88%90API&query=%7B%7D&serviceCode=ark&version=2024-01-01" description="API Explorer 您可以通过 API Explorer 在线发起调用，无需关注签名生成过程，快速获取调用结果。"></APILink>
`}></RenderMd></Tabs.TabPane>
<Tabs.TabPane title="鉴权说明" key="vRJT6oJZ"><RenderMd content={`本接口仅支持 API Key 鉴权，请在 [获取 API Key](https://console.volcengine.com/ark/region:ark+cn-beijing/apiKey) 页面，获取长效 API Key。
`}></RenderMd></Tabs.TabPane>
<Tabs.TabPane title="快速入口" key="MlbBRTbjal"><RenderMd content={` [ ](#)[体验中心](https://console.volcengine.com/ark/region:ark+cn-beijing/experience/vision) <span>![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_2abecd05ca2779567c6d32f0ddc7874d.png =20x) </span>[模型列表](https://www.volcengine.com/docs/82379/1330310?lang=zh#2705b333) <span>![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_a5fdd3028d35cc512a10bd71b982b6eb.png =20x) </span>[模型计费](https://www.volcengine.com/docs/82379/1544106?redirect=1&lang=zh#02affcb8) <span>![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_afbcf38bdec05c05089d5de5c3fd8fc8.png =20x) </span>[API Key](https://console.volcengine.com/ark/region:ark+cn-beijing/apiKey?apikey=%7B%7D)
<span>![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_57d0bca8e0d122ab1191b40101b5df75.png =20x) </span>[调用教程](https://www.volcengine.com/docs/82379/1366799) <span>![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_f45b5cd5863d1eed3bc3c81b9af54407.png =20x) </span>[接口文档](https://www.volcengine.com/docs/82379/1520758) <span>![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_1609c71a747f84df24be1e6421ce58f0.png =20x) </span>[常见问题](https://www.volcengine.com/docs/82379/1359411) <span>![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_bef4bc3de3535ee19d0c5d6c37b0ffdd.png =20x) </span>[开通模型](https://console.volcengine.com/ark/region:ark+cn-beijing/openManagement?LLM=%7B%7D&OpenTokenDrawer=false)
`}></RenderMd></Tabs.TabPane></Tabs>);
```
---
<span id="RxN8G2nH"></span>
## 请求参数
> 跳转 [响应参数](#y2hhTyHB)
<span id="BJ5XLFqM"></span>
### 请求体
---
**model** `string` %%require%%
您需要调用的模型的 ID （Model ID），[开通模型服务](https://console.volcengine.com/ark/region:ark+cn-beijing/openManagement?LLM=%7B%7D&OpenTokenDrawer=false)，并[查询 Model ID](https://www.volcengine.com/docs/82379/1330310) 。
您也可通过 Endpoint ID 来调用模型，获得限流、计费类型（前付费/后付费）、运行状态查询、监控、安全等高级能力，可参考[获取 Endpoint ID](https://www.volcengine.com/docs/82379/1099522)。
---
**content** `object[]` %%require%%
输入给模型，生成视频的信息，支持文本、图片和视频（样片，Draft 视频）格式。支持以下几种组合：
* 文本
* 文本+图片
* 视频：其中视频指已成功生成的样片视频，模型可基于样片生成高质量正式视频。
信息类型
---
**文本信息** `object`
输入给模型生成视频的内容，文本内容部分。
属性
---
content.**type ** `string` %%require%%
输入内容的类型，此处应为 `text`。
---
content.**text ** `string` %%require%%
输入给模型的文本提示词，描述期望生成的视频。
支持中英文。建议中文不超过500字，英文不超过1000词。字数过多信息容易分散，模型可能因此忽略细节，只关注重点，造成视频缺失部分元素。提示词的更多使用技巧请参见 [Seedance 提示词指南](https://www.volcengine.com/docs/82379/1587797)。
---
**图片信息** `object`
输入给模型生成视频的内容，图片信息部分。
属性
---
content.**type ** `string` %%require%%
输入内容的类型，此处应为 `image_url`。支持图片URL或图片 Base64 编码。
---
content.**image_url ** `object` %%require%%
输入给模型的图片对象。
属性
---
content.image_url.**url ** `string` %%require%%
图片信息，可以是图片URL或图片 Base64 编码。
* 图片URL：请确保图片URL可被访问。
* Base64编码：请遵循此格式`data:image/<图片格式>;base64,<Base64编码>`，注意 `<图片格式>` 需小写，如 `data:image/png;base64,{base64_image}`。
:::tip
传入图片需要满足以下条件：
* 图片格式：jpeg、png、webp、bmp、tiff、gif。其中，Seedance 1.5 pro 新增支持 heic 和 heif。
* 宽高比（宽/高）： (0.4, 2.5)
* 宽高长度（px）：(300, 6000)
* 大小：小于 30 MB
:::
---
content.**role ** `string` `条件必填`
图片的位置或用途。
:::warning
首帧图生视频、首尾帧图生视频、参考图生视频为 3 种互斥的场景，不支持混用。
:::
图生视频\-首帧
* **支持模型：** 所有图生视频模型
* **字段role取值：** 需要传入1个image_url对象，且字段role可不填，或字段role为：first_frame
图生视频\-首尾帧
* **支持模型：** Seedance 1.5 pro、Seedance 1.0 pro、Seedance 1.0 lite i2v
* **字段role取值：** 需要传入2个image_url对象，且字段role必填。
* 首帧图片对应的字段role为：first_frame
* 尾帧图片对应的字段role为：last_frame
:::tip
传入的首尾帧图片可相同。首尾帧图片的宽高比不一致时，以首帧图片为主，尾帧图片会自动裁剪适配。
:::
图生视频\-参考图
* **支持模型：** Seedance 1.0 lite i2v
* **字段role取值：** 需要传入1～4个image_url对象，且字段role必填。
* 每张参考图片对应的字段role均为：reference_image
:::tip
参考图生视频功能的文本提示词，可以用自然语言指定多张图片的组合。但若想有更好的指令遵循效果，**推荐使用“[图1]xxx，[图2]xxx”的方式来指定图片**。
示例1：戴着眼镜穿着蓝色T恤的男生和柯基小狗，坐在草坪上，3D卡通风格
示例2：[图1]戴着眼镜穿着蓝色T恤的男生和[图2]的柯基小狗，坐在[图3]的草坪上，3D卡通风格
:::
---
**样片信息==^new^==** ** ** `object`
基于样片任务 ID，生成正式视频。仅 Seedance 1.5 pro 支持该功能。[阅读](https://www.volcengine.com/docs/82379/1366799?lang=zh#5acd28c8)[文档](https://www.volcengine.com/docs/82379/1366799?lang=zh#5acd28c8) 获取 draft 功能的使用教程和注意事项。
属性
---
content.**type ** `string` %%require%%
输入内容的类型，此处应为 `draft_task`。
---
content.**draft_task** ** ** `object` %%require%%
输入给模型的样片任务。
属性
---
content.draft_task.**id ** `string` %%require%%
样片任务 ID。平台将自动复用 Draft 视频使用的用户输入（**model、** content.**text、** content.**image_url、generate_audio、seed、ratio、duration、camera_fixed ** ），生成正式视频。其余参数支持指定，不指定将使用本模型的默认值。
使用分为两步：Step1: 调用本接口生成 Draft 视频。Step2: 如果确认 Draft 视频符合预期，可基于 Step1 返回的 Draft 视频任务 ID，调用本接口生成最终视频。[阅读文档](https://www.volcengine.com/docs/82379/1366799?lang=zh#5acd28c8) 获取详细教程。
---
**callback_url** `string`
填写本次生成任务结果的回调通知地址。当视频生成任务有状态变化时，方舟将向此地址推送 POST 请求。
回调请求内容结构与[查询任务API](https://www.volcengine.com/docs/82379/1521309)的返回体一致。
回调返回的 status 包括以下状态：
* queued：排队中。
* running：任务运行中。
* succeeded： 任务成功。（如发送失败，即5秒内没有接收到成功发送的信息，回调三次）
* failed：任务失败。（如发送失败，即5秒内没有接收到成功发送的信息，回调三次）
* expired：任务超时，即任务处于**运行中或排队中**状态超过过期时间。可通过 **execution_expires_after ** 字段设置过期时间。
---
**return_last_frame** `boolean` `默认值 false`
* true：返回生成视频的尾帧图像。设置为 `true` 后，可通过 [查询视频生成任务接口](https://www.volcengine.com/docs/82379/1521309) 获取视频的尾帧图像。尾帧图像的格式为 png，宽高像素值与生成的视频保持一致，无水印。
使用该参数可实现生成多个连续视频：以上一个生成视频的尾帧作为下一个视频任务的首帧，快速生成多个连续视频，调用示例详见 [教程](https://www.volcengine.com/docs/82379/1366799?lang=zh#141cf7fa)。
* false：不返回生成视频的尾帧图像。
---
**service_tier** `string` `默认值 default`
> 不支持修改已提交任务的服务等级
指定处理本次请求的服务等级类型，枚举值：
* default：在线推理模式，RPM 和并发数配额较低（详见 [模型列表](https://www.volcengine.com/docs/82379/1330310?lang=zh#2705b333)），适合对推理时效性要求较高的场景。
* flex：离线推理模式，TPD 配额更高（详见 [模型列表](https://www.volcengine.com/docs/82379/1330310?lang=zh#2705b333)），价格为在线推理的 50%， 适合对推理时延要求不高的场景。
---
**execution_expires_after** ** ** `integer` `默认值 172800`
任务超时阈值。指定任务提交后的过期时间（单位：秒），从 **created at** 时间戳开始计算。默认值 172800 秒，即 48 小时。取值范围：[3600，259200]。
不论使用哪种 **service_tier**，都建议根据业务场景设置合适的超时时间。超过该时间后任务会被自动终止，并标记为`expired`状态。
---
**generate_audio==^new^==** ** ** `boolean` `默认值 true`
> 仅 Seedance 1.5 pro 支持
控制生成的视频是否包含与画面同步的声音。
* true：模型输出的视频包含同步音频。Seedance 1.5 pro 能够基于文本提示词与视觉内容，自动生成与之匹配的人声、音效及背景音乐。建议将对话部分置于双引号内，以优化音频生成效果。例如：男人叫住女人说：“你记住，以后不可以用手指指月亮。”
* false：模型输出的视频为无声视频。
---
**draft==^new^==** ** ** `boolean` `默认值 false`
> 仅 Seedance 1.5 pro 支持
控制是否开启样片模式。[阅读文档](https://www.volcengine.com/docs/82379/1366799?lang=zh#5acd28c8) 获取使用教程和注意事项。
* true：开启样片模式，生成一段预览视频，快速验证场景结构、镜头调度、主体动作与 prompt 意图是否符合预期。消耗 token 数较正常视频更少，使用成本更低。
* false：关闭样片模式，正常生成一段视频。
:::tip
开启样片模式后，将使用 480p 分辨率生成 Draft 视频（使用其他分辨率会报错），不支持返回尾帧功能，不支持离线推理功能。
:::
---
:::warning 部分参数升级说明
* **对于 resolution、ratio、duration、frames、seed、camera_fixed、watermark 参数，平台升级了参数传入方式，示例如下。Seedance 1.0\-1.5 系列模型依然兼容支持旧方式。**
* 不同模型，可能对应支持不同的参数与取值，详见 [输出视频格式](https://www.volcengine.com/docs/82379/1366799?lang=zh#9fe4cce0)。当输入的参数或取值不符合所选的模型时，该参数将被忽略或触发报错：
* 新方式：在 request body 中直接传入参数。此方式为**强校验，** 若参数填写错误，模型会返回错误提示。
* 旧方式：在文本提示词后追加 \-\-[parameters]。此方式为**弱校验，** 若参数填写错误，模型将自动使用默认值且不会报错。
:::
**新方式（推荐）：在 request body 中直接传入参数**
```JSON
...
// Specify the aspect ratio of the generated video as 16:9, duration as 5 seconds, resolution as 720p, seed as 11, and include a watermark. The camera is not fixed.
"model": "doubao-seedance-1-5-pro-251215",
"content": [
{
"type": "text",
"text": "小猫对着镜头打哈欠"
}
],
// All parameters must be written in full; abbreviations are not supported
"resolution": "720p",
"ratio":"16:9",
"duration": 5,
// "frames": 29, Either duration or frames is required
"seed": 11,
"camera_fixed": false,
"watermark": true
...
```
**旧方式：在文本提示词后追加 \-\-[parameters]**
```JSON
...
// Specify the aspect ratio of the generated video as 16:9, duration as 5 seconds, resolution as 720p, seed as 11, and include a watermark. The camera is not fixed.
"model": "doubao-seedance-1-5-pro-251215",
"content": [
{
"type": "text",
"text": "小猫对着镜头打哈欠 --rs 720p --rt 16:9 --dur 5 --seed 11 --cf false --wm true"
// "text": "小猫对着镜头打哈欠 --resolution 720p --ratio 16:9 --duration 5 --seed 11 --camerafixed false --watermark true"
}
]
...
```
---
**resolution ** `string`
> Seedance 1.5 pro、Seedance 1.0 lite 默认值：`720p`
> Seedance 1.0 pro & pro\-fast 默认值：`1080p`
视频分辨率，枚举值：
* 480p
* 720p
* 1080p：参考图场景不支持
---
**ratio ** `string`
> 文生视频：默认值 `16:9`（ Seedance 1.5 Pro 默认值为 `adaptive`）
> 图生视频：默认值 `adaptive`（参考图生视频场景默认值为 `16:9`）
生成视频的宽高比例。不同宽高比对应的宽高像素值见下方表格。
* 16:9
* 4:3
* 1:1
* 3:4
* 9:16
* 21:9
* adaptive：根据输入自动选择最合适的宽高比（详见下文说明）
:::warning **adaptive ** 适配规则
当配置 **ratio** 为 `adaptive` 时，模型会根据生成场景自动适配宽高比；实际生成的视频宽高比可通过 [查询视频生成任务 API](https://www.volcengine.com/docs/82379/1521309?lang=zh) 返回的 **ratio** 字段获取。
* 文生视频场景：根据输入的提示词，自动选择最合适的宽高比（仅 Seedance 1.5 Pro 支持）。
* 图生视频场景：
* 参考图生视频：不支持配置 **ratio** 为 `adaptive`。
* 首帧 / 首尾帧生视频：根据上传的首帧图片比例，自动选择最合适的宽高比。
:::
**不同宽高比对应的宽高像素值**
Note：图生视频，选择的宽高比与您上传的图片宽高比不一致时，方舟会对您的图片进行裁剪，裁剪时会居中裁剪，详细规则见 [图片裁剪规则](https://www.volcengine.com/docs/82379/1366799?lang=zh#f76aafc8)。
|分辨率 |宽高比|宽高像素值|宽高像素值|\
| | |Seedance 1.0 系列 |Seedance 1.5 pro |
|---|---|---|---|
|480p |16:9 |864×480 |864×496 |
|^^|4:3 |736×544 |752×560 |
|^^|1:1 |640×640 |640×640 |
|^^|3:4 |544×736 |560×752 |
|^^|9:16 |480×864 |496×864 |
|^^|21:9 |960×416 |992×432 |
|720p |16:9 |1248×704 |1280×720 |
|^^|4:3 |1120×832 |1112×834 |
|^^|1:1 |960×960 |960×960 |
|^^|3:4 |832×1120 |834×1112 |
|^^|9:16 |704×1248 |720×1280 |
|^^|21:9 |1504×640 |1470×630 |
|1080p |16:9 |1920×1088 |1920×1080 |\
|> 1.0 lite 参考图场景不支持 | | | |
|^^|4:3 |1664×1248 |1664×1248 |
|^^|1:1 |1440×1440 |1440×1440 |
|^^|3:4 |1248×1664 |1248×1664 |
|^^|9:16 |1088×1920 |1080×1920 |
|^^|21:9 |2176×928 |2206×946 |
---
**duration** `integer` `默认值 5`
> duration 和 frames 二选一即可，frames 的优先级高于 duration。如果您希望生成整数秒的视频，建议指定 duration。
生成视频时长，单位：秒。支持 2~12 秒。
:::warning
Seedance 1.5 pro 支持两种配置方法
* 指定具体时长：支持 [4,12] 范围内的任一整数。
* 不指定具体生成时长：设置为 `-1`，表示由模型在 [4,12] 范围内自主选择合适的视频长度（整数秒）。实际生成视频的时长可通过 [查询视频生成任务 API](https://www.volcengine.com/docs/82379/1521309?lang=zh) 返回的 **duration** 字段获取。注意视频时长与计费相关，请谨慎设置。
:::
---
**frames** `integer`
> Seedance 1.5 pro 暂不支持
> duration 和 frames 二选一即可，frames 的优先级高于 duration。如果您希望生成小数秒的视频，建议指定 frames。
生成视频的帧数。通过指定帧数，可以灵活控制生成视频的长度，生成小数秒的视频。
由于 frames 的取值限制，仅能支持有限小数秒，您需要根据公式推算最接近的帧数。
* 计算公式：帧数 = 时长 × 帧率（24）。
* 取值范围：支持 [29, 289] 区间内所有满足 `25 + 4n` 格式的整数值，其中 n 为正整数。
例如：假设需要生成 2.4 秒的视频，帧数=2.4×24=57.6。由于 frames 不支持 57.6，此时您只能选择一个最接近的值。根据 25+4n 计算出最接近的帧数为 57，实际生成的视频为 57/24=2.375 秒。
---
**seed** `integer` `默认值 -1`
种子整数，用于控制生成内容的随机性。
取值范围：[\-1, 2^32\-1]之间的整数。
:::warning
* 相同的请求下，模型收到不同的seed值，如：不指定seed值或令seed取值为\-1（会使用随机数替代）、或手动变更seed值，将生成不同的结果。
* 相同的请求下，模型收到相同的seed值，会生成类似的结果，但不保证完全一致。
:::
---
**camera_fixed** `boolean` `默认值 false`
> 参考图场景不支持
是否固定摄像头。枚举值：
* true：固定摄像头。平台会在用户提示词中追加固定摄像头，实际效果不保证。
* false：不固定摄像头。
---
**watermark** `boolean` `默认值 false`
生成视频是否包含水印。枚举值：
* false：不含水印。
* true：含有水印。
---
<span id="y2hhTyHB"></span>
## 响应参数
> 跳转 [请求参数](#RxN8G2nH)
**id ** `string`
视频生成任务 ID 。仅保存 7 天（从 **created at** 时间戳开始计算），超时后将自动清除。
* 设置`"draft": true`，为 Draft 视频任务 ID。
* 设置 `"draft": false`，为正常视频任务 ID。
创建视频生成任务为异步接口，获取 ID 后，需要通过 [查询视频生成任务 API](https://www.volcengine.com/docs/82379/1521309) 来查询视频生成任务的状态。任务成功后，会输出生成视频的`video_url`。

1074
docs/API文档/推理节点.md
View File

File diff suppressed because it is too large Load Diff

134
docs/celery-polling-fix-20260404.md
View File

@ -1,134 +0,0 @@
# Celery 轮询机制修复报告
> 日期：2026-04-04
> 版本：v0.16.0
> 影响范围：backend/apps/generation/tasks.py, backend/config/settings.py
---
## 一、问题现象
2026/4/1 下午，大量用户反馈视频生成任务长时间卡在"生成中"，前端显示耗时 60~65 分钟。
火山引擎侧确认视频实际生成仅需约 10 分钟，结果已就绪但未被平台及时同步。
**截图数据**（4/1 下午完成的任务）：
| 提交时间 | 显示耗时 |
|---------|---------|
| 2026/4/1 16:57:28 | 63 分 33 秒 |
| 2026/4/1 16:58:41 | 62 分 37 秒 |
| 2026/4/1 16:59:16 | 62 分 7 秒 |
| 2026/4/1 17:00:36 | 64 分 24 秒 |
| 2026/4/1 17:04:53 | 64 分 2 秒 |
## 二、根因分析
### 2.1 状态同步链路
```
用户提交任务
→ 后端调 create_task（火山 API）
→ 获得 ark_task_id
→ 派发 Celery 任务 poll_video_task
→ Celery worker 每 5 秒查一次火山 API
→ 火山返回完成 → 写 DB + 上传 TOS + 结算
→ 前端轮询 DB → 展示结果
```
前端只读 DB 状态，**不直接调火山 API**。整个链路完全依赖 Celery worker 轮询。
### 2.2 旧实现缺陷
`poll_video_task` 使用 `while True` + `time.sleep(5)` 长驻循环：
```python
# 旧代码
while True:
time.sleep(POLL_INTERVAL) # 5 秒
ark_resp = query_task(...) # 查一次
if terminal:
break
```
**三个致命问题：**
| 问题 | 影响 |
|------|------|
| 每个任务占死一个 worker 进程 | `concurrency=4` 最多同时轮询 4 个任务，第 5 个排队 |
| worker 重启后循环直接丢失 | 内存中的 `while True` 不可持久化，OOM/重启 = 任务丢失 |
| `time.sleep` 浪费进程资源 | worker 99% 时间在 sleep，实际有用工作不到 1% |
### 2.3 OOM 重启链
```
4 个任务同时轮询
→ 某些任务完成，触发 TOS 上传（下载视频 + 上传对象存储）
→ 内存飙升超过 512Mi 限制
→ K8s OOM Kill → worker 重启（共重启 15 次）
→ 4 个进程中的 while True 循环全部丢失
→ 等 recover_stuck_tasks（每 10 分钟）重新派发
→ 重新派发后 worker 又被占满 → 又 OOM → 循环
→ 实际恢复耗时 ≈ 50~60 分钟
```
## 三、修复方案
### 3.1 核心改动：self.retry 替代 while True
```python
# 新代码
@shared_task(bind=True, max_retries=None, ignore_result=True)
def poll_video_task(self, record_id):
record = GenerationRecord.objects.get(pk=record_id)
ark_resp = query_task(record.ark_task_id)
new_status = map_status(ark_resp.get('status', ''))
if new_status in ('queued', 'processing'):
record.save(update_fields=['status', 'updated_at'])
raise self.retry(countdown=5) # 5 秒后重新入队
# 到达终态 → 处理结果
...
```
**原理对比：**
| | 旧方式（while True） | 新方式（self.retry） |
|---|---|---|
| 任务生命周期 | 在 worker 进程内存中 | 在 Redis 队列中 |
| worker 占用 | 持续占用直到完成（分钟级） | 每次查询仅占用毫秒级 |
| worker 重启 | 任务丢失 | Redis 中的任务自动恢复 |
| 并发能力 | 最多 4 个（= concurrency） | 数百个（受 API RPM 限制） |
### 3.2 recover_stuck_tasks 间隔缩短
| | 旧值 | 新值 |
|---|---|---|
| Beat 调度间隔 | 600 秒（10 分钟） | 180 秒（3 分钟） |
| stuck 判定门槛 | 10 分钟 | 3 分钟 |
| 最坏恢复时间 | ~20 分钟 | ~6 分钟 |
### 3.3 变更文件
| 文件 | 改动 |
|------|------|
| `backend/apps/generation/tasks.py` | `poll_video_task`: while True → self.retry；`recover_stuck_tasks`: 门槛 10 → 3 分钟 |
| `backend/config/settings.py` | Beat schedule: 600 → 180 秒 |
## 四、效果预估
| 指标 | 修复前 | 修复后 |
|------|--------|--------|
| 同时轮询任务数上限 | 4 | 数百 |
| worker 重启后任务恢复 | 丢失，等 10 分钟兜底 | 自动恢复，无需兜底 |
| 最坏同步延迟 | 60+ 分钟 | ~15 秒（= 查询间隔 + 网络延迟） |
| 内存占用 | 持续占满（sleep 期间不释放） | 脉冲式占用（查完释放） |
| OOM 风险 | 高（4 进程常驻 + TOS 上传峰值） | 低（进程闲置时内存极小） |
## 五、部署注意
1. **无需数据库迁移** — 仅修改 Python 代码
2. **部署后旧的 while True 任务会自然消亡** — 不需要手动干预
3. **Redis 中可能有旧格式的任务** — 兼容无问题，新旧 `poll_video_task` 签名一致（`record_id` 参数不变）
4. **建议同步部署**：先部署代码，再重启 Celery worker（`kubectl rollout restart deployment celery-worker`）

118
docs/deployment-guide.md
View File

@ -1,118 +0,0 @@
# 部署操作手册
> 本文档说明如何将代码推送到测试环境和生产环境。
> 日常开发在 `dev` 分支，生产发布通过合并到 `master` 分支触发。
---
## 环境说明
| 环境 | 触发分支 | 镜像仓库 | K3s 集群 | 域名 |
|------|---------|---------|---------|------|
| 测试（development） | `dev` | `cr.volces.com/zyc/...` | `192.168.0.129:6443` | `airflow-studio.test.airlabs.art` |
| 生产（production） | `master` | `gitea-prod-cn-shanghai.cr.volces.com/prod/...` | `192.168.0.130:6443` | `airflow-studio.airlabs.art` |
---
## 推送到测试环境
只需要把代码推到 `dev` 分支，CI/CD 自动触发。
```bash
# 确认当前在 dev 分支
git checkout dev
# 提交代码
git add .
git commit -m "feat: 你的改动描述"
# 推送触发构建
git push origin dev
```
构建完成后在 Gitea Actions 查看进度：
- Build and Push Backend ✅
- Build and Push Web ✅
- Setup Kubectl ✅
- Deploy to K3s ✅
---
## 推送到生产环境
> ⚠️ **注意**：操作完成后必须切回 `dev` 分支，不要在 `master` 上继续开发。
### 完整流程
```bash
# 1. 确保 dev 分支代码是最新的
git checkout dev
git pull origin dev
# 2. 切换到 master 分支
git checkout master
# 3. 合并 dev 的代码
git merge dev
# 4. 推送到远程，触发生产构建
git push origin master
# 5. ⚠️ 立刻切回 dev，不要停留在 master
git checkout dev
```
### 如果有合并冲突
```bash
# 解决冲突后
git add .
git commit -m "merge: dev into master"
git push origin master
git checkout dev
```
---
## 构建失败排查
### Build and Push 失败（docker pull 超时）
Docker 镜像拉取超时，CI 会自动重试 3 次。如仍失败，检查构建机网络。
### Setup Kubectl 失败（command not found）
kubectl 未安装或下载失败，CI 会自动从 daocloud 镜像安装。
### Deploy to K3s 失败（i/o timeout）
K3s API Server 连接超时，CI 会自动重试 3 次（每次间隔 10 秒）。
- 若持续失败，检查 K3s 节点状态：`kubectl get nodes`
- 确认 kubeconfig secret（`VOLCANO_TEST_KUBE_CONFIG` / `VOLCANO_PROD_KUBE_CONFIG`）有值
---
## 快速检查部署状态
```bash
# 测试环境
ssh root@14.103.63.199
kubectl get pods -n default
# 生产环境
ssh root@118.196.0.100
kubectl get pods -n default
```
---
## Celery Worker 监控
Celery worker 负责轮询火山 API 的视频生成状态。
```bash
# 查看 worker 日志（测试环境）
kubectl logs -f deployment/celery-worker -n default
# 查看队列积压（测试环境 Redis）
redis-cli -h redis-shzlsczo52dft8mia.redis.ivolces.com -p 6379 -a Zyc188208 llen celery
```
`recover_stuck_tasks` 定时任务每 3 分钟自动扫描卡住的任务并重新入队，无需手动干预。

21
k8s/backend-deployment.yaml
View File

@ -15,7 +15,7 @@ spec:
app: video-backend
spec:
imagePullSecrets:
- name: cr-pull-secret
- name: swr-secret
containers:
- name: video-backend
image: ${CI_REGISTRY_IMAGE}/video-backend:latest
@ -34,20 +34,29 @@ spec:
secretKeyRef:
name: video-backend-secrets
key: DJANGO_SECRET_KEY
# Database (Volcano Engine RDS - 默认测试环境，生产环境通过 CI 替换)
# Database (Aliyun RDS)
- name: DB_HOST
value: "mysql8351f937d637.rds.ivolces.com"
valueFrom:
secretKeyRef:
name: video-backend-secrets
key: DB_HOST
- name: DB_NAME
value: "video_auto"
- name: DB_USER
value: "zyc"
valueFrom:
secretKeyRef:
name: video-backend-secrets
key: DB_USER
- name: DB_PASSWORD
value: "Zyc188208"
valueFrom:
secretKeyRef:
name: video-backend-secrets
key: DB_PASSWORD
- name: DB_PORT
value: "3306"
# Redis (Celery broker)
- name: REDIS_URL
value: "redis://zyc:Zyc188208@redis-shzlsczo52dft8mia.redis.ivolces.com:6379/0"
value: "redis://:vAhRnAA6VMco@redis-cngzyc2r77ka16g7a.redis.ivolces.com:6379/0"
# CORS
- name: CORS_ALLOWED_ORIGINS
value: "https://airflow-studio.airlabs.art"

41
k8s/celery-deployment.yaml
View File

@ -15,13 +15,13 @@ spec:
app: celery-worker
spec:
imagePullSecrets:
- name: cr-pull-secret
- name: swr-secret
containers:
- name: celery-worker
image: ${CI_REGISTRY_IMAGE}/video-backend:latest
imagePullPolicy: Always
command: ["celery", "-A", "config", "worker", "--loglevel=info", "--pool=gevent", "--concurrency=200"]
env: &shared-env
command: ["celery", "-A", "config", "worker", "--loglevel=info", "--concurrency=50", "--pool=threads", "-B"]
env:
- name: USE_MYSQL
value: "true"
- name: DJANGO_DEBUG
@ -35,16 +35,25 @@ spec:
key: DJANGO_SECRET_KEY
# Redis
- name: REDIS_URL
value: "redis://zyc:Zyc188208@redis-shzlsczo52dft8mia.redis.ivolces.com:6379/0"
# Database (Volcano Engine RDS)
value: "redis://:vAhRnAA6VMco@redis-cngzyc2r77ka16g7a.redis.ivolces.com:6379/0"
# Database (Aliyun RDS)
- name: DB_HOST
value: "mysql8351f937d637.rds.ivolces.com"
valueFrom:
secretKeyRef:
name: video-backend-secrets
key: DB_HOST
- name: DB_NAME
value: "video_auto"
- name: DB_USER
value: "zyc"
valueFrom:
secretKeyRef:
name: video-backend-secrets
key: DB_USER
- name: DB_PASSWORD
value: "Zyc188208"
valueFrom:
secretKeyRef:
name: video-backend-secrets
key: DB_PASSWORD
- name: DB_PORT
value: "3306"
# TOS (from Secret)
@ -80,20 +89,8 @@ spec:
value: "true"
resources:
requests:
memory: "256Mi"
cpu: "200m"
memory: "128Mi"
cpu: "100m"
limits:
memory: "1Gi"
cpu: "1000m"
- name: celery-beat
image: ${CI_REGISTRY_IMAGE}/video-backend:latest
imagePullPolicy: Always
command: ["celery", "-A", "config", "beat", "--loglevel=info"]
env: *shared-env
resources:
requests:
memory: "64Mi"
cpu: "50m"
limits:
memory: "128Mi"
cpu: "100m"

2
k8s/cert-manager-issuer.yaml
View File

@ -12,4 +12,4 @@ spec:
solvers:
- http01:
ingress:
class: traefik
class: alb

2
k8s/web-deployment.yaml
View File

@ -15,7 +15,7 @@ spec:
app: video-web
spec:
imagePullSecrets:
- name: cr-pull-secret
- name: swr-secret
containers:
- name: video-web
image: ${CI_REGISTRY_IMAGE}/video-web:latest

7888
video_auto copy.sql
View File

File diff suppressed because one or more lines are too long

7888
video_auto.sql
View File

File diff suppressed because one or more lines are too long

10642
video_auto4.4prod.sql
View File

File diff suppressed because one or more lines are too long

4
web/Dockerfile
View File

@ -1,5 +1,5 @@
# ---- Build Stage ----
FROM docker.m.daocloud.io/node:18-alpine AS builder
FROM node:18-alpine AS builder
RUN npm config set registry https://registry.npmmirror.com
@ -10,7 +10,7 @@ COPY . .
RUN npm run build
# ---- Runtime Stage ----
FROM docker.m.daocloud.io/nginx:alpine
FROM nginx:alpine
RUN sed -i 's#dl-cdn.alpinelinux.org#mirrors.aliyun.com#g' /etc/apk/repositories

16
web/nginx.conf
View File

@ -24,15 +24,19 @@ server {
client_max_body_size 50m;
}
# Cache static assets (JS/CSS/images built by Vite into dist/assets/)
# Use regex to only match actual files with extensions, not bare /assets path
location ~* ^/assets/.+\.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot|mp4|webm)$ {
expires 30d;
add_header Cache-Control "public, immutable";
# SPA client-side routes — must return index.html, not match Vite's dist/assets/ dir
location ~ ^/(assets|login|profile|admin|team)(/|$) {
try_files /index.html =404;
}
# SPA fallback — real files served directly, all other paths return index.html
# SPA fallback
location / {
try_files $uri $uri/ /index.html;
}
# Cache static assets
location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
expires 30d;
add_header Cache-Control "public, immutable";
}
}

12
web/playwright-test.config.ts
View File

@ -1,12 +0,0 @@
import { defineConfig } from '@playwright/test';
export default defineConfig({
testDir: './test/e2e',
timeout: 30000,
retries: 0,
use: {
baseURL: 'https://airflow-studio.test.airlabs.art',
headless: true,
screenshot: 'only-on-failure',
},
});

2
web/src/App.tsx
View File

@ -50,7 +50,7 @@ export default function App() {
}
/>
<Route
path="/user-assets"
path="/assets"
element={
<ProtectedRoute requireTeamMember>
<AssetsPage />

49
web/src/components/AssetLibraryModal.module.css
View File

@ -201,61 +201,12 @@
}
.assetCard {
position: relative;
background: var(--color-bg-card);
border: 1px solid var(--color-border-card);
border-radius: 12px;
overflow: hidden;
}
.assetDeleteBtn {
position: absolute;
top: 6px;
right: 6px;
width: 22px;
height: 22px;
border: none;
border-radius: 50%;
background: rgba(0, 0, 0, 0.6);
color: #fff;
font-size: 14px;
line-height: 1;
cursor: pointer;
display: flex;
align-items: center;
justify-content: center;
opacity: 0;
transition: opacity 0.15s;
z-index: 2;
}
.assetCard:hover .assetDeleteBtn {
opacity: 1;
}
.addAssetCard {
display: flex;
flex-direction: column;
align-items: center;
justify-content: center;
gap: 6px;
border: 1.5px dashed #3a3a48;
border-radius: 12px;
cursor: pointer;
color: var(--color-text-disabled);
font-size: 12px;
transition: all 0.2s;
background: transparent;
/* match assetThumb height + assetInfo height */
min-height: 180px;
}
.addAssetCard:hover {
border-color: var(--color-primary);
color: var(--color-primary);
background: rgba(108, 99, 255, 0.04);
}
.assetThumb {
width: 100%;
height: 140px;

348
web/src/components/AssetLibraryModal.tsx
View File

@ -1,4 +1,4 @@
import { useState, useEffect, useCallback } from 'react';
import { useState, useEffect, useRef, useCallback } from 'react';
import { useAssetLibraryStore } from '../store/assetLibrary';
import { assetsApi, tosThumb } from '../lib/api';
import { showToast } from './Toast';
@ -6,90 +6,6 @@ import { ImageLightbox } from './ImageLightbox';
import type { AssetGroup, AssetItem } from '../types';
import styles from './AssetLibraryModal.module.css';
/** Validate asset file before upload. Returns error message or null if valid. */
async function validateAssetFile(file: File): Promise<string | null> {
const ct = file.type || '';
if (ct.startsWith('image/')) {
// Format: accept all image/* since backend checks ext
if (file.size > 30 * 1024 * 1024) return '图片文件不能超过 30MB';
// Dimension check
try {
const dims = await new Promise<{ w: number; h: number }>((resolve, reject) => {
const img = new Image();
const url = URL.createObjectURL(file);
img.onload = () => { resolve({ w: img.naturalWidth, h: img.naturalHeight }); URL.revokeObjectURL(url); };
img.onerror = () => { reject(); URL.revokeObjectURL(url); };
img.src = url;
});
if (dims.w <= 300 || dims.h <= 300) return `图片尺寸过小（${dims.w}×${dims.h}），宽高需在 300~6000 像素之间`;
if (dims.w >= 6000 || dims.h >= 6000) return `图片尺寸过大（${dims.w}×${dims.h}），宽高需在 300~6000 像素之间`;
const ratio = dims.w / dims.h;
if (ratio <= 0.4 || ratio >= 2.5) return `图片比例不支持（${dims.w}×${dims.h}），宽高比需在 0.4~2.5 之间`;
} catch {
// Can't read dimensions (e.g. HEIC), skip — backend will validate
}
return null;
}
if (ct.startsWith('video/')) {
if (ct !== 'video/mp4' && ct !== 'video/quicktime') return '仅支持 MP4 和 MOV 格式的视频';
if (file.size > 50 * 1024 * 1024) return '视频文件不能超过 50MB';
// Duration + dimension check
try {
const info = await new Promise<{ dur: number; w: number; h: number }>((resolve, reject) => {
const vid = document.createElement('video');
const url = URL.createObjectURL(file);
const timeout = setTimeout(() => { reject(); URL.revokeObjectURL(url); }, 10000);
vid.addEventListener('loadedmetadata', () => {
clearTimeout(timeout);
resolve({ dur: vid.duration, w: vid.videoWidth, h: vid.videoHeight });
URL.revokeObjectURL(url);
});
vid.addEventListener('error', () => { clearTimeout(timeout); reject(); URL.revokeObjectURL(url); });
vid.src = url;
});
if (info.dur < 2 || info.dur > 15.4) return `视频时长需在 2~15 秒之间（当前 ${info.dur.toFixed(1)} 秒）`;
if (info.w < 300 || info.h < 300) return `视频尺寸过小（${info.w}×${info.h}），宽高需在 300~6000 像素之间`;
if (info.w > 6000 || info.h > 6000) return `视频尺寸过大（${info.w}×${info.h}），宽高需在 300~6000 像素之间`;
const ratio = info.w / info.h;
if (ratio < 0.4 || ratio > 2.5) return `视频比例不支持（${info.w}×${info.h}），宽高比需在 0.4~2.5 之间`;
const pixels = info.w * info.h;
if (pixels < 409600) return `视频像素过低（${info.w}×${info.h}=${pixels.toLocaleString()}），需在 409,600~927,408 之间`;
if (pixels > 927408) return `视频像素过高（${info.w}×${info.h}=${pixels.toLocaleString()}），需在 409,600~927,408 之间`;
} catch {
// Can't read metadata, skip — backend will validate
}
return null;
}
if (ct.startsWith('audio/')) {
if (ct !== 'audio/mpeg' && ct !== 'audio/wav') return '仅支持 MP3 和 WAV 格式的音频';
if (file.size > 15 * 1024 * 1024) return '音频文件不能超过 15MB';
// Duration check
try {
const dur = await new Promise<number>((resolve, reject) => {
const audio = new Audio();
const url = URL.createObjectURL(file);
const timeout = setTimeout(() => { reject(); URL.revokeObjectURL(url); }, 10000);
audio.addEventListener('loadedmetadata', () => {
clearTimeout(timeout);
resolve(audio.duration);
URL.revokeObjectURL(url);
});
audio.addEventListener('error', () => { clearTimeout(timeout); reject(); URL.revokeObjectURL(url); });
audio.src = url;
});
if (dur < 2 || dur > 15.4) return `音频时长需在 2~15 秒之间（当前 ${dur.toFixed(1)} 秒）`;
} catch {
// Can't read metadata, skip
}
return null;
}
return '不支持的文件类型';
}
interface Props {
open: boolean;
onClose: () => void;
@ -102,7 +18,12 @@ export function AssetLibraryModal({ open, onClose }: Props) {
const [newName, setNewName] = useState('');
const [uploading, setUploading] = useState(false);
const [editingName, setEditingName] = useState<{ id: number; value: string } | null>(null);
const [uploadFile, setUploadFile] = useState<File | null>(null);
const [uploadPreview, setUploadPreview] = useState<string | null>(null);
const [dragOver, setDragOver] = useState(false);
const [lightboxSrc, setLightboxSrc] = useState<string | null>(null);
const fileInputRef = useRef<HTMLInputElement>(null);
const addFileInputRef = useRef<HTMLInputElement>(null);
const groups = useAssetLibraryStore((s) => s.groups);
const loading = useAssetLibraryStore((s) => s.loading);
@ -110,6 +31,7 @@ export function AssetLibraryModal({ open, onClose }: Props) {
const page = useAssetLibraryStore((s) => s.page);
const loadGroups = useAssetLibraryStore((s) => s.loadGroups);
const createGroup = useAssetLibraryStore((s) => s.createGroup);
const pollAssetStatus = useAssetLibraryStore((s) => s.pollAssetStatus);
const totalPages = Math.ceil(total / 20);
@ -173,22 +95,27 @@ export function AssetLibraryModal({ open, onClose }: Props) {
const handleUploadSubmit = useCallback(async () => {
const trimmed = newName.trim();
if (!trimmed) return;
if (!trimmed || !uploadFile) return;
if (trimmed.length > 64) { showToast('角色名称不能超过64个字符'); return; }
if (trimmed.includes('&&')) { showToast('角色名称不能包含 &&'); return; }
setUploading(true);
const result = await createGroup(trimmed, null);
const result = await createGroup(newName.trim(), uploadFile);
setUploading(false);
if (result) {
pollAssetStatus(result.id);
setNewName('');
// 创建成功后直接进入详情页
const group: AssetGroup = { id: result.id, name: trimmed, thumbnail_url: '', asset_count: 0, remote_group_id: result.remote_group_id || '', description: '', created_at: new Date().toISOString() };
setSelectedGroup(group);
setGroupAssets([]);
setView('detail');
loadGroups(page);
setUploadFile(null);
if (uploadPreview) URL.revokeObjectURL(uploadPreview);
setUploadPreview(null);
handleBackToList();
}
}, [newName, createGroup, loadGroups, page]);
}, [newName, uploadFile, createGroup, pollAssetStatus, uploadPreview, handleBackToList]);
const handleFileSelect = useCallback((file: File) => {
if (uploadPreview) URL.revokeObjectURL(uploadPreview);
setUploadFile(file);
setUploadPreview(URL.createObjectURL(file));
}, [uploadPreview]);
const refreshGroupDetail = useCallback(async () => {
if (!selectedGroup) return;
@ -200,8 +127,6 @@ export function AssetLibraryModal({ open, onClose }: Props) {
const handleAddAsset = useCallback(async (file: File) => {
if (!selectedGroup) return;
const error = await validateAssetFile(file);
if (error) { showToast(error); return; }
const formData = new FormData();
formData.append('file', file);
try {
@ -223,13 +148,21 @@ export function AssetLibraryModal({ open, onClose }: Props) {
clearInterval(pollInterval);
}
}, 3000);
const typeLabel = file.type.startsWith('video/') ? '视频' : file.type.startsWith('audio/') ? '音频' : '图片';
showToast(`${typeLabel}已上传，处理中...`);
showToast('图片已上传，处理中...');
} catch {
showToast('上传失败，请重试');
}
}, [selectedGroup, refreshGroupDetail]);
const handleDrop = useCallback((e: React.DragEvent) => {
e.preventDefault();
setDragOver(false);
const file = e.dataTransfer.files[0];
if (file && file.type.startsWith('image/')) {
handleFileSelect(file);
}
}, [handleFileSelect]);
if (!open) return null;
return (
@ -246,7 +179,7 @@ export function AssetLibraryModal({ open, onClose }: Props) {
</button>
)}
<span className={styles.title}>
{view === 'list' && '人物素材库'}
{view === 'list' && '素材库'}
{view === 'detail' && (selectedGroup?.name || '角色详情')}
{view === 'upload' && '上传新角色'}
</span>
@ -279,7 +212,7 @@ export function AssetLibraryModal({ open, onClose }: Props) {
{groups.map((group) => (
<div key={group.id} className={styles.card} onClick={() => handleGroupClick(group)}>
{group.asset_count === 0 ? (
<div className={styles.cardThumb} style={{ display: 'flex', alignItems: 'center', justifyContent: 'center', color: 'var(--color-text-disabled)', fontSize: 12 }}>暂无素材</div>
<div className={styles.cardThumb} style={{ display: 'flex', alignItems: 'center', justifyContent: 'center', color: 'var(--color-text-disabled)', fontSize: 12 }}>暂无图片</div>
) : (
<img src={tosThumb(group.thumbnail_url, 300)} alt={group.name} className={styles.cardThumb} />
)}
@ -357,26 +290,26 @@ export function AssetLibraryModal({ open, onClose }: Props) {
{view === 'detail' && selectedGroup && (
<>
<div className={styles.actions}>
<button className={styles.actionBtn} onClick={() => addFileInputRef.current?.click()}>
+ 追加图片
</button>
<button
className={styles.actionBtnOutline}
onClick={() => setEditingName({ id: selectedGroup.id, value: selectedGroup.name })}
>
&#9998; 改名
</button>
<button
className={styles.actionBtnOutline}
style={{ color: '#ef4444', borderColor: '#ef4444' }}
onClick={() => {
if (confirm('确认删除整个素材组？组内所有素材将被删除，此操作不可撤销。')) {
assetsApi.deleteGroup(selectedGroup.id).then(() => {
showToast('素材组已删除');
handleBackToList();
}).catch(() => showToast('删除失败，请重试'));
}
<input
ref={addFileInputRef}
type="file"
accept="image/*"
style={{ display: 'none' }}
onChange={(e) => {
const file = e.target.files?.[0];
if (file) handleAddAsset(file);
e.target.value = '';
}}
>
删除素材组
</button>
/>
</div>
{editingName && editingName.id === selectedGroup.id && (
@ -409,125 +342,39 @@ export function AssetLibraryModal({ open, onClose }: Props) {
</div>
)}
{/* ── 按类型分区显示 ── */}
{(['Image', 'Video', 'Audio'] as const).map((assetType) => {
const typeAssets = groupAssets.filter((a) => (a.asset_type || 'Image') === assetType);
const typeLabel = assetType === 'Image' ? '肖像（图片）' : assetType === 'Video' ? '视频' : '音频';
const acceptMap = { Image: 'image/*', Video: 'video/mp4,video/quicktime', Audio: 'audio/mpeg,audio/wav' };
const hintMap = {
Image: '支持 JPG、PNG、WEBP、HEIC，单张不超过 30MB',
Video: '支持 MP4、MOV，单个不超过 50MB',
Audio: '支持 MP3、WAV，单个不超过 15MB',
};
const warningMap = {
Image: '⚠️ 宽高 300~6000 像素，宽高比 0.4~2.5',
Video: '⚠️ 时长 2~15 秒，宽高 300~6000 像素，帧率 24~60 FPS',
Audio: '⚠️ 时长 2~15 秒',
};
return (
<div key={assetType} style={{ marginBottom: 20 }}>
<div style={{ display: 'flex', justifyContent: 'space-between', alignItems: 'center', marginBottom: 4 }}>
<span style={{ fontSize: 13, fontWeight: 600, color: 'var(--color-text-primary)' }}>{typeLabel}</span>
{groupAssets.length === 0 ? (
<div className={styles.empty}>暂无素材图片</div>
) : (
<div className={styles.assetGrid}>
{groupAssets.map((asset) => (
<div key={asset.id} className={styles.assetCard}>
<img
src={tosThumb(asset.url, 300)}
alt={asset.name}
className={styles.assetThumb}
style={{ cursor: 'zoom-in' }}
onClick={() => setLightboxSrc(asset.url)}
/>
<div className={styles.assetInfo}>
<div className={styles.assetName}>{asset.name}</div>
<span className={`${styles.statusBadge} ${
asset.status === 'active' ? styles.statusActive
: asset.status === 'processing' ? styles.statusProcessing
: styles.statusFailed
}`}>
{asset.status === 'active' && '可用'}
{asset.status === 'processing' && '处理中'}
{asset.status === 'failed' && '失败'}
</span>
</div>
</div>
<div style={{ fontSize: 11, color: 'var(--color-text-disabled)', marginBottom: 2 }}>{hintMap[assetType]}</div>
<div style={{ fontSize: 11, color: '#e8952e', marginBottom: 8 }}>{warningMap[assetType]}</div>
<div className={styles.assetGrid}>
{typeAssets.map((asset) => (
<div key={asset.id} className={styles.assetCard}>
{assetType === 'Video' ? (
<img src={tosThumb(asset.thumbnail_url || asset.url, 300)} alt={asset.name} className={styles.assetThumb} />
) : assetType === 'Audio' ? (
<div className={styles.assetThumb} style={{ display: 'flex', alignItems: 'center', justifyContent: 'center', fontSize: 32, background: '#1a1a2e' }}>♫</div>
) : (
<img
src={tosThumb(asset.url, 300)}
alt={asset.name}
className={styles.assetThumb}
style={{ cursor: 'zoom-in' }}
onClick={() => setLightboxSrc(asset.url)}
/>
)}
<button
className={styles.assetDeleteBtn}
onClick={(e) => {
e.stopPropagation();
if (confirm('确认删除此素材？删除后无法恢复。')) {
assetsApi.deleteAsset(asset.id).then(() => {
showToast('素材已删除');
if (selectedGroup) {
assetsApi.getGroupDetail(selectedGroup.id).then(({ data }) => {
setGroupAssets(data.assets || []);
});
}
loadGroups(page);
}).catch(() => showToast('删除失败，请重试'));
}
}}
title="删除素材"
>×</button>
<div className={styles.assetInfo}>
<div className={styles.assetName}>{asset.name}</div>
<span
className={`${styles.statusBadge} ${
asset.status === 'active' ? styles.statusActive
: asset.status === 'processing' ? styles.statusProcessing
: styles.statusFailed
}`}
title={asset.status === 'failed' ? (asset.error_message || '素材处理失败，请删除后重新上传') : undefined}
>
{asset.status === 'active' && '可用'}
{asset.status === 'processing' && '处理中'}
{asset.status === 'failed' && '失败'}
</span>
</div>
</div>
))}
{/* 拖拽上传卡片 — 和素材卡片同大小，始终在最后 */}
<label
className={styles.addAssetCard}
onDragOver={(e) => e.preventDefault()}
onDrop={(e) => {
e.preventDefault();
const file = e.dataTransfer.files[0];
if (!file) return;
// 检查文件类型是否匹配当前分区
const ft = file.type || '';
const matchesSection =
(assetType === 'Image' && ft.startsWith('image/')) ||
(assetType === 'Video' && ft.startsWith('video/')) ||
(assetType === 'Audio' && ft.startsWith('audio/'));
if (!matchesSection) {
const expected = assetType === 'Image' ? '图片' : assetType === 'Video' ? '视频' : '音频';
showToast(`请将${expected}文件拖到此区域`);
return;
}
handleAddAsset(file);
}}
>
<svg width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round">
<line x1="12" y1="5" x2="12" y2="19" />
<line x1="5" y1="12" x2="19" y2="12" />
</svg>
<span>上传</span>
<input
type="file"
accept={acceptMap[assetType]}
style={{ display: 'none' }}
onChange={(e) => {
const file = e.target.files?.[0];
if (file) handleAddAsset(file);
e.target.value = '';
}}
/>
</label>
</div>
</div>
);
})}
))}
</div>
)}
</>
)}
{/* Upload View — only name, no file */}
{/* Upload View */}
{view === 'upload' && (
<div className={styles.uploadForm}>
<div>
@ -538,19 +385,52 @@ export function AssetLibraryModal({ open, onClose }: Props) {
maxLength={64}
value={newName}
onChange={(e) => setNewName(e.target.value)}
onKeyDown={(e) => { if (e.key === 'Enter') handleUploadSubmit(); }}
autoFocus
/>
</div>
<div style={{ fontSize: 12, color: 'var(--color-text-disabled)', marginTop: 4 }}>
创建后可在详情页上传图片、视频、音频素材
<div>
<div className={styles.inputLabel}>角色图片</div>
<div
className={`${styles.dropZone} ${dragOver ? styles.dropZoneActive : ''}`}
onClick={() => fileInputRef.current?.click()}
onDragOver={(e) => { e.preventDefault(); setDragOver(true); }}
onDragLeave={() => setDragOver(false)}
onDrop={handleDrop}
>
{uploadPreview ? (
<>
<img src={uploadPreview} alt="预览" className={styles.dropZonePreview} />
<div className={styles.dropZoneHint}>点击重新选择</div>
</>
) : (
<>
<div className={styles.dropZoneText}>上传角色图片</div>
<div className={styles.dropZoneHint}>将角色的正面图或三视图拖拽到这里，或点击选择文件</div>
<div className={styles.dropZoneHint}>支持 JPG、PNG 格式，单张不超过 30MB</div>
</>
)}
<div className={styles.dropZoneWarning}>⚠️ 素材上传后无法删除，请确认后再上传</div>
<div className={styles.dropZoneWarning}>⚠️ 图片尺寸要求：宽高均需在 300~6000 像素之间</div>
</div>
<input
ref={fileInputRef}
type="file"
accept="image/*"
style={{ display: 'none' }}
onChange={(e) => {
const file = e.target.files?.[0];
if (file) handleFileSelect(file);
e.target.value = '';
}}
/>
</div>
<button
className={styles.submitBtn}
disabled={!newName.trim() || uploading}
disabled={!newName.trim() || !uploadFile || uploading}
onClick={handleUploadSubmit}
>
{uploading ? '创建中...' : '创建角色'}
{uploading ? '上传中...' : '确认上传'}
</button>
</div>
)}

30
web/src/components/GenerationCard.tsx
View File

@ -37,11 +37,10 @@ const DownloadIcon = () => (
);
// Mention tag with thumbnail + hover preview
function MentionTag({ label, thumbUrl, assetType }: { label: string; thumbUrl?: string; assetType?: string }) {
function MentionTag({ label, thumbUrl }: { label: string; thumbUrl?: string }) {
const [hover, setHover] = useState(false);
const ref = useRef<HTMLSpanElement>(null);
const [pos, setPos] = useState({ top: 0, left: 0 });
const isAudio = assetType === 'Audio' || assetType === 'audio';
return (
<>
@ -49,7 +48,7 @@ function MentionTag({ label, thumbUrl, assetType }: { label: string; thumbUrl?:
ref={ref}
className={styles.mentionTag}
onMouseEnter={() => {
if (!isAudio && thumbUrl && ref.current) {
if (thumbUrl && ref.current) {
const rect = ref.current.getBoundingClientRect();
setPos({ top: rect.top - 8, left: rect.left + rect.width / 2 });
setHover(true);
@ -57,15 +56,13 @@ function MentionTag({ label, thumbUrl, assetType }: { label: string; thumbUrl?:
}}
onMouseLeave={() => setHover(false)}
>
{isAudio ? (
<span style={{ marginRight: 3, fontSize: 13, verticalAlign: 'middle' }}>♫</span>
) : thumbUrl ? (
{thumbUrl && (
<img
src={tosThumb(thumbUrl, 28)}
alt=""
style={{ width: 14, height: 14, borderRadius: 3, objectFit: 'cover', verticalAlign: 'middle', marginRight: 3 }}
/>
) : null}
)}
{label}
</span>
{hover && thumbUrl && createPortal(
@ -82,22 +79,16 @@ function MentionTag({ label, thumbUrl, assetType }: { label: string; thumbUrl?:
// Render prompt text with @mentions as styled tags (thumbnail + hover preview)
export function renderPromptWithMentions(
text: string,
assetMentions: Record<string, unknown>[],
assetMentions: { label: string; thumbUrl?: string }[],
references: { label: string; previewUrl?: string }[]
) {
// Build lookup: label → { thumbUrl, assetType }
const thumbMap = new Map<string, { thumbUrl: string; assetType: string }>();
// Build lookup: label → thumbUrl
const thumbMap = new Map<string, string>();
for (const am of assetMentions) {
if (am.label) thumbMap.set(am.label as string, {
thumbUrl: (am.thumbUrl as string) || '',
assetType: (am.assetType as string) || 'image',
});
if (am.label) thumbMap.set(am.label, am.thumbUrl || '');
}
for (const r of references) {
if (r.label && !thumbMap.has(r.label)) thumbMap.set(r.label, {
thumbUrl: r.previewUrl || '',
assetType: (r as Record<string, unknown>).type as string || 'image',
});
if (r.label && !thumbMap.has(r.label)) thumbMap.set(r.label, r.previewUrl || '');
}
const labels = [...thumbMap.keys()];
@ -115,8 +106,7 @@ export function renderPromptWithMentions(
if (regex.test(part)) {
regex.lastIndex = 0;
const label = part.slice(1); // remove @
const info = thumbMap.get(label);
return <MentionTag key={i} label={label} thumbUrl={info?.thumbUrl} assetType={info?.assetType} />;
return <MentionTag key={i} label={label} thumbUrl={thumbMap.get(label)} />;
}
regex.lastIndex = 0;
return part;

2
web/src/components/InputBar.tsx
View File

@ -114,7 +114,7 @@ export function InputBar({ scrollBottomBtn }: { scrollBottomBtn?: React.ReactNod
onMouseEnter={(e) => { (e.currentTarget as HTMLElement).style.borderColor = 'var(--color-primary)'; (e.currentTarget as HTMLElement).style.color = 'var(--color-primary)'; }}
onMouseLeave={(e) => { (e.currentTarget as HTMLElement).style.borderColor = 'var(--color-border-card)'; (e.currentTarget as HTMLElement).style.color = 'var(--color-text-secondary)'; }}
>
人物素材库
素材库
</button>
<button
onClick={() => { if (!searchDisabled) setSearchMode(searchMode === 'smart' ? 'off' : 'smart'); }}

146
web/src/components/PromptInput.tsx
View File

@ -2,9 +2,7 @@ import { useRef, useEffect, useCallback, useState } from 'react';
import DOMPurify from 'dompurify';
import { useInputBarStore } from '../store/inputBar';
import { assetsApi, tosThumb } from '../lib/api';
import type { UploadedFile, AssetSearchResult } from '../types';
import { parseAssetMentionsFromDOM } from '../lib/assetMentions';
import { showToast } from './Toast';
import type { UploadedFile, AssetGroup } from '../types';
import styles from './PromptInput.module.css';
const placeholders: Record<string, string> = {
@ -29,7 +27,7 @@ export function PromptInput() {
const [hoverRef, setHoverRef] = useState<UploadedFile | null>(null);
const [hoverPos, setHoverPos] = useState({ top: 0, left: 0 });
const [mentionMode, setMentionMode] = useState<'references' | 'assets'>('references');
const [assetSearchResults, setAssetSearchResults] = useState<AssetSearchResult[]>([]);
const [assetSearchResults, setAssetSearchResults] = useState<AssetGroup[]>([]);
const searchTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
// Auto-focus
@ -42,7 +40,7 @@ export function PromptInput() {
const el = editorRef.current;
if (!el) return;
if (el.innerHTML !== editorHtml) {
el.innerHTML = DOMPurify.sanitize(editorHtml, { ALLOWED_TAGS: ['span', 'br', 'img'], ALLOWED_ATTR: ['class', 'contenteditable', 'data-ref-id', 'data-ref-type', 'data-asset-group-id', 'data-group-name', 'data-asset-id', 'data-asset-type', 'data-asset-name', 'data-duration', 'data-thumb-url', 'draggable', 'src', 'alt', 'width', 'height', 'style'] });
el.innerHTML = DOMPurify.sanitize(editorHtml, { ALLOWED_TAGS: ['span', 'br', 'img'], ALLOWED_ATTR: ['class', 'contenteditable', 'data-ref-id', 'data-ref-type', 'data-asset-group-id', 'data-group-name', 'data-thumb-url', 'draggable', 'src', 'alt', 'width', 'height', 'style'] });
// If the HTML is plain text but we have references or asset mentions, rebuild mention spans
// This handles the case where editorHtml comes from backend (plain text only)
const currentAssetMentions = useInputBarStore.getState().assetMentions || [];
@ -66,7 +64,6 @@ export function PromptInput() {
const createMentionSpan = useCallback((opts: {
refId: string; refType: string; label: string; thumbUrl?: string;
assetGroupId?: string; groupName?: string;
assetId?: string; assetType?: string; assetName?: string; duration?: string;
}) => {
const span = document.createElement('span');
span.className = styles.mention;
@ -75,18 +72,10 @@ export function PromptInput() {
span.dataset.refType = opts.refType;
span.draggable = true;
if (opts.thumbUrl) span.dataset.thumbUrl = opts.thumbUrl;
// New asset attributes (individual asset reference)
if (opts.assetId) span.dataset.assetId = opts.assetId;
if (opts.assetType) span.dataset.assetType = opts.assetType;
if (opts.assetName) span.dataset.assetName = opts.assetName;
if (opts.duration) span.dataset.duration = opts.duration;
// Legacy group attributes (backward compat for old records)
if (opts.assetGroupId) span.dataset.assetGroupId = opts.assetGroupId;
if (opts.groupName) span.dataset.groupName = opts.groupName;
// Render icon/thumbnail based on type
const isAudio = opts.refType === 'audio' || opts.assetType === 'Audio';
if (isAudio) {
if (opts.refType === 'audio') {
const icon = document.createElement('span');
icon.textContent = '\u266B';
icon.style.cssText = 'margin-right:3px;font-size:13px;vertical-align:middle;pointer-events:none';
@ -113,40 +102,19 @@ export function PromptInput() {
const rebuildMentionSpans = useCallback((el: HTMLElement) => {
// Collect all targets to match: references + asset mentions
const currentAssetMentions = useInputBarStore.getState().assetMentions || [];
type MatchTarget = {
label: string; refId: string; refType: string; thumbUrl: string;
assetGroupId?: string; groupName?: string;
assetId?: string; assetType?: string; assetName?: string; duration?: string;
};
type MatchTarget = { label: string; refId: string; refType: string; thumbUrl: string; assetGroupId?: string; groupName?: string };
const targets: MatchTarget[] = [
...references.map((ref) => ({
label: ref.label, refId: ref.id, refType: ref.type, thumbUrl: ref.previewUrl,
})),
...currentAssetMentions.map((am: Record<string, unknown>) => {
// New format (individual asset)
if (am.assetId) {
return {
label: am.label as string, refId: am.assetId as string, refType: 'asset',
thumbUrl: (am.thumbUrl as string) || '',
assetId: am.assetId as string, assetType: am.assetType as string,
assetName: am.label as string, duration: String(am.duration || 0),
};
}
// Legacy format (group reference)
return {
label: am.label as string, refId: (am.groupId as string) || '', refType: 'asset',
thumbUrl: (am.thumbUrl as string) || '',
assetGroupId: am.groupId as string, groupName: am.label as string,
};
}),
...currentAssetMentions.map((am) => ({
label: am.label, refId: am.groupId, refType: 'asset', thumbUrl: am.thumbUrl || '',
assetGroupId: am.groupId, groupName: am.label,
})),
];
if (targets.length === 0) return;
// Sort targets by label length descending — longer labels match first
// Prevents "苏晓雨" from stealing the match before "苏晓雨音频"
targets.sort((a, b) => b.label.length - a.label.length);
const walker = document.createTreeWalker(el, NodeFilter.SHOW_TEXT);
const replacements: { node: Text; matches: { start: number; end: number; target: MatchTarget }[] }[] = [];
@ -192,10 +160,6 @@ export function PromptInput() {
thumbUrl: m.target.thumbUrl,
assetGroupId: m.target.assetGroupId,
groupName: m.target.groupName,
assetId: m.target.assetId,
assetType: m.target.assetType,
assetName: m.target.assetName,
duration: m.target.duration,
});
frag.appendChild(span);
lastIdx = m.end;
@ -276,16 +240,6 @@ export function PromptInput() {
}
}, [references, extractText]);
// Sync editorHtml immediately on ANY DOM change (backspace delete, etc.)
// Without this, deleting a mention span doesn't update editorHtml until next input event
useEffect(() => {
const el = editorRef.current;
if (!el) return;
const observer = new MutationObserver(() => extractText());
observer.observe(el, { childList: true, subtree: true, characterData: true });
return () => observer.disconnect();
}, [extractText]);
const handleInput = useCallback(() => {
extractText();
@ -331,7 +285,7 @@ export function PromptInput() {
} else {
setShowMentionPopup(false);
}
}).catch(() => { showToast('素材搜索失败，请重试'); });
}).catch(() => {});
}, 300);
} else if (textAfterAt.includes(' ')) {
// Space after @ text, close popup
@ -393,35 +347,7 @@ export function PromptInput() {
extractText();
}, [extractText]);
const insertAssetMention = useCallback((asset: AssetSearchResult) => {
// Instant check: count limit
const stats = editorRef.current ? parseAssetMentionsFromDOM(editorRef.current) : { counts: { image: 0, video: 0, audio: 0 }, durations: { video: 0, audio: 0 } };
const refs = useInputBarStore.getState().references;
const refCounts = { image: 0, video: 0, audio: 0 };
refs.forEach((r) => refCounts[r.type]++);
const typeKey = asset.asset_type === 'Video' ? 'video' : asset.asset_type === 'Audio' ? 'audio' : 'image';
const maxMap = { image: 9, video: 3, audio: 3 };
if (refCounts[typeKey] + stats.counts[typeKey] >= maxMap[typeKey]) {
const typeLabel = asset.asset_type === 'Video' ? '视频' : asset.asset_type === 'Audio' ? '音频' : '图片';
showToast(`${typeLabel}已达上限`);
return;
}
// Instant check: duration limit (video/audio)
if (asset.asset_type === 'Video' || asset.asset_type === 'Audio') {
if (!asset.duration) {
// Duration unknown (still processing or ffprobe failed) — warn but allow
showToast('该素材时长未确定，提交时将由服务端校验');
} else {
const existingDur = refs.filter((r) => r.type === typeKey && r.duration).reduce((s, r) => s + (r.duration || 0), 0);
const assetDur = typeKey === 'video' ? stats.durations.video : stats.durations.audio;
if (existingDur + assetDur + asset.duration > 15.4) {
const typeLabel = asset.asset_type === 'Video' ? '视频' : '音频';
showToast(`${typeLabel}总时长超过15秒限制`);
return;
}
}
}
const insertAssetMention = useCallback((group: AssetGroup) => {
setShowMentionPopup(false);
setMentionMode('references');
setAssetSearchResults([]);
@ -452,16 +378,14 @@ export function PromptInput() {
range.deleteContents();
// Create mention span for individual asset
// Create mention span for asset with thumbnail
const mention = createMentionSpan({
refId: String(asset.id),
refId: String(group.id),
refType: 'asset',
label: asset.name,
thumbUrl: asset.thumbnail_url || asset.url,
assetId: String(asset.id),
assetType: asset.asset_type,
assetName: asset.name,
duration: asset.duration != null ? String(asset.duration) : '',
label: group.name,
thumbUrl: group.thumbnail_url,
assetGroupId: String(group.id),
groupName: group.name,
});
range.insertNode(mention);
@ -476,7 +400,7 @@ export function PromptInput() {
sel.addRange(newRange);
extractText();
}, [extractText, editorHtml, references]);
}, [extractText]);
const handleKeyDown = useCallback((e: React.KeyboardEvent) => {
if (showMentionPopup) {
@ -527,9 +451,8 @@ export function PromptInput() {
ALLOWED_TAGS: ['span', 'br', 'img'],
ALLOWED_ATTR: [
'class', 'contenteditable', 'data-ref-id', 'data-ref-type',
'data-asset-group-id', 'data-group-name',
'data-asset-id', 'data-asset-type', 'data-asset-name', 'data-duration',
'data-thumb-url', 'draggable', 'src', 'alt', 'width', 'height', 'style',
'data-asset-group-id', 'data-group-name', 'data-thumb-url',
'draggable', 'src', 'alt', 'width', 'height', 'style',
],
});
document.execCommand('insertHTML', false, sanitized);
@ -565,15 +488,13 @@ export function PromptInput() {
// 素材库标签：用 data-thumb-url 构造预览数据
if (!found && refType === 'asset') {
const assetType = target.dataset.assetType || 'Image';
if (assetType === 'Audio') return; // 音频素材不弹预览
const thumbUrl = target.dataset.thumbUrl;
if (thumbUrl) {
found = {
id: refId || '',
type: assetType === 'Video' ? 'video' : 'image',
type: 'image',
previewUrl: thumbUrl,
label: target.dataset.assetName || target.textContent || '',
label: target.dataset.groupName || target.textContent || '',
};
}
}
@ -711,32 +632,25 @@ export function PromptInput() {
)}
{mentionMode === 'assets' && assetSearchResults.length > 0 && (
<>
<div className={styles.mentionHeader}>人物素材库匹配</div>
{assetSearchResults.map((asset, idx) => (
<div className={styles.mentionHeader}>素材库匹配</div>
{assetSearchResults.map((group, idx) => (
<button
key={asset.id}
key={group.id}
className={`${styles.mentionItem} ${idx === highlightedIdx ? styles.mentionItemActive : ''}`}
onMouseDown={(e) => {
e.preventDefault();
insertAssetMention(asset);
insertAssetMention(group);
}}
>
<div className={styles.mentionThumb}>
{asset.asset_type === 'Audio' ? (
<span style={{ fontSize: 16 }}>♫</span>
) : (asset.thumbnail_url || asset.url) ? (
<img src={tosThumb(asset.thumbnail_url || asset.url, 72)} alt="" className={styles.thumbMedia} />
{group.thumbnail_url ? (
<img src={tosThumb(group.thumbnail_url, 72)} alt="" className={styles.thumbMedia} />
) : (
<span style={{ fontSize: 9, color: 'var(--color-text-disabled)' }}>无图</span>
)}
</div>
<div style={{ flex: 1, minWidth: 0 }}>
<span className={styles.mentionLabel}>{asset.name}</span>
<span style={{ fontSize: 10, color: '#5a5a6a', marginLeft: 4 }}>{asset.group_name}</span>
</div>
<span className={styles.mentionType}>
{asset.asset_type === 'Video' ? '视频' : asset.asset_type === 'Audio' ? '音频' : '图片'}
</span>
<span className={styles.mentionLabel}>{group.name}</span>
<span className={styles.mentionType}>人像</span>
</button>
))}
</>

4
web/src/components/Sidebar.tsx
View File

@ -38,8 +38,8 @@ export function Sidebar() {
<span>生成</span>
</div>
<div
className={`${styles.navItem} ${isActive('/user-assets') ? styles.active : ''}`}
onClick={() => navigate('/user-assets')}
className={`${styles.navItem} ${isActive('/assets') ? styles.active : ''}`}
onClick={() => navigate('/assets')}
>
<svg width="22" height="22" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.5">
<rect x="3" y="3" width="18" height="18" rx="2" />

10
web/src/lib/api.ts
View File

@ -4,7 +4,7 @@ import type {
AdminRecord, SystemSettings, ProfileOverview, PaginatedResponse,
BackendTask, TeamInfo, Team, TeamDetail, TeamMember, TeamStats,
AuditLog, AssetTeamSummary, AssetMemberSummary, AssetVideo,
LoginAnomaly, TeamAnomalyConfig, AssetGroup, AssetItem, AssetSearchResult,
LoginAnomaly, TeamAnomalyConfig, AssetGroup, AssetItem,
} from '../types';
import { reportError } from './logCenter';
@ -146,7 +146,7 @@ export const videoApi = {
model: string;
aspect_ratio: string;
duration: number;
references: { url: string; type: string; role: string; label: string; thumb_url?: string; duration?: string }[];
references: { url: string; type: string; role: string; label: string; thumb_url?: string }[];
search_mode?: string;
seed?: number;
}) =>
@ -420,16 +420,12 @@ export const assetsApi = {
api.get<AssetGroup & { assets: AssetItem[] }>(`/assets/groups/${id}`),
updateGroup: (id: number, data: { name?: string; description?: string }) =>
api.put(`/assets/groups/${id}`, data),
deleteGroup: (id: number) =>
api.delete(`/assets/groups/${id}`),
addAsset: (groupId: number, data: FormData) =>
api.post<AssetItem>(`/assets/groups/${groupId}/assets`, data, { headers: { 'Content-Type': 'multipart/form-data' } }),
updateAsset: (id: number, data: { name: string }) =>
api.put(`/assets/${id}`, data),
deleteAsset: (id: number) =>
api.delete(`/assets/${id}`),
search: (q: string) =>
api.get<{ results: AssetSearchResult[] }>('/assets/search', { params: { q } }),
api.get<{ results: AssetGroup[] }>('/assets/search', { params: { q } }),
pollStatus: (id: number) =>
api.get<{ id: number; status: string; url: string; error_message: string }>(`/assets/${id}/status`),
};

44
web/src/lib/assetMentions.ts
View File

@ -1,44 +0,0 @@
/**
* Parse asset mention spans directly from a DOM element (real-time, no stale state).
* Use this when you have access to the editor DOM element.
*/
export function parseAssetMentionsFromDOM(el: HTMLElement): {
counts: { image: number; video: number; audio: number };
durations: { video: number; audio: number };
} {
const counts = { image: 0, video: 0, audio: 0 };
const durations = { video: 0, audio: 0 };
el.querySelectorAll('[data-ref-type="asset"]').forEach((span) => {
const t = (span as HTMLElement).dataset.assetType || 'Image';
const rawDur = parseFloat((span as HTMLElement).dataset.duration || '0');
const dur = isNaN(rawDur) ? 0 : rawDur;
if (t === 'Video') { counts.video++; durations.video += dur; }
else if (t === 'Audio') { counts.audio++; durations.audio += dur; }
else { counts.image++; }
});
return { counts, durations };
}
/**
* Parse asset mention spans from editor HTML string.
* Use this when you only have the HTML string (e.g., from store state).
*/
export function parseAssetMentions(html: string): {
counts: { image: number; video: number; audio: number };
durations: { video: number; audio: number };
} {
const counts = { image: 0, video: 0, audio: 0 };
const durations = { video: 0, audio: 0 };
if (!html) return { counts, durations };
const parser = new DOMParser();
const doc = parser.parseFromString(html, 'text/html');
doc.querySelectorAll('[data-ref-type="asset"]').forEach((el) => {
const t = (el as HTMLElement).dataset.assetType || 'Image';
const rawDur = parseFloat((el as HTMLElement).dataset.duration || '0');
const dur = isNaN(rawDur) ? 0 : rawDur; // null/undefined → NaN → 0, ffprobe 失败不计入时长
if (t === 'Video') { counts.video++; durations.video += dur; }
else if (t === 'Audio') { counts.audio++; durations.audio += dur; }
else { counts.image++; }
});
return { counts, durations };
}

10
web/src/store/assetLibrary.ts
View File

@ -1,6 +1,6 @@
import { create } from 'zustand';
import { assetsApi } from '../lib/api';
import type { AssetGroup, AssetSearchResult } from '../types';
import type { AssetGroup } from '../types';
import { showToast } from '../components/Toast';
interface AssetLibraryState {
@ -8,12 +8,12 @@ interface AssetLibraryState {
loading: boolean;
total: number;
page: number;
searchResults: AssetSearchResult[];
searchResults: AssetGroup[];
searching: boolean;
loadGroups: (page?: number) => Promise<void>;
searchAssets: (query: string) => Promise<void>;
createGroup: (name: string, file: File | null) => Promise<AssetGroup | null>;
createGroup: (name: string, file: File) => Promise<AssetGroup | null>;
pollAssetStatus: (assetId: number) => void;
}
@ -45,10 +45,10 @@ export const useAssetLibraryStore = create<AssetLibraryState>((set) => ({
}
},
createGroup: async (name: string, file: File | null) => {
createGroup: async (name: string, file: File) => {
const formData = new FormData();
formData.append('name', name);
if (file) formData.append('file', file);
formData.append('file', file);
try {
const { data } = await assetsApi.createGroup(formData);
showToast('角色创建成功');

73
web/src/store/generation.ts
View File

@ -84,17 +84,8 @@ function buildAssetMentions(refs: Array<Record<string, string>>) {
.filter((ref) => isAssetUrl(ref.url || ''))
.map((ref) => {
const url = ref.url || '';
// New format: asset://local-{id}
if (url.startsWith('asset://local-')) {
const assetId = url.replace('asset://local-', '');
return {
assetId, label: ref.label || '', thumbUrl: ref.thumb_url || '',
assetType: ref.type || 'image', duration: parseFloat(ref.duration || '0'),
};
}
// Legacy format: asset://group-{id}
const groupId = url.startsWith('asset://group-') ? url.replace('asset://group-', '') : '';
return { groupId, label: ref.label || '', thumbUrl: ref.thumb_url || '', assetType: 'image', duration: 0 };
return { groupId, label: ref.label || '', thumbUrl: ref.thumb_url || '' };
});
}
@ -118,7 +109,6 @@ function backendToFrontend(bt: BackendTask): GenerationTask {
status: mapStatus(bt.status),
progress: bt.status === 'processing' ? Number(sessionStorage.getItem(`progress_${bt.task_id}`) || mapProgress(bt.status)) : mapProgress(bt.status),
resultUrl: bt.result_url || undefined,
thumbnailUrl: bt.thumbnail_url || undefined,
errorMessage: mapErrorMessage(bt.error_message),
createdAt: new Date(bt.created_at).getTime(),
tokensConsumed: bt.tokens_consumed || 0,
@ -359,7 +349,7 @@ export const useGenerationStore = create<GenerationState>((set, get) => ({
].filter(Boolean) as ReferenceSnapshot[];
// Extract asset mentions for placeholder display
const placeholderAssetMentions: Record<string, unknown>[] = [];
const placeholderAssetMentions: { groupId: string; label: string; thumbUrl: string }[] = [];
if (input.editorHtml) {
const parser = new DOMParser();
const doc = parser.parseFromString(input.editorHtml, 'text/html');
@ -420,7 +410,7 @@ export const useGenerationStore = create<GenerationState>((set, get) => ({
try {
// Use pre-uploaded TOS URLs (immediate upload), fallback to upload here if needed
const uploadedRefs: { url: string; type: string; role: string; label: string; thumb_url?: string; duration?: string }[] = [];
const uploadedRefs: { url: string; type: string; role: string; label: string; thumb_url?: string }[] = [];
for (const item of filesToUpload) {
if (item.tosUrl && !item.tosUrl.startsWith('blob:')) {
@ -432,69 +422,38 @@ export const useGenerationStore = create<GenerationState>((set, get) => ({
}
}
// Extract asset mentions from editor HTML — deduplicate by assetId
const seenAssetIds = new Set<string>();
// Extract asset mentions from editor HTML — deduplicate by groupId
const seenGroupIds = new Set<string>();
if (input.editorHtml) {
const parser = new DOMParser();
const doc = parser.parseFromString(input.editorHtml, 'text/html');
const assetSpans = doc.querySelectorAll('[data-ref-type="asset"]');
assetSpans.forEach((span) => {
const el = span as HTMLElement;
const assetId = el.dataset.assetId;
const assetType = (el.dataset.assetType || 'Image').toLowerCase();
const assetName = el.dataset.assetName || el.textContent?.replace('@', '') || '';
const duration = el.dataset.duration || '0';
if (assetId && !seenAssetIds.has(assetId)) {
seenAssetIds.add(assetId);
const groupId = el.dataset.assetGroupId;
const groupName = el.dataset.groupName || el.textContent?.replace('@', '') || '';
if (groupId && !seenGroupIds.has(groupId)) {
seenGroupIds.add(groupId);
uploadedRefs.push({
url: `asset://local-${assetId}`,
type: assetType,
role: `reference_${assetType}`,
label: assetName,
url: `asset://group-${groupId}`,
type: 'image',
role: 'reference_image',
label: groupName,
thumb_url: el.dataset.thumbUrl || '',
duration,
});
}
// Legacy: data-asset-group-id (old format)
if (!assetId && el.dataset.assetGroupId) {
const groupId = el.dataset.assetGroupId;
const groupName = el.dataset.groupName || el.textContent?.replace('@', '') || '';
if (!seenAssetIds.has(`group-${groupId}`)) {
seenAssetIds.add(`group-${groupId}`);
uploadedRefs.push({
url: `asset://group-${groupId}`,
type: 'image',
role: 'reference_image',
label: groupName,
thumb_url: el.dataset.thumbUrl || '',
});
}
}
});
}
// Fallback: only use inputBar assetMentions when editorHtml has NO asset spans
// (regenerate scenario where editorHtml is plain text)
// If user edited the HTML and removed some asset tags, respect that — don't re-add from store
const htmlHadAssetSpans = input.editorHtml?.includes('data-ref-type="asset"');
if (!htmlHadAssetSpans) {
const inputAssetMentions = input.assetMentions || [];
for (const am of inputAssetMentions) {
// New format
if (am.assetId && !seenAssetIds.has(am.assetId)) {
seenAssetIds.add(am.assetId);
const t = (am.assetType || 'Image').toLowerCase();
uploadedRefs.push({
url: `asset://local-${am.assetId}`,
type: t,
role: `reference_${t}`,
label: am.label,
thumb_url: am.thumbUrl || '',
duration: String(am.duration || 0),
});
}
// Legacy format
if (!am.assetId && am.groupId && !seenAssetIds.has(`group-${am.groupId}`)) {
seenAssetIds.add(`group-${am.groupId}`);
if (am.groupId && !seenGroupIds.has(am.groupId)) {
seenGroupIds.add(am.groupId);
uploadedRefs.push({
url: `asset://group-${am.groupId}`,
type: 'image',

16
web/src/store/inputBar.ts
View File

@ -2,7 +2,6 @@ import { create } from 'zustand';
import type { CreationMode, ModelOption, AspectRatio, Duration, GenerationType, UploadedFile } from '../types';
import { showToast } from '../components/Toast';
import { mediaApi } from '../lib/api';
import { parseAssetMentions } from '../lib/assetMentions';
let fileCounter = 0;
@ -124,8 +123,7 @@ interface InputBarState {
setSeedEnabled: (enabled: boolean) => void;
// Asset mentions (for reEdit/regenerate to pass asset data to PromptInput rebuild)
// eslint-disable-next-line @typescript-eslint/no-explicit-any
assetMentions: Record<string, any>[];
assetMentions: { groupId: string; label: string; thumbUrl: string }[];
// @ trigger (for toolbar button to insert @ in contentEditable)
insertAtTrigger: number;
@ -172,13 +170,9 @@ export const useInputBarStore = create<InputBarState>((set, get) => ({
prevReferences: [],
addReferences: (files) => {
const state = get();
// Count existing references by type + merge @ asset mentions
// Count existing references by type
const counts = { image: 0, video: 0, audio: 0 };
for (const ref of state.references) counts[ref.type]++;
const { counts: assetCounts } = parseAssetMentions(state.editorHtml);
counts.image += assetCounts.image;
counts.video += assetCounts.video;
counts.audio += assetCounts.audio;
// Separate images (sync) from audio/video (need async duration check)
const imageFiles: File[] = [];
@ -502,13 +496,11 @@ async function _validateAndAddMedia(files: File[]) {
}
}
// Total duration check (same type) — merge @ asset mention durations
// Total duration check (same type)
const state = useInputBarStore.getState();
const { durations: assetDurations } = parseAssetMentions(state.editorHtml);
const refDuration = state.references
const existingDuration = state.references
.filter((r) => r.type === type && r.duration)
.reduce((sum, r) => sum + (r.duration || 0), 0);
const existingDuration = refDuration + (type === 'video' ? assetDurations.video : assetDurations.audio);
if (existingDuration + dur > MAX_MEDIA_DURATION + 0.4) {
showToast(`${typeLabel}总时长不能超过${MAX_MEDIA_DURATION}秒`);
continue;

19
web/src/types/index.ts
View File

@ -44,12 +44,10 @@ export interface GenerationTask {
aspectRatio: AspectRatio;
duration: Duration;
references: ReferenceSnapshot[];
// eslint-disable-next-line @typescript-eslint/no-explicit-any
assetMentions: Record<string, any>[];
assetMentions: { groupId: string; label: string; thumbUrl: string }[];
status: TaskStatus;
progress: number;
resultUrl?: string;
thumbnailUrl?: string;
errorMessage?: string;
createdAt: number;
tokensConsumed?: number;
@ -73,7 +71,6 @@ export interface BackendTask {
base_cost_amount: number;
status: 'queued' | 'processing' | 'completed' | 'failed';
result_url: string;
thumbnail_url: string;
error_message: string;
reference_urls: { url: string; type: string; role: string; label: string }[];
is_favorited: boolean;
@ -438,22 +435,8 @@ export interface AssetItem {
id: number;
name: string;
url: string;
asset_type: 'Image' | 'Video' | 'Audio';
thumbnail_url: string;
duration: number | null;
status: 'processing' | 'active' | 'failed';
remote_asset_id: string;
error_message: string;
created_at: string;
}
export interface AssetSearchResult {
id: number;
name: string;
url: string;
asset_type: 'Image' | 'Video' | 'Audio';
group_name: string;
remote_asset_id: string;
thumbnail_url: string;
duration: number | null;
}

411
web/test/e2e/v018-test.spec.ts
View File

@ -1,411 +0,0 @@
/**
* v0.18.0 E2E Tests — run against test environment
* Tests: asset search, asset library, generation page interactions
*/
import { test, expect, Page } from '@playwright/test';
const BASE_URL = 'https://airflow-studio.test.airlabs.art';
const API_URL = 'https://airflow-studio-api.test.airlabs.art';
const USERNAME = 'tudou';
const PASSWORD = 'seaislee';
let accessToken = '';
// Login and get token
async function login(page: Page) {
const resp = await page.request.post(`${API_URL}/api/v1/auth/login`, {
data: { username: USERNAME, password: PASSWORD },
});
expect(resp.ok()).toBeTruthy();
const body = await resp.json();
accessToken = body.tokens.access;
// Set tokens in localStorage and navigate
await page.goto(BASE_URL);
await page.evaluate(({ access, refresh }) => {
localStorage.setItem('access_token', access);
localStorage.setItem('refresh_token', refresh);
}, { access: body.tokens.access, refresh: body.tokens.refresh });
await page.goto(`${BASE_URL}/app`);
await page.waitForTimeout(2000);
}
// ─── API Tests ───
test.describe('Backend API Tests', () => {
test('asset search returns individual assets (not groups)', async ({ request }) => {
// Login
const loginResp = await request.post(`${API_URL}/api/v1/auth/login`, {
data: { username: USERNAME, password: PASSWORD },
});
const { tokens } = await loginResp.json();
// Search for assets
const searchResp = await request.get(`${API_URL}/api/v1/assets/search?q=test`, {
headers: { Authorization: `Bearer ${tokens.access}` },
});
expect(searchResp.ok()).toBeTruthy();
const data = await searchResp.json();
// Should return results array
expect(data).toHaveProperty('results');
expect(Array.isArray(data.results)).toBeTruthy();
// Each result should have individual asset fields (not group fields)
if (data.results.length > 0) {
const asset = data.results[0];
expect(asset).toHaveProperty('id');
expect(asset).toHaveProperty('name');
expect(asset).toHaveProperty('url');
expect(asset).toHaveProperty('asset_type');
expect(asset).toHaveProperty('group_name');
expect(asset).toHaveProperty('thumbnail_url');
expect(asset).toHaveProperty('duration');
// Should NOT have group-level fields
expect(asset).not.toHaveProperty('asset_count');
expect(asset).not.toHaveProperty('remote_group_id');
}
});
test('asset search only returns active assets', async ({ request }) => {
const loginResp = await request.post(`${API_URL}/api/v1/auth/login`, {
data: { username: USERNAME, password: PASSWORD },
});
const { tokens } = await loginResp.json();
const searchResp = await request.get(`${API_URL}/api/v1/assets/search?q=a`, {
headers: { Authorization: `Bearer ${tokens.access}` },
});
const data = await searchResp.json();
// All returned assets should be active
for (const asset of data.results) {
// Search API doesn't return status, but only queries active ones
expect(asset).toHaveProperty('id');
}
});
test('search query is truncated at 100 chars', async ({ request }) => {
const loginResp = await request.post(`${API_URL}/api/v1/auth/login`, {
data: { username: USERNAME, password: PASSWORD },
});
const { tokens } = await loginResp.json();
const longQuery = 'a'.repeat(200);
const searchResp = await request.get(`${API_URL}/api/v1/assets/search?q=${longQuery}`, {
headers: { Authorization: `Bearer ${tokens.access}` },
});
// Should not crash
expect(searchResp.ok()).toBeTruthy();
});
test('create asset group without file', async ({ request }) => {
const loginResp = await request.post(`${API_URL}/api/v1/auth/login`, {
data: { username: USERNAME, password: PASSWORD },
});
const { tokens } = await loginResp.json();
const formData = new FormData();
formData.append('name', `test-e2e-${Date.now()}`);
// Note: multipart/form-data without file
const createResp = await request.post(`${API_URL}/api/v1/assets/groups`, {
headers: { Authorization: `Bearer ${tokens.access}` },
multipart: { name: `test-e2e-${Date.now()}` },
});
expect(createResp.ok()).toBeTruthy();
const group = await createResp.json();
expect(group).toHaveProperty('id');
expect(group.asset_count).toBe(0);
expect(group.thumbnail_url).toBe('');
});
test('delete asset endpoint works', async ({ request }) => {
const loginResp = await request.post(`${API_URL}/api/v1/auth/login`, {
data: { username: USERNAME, password: PASSWORD },
});
const { tokens } = await loginResp.json();
// Get groups to find an asset to test with
const groupsResp = await request.get(`${API_URL}/api/v1/assets/groups`, {
headers: { Authorization: `Bearer ${tokens.access}` },
});
const groups = await groupsResp.json();
// Find a group with assets
for (const group of groups.results) {
if (group.asset_count > 0) {
const detailResp = await request.get(`${API_URL}/api/v1/assets/groups/${group.id}`, {
headers: { Authorization: `Bearer ${tokens.access}` },
});
const detail = await detailResp.json();
// Verify assets have asset_type and thumbnail_url fields
if (detail.assets && detail.assets.length > 0) {
const asset = detail.assets[0];
expect(asset).toHaveProperty('asset_type');
expect(asset).toHaveProperty('thumbnail_url');
expect(asset).toHaveProperty('duration');
}
break;
}
}
});
test('HEIC format accepted in upload', async ({ request }) => {
const loginResp = await request.post(`${API_URL}/api/v1/auth/login`, {
data: { username: USERNAME, password: PASSWORD },
});
const { tokens } = await loginResp.json();
// Upload a fake HEIC file (just test the format check, not actual processing)
const uploadResp = await request.post(`${API_URL}/api/v1/media/upload`, {
headers: { Authorization: `Bearer ${tokens.access}` },
multipart: {
file: {
name: 'test.heic',
mimeType: 'image/heic',
buffer: Buffer.from('fake heic content'),
},
},
});
// Should not reject with "不支持的文件格式"
// It may fail for other reasons (invalid image), but format should be accepted
const status = uploadResp.status();
if (status === 400) {
const body = await uploadResp.json();
expect(body.error).not.toContain('不支持的文件格式');
}
});
test('asset://local- format accepted in generation', async ({ request }) => {
const loginResp = await request.post(`${API_URL}/api/v1/auth/login`, {
data: { username: USERNAME, password: PASSWORD },
});
const { tokens } = await loginResp.json();
// Try to generate with a non-existent asset://local- reference
const genResp = await request.post(`${API_URL}/api/v1/video/generate`, {
headers: { Authorization: `Bearer ${tokens.access}` },
data: {
prompt: 'test',
mode: 'universal',
model: 'seedance_2.0',
aspect_ratio: '16:9',
duration: 5,
references: [
{ url: 'asset://local-99999', type: 'image', role: 'reference_image', label: 'test' },
],
},
});
// Should return 400 with friendly error (asset not found), not 500
expect(genResp.status()).toBe(400);
const body = await genResp.json();
expect(body.error).toBe('asset_not_found');
});
test('asset://group- format still works (backward compat)', async ({ request }) => {
const loginResp = await request.post(`${API_URL}/api/v1/auth/login`, {
data: { username: USERNAME, password: PASSWORD },
});
const { tokens } = await loginResp.json();
// Try old format with non-existent group
const genResp = await request.post(`${API_URL}/api/v1/video/generate`, {
headers: { Authorization: `Bearer ${tokens.access}` },
data: {
prompt: 'test',
mode: 'universal',
model: 'seedance_2.0',
aspect_ratio: '16:9',
duration: 5,
references: [
{ url: 'asset://group-99999', type: 'image', role: 'reference_image', label: 'test' },
],
},
});
// Should return 400 (not ready), not 500
expect(genResp.status()).toBe(400);
const body = await genResp.json();
expect(body.error).toBe('asset_not_ready');
});
test('blob: URL rejected by backend', async ({ request }) => {
const loginResp = await request.post(`${API_URL}/api/v1/auth/login`, {
data: { username: USERNAME, password: PASSWORD },
});
const { tokens } = await loginResp.json();
const genResp = await request.post(`${API_URL}/api/v1/video/generate`, {
headers: { Authorization: `Bearer ${tokens.access}` },
data: {
prompt: 'test blob',
mode: 'universal',
model: 'seedance_2.0',
aspect_ratio: '16:9',
duration: 5,
references: [
{ url: 'blob:http://localhost/fake', type: 'image', role: 'reference_image', label: 'test' },
],
},
});
expect(genResp.status()).toBe(400);
const body = await genResp.json();
expect(body.error).toBe('upload_failed');
});
test('task detail returns thumbnail_url field', async ({ request }) => {
const loginResp = await request.post(`${API_URL}/api/v1/auth/login`, {
data: { username: USERNAME, password: PASSWORD },
});
const { tokens } = await loginResp.json();
const tasksResp = await request.get(`${API_URL}/api/v1/video/tasks?page_size=1`, {
headers: { Authorization: `Bearer ${tokens.access}` },
});
expect(tasksResp.ok()).toBeTruthy();
const data = await tasksResp.json();
if (data.results.length > 0) {
const task = data.results[0];
expect(task).toHaveProperty('thumbnail_url');
expect(task).toHaveProperty('result_url');
}
});
});
// ─── Frontend Page Tests ───
test.describe('Frontend Page Tests', () => {
test('login page loads', async ({ page }) => {
await page.goto(`${BASE_URL}/login`);
await expect(page).toHaveTitle(/AirDrama|Airflow/i);
});
test('generation page loads after login', async ({ page }) => {
await login(page);
// Should see the input bar
await expect(page.locator('text=人物素材库')).toBeVisible({ timeout: 10000 });
});
test('asset library modal opens', async ({ page }) => {
await login(page);
// Click the asset library button
await page.click('text=人物素材库');
await page.waitForTimeout(1000);
// Should see the modal
await expect(page.locator('text=上传新角色').first()).toBeVisible({ timeout: 5000 });
});
test('create group flow — name only', async ({ page }) => {
await login(page);
await page.click('text=人物素材库');
await page.waitForTimeout(1000);
// Click create
await page.click('text=上传新角色');
await page.waitForTimeout(500);
// Should see name input and "创建角色" button
await expect(page.locator('text=角色名称')).toBeVisible();
await expect(page.locator('text=创建角色')).toBeVisible();
// Should NOT see file upload area
await expect(page.locator('text=创建后可在详情页上传图片、视频、音频素材')).toBeVisible();
});
test('asset detail page shows three sections', async ({ page }) => {
await login(page);
await page.click('text=人物素材库');
await page.waitForTimeout(2000);
// Click on first group with assets (skip the empty test-e2e group)
const groupNames = page.locator('[class*="cardInfo"]');
if (await groupNames.count() > 1) {
await groupNames.nth(1).click();
await page.waitForTimeout(1000);
// Should see three sections
await expect(page.locator('text=肖像（图片）')).toBeVisible({ timeout: 5000 });
await expect(page.locator('text=视频').first()).toBeVisible();
await expect(page.locator('text=音频').first()).toBeVisible();
// Should see warning text
await expect(page.locator('text=宽高 300~6000 像素').first()).toBeVisible();
await expect(page.locator('text=时长 2~15 秒').first()).toBeVisible();
}
});
test('@ mention popup shows individual assets', async ({ page }) => {
await login(page);
// Type @ in the prompt input
const editor = page.locator('[contenteditable="true"]');
await editor.click();
await editor.type('@');
await page.waitForTimeout(500);
// If there are references, popup may show "可能@的内容"
// Type a search query
await editor.type('苏');
await page.waitForTimeout(1000);
// Check if popup appears with asset results
const popup = page.locator('text=人物素材库匹配');
if (await popup.isVisible()) {
// Should show individual asset names, not group names
// Should show type badges (图片/视频/音频)
const typeBadges = page.locator('text=图片, text=视频, text=音频');
// At least one badge should be visible
}
});
test('toast component has glass-card style', async ({ page }) => {
await login(page);
// Trigger a toast by uploading an invalid file format
// Check toast styling includes backdrop-filter
const toastEl = page.locator('[class*="toast"]');
// Toast may not be visible immediately, this is a structural check
});
test('scroll to bottom button appears', async ({ page }) => {
await login(page);
await page.waitForTimeout(2000);
// If there are enough tasks, scroll up
const contentArea = page.locator('[class*="contentArea"]');
if (await contentArea.isVisible()) {
await contentArea.evaluate((el) => el.scrollTop = 0);
await page.waitForTimeout(500);
// Check if "回到底部" button appears
const scrollBtn = page.locator('text=回到底部');
// May or may not appear depending on content height
}
});
test('assets page shows correct order (newest first)', async ({ page }) => {
await login(page);
await page.goto(`${BASE_URL}/assets`);
await page.waitForTimeout(2000);
// First date group should be "今天" or most recent date
const dateLabels = page.locator('h3');
if (await dateLabels.count() > 0) {
const firstLabel = await dateLabels.first().textContent();
// Should be "今天" or a recent date, not an old date
expect(firstLabel).toBeTruthy();
}
});
test('assets page has load more button', async ({ page }) => {
await login(page);
await page.goto(`${BASE_URL}/assets`);
await page.waitForTimeout(2000);
// If there are more than 20 videos, load more should appear
const loadMore = page.locator('text=加载更多');
// Just check it doesn't crash
});
});