Start a Promo campaign
start_campaignStart a campaign for an upcoming release, or a month between releases (between_releases: true, from tomorrow; none starts by itself, so start the next month the same way when one ends). A release already out gets no campaign of its own: its start is made between releases with its song first (the answer says between_releases: true). Audora writes the campaign (every post's day, time, words and what picture or video it needs) at a price that grows with its size (2 a week is the least, Every day the most; the dry run's quote.plan says it), charged when it starts and returned if the plan fails; starting it needs the artist's spend permission. Nothing is made: fill each post from the artist's Library with update_post, or have Audora make one with make_posts (priced then). A campaign is planned in moments: one video or picture posted the same day on every connected account it fits, with words for each account. Each moment costs 1 credit to go out, all its accounts included, only when it is scheduled. The answers about the song (the_story, key_lyrics, key_moments, what_works, sonic_references, note) are the Start panel's: optional, filled from what Audora knows when left out, and they turn on posts that use them. A release (or the time between releases) can run several campaigns at once, each with its own language, lead market and accounts; one that would copy a live campaign in all three is refused (a dry run's quote.duplicate_of names it, quote.live_campaigns lists them). Planned posts fit around the posts other campaigns already have on the same accounts: one video and one picture a day per account. Use dry_run first to see the posts, the price and those answers (quote.answers), tell the artist, then start with confirm_cost_credits.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| note | No | Optional, ≤ 200 characters: "Anything we should know?", anything else the planner should know, in the artist's words. Left out: the last campaign's for this release, if any. | |
| size | Yes | How often: light is 2 moments a week, steady 4 a week, loud every day (a video moment and a picture moment each day, so every account posts every day). A release campaign runs 5 weeks before release day and 2 after (49 days: light 14 moments, steady 28, loud 98), its moments climbing toward release day; between releases a month (30 days: light 9, steady 17, loud 60). A release closer than 5 weeks has fewer days and so fewer moments. The dry run quotes the exact moments and posts. | |
| about | No | Between releases only: what the campaign is about. "song" (with about_track_id, one of the artist's songs) or "artist" (posts about who they are, their sound and their artist page; no line is kept). Left out: planned as before. | |
| lanes | Yes | Where the posts go. Only lanes with a connected account are planned. | |
| artist | No | Only when you are connected as a label: the roster artist this call is for — their artist_user_id from list_roster, or their exact artist name. Required for every artist tool on a label connection. Leave it out on an artist's own connection. | |
| dry_run | No | True to check the call and see what it would do, without writing anything. | |
| accounts | No | Optional, for an artist with more than one account on a platform: which account each platform posts through, as the account's id, @handle or name (a dry run's quote.accounts lists them). Every post of the campaign is tied to its account and never goes out on another. Left out for a platform: the account the newest campaign in this language used there, else the artist's main account. | |
| the_story | No | Optional, ≤ 5000 characters: "The story behind it", in the artist's own words. Where it was written, what happened, who it is for. Posts tell it in your words. Never write it for them. | |
| key_lyrics | No | Optional, up to 2: "A line that matters", word for word from the song's lyrics (get_track has them). A line not in the lyrics is refused; a song with no lyrics takes a line the artist types; an instrumental takes none. | |
| release_id | No | The release (from list_releases or list_campaigns' can_start). Or use between_releases. | |
| what_works | No | Optional, ≤ 2000 characters: "What worked before", in the artist's words. A post, a format or a time that did well for you. Posts can take the same shape again. | |
| key_moments | No | Optional, up to 6: "Something coming up". A show, a video, a date that matters. Posts lead up to it. Left out: Scene's public shows and parties inside the campaign's days. | |
| lead_market | No | Optional: where most of the listeners for this campaign are. Every post is timed for that market's clock. null: timed where the artist is. Left out: the last campaign's market, else the first market on the artist's page (a dry run's quote.markets says which). | |
| lyric_video | No | Optional: the campaign's first made video shows the song's words in time with the song. Audora times the lyrics when the campaign starts (free), so that video comes about 10 minutes later. false: no video shows lyrics. Left out: on when the song's lyrics can be timed. A dry run's quote.lyric_video says the song and where its lyrics stand (to_time, timing, timed, or why not: no_lyrics, instrumental, language, no_master). | |
| loop_opt_out | No | Optional: what the artist does not want Audora to lean on in this campaign, from a dry run's quote.from_results (Start a campaign's "From your results": the angles, hours and picture sources the artist's own post results say have done best, each line with its count). Pass a line's opt_out entries for each line the artist unticks; that choice is then made as it is for everyone, for this campaign only. Left out: every line is planned with. Each post still gets one try at something new either way. quote.from_results is null when there is no line. | |
| post_language | No | Optional: the language every post in this campaign is written in, with the text on its pictures and videos. Left out: the artist's Post language, else the language the artist's own post results have done best in (when their results are in 2 or more languages and one holds 4 or more and beats their usual most often), else the language the release's songs are sung in, else en-US. A dry run's quote.post_language says which and why; its results names the language their results favor, also when their Post language is another (offer it, never assume it). It is the campaign's, never written back to the artist. | |
| about_track_id | No | With about: "song", the song the campaign is about (list_tracks). | |
| idempotency_key | No | Send the same key if you retry, and the change happens once. | |
| replace_plan_id | No | Optional: start that campaign over (an id from list_campaigns, for the same release or between releases). Its posts not yet scheduled are removed once the new campaign is written; scheduled ones stay and go out. | |
| between_releases | No | True for a month between releases instead of a release's campaign. | |
| picture_fallback | No | Optional: what fills a post the artist's own photos and cover do not cover, when Audora is asked to make it (make_posts, or in the app). stock: free Pixabay stock photos, always made into the artist's cards (people and brands left out; not offered for a song about drugs, sex or politics). new: Audora draws a new picture. ask: those posts wait for the artist to pick a photo in the app. Stock and new cost the same (the artist's own photos and cover are free). Left out: the artist's last answer, else stock. A dry run's quote.picture_fallback says the starting choice and whether stock may be used. | |
| sonic_references | No | Optional, up to 5 names: "Artists you sound like". Left out: the Artist page's reference artists. | |
| key_lyrics_track_id | No | The song the lines are from: one of the release's songs, or between releases any of the artist's. Left out: the release's songs are tried; between releases, the artist's newest songs with lyrics. | |
| confirm_cost_credits | No | The price a dry run quoted (charged_at_start: the plan at its size) and you told the artist. Required to start. |