系统间流程交互图 · 产物中心

🧮 打开厂商模型价格计算器（在线估算） — 依据固定模型配置，复刻产物中心 /estimate 估价接口计价逻辑

营销智能 API 场景目录

将营销内部能力封装为标准 API，在墨斗平台上架，合作商以最少输入获得可直接使用的营销方案。

当前 7 个场景接口

API-01 热点分析查询 → DC 定时沉淀的热点数据API-02 ～ API-05 文本 / 决策结果 → 星驿智能体API-06 ～ API-07 海报 / 视频 → 产物中心

营销中心 · 墨斗集市上架接口定义

营销中心 OpenApiController 对墨斗平台暴露的完整接口清单与参数定义，基础路径 /api/v1。数据来源于 com.mkt.aiMarket.backstage 源码。

POST /api/v1/hotspot/analysis

分页查询热点分析明细。day 为空时自动返回最新有数据的一天。

请求参数（Form / JSON）

字段	类型	必填	说明	可选值 / 约束
`pageNum`	int	否	页码	默认 1
`pageSize`	int	否	每页记录数	默认 10
`day`	string	否	日期	格式 yyyy-MM-dd，空=最新
`platform`	string	否	平台来源	模糊匹配，多值逗号分隔
`hotspotName`	string	否	热点名称	模糊查询
`industryOneName`	string	否	一级行业	模糊查询
`industrySecondName`	string	否	二级行业	模糊查询
`industrySku`	string	否	行业 SKU	模糊查询
`heatLevel`	string	否	搜索热度级别	`低` / `中` / `高`
`scoreLevel`	string	否	热点评分级别	`低` / `中` / `高`
`orderBy`	string	否	排序字段	`HOTSPOT_SCORE` / `HEAT_VALUE_NORM` / `CREATED_AT`（默认）
`orderDirection`	string	否	排序方向	`asc` / `desc`（默认）

响应：R<Page<AimktHotspotAnalysisVo>> — 分页返回，每条含 platform、hotspotName、hotspotScore、heatValueNorm、industryOneName、industrySecondName、industrySku、suggestedAction、seoRecommendations 等字段。

POST /api/v1/pricing

给出建议售价区间与定价依据。

请求体（JSON）

字段	类型	必填	说明	约束
`industry`	string	是	行业类型	如"奶茶/饮品"
`city`	string	否	城市（市级）	—
`district`	string	否	区域（区县级）	—
`merchantName`	string	否	商户名称	—
`festival`	string	否	节日名称	如"端午节"
`skus`	array	是	SKU 列表	1~30 个
skus[] 子对象：
`skus[].name`	string	是	SKU 名称	—
`skus[].cost`	double	是	单品综合成本价	> 0
`skus[].currentPrice`	double	否	当前售价	> 0，且 > cost

响应：R<ApiPricingVo> — 含 pricingPlan[]（每个 SKU 的 economyPrice / standardPrice / premiumPrice / profitRateStandard）、festivalPremium 节日溢价倍数、anchorPrice 建议锚定价格、recommendation 建议总结。

POST /api/v1/stock

输出行业热销品选品建议。

请求体（JSON）

字段	类型	必填	说明	约束
`industry`	string	是	行业	如"奶茶/饮品"、"中餐"
`merchantName`	string	否	商户名称	—
`merchantHotProducts`	string[]	否	商户已验证热销品	保持推荐方向一致
`targetCustomer`	string	否	目标客群	如"学生"、"白领"
`avgCustomerPrice`	decimal	否	近30天客单价	约束建议售价带
`investmentBudget`	decimal	否	试销/进货预算	推荐规模约束
`city`	string	否	城市	—
`season`	string	否	季节	春季/夏季/秋季/冬季
`festival`	string	否	节假日	如"端午节"、"春节"
`maxSkus`	long	否	返回热销品最大数量	1~20，默认 10

响应：R<ApiStockVo> — 含 hotSkus[]（skuName / category / hotScore / costRange / priceRange / festivalBoost）、industryMetrics（行业平均客单价/成本率/毛利率）、seasonalFocus（推荐品类 + 节日主推）、recommendationSummary。

POST /api/v1/stock/suggest

给定候选 SKU 和预算，输出建议备货数量与预估 ROI。

请求体（JSON）

字段	类型	必填	说明	约束
`industry`	string	是	行业名称	—
`merchantName`	string	否	商户名称	—
`investmentBudget`	double	是	备货总预算（元）	> 0
`festival`	string	否	即将到来的节日	—
`candidateSkus`	array	是	候选 SKU 列表	1~20 个
candidateSkus[] 子对象：
`name`	string	是	SKU 名称	—
`category`	string	是	SKU 品类	—
`cost`	double	是	成本价（元）	> 0
`suggestedPrice`	double	是	建议售价（元）	> 0，且 > cost
`heatScore`	string	是	热度评分	`高` / `中` / `低`
`selfClaimedHot`	string[]	否	商户自报热销品	—
`targetMargin`	double	否	目标毛利率	0.01~1.0，默认 0.30

