Create a Siren campaign from a plain-language brief — the full
pipeline: plan, on-brand copy, deterministic render, verify. Returns
the run; poll get_run until it finishes. Spends credits (image 10, an ad set of 3 images 20,
video 25; voice or music-only is the same 25). Pass output_type to
pin a film (list_films has the catalog); omit it and Siren picks.
Optional scheduled_at (ISO-8601)
queues a sequential post (X → Instagram → TikTok, or platforms you
pass) when the render succeeds — requires Allow posting. Fails with
a 402 upgrade message if the plan or balance can't cover it.
FILM KNOBS: voiceover (true narrated / false music only), direction
(mood, pace, motion, music in one line), music (a bed id), media
(upload_media URLs the film shows). Images ignore the film knobs:
Siren writes and paints them from the brief and Brand DNA.
ANY BRAND: pass `brand` to make it for a brand that is not this
workspace's own, e.g. brand={"name": "Acme", "site": "acme.com",
"logo_url": "https://acme.com/logo.png", "primary": "#FF4400"}.
Nothing of this workspace's identity leaks in.
The exact same request within 24 hours returns the run it already
started, as it is now, with replayed=true and no new charge. Change
the brief to make another.
View input schema
{
"type": "object",
"properties": {
"brief": {
"description": "Plain-language request for the post, e.g. \"announce the new export feature, use the dashboard screenshot\".",
"type": "string"
},
"channel": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Omit to cut one render per connected platform, up to the credit balance and the plan cap (Spark stops at 2). Pass twitter, instagram, linkedin, tiktok, or youtube for a single cut. A shape named in the brief wins: square, vertical, portrait, story, wide, landscape, 4:5, 9:16, 16:9."
},
"asset_type": {
"default": "card",
"description": "What to make: card (still image) or video.",
"type": "string"
},
"output_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional film to pin, e.g. \"story\" or \"pitch\". Call list_films to browse; describe_film for the contract. Omit and Siren picks the format from the brief."
},
"caption": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional caption for the post this run becomes. Your words are kept; omit and Siren writes the caption."
},
"scheduled_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "ISO-8601 time to post, e.g. 2026-09-12T09:00:00. Interpreted in the given timezone."
},
"timezone": {
"default": "UTC",
"description": "IANA timezone name for scheduled_at, e.g. Africa/Lagos or America/New_York.",
"type": "string"
},
"platforms": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Where to post: any of x, instagram, tiktok, linkedin, youtube, or [\"everything\"] for every connected channel."
},
"voiceover": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Films: true = narrated in the brand voice, false = motion + music only. Omit and the brief decides; if the human never said, ask them once."
},
"direction": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Films: one free line on mood, pace, motion and music, e.g. \"emotional, slow, soft piano\" or \"dark, club energy, fast cuts\"."
},
"music": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Films: a music bed track_id. Omit and the bed follows the film and the direction."
},
"media": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Films: URLs from upload_media (images and videos) for the film to show. Omit and the film shows the brand's recent work. Images (asset_type=card): photos from upload_media are painted into the creative as given, placed where the brief says (\"our mug in the top-left\"); videos are refused for images."
},
"variants": {
"default": 1,
"description": "Images only. 3 makes an ad set: the same creative with three different headlines, for testing hooks on paid feeds. 20 credits for the three instead of 10 for one. get_run then returns all three in asset_urls. Default 1.",
"type": "integer"
},
"brand": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"description": "Make it for ANOTHER brand instead of this workspace's own (a client, a brand people recognise, a side project). Object: {name (required), site, logo_url (https PNG/SVG/JPG of the brand's MARK or app icon, e.g. Duolingo's owl, not the wordmark: the film sets the name in type), accent (hex: the brand's signature colour, the one films are painted in), primary (hex: its dark or ink colour), secondary, tagline, font (the brand's typeface name, e.g. Nunito), x_handle, sells (one line: what they make)}. Clean slate: none of this workspace's logo, colours, mascot, font, handle, screenshots or memory is used; only what you send. YOU look the brand up first: their site, their logo file (the image in their site header, or their /brand or /press page, or the app icon) and their colours as hex. A missing, dead or damaged logo is refused (brand_logo_required / brand_logo_unreachable / brand_logo_unreadable) because a film with no mark is a generic video; one colour for both primary and accent is refused too. Never invent a logo URL and never pass a screenshot of their page as the logo. Omit to use this workspace's Brand DNA."
}
},
"required": [
"brief"
],
"additionalProperties": false
}