[{"id":"article_video","name":"Article to Video","description":"Turn an article, blog post or newsletter (URL or pasted text) into a narrated 9:16 short with word-synced captions over a looping background.","inputSchema":{"type":"object","properties":{"source":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","const":"url"},"url":{"type":"string","format":"uri","description":"Public article, blog or newsletter URL."}},"required":["kind","url"]},{"type":"object","properties":{"kind":{"type":"string","const":"text"},"text":{"type":"string","minLength":1,"maxLength":60000,"description":"Pasted article text. The script step needs 90 to 4000 words."}},"required":["kind","text"]}],"description":"Where the article comes from: a URL we fetch, or the text itself."},"length":{"default":"standard","description":"short ~30s, standard ~60s, deep ~90s.","type":"string","enum":["short","standard","deep"]},"tone":{"default":"explainer","type":"string","enum":["explainer","punchy","authority"]},"voiceId":{"default":"onwK4e9ZLuTAKqWW03F9","description":"Narrator voice. See GET /v1/options voices tagged article_video.","type":"string","enum":["onwK4e9ZLuTAKqWW03F9","JBFqnCBsd6RMkjVDRZzb","EXAVITQu4vr4xnSDxMaL","pNInz6obpgDQGcFmaJgB","LcfcDJNUP1GQjkzn1xUU","TxGEqnHWrfWFTfGW9XjX"]},"captionPresetId":{"description":"Caption style. See GET /v1/options captionPresets.","type":"string","enum":["hormozi","beast","ali","iman","devin","matt","kendrick","laura","doug","carlos","nick","fire","neon","william","leon","luke","classicWhite"]},"silent":{"default":false,"description":"Render with no narration. Refused unless explicitly true.","type":"boolean"}},"required":["source"],"additionalProperties":false,"description":"Plain-text guide for agents: https://api.ghostshorts.com/v1/templates/article_video.txt"},"defaults":{"length":"standard","tone":"explainer","voiceId":"onwK4e9ZLuTAKqWW03F9","silent":false,"aspectRatio":"9:16"},"freeTools":["script"],"paidSteps":[{"step":"narration","credits":"1 credit per minute of narration (legacy plans); included on current plans within fair use"},{"step":"render","credits":"1 video from the monthly allowance (current plans); export counter on legacy plans"}],"notes":["The script is condensed from the source and must stay faithful to it: every figure, quote and named person in the script must appear in the source.","Source text must be 90 to 4000 words after extraction.","Background footage is chosen server-side."]},{"id":"quiz_video","name":"AI Quiz Video","description":"A multiple-choice quiz short: question card, countdown, answer reveal with a fact line, narrated, over a looping background.","inputSchema":{"type":"object","properties":{"topic":{"type":"string","minLength":2,"maxLength":200,"description":"What the quiz is about, e.g. \"the Roman Empire\"."},"difficulty":{"default":"medium","type":"string","enum":["easy","medium","hard"]},"questionCount":{"default":5,"anyOf":[{"type":"number","const":5},{"type":"number","const":7},{"type":"number","const":10}]},"categoryId":{"description":"Optional steer for the generator.","type":"string","enum":["general-knowledge","geography","history","science","movies-tv","music","sports","food-drink","video-games","logos-brands"]},"videoTitle":{"description":"Title on the intro card.","type":"string","minLength":1,"maxLength":48},"voiceId":{"default":"LcfcDJNUP1GQjkzn1xUU","description":"Narrator voice. See GET /v1/options voices tagged quiz_video.","type":"string","enum":["LcfcDJNUP1GQjkzn1xUU","EXAVITQu4vr4xnSDxMaL","pNInz6obpgDQGcFmaJgB","TxGEqnHWrfWFTfGW9XjX","JBFqnCBsd6RMkjVDRZzb","onwK4e9ZLuTAKqWW03F9"]},"theme":{"default":"neon","type":"string","enum":["neon","sunset","classic"]},"font":{"default":"anton","type":"string","enum":["anton","bangers","bebas-neue","poppins"]},"countdownSeconds":{"default":5,"anyOf":[{"type":"number","const":3},{"type":"number","const":5},{"type":"number","const":7}]},"captionsEnabled":{"default":false,"type":"boolean"},"silent":{"default":false,"description":"Render with no narration. Refused unless explicitly true.","type":"boolean"}},"required":["topic"],"additionalProperties":false,"description":"Plain-text guide for agents: https://api.ghostshorts.com/v1/templates/quiz_video.txt"},"defaults":{"difficulty":"medium","questionCount":5,"voiceId":"LcfcDJNUP1GQjkzn1xUU","theme":"neon","font":"anton","countdownSeconds":5,"captionsEnabled":false,"silent":false,"aspectRatio":"9:16"},"freeTools":["script"],"paidSteps":[{"step":"narration","credits":"1 credit per minute of narration across the whole pack (legacy plans); included on current plans within fair use"},{"step":"render","credits":"1 video from the monthly allowance (current plans); export counter on legacy plans"}],"notes":["Get the pack free first with POST /v1/scripts (template quiz_video), check the answers, then pass its projectId to POST /v1/videos.","Questions are AI-generated. Check answers before publishing, especially dates and award years.","Topics that target a group of people are refused."]},{"id":"reddit_story","name":"Reddit Story","description":"Your own Reddit-style story (title plus 300 to 5000 characters of text, written by you: nothing is generated for it), narrated by an AI voice with word-synced captions over gameplay footage, with a Reddit title card. Narration is mandatory: there is no silent option. Free first: POST /v1/previews returns a ~10 second narration teaser for 0 credits.","inputSchema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":200,"description":"Post title, narrated first and shown on the title card."},"text":{"type":"string","minLength":300,"maxLength":5000,"description":"The story body, 300 to 5000 characters."},"author":{"default":"Anonymous","type":"string","maxLength":32},"voiceId":{"default":"pNInz6obpgDQGcFmaJgB","description":"Narrator voice. See GET /v1/options voices tagged reddit_story.","type":"string","enum":["pNInz6obpgDQGcFmaJgB","2EiwWnXFnvU5JabPnv8n","CwhRBWXzGAHq8TQ4Fs17","EXAVITQu4vr4xnSDxMaL","FGY2WhTYpPnrIDTdsKH5","IKne3meq5aSn9XLyUdCD","JBFqnCBsd6RMkjVDRZzb","N2lVS1w4EtoT3dr4eOWO","SAz9YHcvj6GT2YYXdXww","SOYHLrjzK2X1ezoPC6cr","TX3LPaxmHKxFdv7VOQHJ","Xb7hH8MSUJpSbSDYk0k2","XrExE9yKIg1WjnnlVkGX","bIHbv24MWmeRgasZH58o","cgSgspJ2msm6clMCkdW9","cjVigY5qzO86Huf0OWal","iP95p4xoKVk53GoZ742B","nPczCjzI2devNBz1zQrb","onwK4e9ZLuTAKqWW03F9","pFZP5JQG7iQjIQuC4Bku","pqHfZKP75CvOlQylNhV4","vERmHY5ZzBsIRPzH78Rb","papd083UqIoSWdSkh3fG","zAr1POVZUrr1zkX0T94t","EIdfNdxb4fnsE39tEAB1","5Spsi3mCH9e7futpnGE5","G1QUjBCuRBbLbAmYlTgl","6wsXez7Nsh9HQSbtqwIK","SfXg52J54dixBlOl016v","Yf6I1OzNemrgGRsc8z1I","z0gdR3nhVl1Ig2kiEigL","wAWUBOIVEUw9IEUYoNzR","6XNSYkDqZ1blajSVtPok","LNzr3u01PIEDg0fRlvE7","GxxMAMfQkDlnqjpzjLHH","RBnMinrYKeccY3vaUxlZ","sZXOZNdVMeHi5J0uiQF7","8ng6vvUHRpznlJL92xmU","x5tvfc5X0Qh4cqmLpgrs","20ptB7Wn4Q2sMkAxK1qK","JaUVfDrFcfwGIsv8X2kN","iWydkXKoiVtvdn4vLKp9","HnnPtoATgzx4ubChwm24","C1DBnkwmDIzoLOPlBvSg","hIssydxXZ1WuDorjx6Ic","NacdHGUYR1k3M0FAbAia","87QJokeqzysrKtZFt7jl"]},"language":{"default":"en","description":"Narration language (ISO 639-1).","type":"string","minLength":2,"maxLength":5},"backgroundVideoAssetId":{"description":"A background video id from GET /v1/options backgrounds.assets. Mutually exclusive with backgroundCategory.","type":"string","minLength":1},"backgroundCategory":{"description":"Pick any background from this category. Mutually exclusive with backgroundVideoAssetId.","type":"string","enum":["Minecraft","Mario Kart","GTA V","Subway Surfers","Satisfying","Backrooms","Roblox"]},"backgroundVideoUrl":{"description":"Your own footage by public https URL. Video is converted for rendering (H.264 baseline, 1080x1920, cropped to fill, silent); files up to 300 MB / 10 min. Mutually exclusive with backgroundVideoAssetId and backgroundCategory.","type":"string","minLength":1,"maxLength":2048},"backgroundAudioAssetId":{"description":"Background music id from GET /v1/options music.","type":"string","minLength":1},"backgroundAudioUrl":{"description":"Your own track by public https URL. Converted to MP3 for rendering; files up to 30 MB / 10 min. Mutually exclusive with backgroundAudioAssetId.","type":"string","minLength":1,"maxLength":2048},"backgroundAudioVolume":{"default":30,"type":"integer","minimum":0,"maximum":100},"captionPresetId":{"default":"hormozi","type":"string","enum":["hormozi","beast","ali","iman","devin","matt","kendrick","laura","doug","carlos","nick","fire","neon","william","leon","luke","classicWhite"]},"captionPosition":{"default":"middle","type":"string","enum":["top","middle","bottom"]},"captionsEnabled":{"default":true,"type":"boolean"},"titleCardTheme":{"default":"dark","type":"string","enum":["dark","light"]},"voiceSpeed":{"default":1,"type":"number","minimum":0.85,"maximum":1.25},"stability":{"default":50,"type":"number","minimum":0,"maximum":100},"similarity":{"default":75,"type":"number","minimum":0,"maximum":100},"pitch":{"default":1,"type":"number","minimum":0.5,"maximum":2}},"required":["title","text"],"additionalProperties":false,"description":"Plain-text guide for agents: https://api.ghostshorts.com/v1/templates/reddit_story.txt"},"defaults":{"author":"Anonymous","voiceId":"pNInz6obpgDQGcFmaJgB","language":"en","backgroundVideoAssetId":"92992e79fd7bc6f5","backgroundCategory":"Subway Surfers","backgroundAudioVolume":30,"captionPresetId":"hormozi","captionPosition":"middle","captionsEnabled":true,"titleCardTheme":"dark","voiceSpeed":1,"stability":50,"similarity":75,"pitch":1,"aspectRatio":"9:16"},"freeTools":["preview"],"paidSteps":[{"step":"narration","credits":"1 credit per minute of narration, estimated at 15 characters per second (legacy plans); included on current plans within fair use"},{"step":"render","credits":"1 video from the monthly allowance (current plans); export counter on legacy plans"}],"notes":["The story text is yours; nothing is generated for it.","With no background field set, the Subway Surfers default background is used.","Own media by URL is fetched before anything is charged. The same URL is reused for 30 days without re-fetching; up to 20 new URLs per day. Failures: MEDIA_FETCH_FAILED, MEDIA_INVALID, MEDIA_TOO_LONG, MEDIA_QUOTA_EXCEEDED.","Narration always runs on POST /v1/videos, even for a projectId from POST /v1/previews: the teaser is never reused as the narration."]},{"id":"fake_text_message","name":"Text Messages","description":"Your own chat conversation (written by you: nothing is generated for it) rendered as an iMessage, WhatsApp, Instagram or Tinder chat over gameplay footage, with each message voiced by an AI voice for \"me\" and one for \"them\", or silent with music only when voices is omitted. Group chats of up to 6 people (members instead of contact) on iMessage, WhatsApp and Instagram, each person with their own name, picture and voice. Returns one MP4; pass cutAfterMessage to get the exact millisecond where the next message appears, for splicing.","inputSchema":{"type":"object","properties":{"platform":{"default":"imessage","description":"Chat skin. \"ios\" is accepted as an alias of \"imessage\".","type":"string","enum":["imessage","whatsapp","instagram","tinder","ios"]},"theme":{"default":"dark","description":"Light or dark chat skin.","type":"string","enum":["dark","light"]},"contact":{"description":"The person you are texting (a 2-person chat). Required unless members is set; do not send both.","type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":40,"description":"The contact shown in the chat header."},"avatarAssetId":{"description":"An image asset you own (or a system image) for the contact avatar.","type":"string","minLength":1}},"required":["name"],"additionalProperties":false},"members":{"description":"GROUP CHAT: everyone in the chat except you, 1 to 5 people (6 including you). Use instead of contact. iMessage, WhatsApp and Instagram only (Tinder is 1:1). With one member it is a normal 2-person chat.","minItems":1,"maxItems":5,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-z0-9][a-z0-9_-]{0,31}$","description":"Your id for this person (e.g. \"sam\"); messages[].sender uses it. \"me\" and \"them\" are reserved."},"name":{"type":"string","minLength":1,"maxLength":40,"description":"Their name, shown above their bubbles and in the header."},"avatarAssetId":{"description":"An image asset you own (or a system image) for their picture.","type":"string","minLength":1},"voiceId":{"description":"Their voice (GET /v1/options voices tagged fake_text_message). Omitted = a default voice nobody else in the chat has. Ignored on a silent video.","type":"string","enum":["pNInz6obpgDQGcFmaJgB","2EiwWnXFnvU5JabPnv8n","CwhRBWXzGAHq8TQ4Fs17","EXAVITQu4vr4xnSDxMaL","FGY2WhTYpPnrIDTdsKH5","IKne3meq5aSn9XLyUdCD","JBFqnCBsd6RMkjVDRZzb","N2lVS1w4EtoT3dr4eOWO","SAz9YHcvj6GT2YYXdXww","SOYHLrjzK2X1ezoPC6cr","TX3LPaxmHKxFdv7VOQHJ","Xb7hH8MSUJpSbSDYk0k2","XrExE9yKIg1WjnnlVkGX","bIHbv24MWmeRgasZH58o","cgSgspJ2msm6clMCkdW9","cjVigY5qzO86Huf0OWal","iP95p4xoKVk53GoZ742B","nPczCjzI2devNBz1zQrb","onwK4e9ZLuTAKqWW03F9","pFZP5JQG7iQjIQuC4Bku","pqHfZKP75CvOlQylNhV4","vERmHY5ZzBsIRPzH78Rb","papd083UqIoSWdSkh3fG","zAr1POVZUrr1zkX0T94t","EIdfNdxb4fnsE39tEAB1","5Spsi3mCH9e7futpnGE5","G1QUjBCuRBbLbAmYlTgl","6wsXez7Nsh9HQSbtqwIK","SfXg52J54dixBlOl016v","Yf6I1OzNemrgGRsc8z1I","z0gdR3nhVl1Ig2kiEigL","wAWUBOIVEUw9IEUYoNzR","6XNSYkDqZ1blajSVtPok","LNzr3u01PIEDg0fRlvE7","GxxMAMfQkDlnqjpzjLHH","RBnMinrYKeccY3vaUxlZ","sZXOZNdVMeHi5J0uiQF7","8ng6vvUHRpznlJL92xmU","x5tvfc5X0Qh4cqmLpgrs","20ptB7Wn4Q2sMkAxK1qK","JaUVfDrFcfwGIsv8X2kN","iWydkXKoiVtvdn4vLKp9","HnnPtoATgzx4ubChwm24","C1DBnkwmDIzoLOPlBvSg","hIssydxXZ1WuDorjx6Ic","NacdHGUYR1k3M0FAbAia","87QJokeqzysrKtZFt7jl","wJ5MX7uuKXZwFqGdWM4N","tZssYepgGaQmegsMEXjK"]}},"required":["id","name"],"additionalProperties":false}},"groupName":{"description":"GROUP CHAT: the group name in the header (needs members with 2+ people). Omitted = the members' names.","type":"string","minLength":1,"maxLength":40},"messages":{"minItems":1,"maxItems":500,"type":"array","items":{"type":"object","properties":{"sender":{"type":"string","minLength":1,"maxLength":32,"description":"\"me\" is the phone owner (right-hand bubbles); \"them\" is the contact. In a group chat (members set) use \"me\" or a members[].id."},"text":{"description":"The message text. Send text or imageAssetId, not both.","type":"string","minLength":1,"maxLength":500},"imageAssetId":{"description":"An image asset you own (or a system image) shown as a photo message, held 3 seconds.","type":"string","minLength":1},"delayMs":{"description":"Gap in milliseconds before this message appears. Defaults to the pacing preset.","type":"integer","minimum":0,"maximum":10000},"timestampLabel":{"description":"Timestamp row shown above this message, e.g. \"Today 8:12 PM\".","type":"string","minLength":1,"maxLength":40},"gapLabel":{"description":"A time-gap row shown before this message, e.g. \"4 days later\". Fixed at voice-generation time (900 ms).","type":"string","minLength":1,"maxLength":40},"receipt":{"description":"Receipt label under this message, free text, e.g. \"Read 8:14 PM\" or \"Delivered\".","type":"string","minLength":1,"maxLength":30},"typingIndicatorBefore":{"description":"Show a typing bubble before this message (at least 800 ms; fixed at voice-generation time).","type":"boolean"}},"required":["sender"],"additionalProperties":false},"description":"The conversation, in order. Up to 500 messages; the video can be up to 10 minutes."},"pacing":{"default":"normal","description":"Default gap for messages without delayMs: fast 0 ms, normal 0 ms, slow 1000 ms.","type":"string","enum":["fast","normal","slow"]},"linePause":{"default":"natural","description":"Pause after each line: the silence kept after each voice line before the next bubble. snappy 0.05 s (also keeps only ~0.02 s before the first word), tight 0.15 s, natural 0.35 s (default), relaxed 0.6 s. Each clip is trimmed or padded to exactly this tail. No effect on a silent video.","type":"string","enum":["snappy","tight","natural","relaxed"]},"voiceSpeed":{"description":"Speaking speed of both voices, 0.8 to 1.2 (default 1.0 = natural pace; e.g. 1.1 faster, 0.9 slower). A faster voice makes every bubble hold shorter. No effect on a silent video.","type":"number","minimum":0.8,"maximum":1.2},"voices":{"description":"AI voices for the two sides. Omit for a silent video with music only. {} voices both sides with the default voices.","type":"object","properties":{"enabled":{"description":"Optional; only true is accepted. To make a silent video, omit voices entirely instead.","type":"boolean"},"me":{"description":"Voice for \"me\". See GET /v1/options voices tagged fake_text_message. Send both me and them, or neither (then pNInz6obpgDQGcFmaJgB for me). In a group chat send only me (each member's voice goes on members[].voiceId).","type":"string","enum":["pNInz6obpgDQGcFmaJgB","2EiwWnXFnvU5JabPnv8n","CwhRBWXzGAHq8TQ4Fs17","EXAVITQu4vr4xnSDxMaL","FGY2WhTYpPnrIDTdsKH5","IKne3meq5aSn9XLyUdCD","JBFqnCBsd6RMkjVDRZzb","N2lVS1w4EtoT3dr4eOWO","SAz9YHcvj6GT2YYXdXww","SOYHLrjzK2X1ezoPC6cr","TX3LPaxmHKxFdv7VOQHJ","Xb7hH8MSUJpSbSDYk0k2","XrExE9yKIg1WjnnlVkGX","bIHbv24MWmeRgasZH58o","cgSgspJ2msm6clMCkdW9","cjVigY5qzO86Huf0OWal","iP95p4xoKVk53GoZ742B","nPczCjzI2devNBz1zQrb","onwK4e9ZLuTAKqWW03F9","pFZP5JQG7iQjIQuC4Bku","pqHfZKP75CvOlQylNhV4","vERmHY5ZzBsIRPzH78Rb","papd083UqIoSWdSkh3fG","zAr1POVZUrr1zkX0T94t","EIdfNdxb4fnsE39tEAB1","5Spsi3mCH9e7futpnGE5","G1QUjBCuRBbLbAmYlTgl","6wsXez7Nsh9HQSbtqwIK","SfXg52J54dixBlOl016v","Yf6I1OzNemrgGRsc8z1I","z0gdR3nhVl1Ig2kiEigL","wAWUBOIVEUw9IEUYoNzR","6XNSYkDqZ1blajSVtPok","LNzr3u01PIEDg0fRlvE7","GxxMAMfQkDlnqjpzjLHH","RBnMinrYKeccY3vaUxlZ","sZXOZNdVMeHi5J0uiQF7","8ng6vvUHRpznlJL92xmU","x5tvfc5X0Qh4cqmLpgrs","20ptB7Wn4Q2sMkAxK1qK","JaUVfDrFcfwGIsv8X2kN","iWydkXKoiVtvdn4vLKp9","HnnPtoATgzx4ubChwm24","C1DBnkwmDIzoLOPlBvSg","hIssydxXZ1WuDorjx6Ic","NacdHGUYR1k3M0FAbAia","87QJokeqzysrKtZFt7jl","wJ5MX7uuKXZwFqGdWM4N","tZssYepgGaQmegsMEXjK"]},"them":{"description":"Voice for \"them\". Send both me and them, or neither (then EXAVITQu4vr4xnSDxMaL for them). Not used in a group chat.","type":"string","enum":["pNInz6obpgDQGcFmaJgB","2EiwWnXFnvU5JabPnv8n","CwhRBWXzGAHq8TQ4Fs17","EXAVITQu4vr4xnSDxMaL","FGY2WhTYpPnrIDTdsKH5","IKne3meq5aSn9XLyUdCD","JBFqnCBsd6RMkjVDRZzb","N2lVS1w4EtoT3dr4eOWO","SAz9YHcvj6GT2YYXdXww","SOYHLrjzK2X1ezoPC6cr","TX3LPaxmHKxFdv7VOQHJ","Xb7hH8MSUJpSbSDYk0k2","XrExE9yKIg1WjnnlVkGX","bIHbv24MWmeRgasZH58o","cgSgspJ2msm6clMCkdW9","cjVigY5qzO86Huf0OWal","iP95p4xoKVk53GoZ742B","nPczCjzI2devNBz1zQrb","onwK4e9ZLuTAKqWW03F9","pFZP5JQG7iQjIQuC4Bku","pqHfZKP75CvOlQylNhV4","vERmHY5ZzBsIRPzH78Rb","papd083UqIoSWdSkh3fG","zAr1POVZUrr1zkX0T94t","EIdfNdxb4fnsE39tEAB1","5Spsi3mCH9e7futpnGE5","G1QUjBCuRBbLbAmYlTgl","6wsXez7Nsh9HQSbtqwIK","SfXg52J54dixBlOl016v","Yf6I1OzNemrgGRsc8z1I","z0gdR3nhVl1Ig2kiEigL","wAWUBOIVEUw9IEUYoNzR","6XNSYkDqZ1blajSVtPok","LNzr3u01PIEDg0fRlvE7","GxxMAMfQkDlnqjpzjLHH","RBnMinrYKeccY3vaUxlZ","sZXOZNdVMeHi5J0uiQF7","8ng6vvUHRpznlJL92xmU","x5tvfc5X0Qh4cqmLpgrs","20ptB7Wn4Q2sMkAxK1qK","JaUVfDrFcfwGIsv8X2kN","iWydkXKoiVtvdn4vLKp9","HnnPtoATgzx4ubChwm24","C1DBnkwmDIzoLOPlBvSg","hIssydxXZ1WuDorjx6Ic","NacdHGUYR1k3M0FAbAia","87QJokeqzysrKtZFt7jl","wJ5MX7uuKXZwFqGdWM4N","tZssYepgGaQmegsMEXjK"]}},"additionalProperties":false},"background":{"default":{},"type":"object","properties":{"category":{"description":"Pick any background from this category (GET /v1/options backgrounds.categories).","type":"string","enum":["Minecraft","Mario Kart","GTA V","Subway Surfers","Satisfying","Backrooms","Roblox"]},"assetId":{"description":"A background video id from GET /v1/options backgrounds.assets, or your own upload.","type":"string","minLength":1},"ownUrl":{"description":"Your own footage by public https URL. Video is converted for rendering (H.264 baseline, 1080x1920, cropped to fill, silent); files up to 300 MB / 10 min.","type":"string","minLength":1,"maxLength":2048}},"additionalProperties":false},"music":{"default":{},"type":"object","properties":{"assetId":{"description":"Background music id from GET /v1/options music. Omit for none.","type":"string","minLength":1},"ownUrl":{"description":"Your own track by public https URL. Converted to MP3 for rendering; files up to 30 MB / 10 min.","type":"string","minLength":1,"maxLength":2048},"volume":{"description":"0-100. Default 30.","type":"integer","minimum":0,"maximum":100}},"additionalProperties":false},"captions":{"description":"Text captions pinned to messages, up to 20.","maxItems":20,"type":"array","items":{"type":"object","properties":{"afterMessage":{"type":"integer","minimum":1,"maximum":9007199254740991,"description":"1-based number of the message this caption follows (at most the number of messages)."},"text":{"type":"string","minLength":1,"maxLength":120,"description":"Caption text."},"delayMs":{"default":0,"description":"Milliseconds after that message appears. Default 0.","type":"integer","minimum":0,"maximum":10000},"position":{"default":"below_card","description":"Default below_card.","type":"string","enum":["below_card","above_card"]}},"required":["afterMessage","text"],"additionalProperties":false}},"hookText":{"description":"Hook shown before the conversation.","type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":120,"description":"The hook line."},"seconds":{"default":2,"description":"How long the hook holds before the chat starts. Default 2.","type":"number","minimum":0.5,"maximum":10}},"required":["text"],"additionalProperties":false},"endCard":{"description":"End card shown after the last message.","type":"object","properties":{"line1":{"type":"string","minLength":1,"maxLength":80},"line2":{"type":"string","minLength":1,"maxLength":80},"seconds":{"default":2.5,"description":"How long the end card holds. Default 2.5.","type":"number","minimum":0.5,"maximum":10}},"required":["line1"],"additionalProperties":false},"sfx":{"description":"Message sounds, each default false, plus an optional style (iphone | phone-1 | phone-2 | phone-3; default phone-1).","type":"object","properties":{"send":{"default":false,"type":"boolean"},"receive":{"default":false,"type":"boolean"},"typing":{"default":false,"type":"boolean"},"style":{"description":"Sound set. iphone (recommended): Apple's original send and receive sounds, no typing sound; these may be copyrighted and you are responsible for how you use them. phone-1, phone-2, phone-3: our phone-style send and receive sounds plus a typing sound. Omitted = phone-1 ('phone' is accepted as phone-1).","type":"string","enum":["iphone","phone-1","phone-2","phone-3","phone"]},"sentence":{"description":"Play the sound after each message is read: after every text line, 60 ms after the voice ends, the sound set's send sound (after 'me' lines) or receive sound (after the other person's), then the linePause gap before the next line. Replaces the send/receive sound when a text bubble appears (photos keep theirs; typing unchanged). Changes each line's pause, so changing it re-voices. Default false.","type":"boolean"}},"additionalProperties":false},"layout":{"description":"Chat card layout.","type":"object","properties":{"style":{"default":"card_over_background","description":"The chat card over the background video.","type":"string","enum":["card_over_background"]},"cardWidthPct":{"default":80,"description":"Card width as a percentage of the frame. Default 80.","type":"integer","minimum":40,"maximum":100},"cardHeight":{"default":"fit","description":"fit (default): the card grows with the conversation, then scrolls. pages: the card sits at the top, grows one bubble at a time and clears to a fresh card (header kept) when it fills, like most text-story shorts. full: fixed-height card, the wizard's legacy look.","type":"string","enum":["full","fit","pages"]}},"additionalProperties":false},"cutAfterMessage":{"description":"1-based message number. The video reports cutAtMs: where message N+1 appears (or the end of the video when N is the last message), so you can split the MP4 there.","type":"integer","minimum":1,"maximum":500}},"required":["messages"],"additionalProperties":false,"description":"Plain-text guide for agents: https://api.ghostshorts.com/v1/templates/fake_text_message.txt"},"defaults":{"platform":"imessage","theme":"dark","pacing":"normal","linePause":"natural","background":{"assetId":"92992e79fd7bc6f5","category":"Subway Surfers"},"aspectRatio":"9:16"},"freeTools":["preview"],"paidSteps":[{"step":"voices","credits":"Only when voices is sent (a silent video meters no narration): 1 credit per minute of voiced text, estimated at 15 characters per second (legacy plans); included on current plans within fair use"},{"step":"render","credits":"1 video from the monthly allowance (current plans); export counter on legacy plans"}],"notes":["The conversation is yours; nothing is generated for it.","Length: up to 500 messages, and the video can be up to 10 minutes (about 400 short voiced bubbles). A conversation estimated past 10 minutes (15 characters a second of speech, plus delays) is refused with INVALID_INPUT at messages before anything runs; a finished video that still comes out over 10 minutes fails with VIDEO_TOO_LONG and the narration is given back. Split a longer story into parts.","Group chats: send members (1 to 5 people, everyone but you; members[0] is shown like the contact) instead of contact, and use each member id as messages[].sender (\"me\" for you, \"them\" is not used). Each member can carry a name, avatarAssetId and voiceId (omitted = a default voice nobody else has); send voices.me only. groupName sets the header title (default: the members' names). Each incoming bubble shows its sender's name and picture in the platform's own style. iMessage, WhatsApp and Instagram only: Tinder chats are one-to-one. Narration is still priced by characters, so a group costs the same as a 2-person chat of the same length.","Free layout preview: POST /v1/previews with these same inputs answers a previewUrl page that plays the whole chat silently with its exact hook, end card, card layout, theme and background, plus a projectId to create the video from. 0 credits, no video used.","Re-renders: POST /v1/videos with the projectId of an earlier video (or preview) and the full inputs. Renders 2-3 of a project use no video; unchanged messages, voices, pacing, linePause and voiceSpeed reuse the voices (no narration charged).","Each message stays on screen for the length of its voice clip; delayMs (or pacing) adds a gap before it.","linePause sets the silence after each voice line (snappy 0.05 s, tight 0.15 s, natural 0.35 s, relaxed 0.6 s); it is part of each clip, so it lengthens every bubble's hold. A voice line that is all silence (for example \"...\") is cut to a short silence as long as that pause (0.15 s minimum).","voiceSpeed (0.8 to 1.2, default 1.0) speeds up or slows down both voices; each bubble holds for its clip, so a faster voice makes a faster chat.","Omit voices for a silent video with music only; bubble timing then comes from each message's delayMs (plus its gap row and typing window, as when voiced) and a reading hold: clamp(600 + 55 x words, 1200, 4500) ms for a text message, 3000 ms for an image, then a 1000 ms tail; no narration is metered.","With no background fields, the Subway Surfers default background is used.","Own media by URL is fetched before anything is charged. The same URL is reused for 30 days without re-fetching; up to 20 new URLs per day. Failures: MEDIA_FETCH_FAILED, MEDIA_INVALID, MEDIA_TOO_LONG, MEDIA_QUOTA_EXCEEDED.","Gap rows and typing bubbles are timed into the narration when voices are generated, so they are fixed for the video.","sfx.sentence: after each text line, the set's send sound (my lines) or receive sound (theirs) plays 60 ms after the voice ends, then the linePause gap (snappy 0.1 s, tight 0.2 s, natural 0.3 s, relaxed 0.5 s) before the next line; it replaces the bubble-start sound of text messages.","sfx.send / sfx.receive / sfx.typing play a short sound when a message is sent, received, or a typing bubble appears. sfx.style picks the set: iphone (recommended; Apple originals, no typing sound; may be copyrighted, your responsibility) or phone-1 / phone-2 / phone-3 (default phone-1).","hookText, endCard, captions, sfx and layout are objects; hookText is { text, seconds? }, not a bare string.","cutAtMs on the video is null until the render is queued, and null when cutAfterMessage was not sent."]}]