响应：R<ApiStockSuggestionVo> — 含 recommendedSkus[]（skuName / category / qty / unitCost / totalCost / unitPrice / estimatedRevenue / margin）、totalInvestment、estimatedRevenue、estimatedRoi。

POST /api/v1/bundle

生成套餐组合、定价与销售卖点。

请求体（JSON）

字段	类型	必填	说明	约束
`industry`	string	是	行业名称	—
`merchantName`	string	否	商户名称	—
`targetCustomer`	string	否	目标客群	young_white_collar / family / student / other
`festival`	string	否	节日名称	有则优先节日主题套餐
`pricedSkus`	array	是	已定价 SKU 列表	—
pricedSkus[] 子对象：
`name`	string	是	SKU 名称	—
`category`	string	否	SKU 品类	—
`price`	double	是	售价（元）	> 0
`cost`	double	否	成本价（元）	> 0，且 price > cost

响应：R<ApiBundleVo> — 含 bundles[]（最多 5 个套餐，每个含 bundleName / sceneTag / skus[] / originalTotal / bundlePrice / discountRate / grossMarginRatio / sellingPoints[] / timeSlots[] / confidence）、gmvUpliftEstimate。

POST /api/v1/marketing/copy

按节日和商品生成多渠道营销文案。

请求体（JSON）

字段	类型	必填	说明	约束
`festival`	string	是	节日名称	—
`industry`	string	是	所属行业	—
`theme`	string	否	营销主题	未传由模型生成
`merchantName`	string	否	商户名称	—
`sellingPoints`	string[]	否	卖点列表	过滤空值后取前 3 个
`platforms`	string[]	否	目标平台列表	默认 xiaohongshu / douyin / wechat

响应：R<ApiFestivalCopyVo> — 含 contents（按平台分组的文案 Map）、hashtags[]（推荐话题标签）。顶层额外返回 total_tokens。

POST /api/v1/marketing/poster 新需求：多模型可选

异步生成节日营销海报，返回本地任务 ID。支持指定生图模型。

请求体（JSON）

字段	类型	必填	说明	约束
`festival`	string	是	节日名称	—
`industry`	string	是	所属行业	—
`merchantName`	string	否	商户名称	—
`theme`	string	否	海报主题	—
`promotedSku`	string	否	主推产品名称	—
`sellingPoints`	string[]	否	卖点列表	过滤空值后取前 3 个
`style`	string	否	图片风格	未传默认"写实风"
`customContent`	string	否	用户自定义要求	补充主体/场景/构图/配色/避免内容
`size`	string	否	图片比例	`9:16` / `2:3` / `3:4` / `1:1` / `4:3` / `3:2` / `16:9`，默认 1:1
`count`	int	否	生成海报数量	1~5，默认 3
`modelId`	string	否	生图模型 ID	空=默认 `wan2.7-image-pro`；可选见「产物中心 · 生图参数」
`callbackUrl`	string	否	完成/失败通知地址	—

响应：R<ApiGenerationTaskSubmitVo> — 含 taskId、status（PENDING）。
新增 modelId（实际使用的模型）、estimatedCost（预估成本，元，由产物中心 /estimate 返回）。
通过 任务查询 接口轮询结果。

POST /api/v1/marketing/video 新需求：多模型可选

异步生成节日营销短视频，返回本地任务 ID。支持指定生视频模型。

请求体（JSON）

字段	类型	必填	说明	约束
`festival`	string	是	节日名称	—
`industry`	string	是	所属行业	—
`merchantName`	string	否	商户名称	—
`promotedSku`	string	否	主推产品名称	—
`sellingPoints`	string[]	否	卖点列表	过滤空值后取前 3 个
`videoDuration`	int	否	视频时长（秒）	范围取决于 modelId，默认 5；DTO 放宽 2~30，service 层按模型校验
`videoRatio`	string	否	视频比例	`9:16` / `3:4` / `1:1` / `4:3` / `16:9`，默认 9:16
`style`	string	否	视频风格	开放文本，默认"写实风"
`customContent`	string	否	用户自定义要求	补充主体/场景/运镜/节奏/避免内容
`modelId`	string	否	生视频模型 ID	空=默认 `wan30-video`；可选见「产物中心 · 生视频参数」
`callbackUrl`	string	否	完成/失败通知地址	—

GET /api/v1/marketing/tasks/{taskId}

