Skip to content

利用 AI 大模型和自动化工作流,根据主题或关键词一键生成高清短视频。Generate HD short videos from a topic or keyword with an automated AI workflow.

Add multilingual social metadata API

harry0703c8d6d769ffdc
diff --git a/app/controllers/v1/llm.py b/app/controllers/v1/llm.py
index 177dde88..41f6cfb0 100644
--- a/app/controllers/v1/llm.py
+++ b/app/controllers/v1/llm.py
@@ -4,6 +4,8 @@ from app.controllers.v1.base import new_router
from app.models.schema import (
VideoScriptRequest,
VideoScriptResponse,
+ VideoSocialMetadataRequest,
+ VideoSocialMetadataResponse,
VideoTermsRequest,
VideoTermsResponse,
)
@@ -45,3 +47,20 @@ def generate_video_terms(request: Request, body: VideoTermsRequest):
)
response = {"video_terms": video_terms}
return utils.get_response(200, response)
+
+
+ "/social-metadata",
+ response_model=VideoSocialMetadataResponse,
+ summary="Generate social publishing metadata",
+)
+def generate_video_social_metadata(
+ request: Request, body: VideoSocialMetadataRequest
+):
+ metadata = llm.generate_social_metadata(
+ video_subject=body.video_subject,
+ video_script=body.video_script,
+ language=body.language,
+ platform=body.platform,
+ )
+ return utils.get_response(200, metadata)
diff --git a/app/models/schema.py b/app/models/schema.py
index a57c7f92..eee96618 100644
--- a/app/models/schema.py
+++ b/app/models/schema.py
@@ -178,6 +178,22 @@ class VideoTermsParams:
amount: Optional[int] = 5
+class VideoSocialMetadataParams:
+ """
+ {
+ "video_subject": "A day in Shanghai",
+ "video_script": "",
+ "language": "auto",
+ "platform": "tiktok"
+ }
+ """
+
+ video_subject: Optional[str] = Field(default="A day in Shanghai", max_length=500)
+ video_script: Optional[str] = Field(default="", max_length=8000)
+ language: Optional[str] = Field(default="auto", max_length=64)
+ platform: Optional[str] = Field(default="tiktok", max_length=64)
+
+
class BaseResponse(BaseModel):
status: int = 200
message: Optional[str] = "success"
@@ -200,6 +216,10 @@ class VideoTermsRequest(VideoTermsParams, BaseModel):
pass
+class VideoSocialMetadataRequest(VideoSocialMetadataParams, BaseModel):
+ pass
+
+
######################################################################################################
######################################################################################################
######################################################################################################
@@ -284,6 +304,21 @@ class VideoTermsResponse(BaseResponse):
}
+class VideoSocialMetadataResponse(BaseResponse):
+ class Config:
+ json_schema_extra = {
+ "example": {
+ "status": 200,
+ "message": "success",
+ "data": {
+ "title": "A Day in Shanghai You Should Not Miss",
+ "caption": "Save this quick Shanghai inspiration and follow for more short travel ideas.",
+ "hashtags": ["#shorts", "#travel", "#shanghai", "#viral", "#fyp"],
+ },
+ },
+ }
+
+
class BgmRetrieveResponse(BaseResponse):
class Config:
json_schema_extra = {
diff --git a/app/services/llm.py b/app/services/llm.py
index cbb844ff..2494fd1a 100644
--- a/app/services/llm.py
+++ b/app/services/llm.py
@@ -748,6 +748,272 @@ Please note that you must use English for generating video search terms; Chinese
return search_terms
+# =============================================================================
+# Social publishing metadata
+#
+# 根据视频主题和脚本生成发布到短视频平台时常用的 title、caption 和 hashtags。
+# 这块能力只复用现有 LLM provider,不接入任何外部发布服务,也不影响视频生成主链路。
+# =============================================================================
+
+# 不同平台的文案长度和 hashtag 数量偏好不同。这里使用保守上限,避免模型返回
+# 过长内容后调用方还需要二次裁剪。
+SOCIAL_PLATFORMS = {
+ "tiktok": {"title_max": 100, "caption_max": 2200, "hashtag_count": 5},
+ "youtube_shorts": {"title_max": 100, "caption_max": 5000, "hashtag_count": 3},
+ "instagram_reels": {"title_max": 125, "caption_max": 2200, "hashtag_count": 8},
+ "facebook_reels": {"title_max": 125, "caption_max": 2200, "hashtag_count": 5},
+}
+DEFAULT_SOCIAL_PLATFORM = "tiktok"
+DEFAULT_SOCIAL_LANGUAGE = "auto"
+MAX_SOCIAL_SUBJECT_LENGTH = 500
+MAX_SOCIAL_SCRIPT_LENGTH = 8000
+MAX_SOCIAL_LANGUAGE_LENGTH = 64
+
+SOCIAL_PLATFORM_LABELS = {
+ "tiktok": "TikTok",
+ "youtube_shorts": "YouTube Shorts",
+ "instagram_reels": "Instagram Reels",
+ "facebook_reels": "Facebook Reels",
+}
+
+# LLM 不可用时的通用兜底标签。这里故意不绑定某个国家或语种,保证 API
+# 对中文、英文、越南语等不同场景都能返回可用结构。
+DEFAULT_SOCIAL_HASHTAGS = [
+ "#shorts",
+ "#viral",
+ "#trending",
+ "#fyp",
+ "#video",
+ "#reels",
+ "#creator",
+ "#content",
+]
+
+
+def _resolve_social_platform(platform: str | None) -> str:
+ value = (platform or "").strip().lower()
+ return value if value in SOCIAL_PLATFORMS else DEFAULT_SOCIAL_PLATFORM
+
+
+def _normalize_social_language(language: str | None) -> str:
+ value = (language or DEFAULT_SOCIAL_LANGUAGE).strip()
+ if len(value) > MAX_SOCIAL_LANGUAGE_LENGTH:
+ logger.warning(
+ "social metadata language is too long and will be truncated to "
+ f"{MAX_SOCIAL_LANGUAGE_LENGTH} characters."
+ )
+ value = value[:MAX_SOCIAL_LANGUAGE_LENGTH]
+ return value or DEFAULT_SOCIAL_LANGUAGE
+
+
+def _limit_social_text(text: str | None, max_length: int, field_name: str) -> str:
+ value = (text or "").strip()
+ if len(value) <= max_length:
+ return value
+
+ # API 层会限制长度;这里继续兜底,是为了保护内部调用或未来 WebUI
+ # 直接调用时不会把超长内容发送给模型,避免 token 成本异常。
+ logger.warning(
+ f"{field_name} is too long and will be truncated to {max_length} characters."
+ )
+ return value[:max_length]
+
+
+def _social_language_instruction(language: str | None) -> str:
+ language = _normalize_social_language(language)
+ if language.lower() == DEFAULT_SOCIAL_LANGUAGE:
+ return (
+ "Use the same language as the video subject and script. If the subject "
+ "and script use different languages, prefer the script language."
+ )
+
+ return f'Write "title" and "caption" in this language: {language}.'
+
+
+def _clamp_text(text, max_length: int) -> str:
+ value = ("" if text is None else str(text)).strip()
+ if max_length and len(value) > max_length:
+ return value[:max_length].rstrip()
+ return value
+
+
+def _normalize_hashtags(raw, count: int) -> List[str]:
+ """
+ 将 LLM 返回的 hashtag 统一整理成 `#tag` 格式。
+
+ LLM 可能返回字符串、数组、带空格的词组、重复标签或包含标点的内容。
+ 这里集中清洗,可以让接口响应结构稳定,也避免平台发布时出现空标签、
+ 重复标签或不符合常见格式的 hashtag。
+ """
+ if isinstance(raw, str):
+ candidates = re.split(r"[\s,]+", raw)
+ elif isinstance(raw, (list, tuple)):
+ # 数组里的每一项视为一个完整标签,因此 "du lich" 会变成
+ # "#dulich",而不是拆成两个标签。
+ candidates = [str(entry) for entry in raw]
+ else:
+ candidates = []
+
+ seen = set()
+ result: List[str] = []
+ for item in candidates:
+ tag = re.sub(r"[^\w]", "", item, flags=re.UNICODE)
+ if not tag:
+ continue
+ key = tag.lower()
+ if key in seen:
+ continue
+ seen.add(key)
+ result.append(f"#{tag}")
+ if count and len(result) >= count:
+ break
+ return result
+
+
+def build_social_metadata_prompt(
+ video_subject: str,
+ video_script: str = "",
+ language: str = DEFAULT_SOCIAL_LANGUAGE,
+ platform: str = DEFAULT_SOCIAL_PLATFORM,
+) -> str:
+ video_subject = _limit_social_text(
+ video_subject, MAX_SOCIAL_SUBJECT_LENGTH, "video_subject"
+ )
+ video_script = _limit_social_text(
+ video_script, MAX_SOCIAL_SCRIPT_LENGTH, "video_script"
+ )
+ platform = _resolve_social_platform(platform)
+ spec = SOCIAL_PLATFORMS[platform]
+ label = SOCIAL_PLATFORM_LABELS.get(platform, platform)
+ language_instruction = _social_language_instruction(language)
+
+ prompt = f"""
+# Role: Short-Video Social Media Copywriter
+
+## Goal
+Write engaging publishing metadata for a short video that will be posted on {label}.
+
+## Constraints
+1. Respond ONLY with a single valid minified JSON object. No markdown, no code fences, no commentary.
+2. The JSON must contain exactly these keys: "title", "caption", "hashtags".
+3. "title": a catchy hook, at most {spec['title_max']} characters.
+4. "caption": an engaging description that ends with a call to action, at most {spec['caption_max']} characters. Do not put hashtags inside the caption.
+5. "hashtags": a JSON array of exactly {spec['hashtag_count']} strings. Each must start with "#", contain no spaces, and be relevant to the topic and to {label}.
+6. {language_instruction}
+
+## Output Example
+{{"title":"...","caption":"...","hashtags":["#example","#video"]}}
+
+## Context
+### Video Subject
+{video_subject}
+
+### Video Script
+{video_script}
+""".strip()
+ return prompt
+
+
+def _parse_social_metadata(response: str, platform: str) -> dict:
+ spec = SOCIAL_PLATFORMS[_resolve_social_platform(platform)]
+
+ data = None
+ try:
+ data = json.loads(response)
+ except Exception:
+ # 部分模型会在 JSON 外层包一段说明文字或 markdown fence。
+ # API 调用方只需要稳定结构,所以这里尝试提取第一个 JSON object。
+ match = re.search(r"\{.*\}", response or "", re.DOTALL)
+ if match:
+ data = json.loads(match.group())
+
+ if not isinstance(data, dict):
+ raise ValueError("social metadata response is not a JSON object")
+
+ title = _clamp_text(data.get("title", ""), spec["title_max"])
+ caption = _clamp_text(data.get("caption", ""), spec["caption_max"])
+ hashtags = _normalize_hashtags(data.get("hashtags", []), spec["hashtag_count"])
+
+ if not title and not caption:
+ raise ValueError("social metadata response is missing both title and caption")
+
+ return {"title": title, "caption": caption, "hashtags": hashtags}
+
+
+def _fallback_social_metadata(
+ video_subject: str, video_script: str, platform: str
+) -> dict:
+ spec = SOCIAL_PLATFORMS[_resolve_social_platform(platform)]
+ subject = (video_subject or "").strip()
+ script = (video_script or "").strip()
+
+ title = subject
+ if not title and script:
+ # 没有主题时,用脚本第一句兜底生成 title,避免接口返回空标题。
+ title = re.split(r"(?<=[.!?。!?])\s+", script)[0]
+
+ return {
+ "title": _clamp_text(title, spec["title_max"]),
+ "caption": _clamp_text(script or subject, spec["caption_max"]),
+ "hashtags": _normalize_hashtags(
+ DEFAULT_SOCIAL_HASHTAGS, spec["hashtag_count"]
+ ),
+ }
+
+
+def generate_social_metadata(
+ video_subject: str,
+ video_script: str = "",
+ language: str = DEFAULT_SOCIAL_LANGUAGE,
+ platform: str = DEFAULT_SOCIAL_PLATFORM,
+) -> dict:
+ """
+ 生成短视频发布文案元数据。
+
+ 返回结构固定为 `{"title": str, "caption": str, "hashtags": List[str]}`。
+ 如果 LLM 不可用或返回格式异常,会降级为通用启发式结果,保证 API
+ 调用方始终拿到可展示、可发布前编辑的数据结构。
+ """
+ platform = _resolve_social_platform(platform)
+ language = _normalize_social_language(language)
+ video_subject = _limit_social_text(
+ video_subject, MAX_SOCIAL_SUBJECT_LENGTH, "video_subject"
+ )
+ video_script = _limit_social_text(
+ video_script, MAX_SOCIAL_SCRIPT_LENGTH, "video_script"
+ )
+ prompt = build_social_metadata_prompt(
+ video_subject=video_subject,
+ video_script=video_script,
+ language=language,
+ platform=platform,
+ )
+ logger.info(
+ f"generating social metadata: platform={platform}, language={language}"
+ )
+
+ response = ""
+ for i in range(_max_retries):
+ try:
+ response = _generate_response(prompt)
+ if isinstance(response, str) and "Error: " in response:
+ logger.error(f"failed to generate social metadata: {response}")
+ break
+ metadata = _parse_social_metadata(response, platform)
+ logger.success(f"completed: \n{metadata}")
+ return metadata
+ except Exception as e:
+ logger.warning(f"failed to parse social metadata: {str(e)}")
+
+ if i < _max_retries - 1:
+ logger.warning(
+ f"failed to generate social metadata, trying again... {i + 1}"
+ )
+
+ logger.warning("falling back to heuristic social metadata")
+ return _fallback_social_metadata(video_subject, video_script, platform)
+
+
if __name__ == "__main__":
video_subject = "生命的意义是什么"
script = generate_script(
diff --git a/test/services/test_llm.py b/test/services/test_llm.py
index fa70aa4b..70d5acda 100644
--- a/test/services/test_llm.py
+++ b/test/services/test_llm.py
@@ -11,7 +11,7 @@ from pydantic import ValidationError
sys.path.insert(0, str(Path(__file__).parent.parent.parent))
from app.config import config
-from app.models.schema import VideoScriptRequest
+from app.models.schema import VideoScriptRequest, VideoSocialMetadataRequest
from app.services import llm
@@ -614,6 +614,171 @@ class TestRuntimeEnvironmentDetection(unittest.TestCase):
self.assertEqual(config.get_container_default_gateway_ip(str(route_path)), "")
+class TestSocialMetadata(unittest.TestCase):
+ """通用短视频发布文案元数据生成。"""
+
+ def test_build_prompt_auto_language_uses_source_language(self):
+ """
+ language 默认 auto 时,不应该固定成某个国家或语种,而是让模型
+ 跟随视频主题和脚本的语言,扩大 API 适用范围。
+ """
+ prompt = llm.build_social_metadata_prompt(
+ video_subject="上海一日游",
+ video_script="今天带你快速看完上海经典路线。",
+ language="auto",
+ platform="tiktok",
+ )
+
+ self.assertIn("TikTok", prompt)
+ self.assertIn("Use the same language as the video subject and script", prompt)
+ self.assertIn("上海一日游", prompt)
+ self.assertIn("array of exactly 5 strings", prompt)
+
+ def test_build_prompt_accepts_explicit_language(self):
+ prompt = llm.build_social_metadata_prompt(
+ video_subject="Coffee tips",
+ language="en-US",
+ platform="youtube_shorts",
+ )
+
+ self.assertIn("YouTube Shorts", prompt)
+ self.assertIn('Write "title" and "caption" in this language: en-US', prompt)
+ self.assertIn("array of exactly 3 strings", prompt)
+
+ def test_unknown_platform_falls_back_to_tiktok(self):
+ prompt = llm.build_social_metadata_prompt(
+ video_subject="x",
+ platform="unsupported-platform",
+ )
+
+ self.assertIn("TikTok", prompt)
+
+ def test_normalize_hashtags_from_string_dedupes_and_clamps(self):
+ tags = llm._normalize_hashtags("#fyp fyp, trending #Trending viral", count=2)
+
+ self.assertEqual(tags, ["#fyp", "#trending"])
+
+ def test_normalize_hashtags_from_list_keeps_unicode_letters(self):
+ tags = llm._normalize_hashtags(
+ ["上海 旅行", "#việt nam", " ", "@bad!chars"], count=5
+ )
+
+ self.assertEqual(tags, ["#上海旅行", "#việtnam", "#badchars"])
+
+ def test_parse_social_metadata_recovers_embedded_json(self):
+ raw = 'Sure: {"title":"T","caption":"C","hashtags":["#x"]} thanks'
+ result = llm._parse_social_metadata(raw, "tiktok")
+
+ self.assertEqual(result["title"], "T")
+ self.assertEqual(result["caption"], "C")
+ self.assertEqual(result["hashtags"], ["#x"])
+
+ def test_parse_social_metadata_requires_title_or_caption(self):
+ with self.assertRaises(ValueError):
+ llm._parse_social_metadata('{"hashtags":["#x"]}', "tiktok")
+
+ def test_generate_social_metadata_uses_llm_response(self):
+ payload = (
+ '{"title":"上海一日游","caption":"收藏这条路线,下次直接出发!",'
+ '"hashtags":["#上海","#旅行","#shorts"]}'
+ )
+ with patch.object(llm, "_generate_response", return_value=payload):
+ result = llm.generate_social_metadata(
+ video_subject="上海一日游",
+ video_script="今天带你快速看完上海经典路线。",
+ language="zh-CN",
+ platform="tiktok",
+ )
+
+ self.assertEqual(result["title"], "上海一日游")
+ self.assertEqual(result["caption"], "收藏这条路线,下次直接出发!")
+ self.assertEqual(result["hashtags"], ["#上海", "#旅行", "#shorts"])
+
+ def test_generate_social_metadata_falls_back_to_generic_hashtags(self):
+ with patch.object(
+ llm, "_generate_response", return_value="Error: api_key is not set"
+ ):
+ result = llm.generate_social_metadata(
+ video_subject="Coffee tips",
+ video_script="Save these three coffee tips.",
+ platform="instagram_reels",
+ )
+
+ self.assertEqual(result["title"], "Coffee tips")
+ self.assertEqual(result["caption"], "Save these three coffee tips.")
+ self.assertEqual(len(result["hashtags"]), 8)
+ self.assertEqual(result["hashtags"][0], "#shorts")
+
+ def test_request_model_defaults_to_auto_language_tiktok(self):
+ body = VideoSocialMetadataRequest(video_subject="Test")
+
+ self.assertEqual(body.language, "auto")
+ self.assertEqual(body.platform, "tiktok")
+
+ def test_request_model_rejects_oversized_social_metadata_fields(self):
+ """
+ 外部 API 不能接受无限长的脚本和语言参数,否则会直接放大 LLM
+ token 成本。schema 层先拦截,服务层再做内部调用兜底。
+ """
+ with self.assertRaises(ValidationError):
+ VideoSocialMetadataRequest(video_subject="x" * 501)
+
+ with self.assertRaises(ValidationError):
+ VideoSocialMetadataRequest(video_subject="x", video_script="x" * 8001)
+
+ with self.assertRaises(ValidationError):
+ VideoSocialMetadataRequest(video_subject="x", language="x" * 65)
+
+ def test_build_prompt_clamps_direct_service_inputs(self):
+ prompt = llm.build_social_metadata_prompt(
+ video_subject="x" * 600,
+ video_script="y" * 9000,
+ language="en",
+ )
+
+ self.assertIn("x" * llm.MAX_SOCIAL_SUBJECT_LENGTH, prompt)
+ self.assertNotIn("x" * (llm.MAX_SOCIAL_SUBJECT_LENGTH + 1), prompt)
+ self.assertIn("y" * llm.MAX_SOCIAL_SCRIPT_LENGTH, prompt)
+ self.assertNotIn("y" * (llm.MAX_SOCIAL_SCRIPT_LENGTH + 1), prompt)
+
+ def test_social_metadata_endpoint_response_shape(self):
+ from fastapi.testclient import TestClient
+
+ from app.asgi import app
+
+ request_body = {
+ "video_subject": "Tokyo coffee shops",
+ "video_script": "Three quiet coffee shops for your next Tokyo morning.",
+ "language": "en",
+ "platform": "youtube_shorts",
+ }
+ llm_response = (
+ '{"title":"3 Quiet Tokyo Coffee Shops",'
+ '"caption":"Save these spots for your next Tokyo morning.",'
+ '"hashtags":["#Tokyo","#Coffee","#Shorts"]}'
+ )
+
+ with patch.object(llm, "_generate_response", return_value=llm_response):
+ response = TestClient(app).post(
+ "/api/v1/social-metadata",
+ json=request_body,
+ )
+
+ self.assertEqual(response.status_code, 200)
+ self.assertEqual(
+ response.json(),
+ {
+ "status": 200,
+ "message": "success",
+ "data": {
+ "title": "3 Quiet Tokyo Coffee Shops",
+ "caption": "Save these spots for your next Tokyo morning.",
+ "hashtags": ["#Tokyo", "#Coffee", "#Shorts"],
+ },
+ },
+ )
+
+
FOUNDRY_KEY = os.environ.get("ANTHROPIC_FOUNDRY_API_KEY", "")
FOUNDRY_BASE = "https://amanrai-test-resource.services.ai.azure.com/anthropic"
FOUNDRY_MODEL = "azure_ai/claude-sonnet-4-6"