create_video
ChatGPTStart a new video with Velo's agent. The agent replies and usually asks the user what it needs in message or pending_question: show it to the user and send their answer with edit_video. The reply has the same fields as get_video_status; follow the video there. For a website, use flow=auto with the URL in message: Velo opens the site in its own browser, so no recording is needed. If the site needs a sign-in, the status becomes Needs your action. For a document, a screen recording or a video of the user, add the file with upload_file first, then call this with that chat_id and the matching flow. If the user asked to review the script before the video is built, that belongs in message, even for a video without narration. Starting a video doesn't approve a later script. Spends credits. Not safe to retry: if the call fails unclearly, check list_videos before calling it again.
edit_video
ChatGPTSend the user's next message to a video: their reply to a question in message, an answer to pending_question, or a new request such as a change to the draft. Any files waiting from upload_file go with it. The reply has the same fields as get_video_status. Answering a question: - For a question in message only, send the user's words without pending_question_id. If they answered on the Velo page meanwhile, refresh get_video_status first; a prose question has no stale-question ID protection. - For pending_question, pass its id with the user's reply in message, or their choices in answers. Partial answers are accepted. - If that question was already answered or replaced, nothing is sent: the reply has submitted=false, the latest state and since_you_looked, and the conversation goes on from that state: a one-line note of what the user did in Velo, then their request applied to the current question, or the new question if Velo asked one. An "approve" of a script the user rewrote on the Velo page is applied to the rewritten script (notice says so). - A question with free_text_ok=false can only be completed at preview_url. Script approval is the user's go-ahead for the version they were shown: message="approve" with that script's pending_question_id. The first request, a voice pick or opening voices_url is not an approval. A reply with changes, conditions or any doubt goes in message as the user gave it. Spends credits. Not safe to retry: if the call fails unclearly, check get_video_status before calling it again. While the video is Working, this returns a busy error; wait until get_video_status shows another status.
export_video
ChatGPTRender the video's current draft into the finished video, on the user's own request to export, render, download or share it, made in this conversation after the draft is ready. A ready draft, an approved script and "decide for me" answers are not that request: the user watches the draft at preview_url and says when they want the final video. Rendering is free; automatic repairs after a render error may use credits. The status moves to Finishing; follow it with get_video_status until Done, which includes video_url when sharing is enabled. Calling it again while the draft is rendering, or after it has been rendered, starts nothing and returns the current status. If an export call fails unclearly, check get_video_status before requesting another export; the renderer may have accepted work before its handle was saved.
get_video_status
ChatGPTGet one video's current state: its status, the agent's latest message, any question waiting for the user, and since_you_looked, what happened in Velo since your last look. Use it after create_video, edit_video or export_video, or when the user asks how a video is going, and before acting on a request after the user was away. status is one of: - Working: Velo's agent is busy; message is its latest progress line. - Finishing: the final video is rendering; render_percent shows how far along it is. - Needs your answer: show pending_question to the user, then send their reply with edit_video. With no pending_question, message is the agent's reply and it's the user's turn. If pending_question.free_text_ok is false, the user completes that step at preview_url instead. - Needs your action: Velo's browser needs the user (pending_action), for example to sign in to a site. They open preview_url, choose Take control, sign in if needed, then Resume agent; their credentials go into that browser, not into the chat. The status changes once they're back; sending a message doesn't resume that browser. - Draft ready: a draft is ready to watch at preview_url. Read message too: Velo may ask a follow-up question there. Send the user's answer or changes with edit_video; export_video makes the final video when the user asks. - Done: the video is finished. video_url is included when sharing is enabled; give it to the user exactly as returned. - Out of credits or Failed: error.message says what happened and what to do next. While Working or Finishing, this call waits for a change before it returns, so call it again right away. Stop calling it on any other status. preview_url opens the video's chat in Velo, where the user can watch it and answer too. If rate limited, wait retry_after_seconds before retrying.
list_avatars
ChatGPTList the avatars (AI presenters) the user can put in a video, grouped as their own, shared in the workspace, then public. Use it when the user wants a presenter on screen, and pass the chosen id as avatar_id to create_video or edit_video. A pending_question that asks for an avatar carries its own choices: answer from those instead. If Velo asks in message without choices, use this catalog.
list_files
ChatGPTList the files added to a video that haven't been sent to Velo's agent yet (files), and any still uploading (uploading). Use it after the user says they've added files at upload_page_url, to confirm the files arrived before calling create_video or edit_video, which send them all. While an upload is in progress, it waits briefly for it to finish before answering.
list_videos
ChatGPTList the user's videos in this workspace, most recently active first, with each one's chat_id, title, status and preview_url. Use it to find the chat_id of a video the user mentions, or to see whether a create_video call that failed unclearly went through. When next_cursor is returned, pass it back as cursor for the next page.
list_voices
ChatGPTList the voices the user can narrate with, grouped as their own, shared in the workspace, then public. Use it when Velo asks for a voice in message without picker choices, or when the user wants to choose or change the narration voice, and pass the chosen id as voice_id to create_video or edit_video. voices_url opens Velo's voice library, where the user can listen and then come back to choose; opening it selects nothing. A pending_question that asks for a voice carries its own choices: answer from those instead.
upload_file
ChatGPTAdd files (a document, a recording, images, a logo) to a video. With files (ones the user attached in this conversation), Velo adds them directly and returns them in files; any it couldn't take come back in refused, with upload_page_url for adding them another way. Without files, it returns upload_page_url, a link where the user adds files in their browser, then chooses Done uploading to close that link; those files reach Velo only through that page, so the next step is the user saying they're done, and list_files confirms they arrived. Without chat_id, it returns a new chat_id: pass it to create_video to start the video with these files. With an existing video's chat_id, the files go with its next edit_video. Links expire after expires_in_seconds or close when the user finishes. Call again with the same chat_id for a fresh link to add more files.