查询海报或视频异步生成任务的结果。

路径参数

字段	类型	必填	说明
`taskId`	string	是	提交海报/视频接口返回的任务 ID

响应：R<ApiGenerationTaskVo> — 含 taskId、taskType（POSTER/VIDEO）、status（PENDING/RUNNING/SUCCESS/FAILED）、fileList[]（url / expireDate / totalTokens）、errorMessage、callbackStatus（NONE/PENDING/SUCCESS/FAILED）、createdAt、updatedAt。顶层额外汇总 total_tokens。
新增
顶层：modelId（实际使用的模型）、totalCost（实际总成本，元，产物中心统一换算后返回）
fileList[] 每项新增：modelId（该文件使用的模型）、cost（该文件成本，元）

产物中心 · 生图 / 生视频参数定义

API-06 / API-07 经产物中心提交生成请求，以下列出模型 ID 可选项、请求参数结构与取值范围，供墨斗集市营销 API 上架对接参考。

modelId	模型名称	厂商	分辨率	能力	单次上限	单价(元)
wan2.7-image-pro	万象 2.7 图片 Pro	DashScope	1K / 2K / 4K	文生图图生图组图	4 张	0.20~0.40/张
wan2.7-image	万象 2.7 图片	DashScope	1K / 2K	文生图图生图组图	4 张	0.20/张
qwen-image-3.0	通义万相 3.0	DashScope	1K / 2K	文生图图生图组图	6 张	0.18/张 + 输入图0.02
kling-v3-image	可灵 V3 图片	DashScope	1K / 2K	文生图图生图	9 张	0.20/张
kling-v3-omni-image	可灵 V3 图片 Pro	DashScope	1K / 2K / 4K	文生图图生图	9 张	0.20~0.40/张
doubao-seedream-5-0-pro-260628	Seedream 5.0 Pro	VolcEngine	2K	文生图	单张	0.30/张
doubao-seedream-5-0-260128	Seedream 5.0 Lite	VolcEngine	2K	文生图组图(auto)	15 张	0.22/张

imageParams 参数定义

字段	类型	必填	说明	可选值 / 范围
`mode`	string	否	生成模式。`auto` 触发组图模式，模型自主决策或按 `maxImages` 上限生成多张	空（默认单张）/ `auto`
`maxImages`	int	否	组图模式下限张数，各模型上限不同（见上表）	1 ~ 模型上限
`resolution`	string	否	输出分辨率档位，缺失时走模型默认	`1k` / `2k` / `4k`（按模型支持）
`negativePrompt`	string	否	反向提示词，描述不希望出现的内容	自由文本

materials 素材定义（图片场景）

type	字段	必填	说明
`text`	`text`	是	提示词（Prompt），描述期望生成的图片内容
`image_url`	`url`	否	参考图片 URL（图生图场景），支持 OSS 签名地址

modelId	模型名称	厂商	分辨率	时长(秒)	能力	计费	参考单价
kling-v3-video	可灵 V3 视频	DashScope	720p / 1080p / 4K	3~15	文生视频图生视频音频档	amount	0.60~3.00/秒
kling-v3-omni-video	可灵 V3 视频 Pro	DashScope	720p / 1080p / 4K	3~15	文生视频图生视频标准档	amount	0.60~3.00/秒
wan30-video	万象 3.0 视频	DashScope	480p / 720p / 1080p	2~30	文生视频图生视频	amount	0.30~1.20/秒
doubao-seedance-2-0	Seedance 2.0	VolcEngine	480p / 720p / 1080p / 4K	4~30	文生视频图生视频Token	token	16~51 元/百万token
doubao-seedance-2-5	Seedance 2.5	VolcEngine	480p / 720p / 1080p	4~30	文生视频图生视频Token	token	42~77 元/百万token

videoParams 参数定义

字段	类型	必填	说明	可选值 / 范围
`resolution`	string	否	输出分辨率档位，缺失时走模型默认	`480p` / `720p` / `1080p` / `4k`（按模型支持）
`duration`	int	否	输出视频时长（秒），各模型范围不同	2~30（按模型范围）
`ratio`	string	否	视频比例，仅火山 Seedance 系列支持	`adaptive` / `16:9` / `9:16` / `1:1` / `4:3` / `3:4` / `21:9`
`audio`	boolean	否	是否生成音频轨道（仅可灵 V3 视频支持）	`true` / `false`（默认 false）
`referenceVideoUrl`	string	否	参考视频 URL（图生视频 / 视频转视频场景）	OSS 签名地址
`referenceVideoDuration`	int	否	参考视频时长（秒），火山 Token 计费时使用	1~120

materials 素材定义（视频场景）

