accept_image_candidate
ChatGPTAccepts a candidate still, replacing the shot's current image. expectedCandidateUrl guards against accepting a different, newer candidate than the one being reviewed.
accept_video_candidate
ChatGPTAccepts a candidate video clip, replacing the shot's current clip. expectedCandidateUrl guards against accepting a different, newer candidate than the one being reviewed.
analyze_song
ChatGPTStarts audio and lyric analysis: BPM, key, song sections, and transcribed lyrics. A script cannot be generated until this completes. Returns quickly once the run is under way; a short song can finish within that window and come back complete, otherwise poll get_analysis (or get_project's pipelineState, which reaches ANALYSIS_COMPLETE or ERROR) for the result.
apply_score_fixes
ChatGPTApplies the quality score's suggested fixes to the given shot numbers.
approve_creative_direction
ChatGPTApproves the creative brief (narrative, moods and theme). This is a real pipeline gate enforced server-side — script generation is blocked until it has been called, not just a UI checkbox.
approve_thumbnails
ChatGPTApproves the generated stills. This is a real credit gate enforced server-side — video rendering does not start until stills are approved.
assign_shot_sources
ChatGPTBulk-assigns source types across the plan — for example switching every shot to a visualizer preset.
brainstorm
ChatGPTAsks VidGen one creative-direction question about a project and returns its reply. Send only the brainstorm turns for this project: earlier brainstorm questions and replies, if any, plus the new question. Nothing else from the chat belongs in that list. VidGen keeps no brainstorm history between calls. Returns the reply directly when it arrives quickly, otherwise a job id that get_brainstorm_reply can retrieve once the reply is ready.
change_shot_source
ChatGPTChanges one shot's source: 'ai' (generated), 'user_image', 'user_video', or 'visualizer'. Returns the updated shot in the same shape get_shots reports it, plus restoredImage — true when switching back to 'ai' restored a previously-generated still.
compile_360
ChatGPTStarts or resumes the confirmed Studio master export at the quoted 4K, 6K or 8K resolution with project audio. Returns quickly; get_360_project reports progress. The server reuses completed masters and charges a new export once on success.
compile_video
ChatGPTStarts the compile pipeline: normalises and concatenates every rendered clip, mixes the track, applies the watermark policy, and appends the PulseJet Studios logo end-card. This step produces the finished video file and spends credits. Requires every shot rendered (or explicitly skipped). Returns quickly with the run under way; poll get_project for compileProgress/compileMessage and pipelineState reaching COMPLETE.
create_project
ChatGPTCreates a new empty project. kind defaults to MUSIC_VIDEO. A typical next step is uploading a song (upload_song) and running analyze_song.
delete_project
ChatGPTPermanently deletes a project and its media. Irreversible.
delete_shot
ChatGPTDeletes a shot from the plan.
download_project_archive
ChatGPTDownloads a zip archive of the project's raw materials: a README, a project.json manifest (prompts, shot plan, BPM, models), the final compiled video if present, the original audio, the reference photo if uploaded, and every shot's thumbnail/video/lip-sync file.
generate
ChatGPTStarts generation and spends credits. stage: 'thumbnails' generates the still for every shot; stage: 'videos' renders clips from approved stills; stage: 'all' does both. Returns quickly with the run under way; poll get_generation_progress, get_thumbnails or get_shots for progress.
generate_image_candidate
ChatGPTStarts generating an alternative still for a shot, for side-by-side comparison, without replacing the current one. Spends credits. Returns quickly with the run under way; poll get_shots with includeCandidates: true for candidate.imageGenerationStatus reaching IMAGE_COMPLETE or FAILED.
generate_scene_thumbnails
ChatGPTStarts generating a preview still for each scene — a cheap look at the visual direction before committing to a full shot plan. Returns quickly once the run is under way; poll get_scenes and check each scene's thumbnailPath for progress.
generate_script
ChatGPTStarts script generation — the scene breakdown across the track. Requires analysis complete and creative direction approved. Returns quickly once the run is under way; a fast run can finish within that window and come back complete, otherwise poll get_scenes (or get_project's pipelineState reaching SCRIPT_READY or ERROR) for the result.
generate_shot_plan
ChatGPTStarts generating the shot plan — individual shots with prompts and durations, derived from the scenes. Requires a script to exist. Returns quickly with the run under way; poll get_project (shotPlanProgress/shotPlanMessage, pipelineState reaching SHOT_PLAN_READY or ERROR) or get_shots once ready.
generate_song
ChatGPTWrites an original song with PulseJet AI from a description of the sound (style, mood, instruments, sung or instrumental) and, optionally, the customer's own lyrics, which are sung word for word. Spends credits as soon as the job is accepted: quote_song returns the exact cost for the chosen durationSec without spending anything, so the customer can agree to a real number before this is called. Returns quickly with the jobId and status in_progress; the song is written server-side and get_song_job reports when it is complete or failed. requestId makes the call idempotent: the same requestId with the same inputs returns the existing job instead of starting and charging a second one. Omit songProjectId for a new song; pass one to add a new version to an existing song project.
get_360_project
ChatGPTCurrent 360 eligibility, per-shot source and readiness, durable run status, export resolution, errors and available next actions. Read-only; reconnects resume from server state.
get_account_status
ChatGPTWhich PulseJet AI account this connector is acting as (display name, or an email with its local part masked), its plan, credit balance and premium-model eligibility, the scopes granted to this connection, and a readiness summary of what is in place before generation can run (credits, and whether generation is paused for this account right now).
get_analysis
ChatGPTThe completed analysis for a project: BPM, key, detected mood, song structure/sections and lyrics. A read-only view of what analyze_song produced.
get_billing_details
ChatGPTFull billing detail: plan, renewal date, invoice history and credit history. Heavier than get_credit_balance, which returns just the balance.
get_brainstorm_reply
ChatGPTRetrieves a brainstorm reply started by an earlier brainstorm call that had not finished yet, by its job id. The job id only exists in this connector process's own memory for a limited time, not in VidGen itself.
get_credit_balance
ChatGPTThe customer's current credit balance, plan, and premium-model eligibility, read live from the account.
get_feedback_status
ChatGPTThe current status of a feedback report the customer filed earlier: received, investigating or resolved, with the ticket key when one exists and when the report was submitted. The feedbackId comes from submit_feedback's receipt.
get_generation_progress
ChatGPTLive accepted-clip status counts plus separate candidate rerender progress. percentComplete describes accepted clips only; candidates reports running renders, failures and results awaiting explicit review.
get_music_capabilities
ChatGPTWhat PulseJet AI can do when writing a song from a description and optional lyrics: the supported song lengths with the credits each costs (the durationSec values quote_song and generate_song accept), the text limits on the description and lyrics, which music features are on, and the web address of the song studio. There is no separate style field; the description carries style, mood, instruments and whether the song is sung or instrumental.
get_narrative_suggestions
ChatGPTAI-proposed narrative directions for the video, based on the analysed song. The result is generated once and persisted, then reused on later calls; refresh: true discards the cached set and generates (and persists) a new one.
get_project
ChatGPTThe live state of one project: pipeline state, scenes, and shot-by-shot progress with each shot id. Reflects state as of the moment of the call — generation status changes quickly while shots are actively rendering. Also carries the in-progress/error fields for shot-plan generation, compile, upscale and quality scoring, so a caller that started one of those can poll here rather than a separate endpoint. compiledVideoUrl/upscaledVideoUrl are real, directly-fetchable URLs once hasCompiledVideo/hasUpscaledVideo are true — this is how to actually retrieve the finished output.
get_scenes
ChatGPTThe full scene list with every field: title, timings, narrative, location, lighting, camera movement and dominant emotion.
get_score
ChatGPTThe project's quality scorecard: per-goal scores (productionQuality is included in every scorecard), an overall score, a short summary, the weakest shots, and concrete fix suggestions tied to shot numbers — the input apply_score_fixes expects. Reflects whatever score_project last produced.
get_shot_image
ChatGPTFetches one shot's current still image and returns it as real inline image content the model can see, not just a URL. Capped to a few MB — for a shot whose image is unusually large, or to look at many shots at once, use get_shots/get_thumbnails for URLs instead.
get_shots
ChatGPTEvery shot with the fields needed to steer a shot plan: id, number, scene, type, prompts, duration, source type, generation status and staleness, plus whether a still or clip exists. imageUrl/videoUrl are real, directly-fetchable URLs (short-lived where presigned), or null if nothing has been generated yet; use get_shot_image to see a still inline instead of fetching a URL yourself. negativePrompt is reported once at the top level when every shot shares it, and per-shot only where one differs. The A/B candidate-review fields are omitted unless includeCandidates is true. Pass summary: true to browse a large plan cheaply: a fixed narrow field set (id, shotNumber, sceneId, durationSeconds, startTime, generationStatus, sourceType, hasImage, hasVideo, imageStale, videoStale) with no prompt or free-text fields at all — nothing is truncated, fields are left out outright, and the response's omittedFields array names exactly which ones. Read a shot with summary omitted first to see its current imagePrompt/negativePrompt/motionDescription/cameraInstruction/userNotes before editing it via update_shot — summary mode does not carry them at all, stale or otherwise.
get_song_job
ChatGPTThe state of one song-writing job started by generate_song: in_progress, complete or failed, with its length, the credits it cost and, once complete, a short-lived playable link to the MP3 (audio.url, valid until audio.expiresAt), a cover image link when one exists, a browser download link for the signed-in account, and nextStep use_song_for_video. A failed job carries the server's error text. A job still running after ten minutes is closed as failed by the server.
get_spectrogram
ChatGPTThe track's spectrogram — waveform and energy over time — computed once at analysis time.
get_thumbnails
ChatGPTThe generated still for every shot, with a real, directly-fetchable imageUrl (short-lived where presigned) and status. imageUrl is null only when nothing has been generated for that shot yet.
list_projects
ChatGPTThe customer's own projects, newest first, with pipeline state — the way to resolve a project the customer names to its id.
list_songs
ChatGPTThe customer's finished songs written with PulseJet AI, newest first: each song project's id, name, length and latestJobId (the completed version get_song_job reads and use_song_for_video takes). Songs still in progress or failed are not listed; get_song_job reads those by jobId. query filters by name; before continues from a previous result's nextCursor.
list_themes
ChatGPTThe current visual themes/styles catalog. scope: "dome" returns Dome Studio's set instead of the standard VidGen one. The catalog changes over time.
quote_360
ChatGPTAuthoritative AI 360 render quote for pending shots, or an explicit single-shot rerender. Owned footage is excluded from bulk AI work. Returns a source revision, cost, balance and refund policy; starts no work.
quote_360_master
ChatGPTCurrent Studio master export fee, readiness, resolution and immutable master identity. Reusing a paid successful master costs zero. Reads state without starting an export.
quote_song
ChatGPTThe credits a song of a given length costs, against the live balance: costCredits, creditsRemaining, affordable and shortfallCredits. Spends nothing and starts nothing; the figure is exactly what generate_song charges for the same durationSec, so the customer can agree to a real number before a song is written.
regenerate_shot_image
ChatGPTStarts regenerating one shot's still image only, without rendering video. Spends credits. Returns quickly with the run under way; poll get_shots or get_thumbnails for generationStatus reaching IMAGE_COMPLETE or FAILED.
reject_image_candidate
ChatGPTDiscards a candidate still, keeping the current image.
reject_video_candidate
ChatGPTDiscards a candidate video clip, keeping the current clip.
render_360
ChatGPTStarts the exact quoted AI 360 batch or single-shot rerender after explicit confirmation. Returns quickly; get_360_project reports progress. Changed quotes are rejected before charging. Failed attempts are refunded.
render_all_pending_videos
ChatGPTStarts re-rendering video for every eligible shot in the project and spends credits per shot. model optionally forces a specific video model for all of them. Returns quickly with the run under way; poll get_generation_progress or get_shots for progress.
render_shot
ChatGPTStarts rendering (or re-rendering) one shot's video clip and spends credits. regenerateImage: true regenerates the still first. model optionally overrides the video model for this shot only. Returns quickly. With an existing clip this creates an A/B candidate: get_shots with includeCandidates: true exposes candidate.generationStatus and review media; explicit accept_video_candidate promotes the result. Without an existing clip, progress uses generationStatus. get_generation_progress reports candidate progress separately.
reorder_shots
ChatGPTReorders the shots in a project. Takes every shot id in the desired order. Returns the shots in their new order (id + shotNumber only) and the total count.
score_project
ChatGPTStarts the automated quality score over the project. Only available once the project has compiled. Returns quickly with the run under way; poll get_project for scoreStatus reaching complete or error, then get_score for the full findings.
search_features
ChatGPTSearches VidGen's feature registry for anything outside the main wizard: renaming, sharing, downloading, billing, account settings and similar product questions.
set_360_resolution
ChatGPTSelects 4K, 6K or 8K before 360 work begins. The server locks this setting when rendering or exporting starts.
set_artist_in_video
ChatGPTTurns 'pictures of the artist' on or off for a project. Requires a reference photo to already be uploaded (upload_reference_photo). Implemented via goalContext.featureArtist, the same field the creative-direction wizard writes.
set_bpm
ChatGPTOverrides the detected BPM, or re-runs detection with a different strategy.
show_360_media
ChatGPTDisplays a flat equirectangular preview and supplies an authenticated spherical Studio viewer link plus a temporary master download. A flat preview is not an interactive 360 viewer.
show_shot_media
ChatGPTDisplays a shot's still image and playable video clip in the customer-visible media card. Call this after get_shot_image when the user asks to see media. Its card reports image/video load failures explicitly. Do not embed the remote URLs as Markdown media or claim visibility unless the card loads.
skip_shot
ChatGPTExcludes a permanently-FAILED shot from the compile-completeness requirement, so the video can be compiled without it. Only valid on a shot whose generationStatus is FAILED.
stop_generation
ChatGPTStops an in-flight generation run.
submit_feedback
ChatGPTFiles feedback or a bug report on the customer's behalf. This reaches the PulseJet team.
trim_song
ChatGPTSets the portion of the track the video covers. Shot timings are derived from this window, so changing it after a shot plan exists invalidates that plan.
update_project
ChatGPTUpdates project settings and creative direction. Maps to PATCH /api/projects/:id — the same endpoint the project settings UI writes to. Server allow-list: name, goals, goalOther, goalContext, selectedTheme, script, preferredVideoModel, preferredImageModel, outputResolution, aspectRatio, lipSyncEnabled, vjLoopDurationSeconds, vjLoopWorldIds, brandId — any other field in patch is silently ignored. script takes a full { scenes: [...] } object, which is how a caller-authored scene plan gets written in. Shots are a separate resource and are not writable through this endpoint — see update_shot / generate_shot_plan.
update_scenes
ChatGPTReplaces the full scene list. Maps to PATCH /api/projects/:id, writing the script.scenes field — the same endpoint update_project writes, scoped to one field. This overwrites script.scenes wholesale; it does not merge, so a caller changing one scene still sends the complete array. Also how a caller-authored scene plan gets written in.
update_shot
ChatGPTUpdates one shot and returns the updated shot in the same shape get_shots reports it. Maps to PATCH /api/shots/:id. Server allow-list: imagePrompt, negativePrompt, motionDescription, cameraInstruction, durationSeconds, userNotes, beatAlignment, sourceType, visualizerPreset, visualizerSeed — any other field in patch is silently ignored.
update_transcript_line
ChatGPTCorrects one line of the transcribed lyrics. Lyrics feed the script, so a corrected line changes downstream script generation.
upload_reference_photo
ChatGPTUploads a photo of the artist as an identity reference. Once set, generated shots can feature the real person — this is what makes "pictures of the artist" possible in the video. Two ways to supply the bytes — see filePath vs filename/contentType/stagingKey below; filePath only works when this connector runs locally.
upload_shot_image
ChatGPTUploads the customer's own still for one shot, replacing generation for that shot. Two ways to supply the bytes — see filePath vs filename/contentType/stagingKey below; filePath only works when this connector runs locally.
upload_shot_video
ChatGPTUploads the customer's own video clip for one shot, replacing generation for that shot. Two ways to supply the bytes — see filePath vs filename/contentType/stagingKey below; filePath only works when this connector runs locally.
upload_song
ChatGPTUploads an audio file as the project's track. Accepts MP3, WAV, AIFF, M4A and FLAC. Two ways to supply the bytes — see filePath vs filename/contentType/stagingKey below; filePath only works when this connector runs locally. analyze_song is the typical next step once the upload completes.
use_song_for_video
ChatGPTStarts a music video from a finished song written with PulseJet AI: creates a new video project with the song already in place (a copy of the MP3, so later changes to the song cannot affect the video) and returns its videoProjectId, which every project tool then accepts as projectId. Spends no credits. jobId names the song version; omitted, the newest completed version is used. The new project starts at SONG_UPLOADED, so nextStep is analyze_song. requestId makes the call idempotent: repeating it returns the same video project rather than a second one.