@hubfluencer/mcp 0.2.0 → 0.3.0

package/dist/index.js

@@ -29822,6 +29822,14 @@ async function uploadImageFile(client, presignPath, filePath, maxBytes = MAX_IMA
   await putToPresignedUrl(presigned_url, buf, file.mime);
   return { s3_key };
 }
+async function uploadShortPoster(client, slug, filePath) {
+  const file = await resolveReadPath(filePath, IMAGE_EXT_MIME, MAX_IMAGE_BYTES);
+  const presign = await client.post(`/shorts/${slug}/poster/presign`, { content_type: file.mime });
+  const { upload_url, s3_key } = presign;
+  const buf = await readFile(file.path);
+  await putToPresignedUrl(upload_url, buf, file.mime);
+  return { s3_key };
+}
 
 // src/index.ts
 async function fetchStatus(client, kind, slug) {
@@ -29968,7 +29976,7 @@ var WRITE = {
   destructiveHint: false,
   openWorldHint: true
 };
-var server = new McpServer({ name: "hubfluencer", version: "0.2.0" });
+var server = new McpServer({ name: "hubfluencer", version: "0.3.0" });
 var registerTool = server.registerTool.bind(server);
 async function pollToTerminal(client, kind, slug, extra, budgetMs, intervalMs) {
   const deadline = Date.now() + budgetMs;
@@ -30009,13 +30017,17 @@ async function pollSegmentToTerminal(client, slug, segmentId, extra, budgetMs, i
 }
 registerTool("make_video", {
   title: "Make a video from a prompt (one shot)",
-  description: "The simplest path: give a prompt, get a finished MP4. Creates the project (free), PRICES it against " + "your live credit balance, then — only if it's affordable and within max_credits — starts generation, " + "polls to completion (emitting progress), and (if save_path is given) downloads the result. " + "Spends credits (15 for a short; a multi-scene editor ad ~28). Pass dry_run:true to preview the cost " + "WITHOUT charging (returns {estimated_credits, available_credits, slug}); pass max_credits to cap the " + "spend. kind defaults to 'auto' — a multi-scene editor ad for ad/promo/story briefs, a single-clip short " + "for simple/short ones; the chosen kind is reported back as kind_inferred. If it returns terminal=false " + "the render is still running — call wait_for_completion with the returned slug to finish.",
+  description: "The simplest path: give a prompt, get a finished MP4. Creates the project (free), PRICES it against " + "your live credit balance, then — only if it's affordable and within max_credits — starts generation, " + "polls to completion (emitting progress), and (if save_path is given) downloads the result. " + "Spends credits (15 for a short; a multi-scene editor ad ~28). Pass dry_run:true to preview the cost " + "WITHOUT charging (returns {estimated_credits, available_credits, slug}); pass max_credits to cap the " + "spend. kind defaults to 'auto' — a multi-scene editor ad for ad/promo/story briefs, a single-clip short " + "for simple/short ones; the chosen kind is reported back as kind_inferred. If it returns terminal=false " + "the render is still running — call wait_for_completion with the returned slug to finish. " + "BE PROACTIVE WITH BRANDING: pass headline (the on-screen TITLE) and subheadline (secondary title) plus " + "music_vibe/theme so a one-shot short isn't bare — these apply to SHORTS (music_vibe/headline/subheadline " + "are ignored for editor; theme applies to both). For richer branding — a product image, brand logo, or " + "closing card — drive the granular path instead: create_short + set_short_product/set_short_poster, or " + "create_editor_draft + set_product/set_logo/set_closing_image, then start_autopilot/generate_short.",
   inputSchema: {
     prompt: exports_external.string().describe("What the ad/video should be about (min 10 chars)"),
     kind: exports_external.string().optional().describe("'short' (fast, 1 clip), 'editor' (multi-scene), or 'auto' (default — inferred)"),
     language: exports_external.string().optional().describe('Language code, e.g. "en" (default)'),
     aspect: exports_external.string().optional().describe("Aspect ratio for editor: 9:16 (default), 16:9, or 1:1"),
     voice_id: exports_external.string().optional().describe("Preferred narration voice id for editor ads (see list_voices); shorts have no voiceover"),
+    headline: exports_external.string().optional().describe("SHORTS only: the on-screen TITLE overlay (≤160). Set this so the short isn't bare."),
+    subheadline: exports_external.string().optional().describe("SHORTS only: the secondary title / supporting line (≤200)"),
+    music_vibe: exports_external.string().optional().describe("SHORTS only: music mood — Upbeat (default), Cinematic, Minimal, Luxury, Playful, Jazz"),
+    theme: exports_external.string().optional().describe("Visual theme (both kinds): none (literal — no imposed style), realistic (default), cinematic, " + "anime, sci_fi, fantasy, noir, superhero, horror, mockumentary, sports, gaming, retro_80s, " + "minimalist, cyberpunk"),
     save_path: exports_external.string().optional().describe("Optional .mp4 path to download to (confined to HUBFLUENCER_OUTPUT_DIR or cwd)"),
     max_wait_seconds: exports_external.number().optional().describe("Block budget seconds (default 240, capped 10–280)"),
     dry_run: exports_external.boolean().optional().describe("Preview only: create a free draft, price it, and STOP before spending credits. " + "Returns {estimated_credits, available_credits, slug}. Resume with generate_short / start_autopilot."),
@@ -30034,15 +30046,23 @@ registerTool("make_video", {
     resolveSavePath(args.save_path);
   let slug;
   if (kind === "short") {
-    const created = await client.post("/shorts", { product_prompt: args.prompt, language: args.language }, idemKey("make-short", args.prompt, args.language ?? ""));
+    const created = await client.post("/shorts", {
+      product_prompt: args.prompt,
+      language: args.language,
+      headline: args.headline,
+      subheadline: args.subheadline,
+      music_vibe: args.music_vibe,
+      theme: args.theme
+    }, idemKey("make-short", args.prompt, args.language ?? "", args.headline ?? "", args.subheadline ?? "", args.music_vibe ?? "", args.theme ?? ""));
     slug = created.data.slug;
   } else {
     const created = await client.post("/editor", {
       language: args.language ?? "en",
       product_prompt: args.prompt,
       export_aspect_ratio: args.aspect,
-      voice_id: args.voice_id
-    }, idemKey("make-editor", args.prompt, args.language ?? "en", args.aspect ?? "", args.voice_id ?? ""));
+      voice_id: args.voice_id,
+      theme: args.theme
+    }, idemKey("make-editor", args.prompt, args.language ?? "en", args.aspect ?? "", args.voice_id ?? "", args.theme ?? ""));
     slug = created.data.slug;
   }
   const costPath = kind === "short" ? `/shorts/${slug}/cost` : `/editor/${slug}/autopilot/cost`;
@@ -30101,7 +30121,17 @@ registerTool("get_credits", {
   description: "Returns the authenticated account's credit balance. A short costs 15 credits.",
   inputSchema: {},
   annotations: { title: "Get credits", ...RO }
-}, tool(async (_args, client) => ok(await client.get("/studio/credits"))));
+}, tool(async (_args, client) => {
+  const res = await client.get("/studio/credits");
+  const d = asRecord(asRecord(res).data);
+  return ok({
+    credits: d.credits,
+    spendable_credits: d.spendable_credits,
+    reserved_credits: d.reserved_credits,
+    remaining_reserved_credits: d.remaining_reserved_credits,
+    message: d.message
+  });
+}));
 registerTool("list_voices", {
   title: "List voices",
   description: "Lists available narration voices (id + name). Pass a voice id as voice_id to create_editor_ad / " + "make_video to pick the narration voice for an editor ad. Shorts have no voiceover.",
@@ -30141,19 +30171,48 @@ registerTool("list_projects", {
 }));
 registerTool("create_short", {
   title: "Create a short (draft)",
-  description: "Creates a short draft from a product prompt (min 10 chars). Returns the slug. Costs 0 credits. " + "Follow with generate_short to render. Prefer make_video for the one-shot path.",
+  description: "Creates a short draft from a product prompt (min 10 chars). A short is a 12s vertical (two 6s AI " + "segments + an on-screen title overlay + music; 14s when an end-card poster is set). Returns the slug, " + "costs 0 credits. Follow with generate_short to render. " + "BE PROACTIVE: don't ship a bare clip — set a headline (the on-screen TITLE) and subheadline (secondary " + "title), and pick a music_vibe and theme that fit the brand. To brand it further, attach a product image " + "(set_short_product) or an end-card poster (set_short_poster) before generate_short. (Shorts have no logo " + "overlay — that's an editor-only feature; use create_editor_ad for logo branding.)",
   inputSchema: {
     product_prompt: exports_external.string().min(10).describe("What the short should be about"),
     language: exports_external.string().optional().describe('Language code, e.g. "en" (default)'),
-    theme: exports_external.string().optional(),
-    headline: exports_external.string().optional(),
-    subheadline: exports_external.string().optional(),
-    music_vibe: exports_external.string().optional()
+    headline: exports_external.string().max(160).optional().describe("The on-screen TITLE composited over the short (poster text overlay). ≤160 chars. Set this."),
+    subheadline: exports_external.string().max(200).optional().describe("The SECONDARY title / supporting line under the headline. ≤200 chars."),
+    theme: exports_external.string().optional().describe("Visual theme (default realistic). One of: none (no imposed style — follows the prompt literally), " + "realistic, cinematic, anime, sci_fi, fantasy, noir, superhero, horror, mockumentary, sports, " + "gaming, retro_80s, minimalist, cyberpunk."),
+    music_vibe: exports_external.string().optional().describe("Background-music mood. Recognized: Upbeat (default), Cinematic, Minimal, Luxury, Playful, Jazz."),
+    music_instruments: exports_external.array(exports_external.string()).optional().describe('Optional instrument hints, e.g. ["piano", "strings"]'),
+    text_position: exports_external.enum(["top", "center", "bottom"]).optional().describe("Where the title overlay sits (default bottom)"),
+    text_animation: exports_external.enum(["reveal", "typewriter", "fade_in", "pop", "bounce"]).optional().describe("Title overlay animation (default fade_in)"),
+    font_family: exports_external.string().optional().describe("Overlay font (default ShortFontSpaceGrotesk). One of: ShortFontSpaceGrotesk, ShortFontMontserrat, " + "ShortFontTheBold, ShortFontImpact, ShortFontLato, ShortFontProximaNova, ShortFontAnton, " + "ShortFontBebasNeue, ShortFontOswald, ShortFontArchivoBlack, ShortFontPoppins, ShortFontInter, " + "ShortFontTikTokSans, ShortFontBangers.")
   },
   annotations: { title: "Create short", ...WRITE, idempotentHint: true }
 }, tool(async (args, client) => {
-  const res = await client.post("/shorts", args, idemKey("create-short", String(args.product_prompt ?? "")));
-  return ok({ slug: res.data.slug, kind: "short", next: "generate_short" });
+  const body = {
+    product_prompt: args.product_prompt
+  };
+  if (args.language !== undefined)
+    body.language = args.language;
+  if (args.headline !== undefined)
+    body.headline = args.headline;
+  if (args.subheadline !== undefined)
+    body.subheadline = args.subheadline;
+  if (args.theme !== undefined)
+    body.theme = args.theme;
+  if (args.music_vibe !== undefined)
+    body.music_vibe = args.music_vibe;
+  if (args.music_instruments !== undefined)
+    body.music_instruments = args.music_instruments;
+  if (args.text_position !== undefined)
+    body.short_text_position = args.text_position;
+  if (args.text_animation !== undefined)
+    body.short_text_animation = args.text_animation;
+  if (args.font_family !== undefined)
+    body.short_font_family = args.font_family;
+  const res = await client.post("/shorts", body, idemKey("create-short", args.product_prompt, args.language ?? "", args.headline ?? "", args.subheadline ?? ""));
+  return ok({
+    slug: res.data.slug,
+    kind: "short",
+    next: "set_short_product / set_short_poster (optional branding), then generate_short"
+  });
 }));
 registerTool("generate_short", {
   title: "Generate (render) a short",
@@ -30167,11 +30226,11 @@ registerTool("generate_short", {
 }));
 registerTool("create_editor_ad", {
   title: "Create a multi-scene editor ad (autopilot)",
-  description: "Creates an editor project from a product prompt and starts autopilot (server-orchestrated " + "scenario → segments → narration → voice → music → render). Each AI-generated scene is a fixed 8 seconds. " + "Returns the slug. Costs credits. Then poll with get_status / wait_for_completion (kind=editor). Prefer " + "make_video for the one-shot path.",
+  description: "Creates an editor project from a product prompt and starts autopilot (server-orchestrated " + "scenario → segments → narration → voice → music → render). Each AI-generated scene is a fixed 8 seconds. " + "Returns the slug. Costs credits. Then poll with get_status / wait_for_completion (kind=editor). Prefer " + "make_video for the one-shot path. " + "BRANDING: to attach the user's own product image, brand logo, or closing card, create the draft with " + "create_editor_draft first, call set_product / set_logo / set_closing_image (all 0 credits), then " + "start_autopilot — autopilot weaves them in. (Editor ads carry their copy in-scene/narration, not as a " + "title overlay; for an on-screen title/subtitle use a short with headline/subheadline instead.)",
   inputSchema: {
     product_prompt: exports_external.string().min(10).describe("Brief for the ad (min 10 chars)"),
     language: exports_external.string().optional().describe('Language code, e.g. "en" (default)'),
-    theme: exports_external.string().optional().describe('Visual theme (default "realistic")'),
+    theme: exports_external.string().optional().describe('Visual theme (default "realistic"). One of: none (no imposed style — segments follow your prompts literally), realistic, cinematic, anime, sci_fi, fantasy, noir, superhero, horror, mockumentary, sports, gaming, retro_80s, minimalist, cyberpunk.'),
     voice_id: exports_external.string().optional().describe("Preferred narration voice id (see list_voices); omit for the default voice"),
     export_aspect_ratio: exports_external.enum(["9:16", "16:9", "1:1"]).optional().describe('Aspect ratio (default "9:16")')
   },
@@ -30226,7 +30285,7 @@ registerTool("create_editor_draft", {
   inputSchema: {
     product_prompt: exports_external.string().min(10).max(5000).optional().describe("Brief for the ad — 10–5000 chars, or omit entirely"),
     language: exports_external.string().min(2).max(10).optional().describe('Language code, e.g. "en" (default)'),
-    theme: exports_external.string().optional().describe('Visual theme (default "realistic")'),
+    theme: exports_external.string().optional().describe('Visual theme (default "realistic"). One of: none (no imposed style — segments follow your prompts literally), realistic, cinematic, anime, sci_fi, fantasy, noir, superhero, horror, mockumentary, sports, gaming, retro_80s, minimalist, cyberpunk.'),
     voice_id: exports_external.string().regex(/^[A-Za-z0-9_-]+$/).max(64).optional().describe("Preferred narration voice id (see list_voices); ≤64 chars, [A-Za-z0-9_-] only"),
     export_aspect_ratio: exports_external.enum(["9:16", "16:9", "1:1"]).optional().describe('Aspect ratio (default "9:16")'),
     project_intent: exports_external.enum(["social_ad", "creative_story"]).optional().describe("Project intent (optional)")
@@ -30798,6 +30857,37 @@ registerTool("set_logo", {
   }
   return ok(result);
 }));
+registerTool("set_short_product", {
+  title: "Attach a product image to a short (0 credits)",
+  description: "Uploads a local product image and attaches it to a SHORT so the product is woven into the footage. " + "Accepted: " + IMAGE_EXTS.map((e) => `.${e}`).join(", ") + " (≤20 MB), local path confined to HUBFLUENCER_INPUT_DIR (or cwd). 0 credits. Optional description " + "(≤500 chars) guides how it's featured. Attach BEFORE generate_short so the product is part of the scenes. " + "(This is the shorts equivalent of set_product for editor projects.)",
+  inputSchema: {
+    slug: exports_external.string().describe("Short slug (from create_short)"),
+    file_path: exports_external.string().describe("Local product image path (.jpg/.jpeg/.png)"),
+    description: exports_external.string().max(500).optional().describe("Product description (≤500 chars)")
+  },
+  annotations: {
+    title: "Set short product",
+    ...WRITE,
+    idempotentHint: false
+  }
+}, tool(async (args, client) => {
+  const { s3_key } = await uploadImageFile(client, `/shorts/${args.slug}/product/presign`, args.file_path);
+  const res = await client.post(`/shorts/${args.slug}/product/confirm`, { s3_key, product_description: args.description });
+  return ok(asRecord(res).data ?? res);
+}));
+registerTool("set_short_poster", {
+  title: "Set a short's end-card poster image (0 credits)",
+  description: "Uploads a local image as the SHORT's end-card poster — a closing still shown at the end (extends the " + "render from 12s to 14s). Accepted: " + IMAGE_EXTS.map((e) => `.${e}`).join(", ") + " (≤20 MB), confined to HUBFLUENCER_INPUT_DIR/cwd. 0 credits. There is one poster per short; calling " + "again replaces it. (Shorts have no logo overlay — for a brand logo use an editor project + set_logo.)",
+  inputSchema: {
+    slug: exports_external.string().describe("Short slug (from create_short)"),
+    file_path: exports_external.string().describe("Local poster image (.jpg/.jpeg/.png)")
+  },
+  annotations: { title: "Set short poster", ...WRITE, idempotentHint: false }
+}, tool(async (args, client) => {
+  const { s3_key } = await uploadShortPoster(client, args.slug, args.file_path);
+  const res = await client.post(`/shorts/${args.slug}/poster/confirm`, { s3_key });
+  return ok(asRecord(res).data ?? res);
+}));
 registerTool("get_status", {
   title: "Get generation status",
   description: "Returns a normalized status {stage, terminal, ready, video_url, error} for a short or editor " + "project. ready:true means the post-ready MP4 is at video_url.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hubfluencer/mcp",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Model Context Protocol server for Hubfluencer — let AI agents generate post-ready shorts and editor ads.",
   "license": "MIT",
   "author": "Monocursive <contact@monocursive.com>",

package/src/index.ts

@@ -39,6 +39,7 @@ import { runLogin } from "./login.js";
 import {
 	IMAGE_EXTS,
 	uploadImageFile,
+	uploadShortPoster,
 	uploadVideoFile,
 	VIDEO_EXTS,
 } from "./uploads.js";
@@ -323,7 +324,7 @@ const WRITE = {
 	openWorldHint: true,
 };
 
-const server = new McpServer({ name: "hubfluencer", version: "0.2.0" });
+const server = new McpServer({ name: "hubfluencer", version: "0.3.0" });
 
 // The SDK's `registerTool` is generic over the Zod input shape; with this many
 // tools its conditional types hit TS2589 ("excessively deep"). Inputs are still
@@ -424,7 +425,12 @@ registerTool(
 			"WITHOUT charging (returns {estimated_credits, available_credits, slug}); pass max_credits to cap the " +
 			"spend. kind defaults to 'auto' — a multi-scene editor ad for ad/promo/story briefs, a single-clip short " +
 			"for simple/short ones; the chosen kind is reported back as kind_inferred. If it returns terminal=false " +
-			"the render is still running — call wait_for_completion with the returned slug to finish.",
+			"the render is still running — call wait_for_completion with the returned slug to finish. " +
+			"BE PROACTIVE WITH BRANDING: pass headline (the on-screen TITLE) and subheadline (secondary title) plus " +
+			"music_vibe/theme so a one-shot short isn't bare — these apply to SHORTS (music_vibe/headline/subheadline " +
+			"are ignored for editor; theme applies to both). For richer branding — a product image, brand logo, or " +
+			"closing card — drive the granular path instead: create_short + set_short_product/set_short_poster, or " +
+			"create_editor_draft + set_product/set_logo/set_closing_image, then start_autopilot/generate_short.",
 		// Schema kept intentionally flat (no .min/.max/.int chains) — the SDK's
 		// generic inference on registerTool hits TS2589 ("excessively deep") on
 		// larger schemas with chained validators. Ranges are enforced in code.
@@ -452,6 +458,30 @@ registerTool(
 				.describe(
 					"Preferred narration voice id for editor ads (see list_voices); shorts have no voiceover",
 				),
+			headline: z
+				.string()
+				.optional()
+				.describe(
+					"SHORTS only: the on-screen TITLE overlay (≤160). Set this so the short isn't bare.",
+				),
+			subheadline: z
+				.string()
+				.optional()
+				.describe("SHORTS only: the secondary title / supporting line (≤200)"),
+			music_vibe: z
+				.string()
+				.optional()
+				.describe(
+					"SHORTS only: music mood — Upbeat (default), Cinematic, Minimal, Luxury, Playful, Jazz",
+				),
+			theme: z
+				.string()
+				.optional()
+				.describe(
+					"Visual theme (both kinds): none (literal — no imposed style), realistic (default), cinematic, " +
+						"anime, sci_fi, fantasy, noir, superhero, horror, mockumentary, sports, gaming, retro_80s, " +
+						"minimalist, cyberpunk",
+				),
 			save_path: z
 				.string()
 				.optional()
@@ -486,6 +516,10 @@ registerTool(
 				language?: string;
 				aspect?: string;
 				voice_id?: string;
+				headline?: string;
+				subheadline?: string;
+				music_vibe?: string;
+				theme?: string;
 				save_path?: string;
 				max_wait_seconds?: number;
 				dry_run?: boolean;
@@ -515,13 +549,31 @@ registerTool(
 			//    make_video (or a dry_run then a real run) reuses this same draft.
 			let slug: string;
 			if (kind === "short") {
+				// Carry the creative fields inline so a one-shot short can be titled
+				// and branded (headline/subheadline/music_vibe are short-only; theme
+				// applies to both kinds).
 				const created = await client.post<{ data: { slug: string } }>(
 					"/shorts",
-					{ product_prompt: args.prompt, language: args.language },
+					{
+						product_prompt: args.prompt,
+						language: args.language,
+						headline: args.headline,
+						subheadline: args.subheadline,
+						music_vibe: args.music_vibe,
+						theme: args.theme,
+					},
 					// Fold every create-affecting param into the key: two calls that
-					// differ only in language must NOT dedup to the same draft, and a
-					// transport retry of an identical call must reuse it.
-					idemKey("make-short", args.prompt, args.language ?? ""),
+					// differ only in a creative field must NOT dedup to the same draft,
+					// and a transport retry of an identical call must reuse it.
+					idemKey(
+						"make-short",
+						args.prompt,
+						args.language ?? "",
+						args.headline ?? "",
+						args.subheadline ?? "",
+						args.music_vibe ?? "",
+						args.theme ?? "",
+					),
 				);
 				slug = created.data.slug;
 			} else {
@@ -532,6 +584,7 @@ registerTool(
 						product_prompt: args.prompt,
 						export_aspect_ratio: args.aspect,
 						voice_id: args.voice_id,
+						theme: args.theme,
 					},
 					idemKey(
 						"make-editor",
@@ -539,6 +592,7 @@ registerTool(
 						args.language ?? "en",
 						args.aspect ?? "",
 						args.voice_id ?? "",
+						args.theme ?? "",
 					),
 				);
 				slug = created.data.slug;
@@ -677,7 +731,23 @@ registerTool(
 		inputSchema: {},
 		annotations: { title: "Get credits", ...RO },
 	},
-	tool(async (_args, client) => ok(await client.get("/studio/credits"))),
+	tool(async (_args, client) => {
+		const res = await client.get<{ data: unknown }>("/studio/credits");
+		const d = asRecord(asRecord(res).data);
+		// Whitelist generation-relevant fields only. Deliberately DROP
+		// `first_editor_video_pack_available`: it's a purchase-funnel flag for the
+		// PAID one-time starter pack (33 credits — not free), and this server has
+		// no billing scope, so it can't act on it. Passing it through only invited
+		// the agent to misread `true` as "your first video may be free", which
+		// contradicts the product (the first video is never free).
+		return ok({
+			credits: d.credits,
+			spendable_credits: d.spendable_credits,
+			reserved_credits: d.reserved_credits,
+			remaining_reserved_credits: d.remaining_reserved_credits,
+			message: d.message,
+		});
+	}),
 );
 
 // ── Voices ────────────────────────────────────────────────────────────────
@@ -770,8 +840,13 @@ registerTool(
 	{
 		title: "Create a short (draft)",
 		description:
-			"Creates a short draft from a product prompt (min 10 chars). Returns the slug. Costs 0 credits. " +
-			"Follow with generate_short to render. Prefer make_video for the one-shot path.",
+			"Creates a short draft from a product prompt (min 10 chars). A short is a 12s vertical (two 6s AI " +
+			"segments + an on-screen title overlay + music; 14s when an end-card poster is set). Returns the slug, " +
+			"costs 0 credits. Follow with generate_short to render. " +
+			"BE PROACTIVE: don't ship a bare clip — set a headline (the on-screen TITLE) and subheadline (secondary " +
+			"title), and pick a music_vibe and theme that fit the brand. To brand it further, attach a product image " +
+			"(set_short_product) or an end-card poster (set_short_poster) before generate_short. (Shorts have no logo " +
+			"overlay — that's an editor-only feature; use create_editor_ad for logo branding.)",
 		inputSchema: {
 			product_prompt: z
 				.string()
@@ -781,21 +856,109 @@ registerTool(
 				.string()
 				.optional()
 				.describe('Language code, e.g. "en" (default)'),
-			theme: z.string().optional(),
-			headline: z.string().optional(),
-			subheadline: z.string().optional(),
-			music_vibe: z.string().optional(),
+			headline: z
+				.string()
+				.max(160)
+				.optional()
+				.describe(
+					"The on-screen TITLE composited over the short (poster text overlay). ≤160 chars. Set this.",
+				),
+			subheadline: z
+				.string()
+				.max(200)
+				.optional()
+				.describe(
+					"The SECONDARY title / supporting line under the headline. ≤200 chars.",
+				),
+			theme: z
+				.string()
+				.optional()
+				.describe(
+					"Visual theme (default realistic). One of: none (no imposed style — follows the prompt literally), " +
+						"realistic, cinematic, anime, sci_fi, fantasy, noir, superhero, horror, mockumentary, sports, " +
+						"gaming, retro_80s, minimalist, cyberpunk.",
+				),
+			music_vibe: z
+				.string()
+				.optional()
+				.describe(
+					"Background-music mood. Recognized: Upbeat (default), Cinematic, Minimal, Luxury, Playful, Jazz.",
+				),
+			music_instruments: z
+				.array(z.string())
+				.optional()
+				.describe('Optional instrument hints, e.g. ["piano", "strings"]'),
+			text_position: z
+				.enum(["top", "center", "bottom"])
+				.optional()
+				.describe("Where the title overlay sits (default bottom)"),
+			text_animation: z
+				.enum(["reveal", "typewriter", "fade_in", "pop", "bounce"])
+				.optional()
+				.describe("Title overlay animation (default fade_in)"),
+			font_family: z
+				.string()
+				.optional()
+				.describe(
+					"Overlay font (default ShortFontSpaceGrotesk). One of: ShortFontSpaceGrotesk, ShortFontMontserrat, " +
+						"ShortFontTheBold, ShortFontImpact, ShortFontLato, ShortFontProximaNova, ShortFontAnton, " +
+						"ShortFontBebasNeue, ShortFontOswald, ShortFontArchivoBlack, ShortFontPoppins, ShortFontInter, " +
+						"ShortFontTikTokSans, ShortFontBangers.",
+				),
 		},
 		annotations: { title: "Create short", ...WRITE, idempotentHint: true },
 	},
-	tool(async (args: Record<string, unknown>, client) => {
-		const res = await client.post<{ data: { slug: string } }>(
-			"/shorts",
-			args,
-			idemKey("create-short", String(args.product_prompt ?? "")),
-		);
-		return ok({ slug: res.data.slug, kind: "short", next: "generate_short" });
-	}),
+	tool(
+		async (
+			args: {
+				product_prompt: string;
+				language?: string;
+				headline?: string;
+				subheadline?: string;
+				theme?: string;
+				music_vibe?: string;
+				music_instruments?: string[];
+				text_position?: string;
+				text_animation?: string;
+				font_family?: string;
+			},
+			client,
+		) => {
+			// Map the agent-friendly field names onto the API's short_* params.
+			const body: Record<string, unknown> = {
+				product_prompt: args.product_prompt,
+			};
+			if (args.language !== undefined) body.language = args.language;
+			if (args.headline !== undefined) body.headline = args.headline;
+			if (args.subheadline !== undefined) body.subheadline = args.subheadline;
+			if (args.theme !== undefined) body.theme = args.theme;
+			if (args.music_vibe !== undefined) body.music_vibe = args.music_vibe;
+			if (args.music_instruments !== undefined)
+				body.music_instruments = args.music_instruments;
+			if (args.text_position !== undefined)
+				body.short_text_position = args.text_position;
+			if (args.text_animation !== undefined)
+				body.short_text_animation = args.text_animation;
+			if (args.font_family !== undefined)
+				body.short_font_family = args.font_family;
+			const res = await client.post<{ data: { slug: string } }>(
+				"/shorts",
+				body,
+				idemKey(
+					"create-short",
+					args.product_prompt,
+					args.language ?? "",
+					args.headline ?? "",
+					args.subheadline ?? "",
+				),
+			);
+			return ok({
+				slug: res.data.slug,
+				kind: "short",
+				next: "set_short_product / set_short_poster (optional branding), then generate_short",
+			});
+		},
+	),
 );
 
 registerTool(
@@ -829,7 +992,11 @@ registerTool(
 			"Creates an editor project from a product prompt and starts autopilot (server-orchestrated " +
 			"scenario → segments → narration → voice → music → render). Each AI-generated scene is a fixed 8 seconds. " +
 			"Returns the slug. Costs credits. Then poll with get_status / wait_for_completion (kind=editor). Prefer " +
-			"make_video for the one-shot path.",
+			"make_video for the one-shot path. " +
+			"BRANDING: to attach the user's own product image, brand logo, or closing card, create the draft with " +
+			"create_editor_draft first, call set_product / set_logo / set_closing_image (all 0 credits), then " +
+			"start_autopilot — autopilot weaves them in. (Editor ads carry their copy in-scene/narration, not as a " +
+			"title overlay; for an on-screen title/subtitle use a short with headline/subheadline instead.)",
 		inputSchema: {
 			product_prompt: z
 				.string()
@@ -842,7 +1009,9 @@ registerTool(
 			theme: z
 				.string()
 				.optional()
-				.describe('Visual theme (default "realistic")'),
+				.describe(
+					'Visual theme (default "realistic"). One of: none (no imposed style — segments follow your prompts literally), realistic, cinematic, anime, sci_fi, fantasy, noir, superhero, horror, mockumentary, sports, gaming, retro_80s, minimalist, cyberpunk.',
+				),
 			voice_id: z
 				.string()
 				.optional()
@@ -987,7 +1156,9 @@ registerTool(
 			theme: z
 				.string()
 				.optional()
-				.describe('Visual theme (default "realistic")'),
+				.describe(
+					'Visual theme (default "realistic"). One of: none (no imposed style — segments follow your prompts literally), realistic, cinematic, anime, sci_fi, fantasy, noir, superhero, horror, mockumentary, sports, gaming, retro_80s, minimalist, cyberpunk.',
+				),
 			voice_id: z
 				.string()
 				.regex(/^[A-Za-z0-9_-]+$/)
@@ -2159,6 +2330,89 @@ registerTool(
 	),
 );
 
+// ── Shorts: branding images (product + end-card poster) ──────────────────────
+//
+// The editor branding tools above hit /editor/...; these hit /shorts/... A short
+// has no logo overlay (editor-only), but it CAN feature a product image woven
+// into the footage and a closing end-card poster. Both are 0 credits.
+
+registerTool(
+	"set_short_product",
+	{
+		title: "Attach a product image to a short (0 credits)",
+		description:
+			"Uploads a local product image and attaches it to a SHORT so the product is woven into the footage. " +
+			"Accepted: " +
+			IMAGE_EXTS.map((e) => `.${e}`).join(", ") +
+			" (≤20 MB), local path confined to HUBFLUENCER_INPUT_DIR (or cwd). 0 credits. Optional description " +
+			"(≤500 chars) guides how it's featured. Attach BEFORE generate_short so the product is part of the scenes. " +
+			"(This is the shorts equivalent of set_product for editor projects.)",
+		inputSchema: {
+			slug: z.string().describe("Short slug (from create_short)"),
+			file_path: z
+				.string()
+				.describe("Local product image path (.jpg/.jpeg/.png)"),
+			description: z
+				.string()
+				.max(500)
+				.optional()
+				.describe("Product description (≤500 chars)"),
+		},
+		annotations: {
+			title: "Set short product",
+			...WRITE,
+			idempotentHint: false,
+		},
+	},
+	tool(
+		async (
+			args: { slug: string; file_path: string; description?: string },
+			client,
+		) => {
+			const { s3_key } = await uploadImageFile(
+				client,
+				`/shorts/${args.slug}/product/presign`,
+				args.file_path,
+			);
+			const res = await client.post<{ data: unknown }>(
+				`/shorts/${args.slug}/product/confirm`,
+				{ s3_key, product_description: args.description },
+			);
+			return ok(asRecord(res).data ?? res);
+		},
+	),
+);
+
+registerTool(
+	"set_short_poster",
+	{
+		title: "Set a short's end-card poster image (0 credits)",
+		description:
+			"Uploads a local image as the SHORT's end-card poster — a closing still shown at the end (extends the " +
+			"render from 12s to 14s). Accepted: " +
+			IMAGE_EXTS.map((e) => `.${e}`).join(", ") +
+			" (≤20 MB), confined to HUBFLUENCER_INPUT_DIR/cwd. 0 credits. There is one poster per short; calling " +
+			"again replaces it. (Shorts have no logo overlay — for a brand logo use an editor project + set_logo.)",
+		inputSchema: {
+			slug: z.string().describe("Short slug (from create_short)"),
+			file_path: z.string().describe("Local poster image (.jpg/.jpeg/.png)"),
+		},
+		annotations: { title: "Set short poster", ...WRITE, idempotentHint: false },
+	},
+	tool(async (args: { slug: string; file_path: string }, client) => {
+		const { s3_key } = await uploadShortPoster(
+			client,
+			args.slug,
+			args.file_path,
+		);
+		const res = await client.post<{ data: unknown }>(
+			`/shorts/${args.slug}/poster/confirm`,
+			{ s3_key },
+		);
+		return ok(asRecord(res).data ?? res);
+	}),
+);
+
 // ── Status / waiting ──────────────────────────────────────────────────────────
 
 registerTool(

package/src/uploads.ts

@@ -365,5 +365,30 @@ export async function uploadImageFile(
 	return { s3_key };
 }
 
+/**
+ * Uploads a local image as a short's end-card POSTER. The short poster presign
+ * is older than the editor asset presign and uses a different envelope: it takes
+ * `{ content_type }` and returns a bare `{ upload_url, s3_key }` (no `data`
+ * wrapper, `upload_url` not `presigned_url`, and a single fixed key per short).
+ * Kept separate from `uploadImageFile` (which speaks the editor `{data:{...}}`
+ * shape) so neither has to branch on the surface. Returns the `s3_key` to thread
+ * into `/shorts/:slug/poster/confirm`.
+ */
+export async function uploadShortPoster(
+	client: HubfluencerClient,
+	slug: string,
+	filePath: string,
+): Promise<{ s3_key: string }> {
+	const file = await resolveReadPath(filePath, IMAGE_EXT_MIME, MAX_IMAGE_BYTES);
+	const presign = await client.post<{ upload_url: string; s3_key: string }>(
+		`/shorts/${slug}/poster/presign`,
+		{ content_type: file.mime },
+	);
+	const { upload_url, s3_key } = presign;
+	const buf = await readFile(file.path);
+	await putToPresignedUrl(upload_url, buf, file.mime);
+	return { s3_key };
+}
+
 export const LOGO_MAX_BYTES = MAX_LOGO_BYTES;
 export const IMAGE_MAX_BYTES = MAX_IMAGE_BYTES;