type	字段	必填	说明
`text`	`text`	是	提示词（Prompt），描述期望生成的视频内容或脚本
`image_url`	`url`	否	首帧图片 URL（图生视频场景）
`video_url`	`url`	否	参考视频 URL（视频转视频场景）

POST /api/artifact/submit · 请求体结构

{ // 产物生成提交请求 "requestId": "biz_order_001", // 业务请求ID，幂等键 "source": "moke", // 调用来源：moke / marketing "userId": "user_123", // 终端用户标识 "modelId": "wan2.7-image-pro", // 模型ID（见上表可选项） "artifact": { "type": "image", // 产物类型：image / video "materials": [ { "type": "text", "text": "节日促销海报，红色主色调，雪花飘落" }, { "type": "image_url", "url": "https://oss.../ref.png" } // 可选，图生图/视频 ], "imageParams": { // type=image 时使用 "mode": "auto", // 组图模式 "maxImages": 4, // 组图上限 "resolution": "2k" // 分辨率档位 }, "videoParams": { // type=video 时使用 "resolution": "1080p", "duration": 10, "ratio": "9:16", // 仅火山 Seedance 支持 "audio": true // 仅可灵 V3 视频支持 } } }

POST /api/artifact/detail · 响应结构

{ // 产物详情查询响应 "taskId": "gen_f6a3c1efca58498c8b099904d3a5f25a", "status": "SUCCEEDED", // PENDING / PROCESSING / SUCCEEDED / FAILED "modelId": "wan2.7-image-pro", "artifacts": [ { "url": "https://oss.../art_xxx.png", "width": 2048, "height": 2048, "format": "PNG" } ], "cost": { // 厂商成本（产物中心统一换算为元） "amount": 0.80, "currency": "CNY" } }

modelId 选择决策树

场景	推荐 modelId	理由
营销海报（高质量）	`wan2.7-image-pro`	DashScope 默认图片模型，4K 支持，组图能力，性价比优
营销海报（批量/低成本）	`wan2.7-image`	固定 0.20 元/张，支持组图，适合大量铺货
创意海报（多风格）	`qwen-image-3.0`	支持最多 6 张组图 + 输入图参考，灵活度高
高精度产品图	`kling-v3-omni-image`	4K 分辨率 + 可灵画质，适合产品特写
短视频（成本可控）	`wan30-video`	amount 计费直观，最长 30 秒，480p 低至 0.30/秒
短视频（高质量）	`kling-v3-omni-video`	4K + 标准档有声，画质与音频兼优
短视频（竖屏/多比例）	`doubao-seedance-2-5`	支持 7 种比例（含 9:16 竖屏），适合抖音/快手

当前产物中心已具备的能力与约束：

模型路由：产物中心通过 agent-models.yml 配置化注册模型，新增模型只需添加 YAML 条目，无需改代码。
协议统一：对外统一使用 modelId（厂商模型名称），DTO/VO/Registry 已去除内部 modelCode 编码。
双厂商适配：DashScope（阿里云百炼）和 VolcEngine（火山方舟）适配器均已上线，支持 messages 协议。
计费透明：所有模型成本统一换算为「元(CNY)」返回，amount 和 token 两种计费维度对上游透明。
估价接口：/estimate 已上线，可在提交前预估成本，便于墨斗套餐扣减决策。
异步任务：图片同步出图（~60s），视频异步轮询（POST /submit → GET /detail）。

墨斗集市 API 上架对接要点：

API-06（海报）：营销系统接收墨斗请求 → 组装 materials + imageParams → 调用产物中心 /submit → 轮询 /detail → 返回海报结果。
API-07（视频）：同上，使用 videoParams，注意视频为异步任务，需处理 PENDING/PROCESSING 中间态。
modelId 透传：墨斗 PRD 中可定义默认 modelId（如 wan2.7-image-pro），也支持合作商指定可选 modelId 透传至产物中心。
套餐计费：先调 /estimate 获取预估成本 → 墨斗套餐扣减 → 再调 /submit 实际生成。

已知约束与风险：

模型权限：部分模型（如 wan2.6-t2i、qwen-image-3.0-pro）需在百炼控制台单独开通 API Key 权限。
组图差异：DashScope 组图为固定数量（enable_sequential=true），火山 Seedream Lite 为 auto 模式（模型自主决策），行为不一致需在 PRD 中明确。
视频时长：可灵系列上限 15 秒，万象 3.0 和 Seedance 支持到 30 秒；超长视频需拼接方案。
火山 Token 计费：Seedance 系列按 token 计费，金额与分辨率×比例×时长强相关，竖屏（9:16）比横屏成本高约 78%。
内容安全：VolcEngine 内容安全过滤器可能拦截含敏感符号的提示词，需在营销系统侧做前置审核或错误包装。