Tools reference

Once your agent is connected, it has access to four Popcorn tools.

create_movie

Kicks off a new movie from a natural-language brief. Returns immediately with a movie id; the agent then runs autonomously for several minutes (typically 3–10 min).

Input:

Field	Type	Description
brief	string	What you want made. Be specific about format.
duration	number?	Target duration in seconds. Optional; agent infers from brief if omitted.
orientation	string?	vertical, horizontal, or square. Optional.
style	string?	A visual style or reference. Optional.

Returns: { id: string } — the movie id. The movie is now being produced.

Tip for agents: be specific about format in the brief. “10-second reaction video to https://youtu.be/…”, ”30s UGC ad for <product>”, ”15s clip starting at 1:23 of <url> with new narration over it” all produce much better results than “make a video about X”.

get_movie

Polls the status of a movie. Call this every 15–30 seconds while the movie is running.

Input: { id: string }

Returns:

Field	Description
status	running, completed, or failed
video_url	URL of the finished video (when status is completed)
error	Reason for failure (when status is failed)

CRITICAL — completed without a video

If status is completed but video_url is missing or null, the movie agent stopped before delivering the final video. Do not report success. Instead, call send_movie_message(id, "...") asking why there’s no final video and whether the agent can continue producing it. Then resume polling.

This pattern means Popp likely needs a nudge to finish.

send_movie_message

Sends a follow-up chat message to an existing movie — the same effect as typing in the studio chat. Popp runs a new turn asynchronously (it can revise the script, regenerate a shot, swap music, etc.).

Input:

Field	Type	Description
id	string	The movie id.
message	string	What to tell Popp.

Returns: an acknowledgement that the message was received.

After sending a message, resume polling get_movie until the new turn settles, then call get_movie_messages to read what Popp did.

get_movie_messages

Reads the recent chat transcript so you can see Popp’s reply after sending a message.

Input: { id: string }

Returns: an array of recent messages between you and Popp.

Useful after send_movie_message to see what Popp actually changed, what tools it ran, and whether it has any clarifying questions back.

Typical flows

New movie, end-to-end

1. create_movie(brief)  →  { id: "abc-123" }
2. get_movie("abc-123") every 15-30s until status == "completed"
3. Hand back video_url to the user

Iterate on an existing movie

1. send_movie_message(id, "make scene 2 more dramatic")
2. get_movie(id) every 15-30s until status == "completed" again
3. get_movie_messages(id) to read Popp's reply
4. Hand back the new video_url

Studio link

Every movie is also viewable and editable in the Popcorn studio at:

https://popcorn.co/movie-chat/{movie_id}

Agents are encouraged to share that link with the user so they can open the movie in the studio at any time.

Want more?

For deeper integration, the Popcorn skill packages all the patterns above (polling intervals, error recovery, studio links, message handling) into a drop-in skill for any agent that supports them.