# Connect your accounts and choose an agent Source: https://docs.voyager.so/account/accounts-and-agents Understand your Voyager account, connect an agent, and choose which account powers your chat. Your Voyager account signs you into the app; your agent account supplies the AI that works with you in chat. Chat uses your own Claude, ChatGPT or Google account (signed in with a subscription or an API key), Voyager models on a Voyager plan, or an Anthropic, OpenAI, Gemini or xAI API key you add in Voyager. For example, you can sign in to Voyager, use your Claude subscription for chat, and generate images with your own fal key. Each connection has its own purpose and billing. > [!NOTE] > > A paid Voyager plan is optional. A free Voyager account plus your own Claude or ChatGPT is enough to finish setup and chat. Your own media keys generate media without a plan. ## Know which account does what | Connection | What it does | Where usage is billed | | - | - | - | | Voyager account | Signs you into Voyager and selects your workspace | Free; signing in does not require a paid plan | | Claude | Powers the agent through Claude Code, signed in with your Claude subscription or an Anthropic API key | Your Claude plan, or Anthropic per use | | ChatGPT | Powers the agent through Codex, signed in with your ChatGPT subscription or an OpenAI API key | Your ChatGPT plan, or OpenAI per use | | Google | Powers the agent through Google's connection, signed in with your Google account or a Gemini API key | Your Google account, or Google per use | | Voyager models | Powers the agent using models available on your Voyager plan | Your workspace's Voyager credits | | Your own API key | Powers the agent with an Anthropic, OpenAI, Gemini or xAI key saved on that provider's card | The provider bills your account per use | | Image, video and voice providers (**Apps & Models → Providers**) | Make images, video, voices, music, and sound effects | The provider or Voyager account used for that generation | Your Claude or ChatGPT covers agent usage under that provider's terms. It does not supply Voyager credits or pay for media generation. ## Manage your connections Your Voyager sign-in and plan are in **Settings → Account**. Every other account and key is in **Apps & Models → Providers**; the **Providers** link at the bottom of the Settings list takes you there. ![The Settings → Voyager account page. The Voyager card shows the Demo Studio workspace menu, a Creator badge and a Manage plan button, the signed-in email, the credits available with Updated just now, Auto-reload on with a Buy credits button, a Team box with Switch to Team and Manage team, the Plan & billing row reading Change plan, add credits, see usage and invoices, and a Promo code field with Apply. Below it, an Other accounts and AI providers row with an Open Providers button, then the Model choices section with the Show advanced model choices switch.](https://mintcdn.com/voyager/gEgW5f4IO2eEELDK/images/screenshots/settings-voyager-account.light.png?fit=max\&auto=format\&n=gEgW5f4IO2eEELDK\&q=85\&s=46fdf4987eb3ee0531e44b12b1c75aff) Settings → Account holds your Voyager sign-in, plan and credits. Other accounts are one click away in Providers. In **Apps & Models → Providers**, each provider has a card. Providers that need you are under **Needs attention**, working ones under **Connected**, and the rest under **More providers**. Open a card to sign in, add an API key, or sign out. ![The Apps & Models page on its Providers tab, with Apps and Models tabs beside it. The Connected group shows Voyager, Claude and ChatGPT cards, each with how many models you can use. Below them, More providers lists Google, xAI, Higgsfield, fal, ElevenLabs and others with Connect buttons. The Image, video and voice order button sits in the toolbar.](https://mintcdn.com/voyager/gEgW5f4IO2eEELDK/images/screenshots/connectors-providers.light.png?fit=max\&auto=format\&n=gEgW5f4IO2eEELDK\&q=85\&s=33844673fd00a2ec5e3f60eff3f50ae4) Providers shows every account Voyager can use, grouped by whether it is working. For a new connection, follow [Connect Claude](/setup/connect-claude), [Connect ChatGPT](/setup/connect-chatgpt), or [Voyager models and media](/setup/voyager-models). To use Google for chat, open the **Google** card and choose **Sign in** to use your Google account, or add a Gemini API key. Voyager installs and updates Google's connection for you when you sign in. ### Add a second ChatGPT or Claude account 1. Open the **ChatGPT** (or **Claude**) card in **Apps & Models → Providers**. 2. Expand **Advanced**. 3. Beside **Another ChatGPT account**, choose **Add**. 4. In the dialog that opens, give the account a name such as "Work", then continue and sign in. ![The Add a ChatGPT account dialog. It explains that each ChatGPT account gets its own sign-in and appears as its own provider in the model picker. An Account name field reads Personal, with the hint Shown as ChatGPT · Personal in the model picker, and Cancel and Continue buttons.](https://mintcdn.com/voyager/gEgW5f4IO2eEELDK/images/screenshots/connectors-add-account.light.png?fit=max\&auto=format\&n=gEgW5f4IO2eEELDK\&q=85\&s=d4138e02671dffb98af6180bea2fc2b2) Name the second account so you can tell it apart in the model picker. Each account has its own sign-in. You can select personal and work accounts separately in the model picker. **Advanced** also has **Bring in from Codex** (or **Bring in from Claude Code**), which brings that agent's skills, plugins and connections into Voyager. ### Chat with your own API key 1. Open the **Claude**, **ChatGPT**, **Google** or **xAI** card in **Apps & Models → Providers**. 2. Under the **Anthropic API key**, **OpenAI API key**, **Google API key** or **xAI API key** row, choose **Add API key**. Use **Get an API key** if you need to create one. 3. Paste the key into **Paste your API key** and choose **Save**. The key's models appear in the chat's model picker under that provider. > [!WARNING] > > Requests through your own API key are billed per use by that provider, separately from any Claude or ChatGPT subscription. To connect your own media keys, follow [Generation providers](/account/generation-providers). ## Workspaces and teams If your Voyager account belongs to several workspaces, use **Switch workspace** under **Signed in** in **Settings → Account** to choose the one Voyager uses. Check the workspace name before buying credits or starting paid work. Individual plans are for one person. On a Team plan, everyone in the workspace shares its plan and one pool of credits. The **Team** row in **Settings → Account** has **Manage team**, which opens the Voyager website to invite teammates and choose admins. If it shows **Needs a seat**, ask a workspace admin to give you a Voyager seat. ## Choose the agent for a chat Open the model picker beside the chat composer. Tabs across the top switch between your providers; the open tab lists its models with what each is for. **More models** shows every model, with search and favourites. **Advanced** sets speed and effort for the chosen model. ![The compact model picker open above the composer. Provider tabs run across the top, such as Claude, ChatGPT and Voyager. Below them, the open tab's models, each with a short line about what it is for. At the bottom, More models and Advanced rows.](https://mintcdn.com/voyager/gEgW5f4IO2eEELDK/images/screenshots/accounts-model-picker.light.png?fit=max\&auto=format\&n=gEgW5f4IO2eEELDK\&q=85\&s=c369a42c4567d94b8cc8c4f19dca1723) Pick the provider tab first, then the model, so you know which subscription or balance you are using. Setup prefers your own ready accounts and keys before Voyager models: Claude first, then ChatGPT, then Google, then your own API keys, then Voyager. You can change the choice. Set the default for new chats in **Settings → General → Chats → AI for new chats**; individual projects can override it. When you switch to a different provider in an existing chat, the picker says **Continues in a new chat**. Voyager copies the conversation into a new chat on that provider. The button just before the model picker opens **Preferred models and apps**, where you pick which image, video, voice and music models and which creative apps Voyager uses. The same choices are under **Default models** in **Apps & Models → Models** and **Preferred apps** in **Apps & Models → Apps**. ## Understand the limits Available models depend on the connected account, its plan, and its installed software. **Show every AI option** in **Settings → General → Advanced → AI choices** reveals the full model list and reasoning effort controls. With it off, Voyager shows a smaller selection and uses medium effort. A plan badge on a Voyager model means that model needs a different Voyager plan. Choosing it offers the plans; it does not unlock the model automatically. The sidebar's **Usage** page shows your **Voyager credits** and what used them, including cloud computers and GPU renders, then the limits of your connected **Claude** and **ChatGPT** plans, then **Your keys**: the balance or spend of your own provider keys. Manage your plan in **Settings → Account**; see [Plans and credits](/account/plans-and-credits). If a model is missing or an account stops working, see [Setup problems](/help/setup-problems). > [card] [Choose how media generation is paid for](/account/generation-providers) > > Connect your own keys and set the order Voyager tries them. # Choose your generation providers Source: https://docs.voyager.so/account/generation-providers Connect media accounts and keys, choose their order, and control automatic fallback. A generation provider is the account Voyager uses to make an image, video, voice, music track, or sound effect. For example, you can use ChatGPT for the conversation and your fal key for the video. The agent subscription and the generation provider are separate connections, with separate bills. ## Find your providers Open **Apps & Models → Providers**. Each provider has a card: working ones are under **Connected**, ones that need you are under **Needs attention**, and the rest are under **More providers**. Open a card to sign in, add or replace a key, or turn it off. | Provider | Connection | What it offers | | - | - | - | | Higgsfield | Sign in to your Higgsfield account, or a Higgsfield API key | Images and video | | fal | Your fal API key | A broad catalog of image and video models | | Google | Your Google API key | Gemini images and speech, and Lyria music | | ElevenLabs | Your ElevenLabs API key | Voices, music, and sound effects | | Fish Audio | Your Fish Audio API key | Voices | | Inworld | Your Inworld API key | Narration and voice clones on your own Inworld account | | Runway | Your Runway API key | Runway's own image, video, voice and sound models | | BytePlus | Your BytePlus API key | Images and video | | ChatGPT | Your Codex, signed in with ChatGPT | Images on your own ChatGPT plan | | Sume | Your Sume API key | Seedance, Veo and MiniMax video, and Nano Banana and GPT Image images, billed to your Sume balance | | OpenAI | Your OpenAI API key | GPT Image 2, 2.5 and 2.6, billed to your OpenAI account | | Voyager | Your Voyager account | Generation paid with your workspace's Voyager credits | A provider cannot run every model just because it is connected. Voyager uses the first provider in your order that has the model you asked for. ## Add your own media keys Your own keys work without a paid Voyager plan. The provider bills your account directly. 1. In **Apps & Models → Providers**, open the provider's card, such as **fal**. 2. Choose **Add API key**. Use **Get an API key** if you need to create one. 3. Paste the key into **Paste your API key** and choose **Save**. Voyager checks the key when you save. 4. Check that the card now says **Connected** before starting a generation. ![The fal card open, with its API key row expanded. A Paste your API key field holds a pasted key, with Paste, Get an API key, Cancel and Save buttons.](https://mintcdn.com/voyager/gEgW5f4IO2eEELDK/images/screenshots/providers-add-key.light.png?fit=max\&auto=format\&n=gEgW5f4IO2eEELDK\&q=85\&s=bd4c0e386e6fd53a36eba9d5d1a9826e) Paste the key on the provider's card. Voyager checks it with the provider when you save. If a provider doesn't accept the key, the card says so. Choose **Replace API key** and paste the whole key again. A Runway key comes from the Runway developer portal at dev.runway.com and spends your Runway API credits, which are separate from a Runway app subscription. Runway models run only on your Runway key; Voyager does not fall back to another provider for them. A Sume key comes from sume.com/dashboard/api-keys. Sume runs Seedance, Veo and MiniMax video and Nano Banana and GPT Image images, and those generations are billed to your Sume balance, not your Voyager credits. An OpenAI key comes from platform.openai.com/api-keys. It runs GPT Image 2, 2.5 and 2.6 (Flare and Sunburst) directly with OpenAI, including edits, masks and transparent backgrounds, billed to your OpenAI account. OpenAI may ask you to verify your organization before its key can make images. This key is separate from signing in to ChatGPT. An Inworld key comes from platform.inworld.ai/api-keys: copy the **Basic (Base64)** key as shown. Ask the agent to narrate with Inworld, or to clone a voice into your Inworld account. Inworld narration runs only on your Inworld key and bills your Inworld account; Voyager does not fall back to another provider for it. Cloning a voice needs a key with Voice write access. Keys entered here are saved in your system's secure storage, not in project files. Paste keys into the provider cards, not into a chat. If Voyager finds a key you already set up on your computer, the card says it comes from this computer's settings. Check that it is the account you intend to pay with. A key you save in Voyager takes precedence over it. ## Set the provider order Choose **Image, video and voice order** at the top of **Apps & Models → Providers**. A provider's card also shows its place in the order, with a **Change order** link. ![The Image, video and voice order dialog, reading Voyager uses the first one in your order that has the model. Two rows: fal, API key ending in a few characters, and Voyager, Signed in · Demo Studio, each with an on switch, up and down arrows and a ••• menu. Below them a collapsed Not set up section. At the bottom, the If one can't finish, try the next provider switch is on, beside a Done button.](https://mintcdn.com/voyager/gEgW5f4IO2eEELDK/images/screenshots/providers-order-dialog.light.png?fit=max\&auto=format\&n=gEgW5f4IO2eEELDK\&q=85\&s=c48f561f4b25c57cd3de4a9d4a1c233e) The order decides which provider Voyager tries first. The switch at the bottom controls whether it moves on when one can't finish. 1. Move a provider with its up and down arrows, or open its menu and choose **Move to top** or **Move to bottom**. 2. Turn off the switch beside any provider you do not want used for new generations. It then reads **Off: new generations skip it**. 3. Check **If one can't finish, try the next provider** at the bottom. 4. Choose **Done**. Providers you haven't connected are folded under **Not set up**; choose **Set up** to connect one. On a fresh setup, the order follows the table above, with BytePlus turned off: Higgsfield, fal, Google, ElevenLabs, Fish Audio, Inworld, Runway, BytePlus, ChatGPT plan, Sume, OpenAI, then Voyager credits. Changes apply to new jobs. They do not move a job that is already running to another account. ## Generate images on your ChatGPT plan If you pay for ChatGPT, Voyager can make images on that plan through the Codex on your computer. Sign in to ChatGPT in **Apps & Models → Providers → ChatGPT**. The card's **Advanced** section then shows **Images through ChatGPT**, which uses the ChatGPT account Codex is signed in to on this computer. There is nothing to paste into Voyager. When your chat uses a native Codex account, images use that same account. Other chats use the default Codex sign-in on this computer. ChatGPT accounts added in Voyager as a second account cannot generate images through that connection yet because of OpenAI's current limitations. Those chats still generate through the default sign-in; estimates, run results and connections reports name that account and explain how to switch it. Ask the agent to generate on your ChatGPT or Codex subscription. Each image runs once in your signed-in Codex, uses your plan's Codex usage (and any OpenAI credits on your account once that runs out), and lands in your project like any other generation. It makes still images only. If your plan refuses the image before making it, for example because its usage limit is reached, and **If one can't finish, try the next provider** is on, Voyager makes it with GPT Image 2 on Voyager credits instead and tells you. Ask the agent to stay on your plan only if you never want that. A run that may have used your plan is never repeated automatically. Image generation is not on ChatGPT's Free plan. ## Understand automatic fallback **If one can't finish, try the next provider** is on by default. If a provider is out of credits, rejects its sign-in, or is down, Voyager tries the next usable provider in your order. It shows a notification that names the provider and where the generation continued, for example **Higgsfield is out of credits** with **Continued on Voyager credits** below it. Settings such as duration or resolution may change slightly to match what that provider offers; the notification lists the main changes. The button fixes the cause: **Open Apps & Models** when a provider is out of credits or not connected, **Update key** when it rejected your key, and **Reconnect** when a sign-in expired. > [!WARNING] > > Fallback can bill a different account. For example, a job that starts with your Higgsfield plan can continue using a personal API balance or Voyager credits. That includes a Higgsfield model the agent asked for by its Higgsfield name, when Voyager credits run the same model. Turn the switch off if you want Voyager to stop when the first usable provider fails. For one request, ask the agent to pin a provider: “Generate this with my fal account only. Pin fal and stop if it cannot run.” A pinned provider prevents fallback for that request. Fallback does not fix rejected inputs or a content-filter refusal. A model that needs a higher Voyager plan also needs you to choose an included model or change the plan; Voyager does not automatically charge another account to get around that refusal. ## Higgsfield plan versus API balance The **Higgsfield** card has two separate balances: * **Your Higgsfield account** signs in to your Higgsfield plan. Choose **Sign in** and finish in your browser. If Voyager finds an existing sign-in, it offers **Use this account**. * **Higgsfield API key** uses a separate prepaid API balance. Choose **Add API key**, paste the key as Higgsfield shows it, and choose **Save**. When both are connected, Voyager tries the plan before the API balance. With fallback on, a depleted plan can continue on the API balance. The notification says **Higgsfield plan credits ran out** and tells you where the generation continued. Turning fallback off prevents that move for a failed plan attempt. If no plan sign-in is connected, the saved API key can still be the Higgsfield connection used first. Remove the API key if you do not want Voyager to use that balance at all. ## Choose which models Voyager uses The order above decides who pays when several providers have the same model. To choose the model itself for each kind of media, use **Preferred models and apps**: the button just before the model picker in the composer, or **Apps & Models → Models**. Anything you leave alone stays on **Auto**. ## Check who paid Read any fallback notification and check the generation in the chat's activity. An out-of-credits message for fal or Higgsfield refers to that provider account, not necessarily your Voyager balance. Managed Voyager voices always use your Voyager account; rearranging the order does not move them to a personal key. For credit renewals and auto-reload, see [Plans and credits](/account/plans-and-credits). For expired sign-ins, refused keys, or stopped jobs, see [Generation problems](/help/generation-problems). # Understand plans and credits Source: https://docs.voyager.so/account/plans-and-credits Learn what uses Voyager credits, how prepaid billing works, and where to manage your plan in Voyager. Voyager credits pay for agent chat and cloud generation through your Voyager workspace. For example, making a video can use credits for reference images, video clips, voiceover, and chat with a Voyager model. If you use your own Claude subscription for the chat, that part uses your Claude account instead. ## A paid plan is optional You can sign in or sign up, finish setup, and work with your own Claude or ChatGPT (subscription or API key) and your own media keys without a paid Voyager plan. Those services keep their own billing and usage limits. An eligible workspace without a paid plan gets **Voyager Free**: a monthly allowance of Voyager credits, shared by the workspace. If Free isn't available for your workspace, Voyager says so, and your own Claude or ChatGPT still works. See [Voyager Free](#voyager-free) below. Voyager's paid plans are **Starter**, **Creator**, **Ultra**, and **GigaMax™**. Plans include credits and determine the models, parallel generations, cloud computers and Cloud GPUs available to you. * **Individual** plans are for one person. * **Team** plans are for 2 to 25 people: one bill, one shared pool of credits and admin roles. See [Team plans](#team-plans). * **Enterprise** is for larger teams, by arrangement. See [Voyager pricing](https://voyager.so/pricing) for current prices, allowances, model access, and offers. Downloading Voyager and using local editing tools does not itself spend Voyager credits. Chat or cloud generation used alongside those tools can. ## Voyager Free Free needs no card. It includes: * **Chat on Voyager's cheaper models.** Some use credits faster than others. * **Images** on the image models Free includes, up to a monthly limit. * **Stock narration** with premade voices, a few takes a month. Custom voices and managed takes need a paid plan. * **Your own agents and keys**: your Claude or ChatGPT subscription, your own API keys, and your own media keys work as on any plan. Free does not include video, music, sound effects, 3D, cloud computers, Cloud GPUs, or custom or managed voices through Voyager. When you ask for one, Voyager says which plan it starts on and offers **See plans** or **Use my own key**. Your own media keys can still generate video, music, sound effects and voices. Free's credits come with two limits: * **A monthly allowance** for the whole workspace. It resets each month, and unused credits don't roll over. * **A 5-hour limit**, so one sitting can't use the whole month. Generations still running count toward it. When a request doesn't fit, the chat shows a card that says **Free's 5-hour limit reached** or **This month's free credits are used**, and when Voyager picks up again. Bonus credits added to your workspace keep working after the monthly allowance is used. Free has no credit packs or auto-reload. When either limit is reached, wait until it resets, continue with your own agent subscription and keys, or upgrade. The notice above the message box shows what is left this month. See [Voyager pricing](https://voyager.so/pricing) for the current allowance and the models Free includes. ## What spends credits | Work | How it is paid for | | - | - | | Agent chat using Voyager models | Uses your workspace's Voyager credits | | Images and video generated through Voyager credits | Uses Voyager credits | | Voice, music, and sound effects generated through Voyager credits | Uses Voyager credits | | Managed Voyager voices | Uses Voyager credits | | Work on Cloud GPUs or a cloud computer | Uses Voyager credits while the machine runs | | Chat using your own Claude or ChatGPT subscription | Uses that subscription; Voyager does not charge for the agent chat | | Chat using your own provider API key | The provider bills your API account per use, separately from a chat subscription | | Generation using your own media key or Higgsfield account | Bills that provider account directly | The cost varies with the model and settings. Treat an estimate as an estimate: duration, resolution, inputs, and additional attempts can change the total. The [pricing page](https://voyager.so/pricing) explains credit values and model rates. > [!WARNING] > > With **If one can't finish, try the next provider** on, a generation can move to another provider > in your list, which may bill a different account. Review your [generation provider > order](/account/generation-providers) before paid work. ## Check your plan and balance Open **Settings → Account**. **Plan & credits** at the top shows your plan and the credits available, and **Signed in** below it shows your account and workspace. Your plan also shows under your name at the bottom of the sidebar. ![The Settings → Voyager account page. The Voyager card shows the Demo Studio workspace menu, a Creator badge and a Manage plan button, the signed-in email, the credits available with Updated just now, Auto-reload on with a Buy credits button, a Team box with Switch to Team and Manage team, the Plan & billing row reading Change plan, add credits, see usage and invoices, and a Promo code field with Apply. Below it, an Other accounts and AI providers row with an Open Providers button, then the Model choices section with the Show advanced model choices switch.](https://mintcdn.com/voyager/gEgW5f4IO2eEELDK/images/screenshots/settings-voyager-account.light.png?fit=max\&auto=format\&n=gEgW5f4IO2eEELDK\&q=85\&s=46fdf4987eb3ee0531e44b12b1c75aff) Settings → Account shows your plan, your credits and your sign-in. The sidebar's **Usage** page starts with **Voyager credits**: your balance, when it refills, and what used credits this month, such as chat, images, video, **Cloud computers** and **GPU renders**. On Free it also shows **Free plan limits**. Below that are your connected **Claude** and **ChatGPT** plans and **Your keys**. Estimates there are not a Voyager invoice. ## Manage billing in Voyager Open **Settings → Account** to see and change everything about how you pay, without leaving the app. **Plan & credits** comes first: your plan, when it renews, and **Change plan**. You can also cancel, or **Keep plan** if a cancellation or trial is pending. The rest is under **Credits, usage and invoices**: * **Credits**: your balance, credits held by running generations, **Add credits**, and the auto-reload rule. * **Usage this period**: where your credits went, **By AI** and, for billing admins in a workspace with several people, **By member**. * **Payment method** (billing admins): the card on file and **Update card**. * **Invoices** (billing admins): invoices and credit pack receipts, each with a PDF. Other members see the plan, the credits and their own usage. ![Settings → Plan & billing, with an Open in browser link. The Credits card shows the credits available, the refresh date, Auto-reload on and a Buy credits button. The Current plan card shows Creator, Monthly and Demo Studio with the renewal date and a See plans button.](https://mintcdn.com/voyager/gEgW5f4IO2eEELDK/images/screenshots/settings-plan-billing.light.png?fit=max\&auto=format\&n=gEgW5f4IO2eEELDK\&q=85\&s=ecdfb4bd8061f6f19e4a5a6f20499f5c) Account starts with your plan and credits. **Change plan** and **Add credits** open the plan picker inside Voyager. Checkout and card changes finish in your browser; afterwards, **Back to Voyager** returns you to the app with the new plan ready. You can also manage everything on the Voyager website under **Plan & billing** ([voyager.so/dashboard/billing](https://voyager.so/dashboard/billing)). On a workspace that a teammate pays for, only billing admins can change the plan or payment; Account says so. ## How credits renew Included credits reset each month rather than rolling over. Annual billing still grants credits monthly. Credit packs have an expiry date. See [pricing](https://voyager.so/pricing) for the current terms. An Individual plan's credits are for one person. A Team plan grants credits for each seat into one pool that the whole workspace shares. ## Team plans A Team plan is for 2 to 25 people. Everyone with a seat shares the plan and one pool of credits on one bill, and admins manage seats, roles and billing. Team plans come in Starter, Creator and Ultra; GigaMax™ is for individuals. For more than 25 people, ask about **Enterprise**. * **Settings → Account** shows a **Team** row under **Signed in**. **Manage team** opens the Voyager website, where admins invite people and choose who's an admin. * If you belong to several workspaces, use the workspace menu under **Signed in** or **Switch workspace** to choose which one Voyager uses. Work that's already running finishes in the workspace it started in. * If you're in a workspace but don't have a seat on its plan, the card and the sidebar show **Needs a seat**. Choose **Ask for a seat**, or ask a workspace admin to give you one. * If the workspace's plan is for one person, Voyager offers **Switch to Team** to an admin, or **Ask to switch to Team** to everyone else. Check the workspace name before buying credits or starting paid work. To start a Team plan, choose the **Team** tab on [Voyager pricing](https://voyager.so/pricing). For Enterprise, email [support@voyager.so](mailto:support@voyager.so). To invite people and choose admins, see [Work as a team](/account/team). ## Cloud computers and Cloud GPUs The **Cloud** section of **Settings → Account** has two rows: * **Cloud computer**: a whole computer in the cloud that keeps working with your laptop off. **Open** takes you to its settings in **Devices & sharing**. * **Cloud GPU**: a powerful GPU Voyager borrows for heavy renders, simulations and exports, then releases. **Open** takes you to **Settings → Creative → Cloud GPUs**, where you choose **Ask**, **Always for heavy work** or **Never**, and how many GPUs a task may use. Both use Voyager credits while they run and need a paid plan; on Free, each row offers **Upgrade**. The number of GPUs per task depends on your plan. **Never** stops Voyager from using Cloud GPUs; chat and cloud generation are separate. See [Computers and Cloud GPUs](/guides/computers-and-cloud-gpus). ## If credits run out during a batch Voyager billing is prepaid. Without a credit pack or working auto-reload, new work that needs more Voyager credits stops until credits are available again. Chat through Voyager uses the same credit pool and can stop too. A batch contains separate generations, so some may finish before another runs out of credits. Keep the completed results. Check the **Activity** tray above the message box, or the **Background** panel, to see which work finished, failed, or is still running before asking the agent to continue only the missing parts. When a request doesn't fit, the chat shows an **Out of credits** card with **Add credits** and **Turn on auto-reload**. If a generation continued on another connected provider, check the notification before buying credits or retrying. If it says **Waiting for auto-reload to top up credits…**, Voyager is already waiting for the purchase; do not start another copy. You can buy a credit pack, enable or fix auto-reload, wait for the next credit reset, or use your own agent subscription and media keys. Credit packs need a paid plan and aren't sold on Free or during a trial. ## Failed and cancelled jobs | What happened | What it means for charges | | - | - | | The job was refused before generation started, such as a wait for a free slot | That refused attempt was not charged | | You cancelled while the job was still waiting and had not been sent | The generation was not charged | | You cancelled after the provider started | It may still be charged; some generations cannot be stopped | | The provider finished before cancellation took effect | Voyager keeps the finished result; cancellation does not make it free | | A generation failed after it started | A failure does not prove it was uncharged or refunded; the outcome depends on the provider | | Voyager could not confirm whether the request started | Check the existing job before submitting another paid attempt | A new attempt is a separate generation. If the billing outcome is unclear, use **Send feedback…** from that chat's menu and include the job or request ID. ## Set up auto-reload Auto-reload buys a credit pack when your balance falls below your chosen threshold. It needs a paid plan, outside a trial, and a payment method on file. > [!WARNING] > > Auto-reload charges your saved payment method. Review the pack and monthly limit before turning > it on. Choosing no monthly limit allows repeated purchases whenever credits run low. 1. Open **Settings → Account**, open **Credits, usage and invoices** and find the auto-reload rule in **Credits**. 2. Choose **Turn on** (or **Manage** if it's already set up). Your billing dashboard opens in the browser. 3. Set the balance that triggers a reload, the pack to buy, and the monthly limit, then save. 4. Back in Voyager, **Credits** reads **Auto-reload is on.** and shows the rule. If it pauses, **Credits** says why, for example **Paused because the last payment failed. Update your card in Manage.** or **Monthly limit reached.** Fix the card, turn it back on, or raise the limit in **Manage**. An enabled rule alone does not mean a purchase can currently go through. ## Apply a promo code or check a trial Enter a code in **Promo code (optional)** during setup, or open **Settings → Account**, enter it under **Promo code** and choose **Apply**. A successful result says **Code applied** or names the activated Voyager trial. An offer can also come by email as a link (voyager.so/offer/…). Open it to claim the offer in your browser. Offers waiting for you also show under **Offers** in **Settings → Account**. Codes can have eligibility rules. An expired code, an already redeemed offer, or an offer for a different workspace cannot be applied by retrying it. A failed promo code does not have to stop setup; you can add it later in Settings. > [!WARNING] > > Check the trial's end date and what happens next in **Settings → Account**. A trial can > convert to a paid plan and charge the payment method on file. **Plan & credits** says what happens > when the trial ends. ## Control spending In **Settings → Creative → Limits**, set **Ask before spending more than**. Voyager asks before spending more than your limit (in **Wait, then go ahead** and **Always ask**). This is a preference the agent follows, not a hard billing cap. **Wait, then go ahead** otherwise counts down to the recommended answer; **Always ask** waits for every answer. **Don't ask** takes the recommended answer immediately, including approval for paid generation above your limit. See [Approvals and spending](/guides/approvals-and-spending). When chat through Voyager is refused, the billing button on the **Voyager** card names the fix: | Button | When it appears | | - | - | | **Add credits** | The workspace is out of credits | | **Update payment** | The last payment failed | | **Upgrade plan** | The plan doesn't include the model you chose | | **See plans** | Free reached a limit, or the workspace has no plan | | **Turn chat back on** | An admin turned off chat through Voyager | | **Raise chat limit** | Chat reached the monthly limit an admin set | | **Open seats** | You need a seat on the workspace's plan | Most of these open the plan picker or **Settings → Account** inside Voyager. For a specific refusal or a generation that stopped, see [Generation problems](/help/generation-problems). ## Use your credits outside the app The same Voyager credits work beyond the desktop app: * [Generate in the browser](/web/generate): make images, video and audio on voyager.so. * [Connect your AI](/connect/overview): use Voyager from Claude, ChatGPT or Codex. * [Voyager API](/api/overview): call Voyager from your own code. # Work as a team Source: https://docs.voyager.so/account/team Share one Voyager plan and one pool of credits with your team, invite people, and choose who's an admin. A Team plan lets 2 to 25 people work in one Voyager workspace with one bill and one shared pool of credits. For example, a studio of four can share one Creator Team plan. Everyone signs in to the same workspace, and every chat or generation draws on the workspace's credits. For more than 25 people, ask about **Enterprise** at [support@voyager.so](mailto:support@voyager.so). ## How a team fits with workspaces * A **workspace** is where your plan, credits, brand kits and billing live. Everyone has one, even on their own. * An **Individual** plan is for one person. A **Team** plan adds seats, so several people can use the workspace's plan and credits. * You can belong to more than one workspace. In **Settings → Account**, use **Switch workspace** under **Signed in** to choose which one Voyager uses. Work that's already running finishes in the workspace it started in. > [!WARNING] > > Check the workspace name in **Settings → Account** before buying credits or starting paid work. Credits come from the workspace Voyager is using. ## Start a team **1. Choose a Team plan** On [Voyager pricing](https://voyager.so/pricing), open the **Team** tab, pick a plan and how many people, and start the team. Team plans come in Starter, Creator and Ultra. **2. Or switch from inside Voyager** If your workspace is on a plan for one person, **Settings → Account** offers **Switch to Team** to an admin, or **Ask to switch to Team** to everyone else. ## Invite people and choose admins **1. Open Team on the website** In **Settings → Account**, choose **Manage team**. It opens **Team** in your Voyager settings on voyager.so. **2. Invite teammates** Choose **Invite**, enter email addresses separated by commas or new lines, and choose **Send invitations**. Each person gets an email to join. **3. Set roles** Each person is a **Member** or an **Admin**. Admins can invite and remove people and change roles. Pending invitations count toward your seats. If the page says **Every seat is taken**, an owner or admin can add seats in **Plan & billing**. ## If you don't have a seat If you belong to a workspace but don't have a seat on its plan, **Settings → Account** and the sidebar show **Needs a seat**. Choose **Ask for a seat**, or ask a workspace admin to give you one. ## See who used what Billing admins see **By member** under **Usage this period** in **Settings → Account → Credits, usage and invoices**. Other members see the plan, the credits and their own usage. See [Plans and credits](/account/plans-and-credits). > [card] [Understand plans and credits](/account/plans-and-credits) > > What uses credits, how they renew and how to manage billing. # Get account Source: https://docs.voyager.so/api-reference/account/get-account /openapi/voyager-api.yaml get /account The key's workspace, its plan, available credits and this key's limits. Works on every plan. # Add a Cast reference Source: https://docs.voyager.so/api-reference/cast/add-a-cast-reference /openapi/voyager-api.yaml post /cast/{cast_id}/references Add an image you own to the card (at most 8 references). An `Idempotency-Key` makes a retry safe. # Create a Cast card Source: https://docs.voyager.so/api-reference/cast/create-a-cast-card /openapi/voyager-api.yaml post /cast A new card from images you own. Each reference is copied to a permanent Cast file. Send an `Idempotency-Key` to retry safely: the same key and body return the card made the first time. # Delete a Cast card Source: https://docs.voyager.so/api-reference/cast/delete-a-cast-card /openapi/voyager-api.yaml delete /cast/{cast_id} Delete the card and the reference files no other card uses. Jobs already started keep theirs. # Get a Cast card Source: https://docs.voyager.so/api-reference/cast/get-a-cast-card /openapi/voyager-api.yaml get /cast/{cast_id} One card by id (cst_…) or slug, with fresh links to its references. # List Cast Source: https://docs.voyager.so/api-reference/cast/list-cast /openapi/voyager-api.yaml get /cast This workspace's Cast: characters, locations and props with their reference images, newest change first. # Remove a Cast reference Source: https://docs.voyager.so/api-reference/cast/remove-a-cast-reference /openapi/voyager-api.yaml delete /cast/{cast_id}/references/{file_id} Remove one reference; its file is deleted when no other card uses it. # Update a Cast card Source: https://docs.voyager.so/api-reference/cast/update-a-cast-card /openapi/voyager-api.yaml patch /cast/{cast_id} Change the fields you send; `references`, when sent, replaces them all. Needs `expected_version`. # Check a file download Source: https://docs.voyager.so/api-reference/files/check-a-file-download /openapi/voyager-api.yaml head /files/{file_id}/content The signed link from a job or file object (``exp``/``sig``, one hour). Revalidated on every request. # Complete an upload Source: https://docs.voyager.so/api-reference/files/complete-an-upload /openapi/voyager-api.yaml post /files/{file_id}/complete Check the uploaded bytes and make the file usable: ``ready``, or ``failed`` with ``error`` (wrong type, size other than declared, over the plan's limit). Idempotent; 409 ``upload_incomplete`` before the PUT, 409 ``idempotency_in_flight`` while the same key's completion is still running. # Delete a file Source: https://docs.voyager.so/api-reference/files/delete-a-file /openapi/voyager-api.yaml delete /files/{file_id} Delete a file now. A file a running job still uses, or one saved in a Cast card, is 409 ``asset_in_use``. # Download a file Source: https://docs.voyager.so/api-reference/files/download-a-file /openapi/voyager-api.yaml get /files/{file_id}/content The signed link from a job or file object (``exp``/``sig``, one hour). Revalidated on every request. # Get a file Source: https://docs.voyager.so/api-reference/files/get-a-file /openapi/voyager-api.yaml get /files/{file_id} A file with a fresh one-hour ``url`` (ready), or its upload state (pending, failed). # Upload or import a file Source: https://docs.voyager.so/api-reference/files/upload-or-import-a-file /openapi/voyager-api.yaml post /files An upload (``status: pending`` with ``upload_url``: PUT the bytes with ``headers``, then ``POST /v1/files/{id}/complete``), or with ``url`` an import, ready at once. With ``Idempotency-Key``, a retry returns the same file (an upload still pending gets a fresh ``upload_url``). # Jobcanceled Source: https://docs.voyager.so/api-reference/jobcanceled /openapi/voyager-api.yaml webhook job.canceled A job was canceled (error.code queue_timeout when it waited in the queue too long). Sent to the job's `webhook_url` once, when the job reaches this terminal status (not when its charge settles: `data.credits.state` may still be `pending`). The event is thin: `GET /v1/jobs/{id}` is authoritative, and the output links in `data` expire one hour after the event is rendered. Signed per Standard Webhooks with the key's `whsec_` secret (shown once at key creation). Any 2xx response marks it delivered; anything else (or no answer) is retried with backoff for 24 hours, same `webhook-id`, fresh `webhook-timestamp`. Revoking the key stops its undelivered events. # Jobfailed Source: https://docs.voyager.so/api-reference/jobfailed /openapi/voyager-api.yaml webhook job.failed A job failed (error.code says why; outcome_unknown means a new submission may charge again). Sent to the job's `webhook_url` once, when the job reaches this terminal status (not when its charge settles: `data.credits.state` may still be `pending`). The event is thin: `GET /v1/jobs/{id}` is authoritative, and the output links in `data` expire one hour after the event is rendered. Signed per Standard Webhooks with the key's `whsec_` secret (shown once at key creation). Any 2xx response marks it delivered; anything else (or no answer) is retried with backoff for 24 hours, same `webhook-id`, fresh `webhook-timestamp`. Revoking the key stops its undelivered events. # Cancel a job Source: https://docs.voyager.so/api-reference/jobs/cancel-a-job /openapi/voyager-api.yaml post /jobs/{job_id}/cancel Ask to stop a job. A queued job that has not reached its provider is canceled at once and costs nothing (any type). A running image, video or speech job is canceled best effort (work done may still be charged); other running jobs are 409 ``cancel_unsupported``. Returns the job as it now stands: a job that finished first stays finished. # Create a job Source: https://docs.voyager.so/api-reference/jobs/create-a-job /openapi/voyager-api.yaml post /jobs Start a generation. 201 with the queued job, or 200 with the finished job when it ends within ``Prefer: wait=N`` (``Preference-Applied`` echoes it). # Estimate a job Source: https://docs.voyager.so/api-reference/jobs/estimate-a-job /openapi/voyager-api.yaml post /estimate What a job with this body would cost. Reserves nothing; null when unknown; not a price cap (the charge is the job's real cost). ``can_run`` is false when the plan, model access or balance refuses it, or it is unknown. An https URL in ``input`` is priced as it is (checked, never downloaded or stored). One exception: a source recording for a speech, voice or audio model, whose price depends on its length, is imported into your workspace to measure it (a reference file that expires after 7 days, like any imported reference); send a file_ id from POST /v1/files to avoid the import. # Get a job Source: https://docs.voyager.so/api-reference/jobs/get-a-job /openapi/voyager-api.yaml get /jobs/{job_id} The job with fresh one-hour output links. While it is active, ``Retry-After`` says when to poll again. # List jobs Source: https://docs.voyager.so/api-reference/jobs/list-jobs /openapi/voyager-api.yaml get /jobs Your jobs in this workspace, newest first. Send the same filters with each page's cursor. # Jobsucceeded Source: https://docs.voyager.so/api-reference/jobsucceeded /openapi/voyager-api.yaml webhook job.succeeded A job finished with its outputs. Sent to the job's `webhook_url` once, when the job reaches this terminal status (not when its charge settles: `data.credits.state` may still be `pending`). The event is thin: `GET /v1/jobs/{id}` is authoritative, and the output links in `data` expire one hour after the event is rendered. Signed per Standard Webhooks with the key's `whsec_` secret (shown once at key creation). Any 2xx response marks it delivered; anything else (or no answer) is retried with backoff for 24 hours, same `webhook-id`, fresh `webhook-timestamp`. Revoking the key stops its undelivered events. # Cancel Job Source: https://docs.voyager.so/api-reference/machines/cancel-job /openapi/voyager-api.yaml post /machines/jobs/{job}/cancel Stop a running job (SIGTERM, then SIGKILL after 10 s). # Complete Upload Source: https://docs.voyager.so/api-reference/machines/complete-upload /openapi/voyager-api.yaml post /machines/{machine}/files/upload/complete Commit files uploaded to their `upload_url`s onto the machine. # Create Machine Source: https://docs.voyager.so/api-reference/machines/create-machine /openapi/voyager-api.yaml post /machines Lease a GPU machine. It starts in the background (`status: starting`); wait with `GET /machines/{id}?wait=60`. It bills per second until it is paused or released; it pauses itself after `idle_timeout` idle seconds. # Download Files Source: https://docs.voyager.so/api-reference/machines/download-files /openapi/voyager-api.yaml post /machines/{machine}/files/download Get files or whole folders from the machine: small files inline (base64), the rest as download links. # Get Job Source: https://docs.voyager.so/api-reference/machines/get-job /openapi/voyager-api.yaml get /machines/jobs/{job} # Get Job Logs Source: https://docs.voyager.so/api-reference/machines/get-job-logs /openapi/voyager-api.yaml get /machines/jobs/{job}/logs # Get Machine Source: https://docs.voyager.so/api-reference/machines/get-machine /openapi/voyager-api.yaml get /machines/{machine} # List Gpus Source: https://docs.voyager.so/api-reference/machines/list-gpus /openapi/voyager-api.yaml get /machines/gpus Every GPU you can lease, with its price. # List Images Source: https://docs.voyager.so/api-reference/machines/list-images /openapi/voyager-api.yaml get /machines/images The machine images (operating system and software) you can start a machine with. # List Machines Source: https://docs.voyager.so/api-reference/machines/list-machines /openapi/voyager-api.yaml get /machines Your workspace's machines, newest first. # List Presets Source: https://docs.voyager.so/api-reference/machines/list-presets /openapi/voyager-api.yaml get /machines/presets Ready-made machine setups. `render` (the default) runs Vork and Blender; `compute` cannot run Vork. # Open Port Source: https://docs.voyager.so/api-reference/machines/open-port /openapi/voyager-api.yaml post /machines/{machine}/ports Serve a port on the machine at a public `https://.run.voyager.computer/` link (HTTP and WebSocket). Anyone with the link can reach it while the machine runs. # Pause Machine Source: https://docs.voyager.so/api-reference/machines/pause-machine /openapi/voyager-api.yaml post /machines/{machine}/pause Stop billing and keep the disk. Running a command or moving files resumes it. # Release Machine Source: https://docs.voyager.so/api-reference/machines/release-machine /openapi/voyager-api.yaml delete /machines/{machine} Release the machine: billing stops and its disk is deleted. Returns the final machine with its cost. # Resume Machine Source: https://docs.voyager.so/api-reference/machines/resume-machine /openapi/voyager-api.yaml post /machines/{machine}/resume # Run Command Source: https://docs.voyager.so/api-reference/machines/run-command /openapi/voyager-api.yaml post /machines/{machine}/run Run a command. With `wait: true` it answers with the output once the command ends (up to about 60 s; after that it answers 202 with the running job). A paused machine is resumed first (`resumed: true`). # Snapshot Machine Source: https://docs.voyager.so/api-reference/machines/snapshot-machine /openapi/voyager-api.yaml post /machines/{machine}/snapshots Save the machine's disk. Start new machines from it with `from_snapshot`. # Upload Files Source: https://docs.voyager.so/api-reference/machines/upload-files /openapi/voyager-api.yaml post /machines/{machine}/files/upload Put files on the machine. Send files up to 4 MiB inline (`content_base64`); larger ones come back with an `upload_url` to PUT and an `upload_id` to commit (`POST …/files/upload/complete`). Unchanged files are skipped. # Get a model Source: https://docs.voyager.so/api-reference/models/get-a-model /openapi/voyager-api.yaml get /models/{model_id} One model with the JSON Schema of its `input` per operation, defaults, an example and price detail. # List models Source: https://docs.voyager.so/api-reference/models/list-models /openapi/voyager-api.yaml get /models The models the API can run, with expected price and (when known) availability for this workspace. # List voices Source: https://docs.voyager.so/api-reference/voices/list-voices /openapi/voyager-api.yaml get /voices Voices for speech jobs. A voice renders only on its own engine's models (`compatible_models`). # Authentication Source: https://docs.voyager.so/api/authentication Create a Voyager API key on the dashboard, send it as a Bearer token, and know what it can do and who can revoke it. Every request needs a Voyager API key in the `Authorization` header: ```bash theme={"system"} curl https://api.voyager.so/v1/account \ -H "Authorization: Bearer $VOYAGER_API_KEY" ``` A request without a valid key returns `401` with error code [`invalid_api_key`](/api/errors#invalid_api_key) and a `WWW-Authenticate: Bearer` header. ## Create a key > [!NOTE] > > **Before you start:** API keys are for paid Voyager plans, trials included. On Free, the **API** tab shows an upgrade prompt instead; workspace members who can't change the plan should ask an owner or admin. Plans are on [voyager.so/pricing](https://voyager.so/pricing). **1. Open the API tab** Sign in at [voyager.so/dashboard/api](https://voyager.so/dashboard/api), or open **API** in the dashboard's top bar. On a phone, it's in the profile menu. Check that the workspace you want is selected: a key belongs to one workspace. **2. Create the key** Click **Create API key** and give it a name you'll recognize later, such as `ci` or `my-app-prod`. **3. Copy the key and the webhook secret** The key (`vy_live_` followed by 64 hex characters) and its webhook signing secret (`whsec_…`) are shown **once**. Copy both now. Voyager stores only a hash of the key, so nobody can show it to you again. If you lose it, revoke it and create another. **4. Put it in your environment** ```bash theme={"system"} export VOYAGER_API_KEY=vy_live_... ``` In a project, keep it in an untracked `.env` file, add `VOYAGER_API_KEY=` to `.env.example`, and make sure `.env` is in `.gitignore`. Check it worked: ```bash theme={"system"} curl -s https://api.voyager.so/v1/account -H "Authorization: Bearer $VOYAGER_API_KEY" ``` You should see your workspace, plan and credits available. ## Who a key acts as A key acts as **you, in one workspace**. Jobs it creates are paid from that workspace's Voyager credits and count toward your own [parallel generations](/api/rate-limits#concurrency), shared with the Voyager app. Jobs and files are visible to the person who created them: a job made with one of your keys can be read with any of your other live keys in the same workspace, so rotating a key doesn't strand your results. ## Scopes Every key has the same fixed set of scopes. There is no scope picker. | Scope | Allows | | - | - | | `media:generate` | Estimate and create jobs; use Cast in jobs | | `uploads:write` | Upload and import files, manage Cast cards | | `files:read` | Read and download files and outputs | | `credits:read` | Read `GET /v1/account` | | `tasks:read` | Read and list jobs | | `tasks:cancel` | Cancel jobs | A key can't change billing, invite members, or manage other keys. Treat it as a password anyway: anyone holding it can spend your workspace's credits. ## Limits * Up to **25 active keys** per person per workspace. * Requests are rate-limited per key. See [Rate limits and usage](/api/rate-limits). ## See, rotate and revoke keys The **API** tab lists keys by name and prefix (`vy_live_ab12…`), with who created each, when, and when it was last used, plus credits used by each key over the last 30 days. * **Anyone** can revoke their own keys. * **Workspace owners and admins** see and can revoke everyone's keys in the workspace. * **Removing a member** from the workspace revokes all of their keys. Click **Revoke** to revoke a key. Revoking takes effect right away: requests with that key return `401` `invalid_api_key`, signed result links issued to it stop working, and webhooks it hasn't delivered yet are dropped. Jobs it already started still finish and are still charged; read them with another of your keys. To rotate a key: create a new one, deploy it, then revoke the old one. Retrying a request with the same `Idempotency-Key` from the new key still returns the original job, so a rotation in the middle of a retry never buys twice. ## If your plan changes If your workspace moves to Free, your keys are kept. These keep working: * reading and listing jobs, and downloading their results, * cancelling work that was already accepted, deleting files, and managing Cast cards, * `GET /v1/account`, which reports `plan.paid: false`, * listing and revoking keys on the dashboard. Anything that starts new paid work (creating jobs, estimates, uploads) returns `402` [`paid_plan_required`](/api/errors#paid_plan_required) with an `upgrade_url`. Upgrade and the same keys work again. ## Keep keys safe * Never commit a key, paste it into an issue, or ship it in a browser, mobile app or other client code. Call the API from a server. * Use one key per app or environment, so you can revoke one without touching the rest. * Revoke keys you no longer use. * If a key leaks, revoke it on the **API** tab first, then replace it. # Cast Source: https://docs.voyager.so/api/cast Save characters, locations and props as workspace Cast cards and pass up to four of them to an image or video job for consistent shots. A **Cast card** is a saved character, location or prop: a name, a short description of what never changes, and up to 8 reference images. Pass cards to an image or video job with `input.cast` and Voyager puts their best references into the model's reference field and describes them in the prompt, so the same person, place or object looks the same from shot to shot. Cast cards belong to the workspace. They're the same cards you use when you connect ChatGPT or Codex to Voyager (see [Connect your AI](/connect/overview)): a card saved from the API shows up there, and the other way round. > [!NOTE] > > Cast in the API is not the same as **Elements** in the Voyager desktop app. Elements are local files in each project on your computer and aren't reachable from the API. To use a character from the app, upload its reference images and save them as a Cast card. ## The Cast card An example card: ```json theme={"system"} { "id": "cst_01JC4S0B6Q8R2T4V6X8Z0A2C4E", "object": "cast", "slug": "mara", "name": "Mara", "kind": "character", "style": "photoreal", "description": "Woman in her 30s, short curly black hair, round silver glasses, green raincoat.", "references": [ { "file_id": "file_01JC4R2M7K9T3V5B8N1X6D0QWE", "role": "hero", "note": "front, neutral light", "url": "https://…", "url_expires_at": "2026-11-05T21:44:03Z" }, { "file_id": "file_01JC4R3A1C3E5G7J9L1N3Q5S7U", "role": "fullbody", "note": null, "url": "https://…", "url_expires_at": "2026-11-05T21:44:03Z" } ], "voice_id": null, "version": 3, "created_at": "2026-11-05T20:01:12Z", "updated_at": "2026-11-05T20:44:03Z" } ``` | Field | Type | Description | | - | - | - | | `object` | `string` | Always "cast". Always `cast`. | | `id` | `string` | cst\_… Pass in input.cast (up to 4) on a job. | | `slug` | `string` | A short handle for this Cast card, unique in the workspace. | | `name` | `string` | The card's display name. | | `kind` | `string` | What this Cast card is: a character, a location or a prop. One of `character`, `location`, `prop`. | | `style` | `string` | How references render: photoreal or stylized. One of `photoreal`, `stylized`. | | `description` | `string` | What the card shows; prefixed to the prompt of jobs that feature it. | | `version` | `integer` | Increases on every change; pass it as expected\_version to change it safely. | | `voice_id` | `string` or `null` | A voice for this character, when set. | | `references` | array of `CastReference` | The card's reference images, in order. | | `created_at` | `string` (date-time) or `null` | When it was created (ISO 8601). | | `updated_at` | `string` (date-time) or `null` | When it last changed (ISO 8601). | Each entry in `references` (`url` is a signed preview link, valid about 1 hour): | Field | Type | Description | | - | - | - | | `file_id` | `string` | The reference image (a file\_ id). | | `role` | `string` | What the image shows of the card: hero, fullbody, angle, expression, outfit, plate or style. One of `hero`, `fullbody`, `angle`, `expression`, `outfit`, `plate`, `style`. | | `note` | `string` or `null` | A short note about this reference. | | `url` | `string` or `null` | Signed link to the image, valid about an hour. | | `url_expires_at` | `string` (date-time) or `null` | When `url` stops working (ISO 8601); read the object again for a fresh link. | `version` goes up on every change; send it back as `expected_version` when you change the card. ## Endpoints | Method | Path | What | | - | - | - | | `GET` | `/v1/cast` | List the workspace's cards, most recently changed first. | | `POST` | `/v1/cast` | Create a card. Each reference is copied to a permanent Cast file. | | `GET` | `/v1/cast/{id}` | Read a card. `{id}` is the `cst_…` ID or the slug. | | `PATCH` | `/v1/cast/{id}` | Change only the fields you send. `references`, when sent, replaces them all. Requires `expected_version`. | | `DELETE` | `/v1/cast/{id}` | Delete a card and the reference files no other card uses. Optional `?expected_version=` refuses the delete if the card changed. Jobs already started keep their references. | | `POST` | `/v1/cast/{id}/references` | Add a reference. Returns `201` with the card. | | `DELETE` | `/v1/cast/{id}/references/{file_id}?expected_version=` | Remove a reference; its file is deleted when no other card uses it. | `GET /v1/cast` takes: | Parameter | Type | Description | | - | - | - | | `limit` | `integer` | 1–100. Default `20`. | | `cursor` | `string` or `null` | Up to 200 characters. | The `POST /v1/cast` body: | Field | Type | Description | | - | - | - | | `name` | `string` · required | The card's display name. Up to 120 characters. | | `kind` | `string` · required | What this Cast card is: a character, a location or a prop. One of `character`, `location`, `prop`. | | `style` | `string` · required | How references render: photoreal or stylized. One of `photoreal`, `stylized`. | | `description` | `string` | Fixed features that never change between shots. Up to 600 characters. | | `references` | array of `ReferenceIn` | The card's reference images, in order. Up to 8 items. | | `slug` | `string` or `null` | Short handle; derived from the name if omitted. Up to 48 characters. | | `voice_id` | `string` or `null` | A voice (vox\_…) for this character. Up to 64 characters. | Each entry in its `references`: | Field | Type | Description | | - | - | - | | `file_id` | `string` · required | An image you own (file\_…), from an upload or job. Up to 64 characters. | | `role` | `string` · required | What it shows: hero (the main look), fullbody, angle, expression, outfit… One of `hero`, `fullbody`, `angle`, `expression`, `outfit`, `plate`, `style`. | | `note` | `string` or `null` | A short note about this reference. Up to 200 characters. | The `PATCH /v1/cast/{id}` body: | Field | Type | Description | | - | - | - | | `expected_version` | `integer` · required | The version you read; a stale one is 409 version\_conflict. | | `name` | `string` or `null` | A new display name. Up to 120 characters. | | `kind` | `string` or `null` | A new kind. One of `character`, `location`, `prop`. | | `style` | `string` or `null` | A new style. One of `photoreal`, `stylized`. | | `description` | `string` or `null` | A new description. Up to 600 characters. | | `references` | array of `ReferenceIn` or `null` | Replaces every reference when given. Up to 8 items. | | `slug` | `string` or `null` | A new slug. Up to 48 characters. | | `voice_id` | `string` or `null` | Send null to clear. Up to 64 characters. | The `POST /v1/cast/{id}/references` body: | Field | Type | Description | | - | - | - | | `file_id` | `string` · required | An image you own (file\_…), from an upload or job. Up to 64 characters. | | `role` | `string` · required | What it shows: hero (the main look), fullbody, angle, expression, outfit… One of `hero`, `fullbody`, `angle`, `expression`, `outfit`, `plate`, `style`. | | `note` | `string` or `null` | A short note about this reference. Up to 200 characters. | | `expected_version` | `integer` · required | The card's current version; a change made meanwhile answers 409. | ## Create a card and use it **1. Upload the references** Upload each photo or image with [`POST /v1/files`](/api/jobs#uploads) and complete it, or reuse a `file_…` from an earlier output. **2. Save the card** ```bash theme={"system"} curl https://api.voyager.so/v1/cast \ -H "Authorization: Bearer $VOYAGER_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{ "name": "Mara", "kind": "character", "style": "photoreal", "description": "Woman in her 30s, short curly black hair, round silver glasses, green raincoat.", "references": [ { "file_id": "file_01JC4R2M7K9T3V5B8N1X6D0QWE", "role": "hero" }, { "file_id": "file_01JC4R3A1C3E5G7J9L1N3Q5S7U", "role": "fullbody" } ] }' ``` **3. Pass it to a job** ```bash theme={"system"} curl https://api.voyager.so/v1/jobs \ -H "Authorization: Bearer $VOYAGER_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{ "model": "nano-banana-2.1", "operation": "text-to-image", "input": { "prompt": "Mara waits at a rainy bus stop at night", "cast": ["cst_01JC4S0B6Q8R2T4V6X8Z0A2C4E"] } }' ``` ## How Cast goes into a job * Up to **4** cards per job in `input.cast`. * Voyager takes each card's references in role order (`hero` first) and alternates between cards so each one gets its best reference in, up to the model's own reference limit. * The cards' names, kinds and descriptions are added to the start of the prompt. * The job records which version of each card it used. * Cast works with image and video models only; anything else returns `422` [`cast_not_supported`](/api/errors#cast_not_supported). Look for a `cast` field in the operation's `input_schema` on [`GET /v1/models/{id}`](/api/models#read-a-model). More references than the model takes, counting Cast's, is `422` [`too_many_references`](/api/errors#too_many_references). ### Realistic faces Some video models need a higher plan (Ultra or GigaMax today) for **photoreal characters**: a job that passes a `photoreal` `character` card to one of them on a lower plan returns `403` [`plan_required_for_faces`](/api/errors#plan_required_for_faces) before anything is charged. Use a `stylized` character, another model, or upgrade; [voyager.so/pricing](https://voyager.so/pricing) shows which plans include them. Locations, props and stylized characters aren't affected. Every model also applies its own content rules to all inputs. ## Changing cards safely Every change takes the `expected_version` you last read (optional only for deleting a card). If someone changed the card since (in the API, ChatGPT or Codex), you get `409` [`version_conflict`](/api/errors#version_conflict): read it again and retry with the new version. ## Retention Cast reference images are kept until you remove them from the card or delete the card, unlike plain uploads, which are deleted after 7 days. Saving an upload to a card is how you keep a reference for good. # Set up with your coding agent Source: https://docs.voyager.so/api/coding-agents Paste one prompt into Claude Code, Codex or Cursor to wire the Voyager API into your project, give your agent a cloud GPU, and give it these docs as llms.txt, Markdown, an MCP server or OpenAPI. The Voyager API is built to be used by coding agents. Give your agent the prompt below and it will add a small client to your project, generate a test image and tell you what it cost. > [!NOTE] > > **Before you start:** create an API key at [voyager.so/dashboard/api](https://voyager.so/dashboard/api) (paid plans, trials included) and put it in `VOYAGER_API_KEY` in your project's `.env`. Don't paste the key into the chat. ## The setup prompt Copy this into your agent, in the project where you want to use Voyager. The same prompt is on the dashboard's **API** tab. ```text theme={"system"} Set up the Voyager API in this project. Voyager generates images, video, speech, music, sound effects, 3D and object masks with the same models and credits as the Voyager app. Docs: https://docs.voyager.so/api (agent-readable: https://docs.voyager.so/llms.txt, OpenAPI: https://api.voyager.so/v1/openapi.json) 1. Key: read it from the env var VOYAGER_API_KEY. Never hard-code it or commit it; add VOYAGER_API_KEY= to .env.example and make sure .env is git-ignored. If it's missing, ask me to create one at https://voyager.so/dashboard/api (paid plans). 2. Base URL https://api.voyager.so/v1, header: Authorization: Bearer $VOYAGER_API_KEY 3. Pick a model: GET /models?type=image|video|speech|music|sound_effect|3d|segment. Read GET /models/{id} for its input_schema before building a request. 4. Optional cost check: POST /estimate with the same body as step 5; it returns estimated_charge (credits) and can_run. 5. Create: POST /jobs {"model": "", "operation": "", "input": {...}} with an Idempotency-Key header (a new UUID per logical request; reuse it when retrying the same request). 6. Wait: GET /jobs/{id}?wait=25 until status is succeeded, failed or canceled (honor Retry-After / poll_after_ms). Or pass "webhook_url" and verify the Standard Webhooks signature with the secret from the dashboard. 7. Results: job.outputs[].url is a signed link valid for 1 hour; download it right away, or GET /jobs/{id} again for a fresh link. Files are kept 30 days. 8. Errors are {"error": {"code","message","retryable",...}}. 402 = out of credits or not on a paid plan (show error.details.upgrade_url to me). 429 = slow down: wait Retry-After seconds. Retry only when retryable is true, with the same Idempotency-Key. Minimal example (curl): curl -s https://api.voyager.so/v1/jobs \ -H "Authorization: Bearer $VOYAGER_API_KEY" -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{"model":"nano-banana-2.1","operation":"text-to-image","input":{"prompt":"a red fox in snow","aspect_ratio":"16:9"}}' curl -s "https://api.voyager.so/v1/jobs/?wait=25" -H "Authorization: Bearer $VOYAGER_API_KEY" Write a small typed client (create → wait → download) with retries as above, then generate one test image to prove it works and tell me what it cost (job.credits.charged; if credits.state is still "pending", report job.credits.estimated and say it's an estimate). ``` ### Check it worked Your agent should end with a saved test image and a cost in Voyager credits. If it reports an estimate, the final charge isn't confirmed yet; see [Credits](/api/jobs#credits). If it stops at a `402`, open the `upgrade_url` it shows you. ## Give your agent a cloud GPU Your agent can also lease a Voyager cloud GPU, run commands on it and copy files in and out with the `voyager-cloud` CLI, for renders, simulations and CUDA jobs. Paste this to get it going: ```text theme={"system"} Use Voyager cloud GPUs for GPU work in this project (needs a paid Voyager workspace, Starter or above). 1. Install the CLI if it's missing: macOS / Linux: curl -fsSL https://voyager.so/cloud/install.sh | sh Windows (PowerShell): irm https://voyager.so/cloud/install.ps1 | iex 2. Sign in: voyager-cloud login (opens my browser). If VOYAGER_API_KEY is set, use it instead. Never ask me to paste a key. 3. Lease one machine and wait: voyager-cloud lease render --wait --json (render-lite is cheaper; compute is an H100 without ray tracing). Reuse it for the whole session. 4. voyager-cloud push , voyager-cloud exec -- (waits, prints output, passes the exit code through), voyager-cloud pull . Long jobs: exec --detach, then logs --follow and wait. 5. When done: voyager-cloud release and tell me the cost it prints. If access is refused, show me the billing link from the error. Docs: https://docs.voyager.so/api/machines/overview ``` To render with [Vork](https://github.com/voyager-so/vork), use the prompt in [Render with Vork](/api/machines/vork) instead. Agents that work through MCP can use the [cloud machines MCP server](/api/machines/mcp). ## Give your agent these docs These docs are published in forms agents read directly. | Format | Where | Use it for | | - | - | - | | **llms.txt** | [docs.voyager.so/llms.txt](https://docs.voyager.so/llms.txt) | An index of every page with a one-line summary. [llms-full.txt](https://docs.voyager.so/llms-full.txt) has every page in one file. | | **Markdown** | Add `.md` to any page URL, such as [docs.voyager.so/api/jobs.md](https://docs.voyager.so/api/jobs.md) | One page as plain Markdown. | | **MCP server** | `https://docs.voyager.so/mcp` | Lets the agent search and read these docs while it works. | | **OpenAPI** | [api.voyager.so/v1/openapi.json](https://api.voyager.so/v1/openapi.json) | The full machine-readable API: every endpoint, field and error. Generate a client from it, or point your agent at it. | ### Add the docs MCP server > [tab] Claude Code > > ```bash theme={"system"} > claude mcp add --transport http voyager-docs https://docs.voyager.so/mcp > ``` > [tab] Codex > > ```bash theme={"system"} > codex mcp add voyager-docs --url https://docs.voyager.so/mcp > ``` > > Or add it to `~/.codex/config.toml`: > > ```toml theme={"system"} > [mcp_servers.voyager-docs] > url = "https://docs.voyager.so/mcp" > ``` > [tab] Cursor > > Open **Cursor Settings → MCP** and add a server, or add this to `~/.cursor/mcp.json` (or `.cursor/mcp.json` in your project): > > ```json theme={"system"} > { > "mcpServers": { > "voyager-docs": { > "url": "https://docs.voyager.so/mcp" > } > } > } > ``` The docs server only reads documentation. It can't generate anything or see your account. ## Don't want to write code? To generate from ChatGPT, Claude or Codex without an API key or any code, connect Voyager's hosted MCP server instead. It uses the same models and credits. See [Connect your AI](/connect/overview). # Errors Source: https://docs.voyager.so/api/errors The Voyager API error envelope and every error code, with its HTTP status, whether to retry, and what to do. Every error response has the same shape, and every `code` has a section on this page. `doc_url` links straight to it. An example: ```json theme={"system"} { "error": { "type": "permission", "code": "insufficient_credits", "message": "Not enough credits for this job.", "doc_url": "https://docs.voyager.so/api/errors#insufficient_credits", "request_id": "req_01JC4T6P0D2F4H6K8M0P2R4T6V", "retryable": false, "details": { "upgrade_url": "https://voyager.so/dashboard/billing", "required_hold": …, "available_credits": … } } } ``` | Field | Type | Description | | - | - | - | | `type` | `ErrorType` | Stable category to branch on. | | `code` | `string` | Stable machine code; never renamed once published (x-voyager-errors lists each). | | `message` | `string` | For developers. Not localized. | | `doc_url` | `string` | [https://docs.voyager.so/api/errors#\<code>](https://docs.voyager.so/api/errors#\<code>) | | `request_id` | `string` or `null` | Also in the X-Request-ID header; quote it to support. | | `retryable` | `boolean` or `null` | Whether the same request can succeed later. | | `retry_after_ms` | `integer` or `null` | How long to wait before retrying. | | `param` | `string` or `null` | The request field at fault, as a path (e.g. input.resolution); set on invalid\_input. | | `details` | `object` or `null` | Code-specific detail, e.g. upgrade\_url on a billing wall. | `type` is a broad category; `code` is the specific error and is never renamed, so branch on it. `message` is for developers and can change: don't parse it. `429` responses also send `Retry-After` in seconds. ## How to handle errors * **Branch on `code`**, not on `message` or the status alone. * **Retry only when `retryable` is `true`**, after `retry_after_ms` or `Retry-After`, with backoff, and with the **same `Idempotency-Key`**. Then a retry can never create a second job. * **Billing errors (`402`) aren't fixed by retrying**, except `credits_reloading`. Show `details.upgrade_url` to the person who manages the workspace. Nothing was held or charged. * **Log `request_id`** on every error. Codes come back in two ways: as an HTTP error response, or in a finished job's `error` object (`{code, message, details}`). | Group | Code | Returned as | Retryable | Meaning | | - | - | - | - | - | | **model** | [`invalid_request`](#invalid_request) | `400` | no | The request is not a valid model request. | | | [`invalid_input`](#invalid_input) | `400` | no | The model can't take this input as sent. | | | [`content_policy`](#content_policy) | `422` | no | This request was refused under the model's content policy. | | | [`upstream_unavailable`](#upstream_unavailable) | `503` | yes | The model couldn't run this request right now. | | | [`rate_limited`](#rate_limited) | `429` | yes | Too many requests. | | | [`queue_full`](#queue_full) | `429` | yes | Your plan's limit of generations running at once is reached. | | | [`model_unavailable`](#model_unavailable) | `503` | yes | This model isn't available right now. | | | [`model_not_found`](#model_not_found) | `404` | no | Unknown model. | | | [`insufficient_credits`](#insufficient_credits) | `402` | no | Not enough credits for this generation. | | | [`paid_plan_required`](#paid_plan_required) | `402` | no | This model needs a paid plan. | | | [`model_not_in_plan`](#model_not_in_plan) | `402` | no | This model isn't included in your plan. | | | [`model_access_required`](#model_access_required) | `403` | no | This model needs access to be granted first. | | | [`outcome_unknown`](#outcome_unknown) | `503` | yes | Voyager couldn't confirm this generation yet. | | | [`expired`](#expired) | `410` | no | These results have expired. | | | [`not_found`](#not_found) | `404` | no | No such generation for this workspace. | | | [`conflict`](#conflict) | `409` | no | This generation can't change from its current state. | | | [`forbidden`](#forbidden) | `403` | no | This request isn't allowed for this workspace. | | | [`internal_error`](#internal_error) | `500` | no | Something went wrong on Voyager's side. | | | [`catalog_unavailable`](#catalog_unavailable) | `503` | yes | The model catalog is temporarily unavailable. | | | [`billing_unavailable`](#billing_unavailable) | `503` | yes | Your plan couldn't be checked right now, so this paid request can't run yet. | | | [`no_voyager_seat`](#no_voyager_seat) | `402` | no | You don't have a seat on this workspace's Voyager plan. | | | [`credits_reloading`](#credits_reloading) | `402` | yes | Your credits are reloading and the balance is briefly short. | | | [`cast_not_supported`](#cast_not_supported) | `422` | no | Cast works with image and video models only. | | | [`voice_cloning_unavailable`](#voice_cloning_unavailable) | `403` | no | Voice cloning isn't available to this workspace. | | | [`too_many_references`](#too_many_references) | `422` | no | Too many reference files for this model and operation. | | | [`payload_too_large`](#payload_too_large) | `413` | no | The request body is too large. | | | [`upload_too_large`](#upload_too_large) | `413` | no | This file is over your plan's per-file limit. | | | [`intake_full`](#intake_full) | `429` | yes | Too many recent reference files are stored. | | | [`invalid_url`](#invalid_url) | `422` | no | That URL can't be used: it must be a public https URL. | | | [`fetch_failed`](#fetch_failed) | `502` | no | That URL couldn't be downloaded. | | | [`unsupported_file`](#unsupported_file) | `415` | no | That file isn't a supported image, video or audio type. | | **api** | [`invalid_api_key`](#invalid_api_key) | `401` | no | Missing, invalid or revoked API key. | | | [`idempotency_conflict`](#idempotency_conflict) | `409` | no | This Idempotency-Key was already used for a different request. | | | [`idempotency_in_flight`](#idempotency_in_flight) | `409` | yes | A request under this Idempotency-Key is still running; retry shortly. | | | [`invalid_idempotency_key`](#invalid_idempotency_key) | `400` | no | Idempotency-Key must be 1-200 printable ASCII characters. | | | [`invalid_cursor`](#invalid_cursor) | `400` | no | Pass next\_cursor exactly as a page returned it. | | | [`invalid_webhook_url`](#invalid_webhook_url) | `400` | no | webhook\_url must be a public https URL. | | | [`method_not_allowed`](#method_not_allowed) | `405` | no | This method is not supported on this path. | | | [`account_unavailable`](#account_unavailable) | `402` | no | This Voyager account is not eligible for generation. | | | [`plan_required_for_faces`](#plan_required_for_faces) | `403` | no | This video model needs the Ultra or GigaMax plan for a photoreal Cast character. | | | [`version_conflict`](#version_conflict) | `409` | no | The Cast card changed since you read it. | | | [`slug_taken`](#slug_taken) | `409` | no | Another Cast card in this workspace already uses that slug. | | | [`already_referenced`](#already_referenced) | `409` | no | That image is already a reference on this Cast card. | | | [`asset_in_use`](#asset_in_use) | `409` | yes | The file is in use by a running job or saved in a Cast card. | | | [`upload_incomplete`](#upload_incomplete) | `409` | no | Nothing was uploaded yet. | | | [`cancel_unsupported`](#cancel_unsupported) | `409` | no | This kind of job cannot be stopped once started. | | | [`unsupported_model`](#unsupported_model) | `422` | no | This model can't run that operation. | | | [`invalid_job_id`](#invalid_job_id) | `400` | no | Job ids look like job\_…; pass one exactly as returned. | | | [`voice_required`](#voice_required) | `422` | no | Choose a voice: pick one from GET /v1/voices and pass its id as input.voice\_id. | | | [`observation_timeout`](#observation_timeout) | `503` | yes | The job's status couldn't be read in time. | | | [`reference_unavailable`](#reference_unavailable) | `503` | yes | A reference file couldn't be prepared right now. | | **job** | [`queue_timeout`](#queue_timeout) | job `canceled` | no | The job waited in the queue too long and was canceled; nothing was charged. | | | [`reference_missing`](#reference_missing) | job `failed` | no | A reference file was deleted before the job started. | ## invalid\_request **`400`** · type `invalid_request` · not retryable The request is not a valid model request. ## invalid\_input **`400`** · type `invalid_request` · not retryable The model can't take this input as sent. | `details` field | Description | | - | - | | `field` | The input at fault, as a path (input.\); also in param. | | `fields` | Unknown input names, when the input names fields the model does not take. | ## content\_policy **`422`** · type `unprocessable` · not retryable This request was refused under the model's content policy. Change the prompt or inputs; retrying it unchanged will not succeed. | `details` field | Description | | - | - | | `reason` | What the refusal was about. One of `copyright`, `likeness`, `minors`, `other`, `sexual`, `violence`. One of `copyright`, `likeness`, `minors`, `other`, `sexual`, `violence`. | ## upstream\_unavailable **`503`** · type `upstream_error` · retryable The model couldn't run this request right now. You were not charged; try again shortly. ## rate\_limited **`429`** · type `rate_limited` · retryable Too many requests. Retry after the indicated delay. ## queue\_full **`429`** · type `rate_limited` · retryable Your plan's limit of generations running at once is reached. Retry when one finishes. | `details` field | Description | | - | - | | `upgrade_url` | Where to upgrade the plan or add credits. | ## model\_unavailable **`503`** · type `upstream_error` · retryable This model isn't available right now. ## model\_not\_found **`404`** · type `not_found` · not retryable Unknown model. ## insufficient\_credits **`402`** · type `permission` · not retryable Not enough credits for this generation. | `details` field | Description | | - | - | | `upgrade_url` | Where to upgrade the plan or add credits. | ## paid\_plan\_required **`402`** · type `permission` · not retryable This model needs a paid plan. | `details` field | Description | | - | - | | `upgrade_url` | Where to upgrade the plan or add credits. | ## model\_not\_in\_plan **`402`** · type `permission` · not retryable This model isn't included in your plan. | `details` field | Description | | - | - | | `upgrade_url` | Where to upgrade the plan or add credits. | ## model\_access\_required **`403`** · type `permission` · not retryable This model needs access to be granted first. ## outcome\_unknown **`503`** · type `upstream_error` · retryable Voyager couldn't confirm this generation yet. Ask for its status again; never submit it again, or it may be charged twice. | `details` field | Description | | - | - | | `support_ref` | Quote it to support. | ## expired **`410`** · type `not_found` · not retryable These results have expired. ## not\_found **`404`** · type `not_found` · not retryable No such generation for this workspace. ## conflict **`409`** · type `conflict` · not retryable This generation can't change from its current state. ## forbidden **`403`** · type `permission` · not retryable This request isn't allowed for this workspace. ## internal\_error **`500`** · type `internal_error` · not retryable Something went wrong on Voyager's side. ## catalog\_unavailable **`503`** · type `upstream_error` · retryable The model catalog is temporarily unavailable. Retry shortly. ## billing\_unavailable **`503`** · type `upstream_error` · retryable Your plan couldn't be checked right now, so this paid request can't run yet. Retry shortly. ## no\_voyager\_seat **`402`** · type `permission` · not retryable You don't have a seat on this workspace's Voyager plan. ## credits\_reloading **`402`** · type `permission` · retryable Your credits are reloading and the balance is briefly short. Retry shortly. ## cast\_not\_supported **`422`** · type `unprocessable` · not retryable Cast works with image and video models only. ## voice\_cloning\_unavailable **`403`** · type `permission` · not retryable Voice cloning isn't available to this workspace. ## too\_many\_references **`422`** · type `unprocessable` · not retryable Too many reference files for this model and operation. ## payload\_too\_large **`413`** · type `invalid_request` · not retryable The request body is too large. ## upload\_too\_large **`413`** · type `invalid_request` · not retryable This file is over your plan's per-file limit. ## intake\_full **`429`** · type `rate_limited` · retryable Too many recent reference files are stored. Delete some, or wait: they're kept 7 days. ## invalid\_url **`422`** · type `unprocessable` · not retryable That URL can't be used: it must be a public https URL. ## fetch\_failed **`502`** · type `upstream_error` · not retryable That URL couldn't be downloaded. Check it is live and public. ## unsupported\_file **`415`** · type `invalid_request` · not retryable That file isn't a supported image, video or audio type. ## invalid\_api\_key **`401`** · type `authentication` · not retryable Missing, invalid or revoked API key. ## idempotency\_conflict **`409`** · type `idempotency_conflict` · not retryable This Idempotency-Key was already used for a different request. ## idempotency\_in\_flight **`409`** · type `conflict` · retryable A request under this Idempotency-Key is still running; retry shortly. ## invalid\_idempotency\_key **`400`** · type `invalid_request` · not retryable Idempotency-Key must be 1-200 printable ASCII characters. ## invalid\_cursor **`400`** · type `invalid_request` · not retryable Pass next\_cursor exactly as a page returned it. ## invalid\_webhook\_url **`400`** · type `invalid_request` · not retryable webhook\_url must be a public https URL. ## method\_not\_allowed **`405`** · type `invalid_request` · not retryable This method is not supported on this path. ## account\_unavailable **`402`** · type `permission` · not retryable This Voyager account is not eligible for generation. ## plan\_required\_for\_faces **`403`** · type `permission` · not retryable This video model needs the Ultra or GigaMax plan for a photoreal Cast character. Use a stylized character or a different video model. ## version\_conflict **`409`** · type `conflict` · not retryable The Cast card changed since you read it. Read it again and retry with its current version. ## slug\_taken **`409`** · type `conflict` · not retryable Another Cast card in this workspace already uses that slug. ## already\_referenced **`409`** · type `conflict` · not retryable That image is already a reference on this Cast card. ## asset\_in\_use **`409`** · type `conflict` · retryable The file is in use by a running job or saved in a Cast card. Delete it after the job ends, or remove it from the card first. ## upload\_incomplete **`409`** · type `conflict` · not retryable Nothing was uploaded yet. PUT the file to upload\_url first. ## cancel\_unsupported **`409`** · type `conflict` · not retryable This kind of job cannot be stopped once started. It finishes on its own. ## unsupported\_model **`422`** · type `unprocessable` · not retryable This model can't run that operation. GET /v1/models/\{id} lists the operations it runs. ## invalid\_job\_id **`400`** · type `invalid_request` · not retryable Job ids look like job\_…; pass one exactly as returned. ## voice\_required **`422`** · type `unprocessable` · not retryable Choose a voice: pick one from GET /v1/voices and pass its id as input.voice\_id. ## observation\_timeout **`503`** · type `upstream_error` · retryable The job's status couldn't be read in time. Ask again with the same id; never submit it again. ## reference\_unavailable **`503`** · type `upstream_error` · retryable A reference file couldn't be prepared right now. Retry shortly. ## queue\_timeout On a finished job: status `canceled` · not retryable The job waited in the queue too long and was canceled; nothing was charged. ## reference\_missing On a finished job: status `failed` · not retryable A reference file was deleted before the job started. Nothing was charged. ## Cloud machines errors The cloud machines endpoints (`/v1/machines`) use the same envelope with UPPER\_SNAKE codes, such as `PLAN_REQUIRED`, `INSUFFICIENT_CREDITS` and `MACHINE_NOT_READY`. They're listed in the [cloud machines reference](/api/machines/reference#errors). # Jobs and polling Source: https://docs.voyager.so/api/jobs The job object, statuses, waiting and polling, how credits are held and charged, cancelling, uploads, output retention and idempotency. A **job** is one generation: an image, a video, speech, music, a sound effect or a 3D model. You create it with `POST /v1/jobs`, it runs on Voyager's side, and you read the result with `GET /v1/jobs/{id}` or receive it by [webhook](/api/webhooks). ## Create a job ```bash theme={"system"} curl https://api.voyager.so/v1/jobs \ -H "Authorization: Bearer $VOYAGER_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: 9b2f6c1e-2f43-4d0e-9a51-5d1f8f0a7c11" \ -d '{ "model": "nano-banana-2.1", "operation": "text-to-image", "input": { "prompt": "a red fox in snow", "aspect_ratio": "16:9" }, "webhook_url": "https://example.com/hooks/voyager", "metadata": { "shot": "12" } }' ``` | Field | Type | Description | | - | - | - | | `model` | `string` · required | A model id from GET /v1/models. Up to 200 characters. | | `operation` | `string` or `null` | One of text-to-image, edit, text-to-video, image-to-video, reference-to-video, tts, music, sound-effects, text-to-3d, image-to-3d, image-to-3d-body, align-3d, segment-image, segment-image-data, segment-video, segment-video-data, segment-everything, image-embedding (GET /v1/models/\{id} lists a model's). Required unless the model runs only one. | | `input` | `JobInput` | The model's canonical inputs: its input\_schema on GET /v1/models/\{id} (file\_ ids or https URLs for media), plus optional cast (up to 4 cst\_ ids) on image and video operations. | | `webhook_url` | `string` or `null` | Public https URL that receives job.succeeded / job.failed / job.canceled (Standard Webhooks). Up to 2048 characters. | | `metadata` | `object` or `null` | Up to 16 string pairs echoed on the job and its webhooks (values ≤ 500 chars). | `input.cast` takes up to 4 `cst_…` IDs from [Cast](/api/cast) on image and video operations; other models refuse it with [`cast_not_supported`](/api/errors#cast_not_supported). The fields `input` takes are on [Models](/api/models#input-fields). The response is `201 Created` with the job, usually `queued`. Unknown top-level fields are refused with `400` [`invalid_request`](/api/errors#invalid_request). ### Wait on create Add `Prefer: wait=N` (N up to 60) to hold the create request for up to N seconds. If the job finishes in time, the response is `200 OK` with the finished job; otherwise it's `201 Created` with the queued or running job and you continue with `GET`. The response echoes `Preference-Applied: wait=N`. Use it for fast models; for video and 3D, create without waiting. ## The job object ```json theme={"system"} { "id": "job_01JC4Q8ZK3V0B7M2X9T5R6N4PA", "object": "job", "type": "image", "model": "nano-banana-2.1", "operation": "text-to-image", "status": "succeeded", "input": { "prompt": "a red fox in snow", "aspect_ratio": "16:9" }, "outputs": [ { "id": "file_01JC4QB3N8D5H1W6Y2K7M0F9EC", "object": "file", "type": "image", "mime_type": "image/png", "file_name": "image-1.png", "size_bytes": 1843120, "url": "https://api.voyager.so/v1/files/file_01JC4QB3N8D5H1W6Y2K7M0F9EC/content?exp=…&sig=…", "url_expires_at": "2026-11-05T22:10:00Z", "expires_at": "2026-12-05T21:09:55Z", "width": 1344, "height": 768, "duration_seconds": null } ], "credits": { "estimated": …, "held": …, "charged": …, "released": …, "state": "settled", "charge_ref": "chg_01JC4QB9…" }, "error": null, "metadata": { "shot": "12" }, "created_at": "2026-11-05T21:09:41Z", "started_at": "2026-11-05T21:09:42Z", "completed_at": "2026-11-05T21:09:55Z", "poll_after_ms": null, "links": { "self": "/v1/jobs/job_01JC4Q8ZK3V0B7M2X9T5R6N4PA", "cancel": "/v1/jobs/job_01JC4Q8ZK3V0B7M2X9T5R6N4PA/cancel" } } ``` | Field | Type | Description | | - | - | - | | `id` | `string` | job\_… | | `object` | `string` | Always "job". Always `job`. | | `type` | `string` | image, video, speech, music, sound\_effect or 3d. | | `model` | `string` or `null` | The model that ran (or will run) the job. | | `operation` | `string` or `null` | e.g. text-to-image, edit, image-to-video, tts. | | `status` | `string` | queued, running, succeeded, failed or canceled. One of `queued`, `running`, `succeeded`, `failed`, `canceled`. | | `input` | `object` | The job's input, as sent. | | `outputs` | array of `JobOutput` | The files the job made, once it succeeded. | | `credits` | `JobCredits` | What the job is expected to cost and what it was charged. | | `error` | `JobError` or `null` | Why the job failed or was canceled. | | `metadata` | `object` | The metadata sent with the job, echoed as is. | | `created_at` | `string` (date-time) or `null` | When it was created (ISO 8601). | | `started_at` | `string` (date-time) or `null` | When the job started running (ISO 8601); null while queued. | | `completed_at` | `string` (date-time) or `null` | When the job reached a terminal status (ISO 8601); null until then. | | `poll_after_ms` | `integer` or `null` | While active: when to poll again. | | `links` | `JobLinks` | Links to read and cancel the job. | | `cast_usage` | `object` or `null` | Jobs created with X-Voyager-Cast-Version: 1 and input.cast: what the Elements compiled to (strategy, card versions, sent and omitted photos, warnings). Absent on every other job. | Each entry in `outputs`. A signed `url` is valid until `url_expires_at` (1 hour); `expires_at` is when the file itself is deleted. 3D outputs add `formats` (one downloadable file per format) and a still `preview_url`. | Field | Type | Description | | - | - | - | | `id` | `string` | file\_… id; GET /v1/files/\{id} for a fresh link. | | `object` | `string` | Always "file". Always `file`. | | `type` | `string` | image, video, audio, model3d or other. | | `mime_type` | `string` | The file's media type, e.g. image/png or video/mp4. | | `file_name` | `string` | The file's name. | | `size_bytes` | `integer` | Size in bytes. | | `url` | `string` | Signed download link, valid one hour. | | `url_expires_at` | `string` (date-time) | When `url` stops working (ISO 8601); read the object again for a fresh link. | | `expires_at` | `string` (date-time) or `null` | When the file itself is deleted (outputs are kept 30 days). | | `width` | `integer` or `null` | Width in pixels, when known. | | `height` | `integer` or `null` | Height in pixels, when known. | | `duration_seconds` | `number` or `null` | Length in seconds, when known. | | `formats` | array of `JobOutputFormat` or `null` | 3D jobs: every downloadable format. | | `preview_url` | `string` or `null` | 3D jobs: a still preview. | | `role` | `string` or `null` | What the file is beside the main output: mask, cutout, mask\_video, data or preview (segmentation). | | `metadata` | `object` or `null` | Per-file facts: a mask's object\_id, score and box (source pixels), a mask video's frames. | `error`, when the job `failed` or was `canceled` by Voyager (the codes are on [Errors](/api/errors)): | Field | Type | Description | | - | - | - | | `code` | `string` | A stable machine code (see x-voyager-errors). | | `message` | `string` | For developers. Not localized. | | `details` | `object` or `null` | Code-specific detail. | ## Statuses ```text theme={"system"} queued ──▶ running ──▶ succeeded │ ├──────▶ failed └──────────┴──────▶ canceled ``` | Status | Meaning | | - | - | | `queued` | Accepted and waiting to start, for example because you're at your [parallel generation limit](/api/rate-limits#concurrency). | | `running` | Generating. | | `succeeded` | Finished; `outputs` holds the results. | | `failed` | Finished without a result. `error.code` says why, for example [`content_policy`](/api/errors#content_policy) for a refused prompt, or [`outcome_unknown`](#unresolved-outcomes). | | `canceled` | Stopped by you, or by Voyager after waiting too long in the queue (`error.code` [`queue_timeout`](/api/errors#queue_timeout)). | `succeeded`, `failed` and `canceled` are terminal: a job in one of them never changes status again. Its `credits` can still change until `credits.state` is `settled` or `unresolved`. ## Wait for a result ### Long-poll `GET /v1/jobs/{id}?wait=N` (N up to 25) holds the request until the job reaches a terminal status or N seconds pass, then returns the job either way. Loop while the status is `queued` or `running`: ```bash theme={"system"} curl "https://api.voyager.so/v1/jobs/job_01JC4Q8ZK3V0B7M2X9T5R6N4PA?wait=25" \ -H "Authorization: Bearer $VOYAGER_API_KEY" ``` ### Plain polling Without `wait`, `GET /v1/jobs/{id}` returns at once. While the job is active the response has a `Retry-After` header (seconds) and `poll_after_ms` in the body: wait that long before the next request. Polling faster doesn't make the job finish sooner and counts against your [rate limit](/api/rate-limits). ### Webhooks Pass `webhook_url` on create and Voyager calls you when the job finishes. See [Webhooks](/api/webhooks). `GET /v1/jobs/{id}` stays the source of truth. ## List jobs `GET /v1/jobs` lists your jobs in this workspace, newest first. | Parameter | Type | Description | | - | - | - | | `limit` | `integer` | 1–100. Default `20`. | | `cursor` | `string` or `null` | next\_cursor from the previous page. Up to 400 characters. | | `type` | `string` or `null` | One of `image`, `video`, `speech`, `music`, `sound_effect`, `3d`, `segment`. | | `status` | `string` or `null` | One of `queued`, `running`, `succeeded`, `failed`, `canceled`. | | `created_after` | `string` (date-time) or `null` | Only jobs created after this instant. | ```json theme={"system"} { "object": "list", "data": [ { "id": "job_…", "object": "job", "status": "succeeded" } ], "has_more": true, "next_cursor": "eyJ2Ijox…" } ``` ## Credits Every job is paid from your workspace's Voyager credits. The `credits` object keeps the job's result apart from its bill: | Field | Type | Description | | - | - | - | | `estimated` | `number` or `null` | Estimated charge when the job is accepted. Not a cap. | | `held` | `number` or `null` | Credits held for this job now, where proven; null when unknown. | | `charged` | `number` or `null` | Final charge once settled; null until then (never a stand-in zero). | | `released` | `number` or `null` | Held credits returned, where proven; null when unknown. | | `state` | `string` | pending: the final charge may still arrive; settled: final; unresolved: this API will not state it (see your usage), or the job's outcome could not be proven. One of `pending`, `settled`, `unresolved`. | | `charge_ref` | `string` or `null` | The charge reference in your usage records; quote it to support. | Any amount can be `null`, which means **not known yet**, never zero. A job finishing (and its webhook firing) doesn't mean its charge is final: read `credits.state`. To see a cost before you run, call `POST /v1/estimate` with the same body you'd send to `POST /v1/jobs`: ```json theme={"system"} { "object": "estimate", "model": "nano-banana-2.1", "operation": "text-to-image", "estimated_charge": …, "required_hold": …, "available_credits": …, "can_run": true, "reason": null, "upgrade_url": null } ``` | Field | Type | Description | | - | - | - | | `object` | `string` | Always "estimate". Always `estimate`. | | `model` | `string` | The model estimated. | | `operation` | `string` | The operation estimated. | | `estimated_charge` | `number` or `null` | Expected credits for this request; null when unknown. | | `required_hold` | `number` or `null` | Credits held when the job is accepted, at today's prices; null when unknown. | | `available_credits` | `number` or `null` | The workspace's credit balance, as its Voyager dashboard shows it; null when unknown. | | `can_run` | `boolean` | False when the plan, access or balance refuses it, or it is unknown. | | `reason` | `string` or `null` | Why not, as the error code a create would get: model\_not\_in\_plan, model\_access\_required, insufficient\_credits, credits\_reloading (retry shortly), free\_allowance\_exhausted, free\_window\_limit, free\_media\_limit, paid\_plan\_required, no\_voyager\_seat, model\_unavailable; estimate\_unavailable when it could not be read. | | `upgrade_url` | `string` or `null` | Where to upgrade the plan or add credits, when that is the reason. | | `estimate_basis` | `string` or `null` | "fallback" when nothing prices this request and estimated\_charge is its model's fallback rate (show it as an estimate); absent otherwise. A fallback figure never refuses the job. | | `estimate_source` | `string` or `null` | With estimate\_basis fallback, the rate's evidence: a its own settlements, b its provider's published price, c its own other prices scaled, d a peer model's, e its media type's default. One of `a`, `b`, `c`, `d`, `e`. | | `cast_usage` | `object` or `null` | With X-Voyager-Cast-Version: 1 and input.cast: what the Elements compile to. Pass its plan as input.cast\_plan to create the job only if the Elements still compile to it. | An estimate holds no credits and isn't a cap: the charge is the real cost. When `can_run` is `false`, `reason` is the error code creating the same job would get; for plan and credit refusals, `upgrade_url` opens the dashboard. An estimate also needs a paid plan. It never imports `https` media inputs, except a source recording for a speech, voice or audio model whose price depends on its length: that one is imported into your workspace to measure it and kept as a reference file for 7 days. Send a `file_…` ID from `POST /v1/files` to avoid the import. ### How each type is charged | Type | Rule | | - | - | | `image`, `video` | Credits are held when the job is accepted. After the job succeeds, `state` stays `pending` and `charged` stays `null` until the real cost is confirmed, which can take up to 7 days; if it's never confirmed, the estimate is charged. Whatever isn't charged is released. | | `speech` | Charged when the job finishes; `state` is `settled` at completion. | | `music`, `sound_effect` | Charged when the job finishes; `state` is `settled` at completion. | | `3d` | Charged when the job finishes. If texturing fails after the untextured preview is ready, the job succeeds with the preview as its output, and you're charged for the preview only. | A `failed` job releases its hold and charges nothing, except under the 3D rule above or an [unresolved outcome](#unresolved-outcomes). A job canceled while still `queued` charges nothing. ### Unresolved outcomes Rarely, Voyager can't confirm how a generation went, for example when a model stops answering mid-job. You then get [`outcome_unknown`](/api/errors#outcome_unknown) (retryable): Voyager couldn't confirm the generation yet. **Ask for its status again** with `GET /v1/jobs/{id}`, with backoff. `credits.state` can be `unresolved`: the API won't state that charge, or the outcome couldn't be proven; your usage on the dashboard shows what was charged. > [!WARNING] > > **Never submit the same request again** as a new job (a new `Idempotency-Key`): it may be charged twice. If it stays unresolved, contact [support@voyager.so](mailto:support@voyager.so) with `error.details.support_ref` and `credits.charge_ref`. ## Cancel a job `POST /v1/jobs/{id}/cancel` returns the job as it stands after the request. | When | What happens | | - | - | | `queued`, not yet sent to the model | Canceled, any type. Nothing is charged and the hold is released. | | `running` image, video or speech | Best effort. The model may finish first, so check the returned `status`: it can be `succeeded`. If it stops, work already done may still be charged; read `credits` once `state` is `settled`. | | `running` music, sound effect or 3D | Can't be stopped: `409` [`cancel_unsupported`](/api/errors#cancel_unsupported). The job finishes and is charged normally. | | Already terminal | No change; the job is returned as is. | ## Outputs and retention * Outputs are files in your workspace, kept for **30 days** after the job finishes. Then they're deleted. * `outputs[].url` is a signed link valid for **1 hour** that needs no Authorization header. Each `GET /v1/jobs/{id}` or `GET /v1/files/{id}` returns a fresh link. Download results you want to keep. * An output's `file_…` ID can be used as an input to another job, for example to edit an image or animate it into a video. * After its outputs are deleted, a job's results are gone: you get [`expired`](/api/errors#expired) (`410`), and `outputs` is empty. * `DELETE /v1/files/{id}` deletes a file now (`204 No Content`). A file a running job still uses, or one saved in a Cast card, returns `409` [`asset_in_use`](/api/errors#asset_in_use). ## Uploads Reference images, audio and video go in through `/v1/files`. Use the returned `file_…` ID in a job's `input`. A media input can also be a public `https` URL: when you create the job, Voyager imports it into your workspace, like `POST /v1/files` with a `url`. The import happens after the plan and credit checks, so a refused request leaves no file behind. An unusable URL is [`invalid_url`](/api/errors#invalid_url); one that can't be downloaded is [`fetch_failed`](/api/errors#fetch_failed). **1. Create the file** ```bash theme={"system"} curl https://api.voyager.so/v1/files \ -H "Authorization: Bearer $VOYAGER_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{"file_name": "hero.jpg", "content_type": "image/jpeg", "size_bytes": 482113}' ``` ```json theme={"system"} { "id": "file_01JC4R2M7K9T3V5B8N1X6D0QWE", "object": "file", "status": "pending", "file_name": "hero.jpg", "content_type": "image/jpeg", "size_bytes": 482113, "retention": "pending", "expires_at": "2026-11-06T21:10:00Z", "upload_url": "https://…", "method": "PUT", "headers": { "Content-Type": "image/jpeg" }, "upload_expires_at": "2026-11-05T21:40:00Z" } ``` **2. Upload the bytes** Send the file to `upload_url` with `method` and exactly the `headers` returned, before `upload_expires_at`. `size_bytes` must be the exact size you'll send. Don't send your API key to this URL. ```bash theme={"system"} curl -X PUT --upload-file hero.jpg -H "Content-Type: image/jpeg" "" ``` **3. Complete the upload** ```bash theme={"system"} curl -X POST https://api.voyager.so/v1/files/file_01JC4R2M7K9T3V5B8N1X6D0QWE/complete \ -H "Authorization: Bearer $VOYAGER_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" ``` Voyager checks the bytes, type and size. The file comes back `ready`, or `failed` with an `error` (wrong type, a size other than declared, or over your plan's limit). Only `ready` files can be used in jobs. Completing is safe to repeat; calling it before the bytes are uploaded returns `409` [`upload_incomplete`](/api/errors#upload_incomplete). To import from a public URL instead, send `{"url": "https://…"}` to `POST /v1/files`. Voyager downloads it and the file comes back `ready` at once. The `POST /v1/files` body: One of: **FileUpload** | Field | Type | Description | | - | - | - | | `file_name` | `string` · required | Up to 200 characters. | | `content_type` | `string` · required | image/png, image/jpeg, video/mp4, audio/mpeg… Up to 100 characters. | | `size_bytes` | `integer` · required | Exact size of the file you will PUT. | **FileImport** | Field | Type | Description | | - | - | - | | `url` | `string` · required | Import a public https file instead. Up to 4096 characters. | | `file_name` | `string` | Up to 200 characters. | The file object: | Field | Type | Description | | - | - | - | | `id` | `string` | file\_…; pass it in a job's input (image, images, video, audio…). | | `object` | `string` | Always "file". Always `file`. | | `status` | `string` | pending until the upload completes, then ready (or failed). One of `pending`, `ready`, `failed`. | | `type` | `string` or `null` | image, video, audio, model3d or other (ready files). | | `file_name` | `string` | The file's name. | | `content_type` | `string` | The file's media type, e.g. image/png. | | `size_bytes` | `integer` | Size in bytes. | | `url` | `string` or `null` | Ready files: signed download link, valid one hour. | | `url_expires_at` | `string` (date-time) or `null` | When `url` stops working (ISO 8601); read the object again for a fresh link. | | `expires_at` | `string` (date-time) or `null` | When the file is deleted: references 7 days, outputs 30 days, Cast never; pending uploads 24 h. | | `retention` | `string` or `null` | How long the file is kept. One of `reference`, `output`, `cast`, `pending`. | | `created_at` | `string` (date-time) or `null` | When it was created (ISO 8601). | | `error` | `JobError` or `null` | Why the upload failed, when status is failed. | | `width` | `integer` or `null` | Width in pixels, when known. | | `height` | `integer` or `null` | Height in pixels, when known. | | `duration_seconds` | `number` or `null` | Length in seconds, when known. | | `upload_url` | `string` or `null` | PUT the bytes here with `headers`, then complete. | | `method` | `string` or `null` | The HTTP method to upload the bytes with, while pending. | | `headers` | `object` or `null` | Headers to send with the upload, while pending. | | `upload_expires_at` | `string` (date-time) or `null` | When upload\_url stops accepting the bytes (ISO 8601). | | Limit | Value | | - | - | | File size | Up to 250 MiB per file on paid plans | | File types | Images, video and audio (for example `image/png`, `image/jpeg`, `video/mp4`, `audio/mpeg`). Others return `415` [`unsupported_file`](/api/errors#unsupported_file). | | Uploads never completed | Deleted after **24 hours** | | Uploaded references | Kept **7 days**, then deleted. Upload again, or save them to a [Cast](/api/cast) card to keep them. | | Outputs | Kept **30 days** | | Cast references | Kept until you remove them | `GET /v1/files/{id}` returns the file with a fresh signed `url` to `GET /v1/files/{id}/content` (valid 1 hour; returns the bytes, answers `HEAD`, and a single `Range` request gets `206`). `expires_at` and `retention` say when it will be deleted. ## Idempotency Every `POST` accepts an `Idempotency-Key` header. On the calls that create something (jobs, files and their `complete`, Cast cards and references) Voyager stores the result and replays it as below. Estimates and cancel accept the key too, but don't replay: repeating them never starts work or spends credits. (An estimate for a speech, voice or audio model priced by a source recording's length imports an `https` recording each time it's called; send a `file_…` ID from `POST /v1/files` instead to avoid that.) Send a new UUID per logical request and reuse it on every retry of that request (1–200 printable ASCII characters; anything else is `400` [`invalid_idempotency_key`](/api/errors#invalid_idempotency_key)). It matters most on `POST /v1/jobs`, where a lost response could otherwise buy twice. * **Same key, same body:** you get the original result back (for a job, `200 OK` with an `Idempotent-Replayed: true` header), however long ago it was made. Voyager never buys twice for one key. * **Same key, different body:** `409` [`idempotency_conflict`](/api/errors#idempotency_conflict). Use a new key for a new request. * **Same key while the first request is still being processed:** `409` [`idempotency_in_flight`](/api/errors#idempotency_in_flight). Retry shortly with the same key and body. * **No key:** every request is new. A retry after a lost response can create, and charge for, a second job. "Same body" compares `model`, `operation`, `input`, `webhook_url` and `metadata` (key order and whitespace don't matter). Keys belong to you and the workspace, not to one API key, so a retry from a rotated key still finds the original. A request refused before it was accepted (`400`, `401`, `402`, `403`, `404`, `422` or `429`, including a full queue) doesn't use up its key: fix the problem and retry with the same key. Once a request is accepted, its key stays bound to its result. ## Related * [Webhooks](/api/webhooks) * [Errors](/api/errors) * [Rate limits and usage](/api/rate-limits) # Run commands Source: https://docs.voyager.so/api/machines/commands Run a shell command on a cloud machine and wait for its output, or start a long job and follow its logs, wait for it and cancel it. `POST /v1/machines/{id}/run` runs a command on the machine. Running a command on a paused machine resumes it first, and the response says `"resumed": true`. | Body field | Description | | - | - | | `command` | A shell command line, run with `sh -c`. Send `command` or `argv`. | | `argv` | The program and its arguments as a list, run without a shell. | | `cwd` | Working folder on the machine (default `/project`). | | `env` | Extra environment variables, as an object. | | `timeout` | Seconds before the command is killed. | | `wait` | `true` to wait up to about 60 seconds for it to finish and return its output. | ## Short commands: wait for the output With `"wait": true` the call waits up to about 60 seconds and returns `{job_id, status, exit_code, stdout, stderr, truncated, resumed, next}`. `stderr` is merged into `stdout` in order, so `stderr` is always empty. When the output is longer than 256 KB, `stdout` holds the last 256 KB and `truncated` is `true`; read all of it from the job's logs. If the command is still running after about 60 seconds, the call returns the running job instead (`202`), and you follow it as below. ```sh curl theme={"system"} curl -s https://api.voyager.so/v1/machines/$MACHINE/run \ -H "Authorization: Bearer $VOYAGER_API_KEY" -H "Content-Type: application/json" \ -d '{"command": "nvidia-smi --query-gpu=name,memory.total --format=csv", "wait": true}' ``` ```python Python theme={"system"} import os, requests r = requests.post( f"https://api.voyager.so/v1/machines/{os.environ['MACHINE']}/run", headers={"Authorization": f"Bearer {os.environ['VOYAGER_API_KEY']}"}, json={"argv": ["nvidia-smi"], "wait": True}, ).json() print(r["exit_code"], r["stdout"]) ``` ```sh CLI theme={"system"} voyager-cloud exec $MACHINE -- nvidia-smi ``` A non-zero `exit_code` means the command failed. `voyager-cloud exec` waits for any length of command, streams its output and exits with the same code. ## Long commands: jobs Without `wait`, the call returns `202` with a **job** (`mjb_…`) straight away. | Call | What it does | | - | - | | `GET /v1/machines/jobs/{job}?wait=N` | The job: `{id, machine_id, status, exit_code, output_tail, started_at, ended_at, next}`, holding up to `N` seconds (at most 60) for it to finish. `status` is `running`, `succeeded`, `failed` or `canceled`; `output_tail` is the last few KB of output. | | `GET /v1/machines/jobs/{job}/logs?cursor=` | The output so far, a page at a time: `{text, next_cursor, eof}`. Pass `next_cursor` as `cursor` for the next page; `eof` is `true` once the job has ended and everything was returned. Add `follow=true` to stream the output as plain text until the job ends. | | `POST /v1/machines/jobs/{job}/cancel` | Stops the job. | With the CLI: ```sh theme={"system"} job=$(voyager-cloud exec --detach $MACHINE -- ./long-render.sh) voyager-cloud logs $job --follow voyager-cloud wait $job # exits with the job's exit code ``` A machine pauses itself after `idle_timeout` seconds without a command or file transfer. # Files and ports Source: https://docs.voyager.so/api/machines/files Copy files and folders to and from a cloud machine, and open a port on it at a private run.voyager.computer link. Moving files to or from a paused machine resumes it first. ## Upload The CLI handles everything below; use it unless you're writing your own client: ```sh theme={"system"} voyager-cloud push $MACHINE scene/ # a folder, to the same path on the machine voyager-cloud push $MACHINE ./big.blend assets/big.blend ``` `POST /v1/machines/{id}/files/upload` takes `{"root", "files": [{"path", "size", "sha256", "content_base64"}]}`. Paths are relative to `root` (default `/project`) or absolute. Each file in the response has a `status`: | `status` | What it means | | - | - | | `unchanged` | The machine already has this file with the same `sha256`; it was skipped. | | `written` | Sent inline in `content_base64` (files up to 4 MiB) and written. | | `upload` | Too big to send inline. `PUT` the whole file to its `upload_url` before `expires_at`, then commit it. | Commit uploaded files with `POST /v1/machines/{id}/files/upload/complete` and `{"root", "files": [{"path", "sha256", "upload_id"}]}`, using each file's `upload_id`. Each file comes back `written`, or `committing` while it's still being copied onto the machine. ## Download ```sh theme={"system"} voyager-cloud pull $MACHINE out/ # a folder voyager-cloud pull $MACHINE out/final.exr ./renders/ ``` `POST /v1/machines/{id}/files/download` takes `{"root", "paths": [...]}`, files or folders, relative to `root` (default `/project`). Each file comes back with its `path`, `size` and `sha256`, and either `content_base64` (small files) or a `download_url` to `GET` (larger files; valid 2 hours). ## Ports Run a server on the machine, such as a preview, a notebook or a viewer, and open it in your browser: ```sh theme={"system"} voyager-cloud exec --detach $MACHINE -- python3 -m http.server 8080 voyager-cloud port $MACHINE 8080 ``` `POST /v1/machines/{id}/ports` with `{"port": 8080}` returns `{port, url, expires_at}`, where `url` is a link like `https://k3v9q2m7x4b8n1c6z5w0.run.voyager.computer/`. It serves HTTP and WebSockets while the machine runs, and stops working when it's released or the link expires. > [!WARNING] > > Anyone with the link can reach that port while the machine runs. Don't share it, and don't serve anything on it you wouldn't want seen. # Machines and cost Source: https://docs.voyager.so/api/machines/machines Lease a cloud machine with a preset, GPU, image, idle timeout and budget, wait until it's ready, pause, resume, snapshot and release it, and read what it cost. Every request needs `Authorization: Bearer $VOYAGER_API_KEY` (an API key from [voyager.so/dashboard/api](https://voyager.so/dashboard/api)), or a signed-in `voyager-cloud`. Paths below are relative to `https://api.voyager.so/v1/machines`. Every route that takes a machine id (`mch_…`) also takes its name. ## Lease a machine `POST /v1/machines` returns `202` with the new machine in `starting`. Send an `Idempotency-Key` (a new UUID per machine you mean to lease, reused on retries) so a retry never leases a second one. ```sh curl theme={"system"} curl -s https://api.voyager.so/v1/machines \ -H "Authorization: Bearer $VOYAGER_API_KEY" -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{"preset": "render", "name": "shot-42", "idle_timeout": 900}' ``` ```python Python theme={"system"} import os, uuid, requests api = "https://api.voyager.so/v1/machines" headers = {"Authorization": f"Bearer {os.environ['VOYAGER_API_KEY']}"} machine = requests.post( api, headers={**headers, "Idempotency-Key": str(uuid.uuid4())}, json={"preset": "render", "name": "shot-42", "idle_timeout": 900}, ).json() machine = requests.get(f"{api}/{machine['id']}", headers=headers, params={"wait": 60}).json() print(machine["status"], machine["next"]) ``` ```sh CLI theme={"system"} voyager-cloud lease render --name shot-42 --wait --json ``` | Body field | Default | Description | | - | - | - | | `preset` | `render` | `render`, `render-lite` or `compute`. See [presets](/api/machines/overview#presets). | | `name` | `-` | Your name for the machine, unique among your live machines. Use it in place of the id anywhere. | | `gpu` | the preset's | Lease a different GPU from `GET /v1/machines/gpus`. | | `image` | the preset's | A software image from `GET /v1/machines/images`. | | `idle_timeout` | `900` | Seconds without a command or file transfer before the machine pauses itself, from `30` to `604800` (7 days). | | `budget_usd` | none | Stop the machine once it has spent this much, in US dollars. | | `from_snapshot` | none | Start from a saved [snapshot](#snapshots) (`snp_…`) instead of a fresh disk. | ## Wait until it's ready `GET /v1/machines/{id}?wait=60` holds the request up to `wait` seconds (at most 60) for the machine to become ready, then returns it. Repeat until `status` is `ready` (or `failed`). ```json theme={"system"} { "id": "mch_01JC4V8F2H4K6M8P0R2T4W6Y8A", "name": "shot-42", "status": "ready", "gpu": "RTX-PRO-6000", "image": "creative-cuda@v3", "preset": "render", "created_at": "2026-11-06T22:01:12Z", "ready_at": "2026-11-06T22:02:40Z", "idle_timeout": 900, "cost": { "credits": "…", "usd": "…" }, "next": "Machine ready. Run a command: POST /v1/machines/mch_01JC4V8F2H4K6M8P0R2T4W6Y8A/run" } ``` This is an example. `cost` holds numbers: the credits and US dollars spent so far. | Field | Description | | - | - | | `id` | `mch_…`. Use it in every other call. | | `status` | `starting`, `ready`, `paused`, `released` or `failed`. | | `gpu`, `image`, `preset` | What the machine is running. | | `created_at`, `ready_at` | When it was leased and when it became ready (ISO 8601). | | `idle_timeout` | Seconds without a command or file transfer before it pauses itself. | | `cost` | What it has cost so far, in Voyager `credits` and `usd`. Final once released. | | `error` | Only on a `failed` machine: `{code, message}`, with an UPPER\_SNAKE `code`. | | `next` | A plain-English hint for what to do next. | `GET /v1/machines` returns `{machines, next_cursor}`: your workspace's machines, newest first, `limit` per page (default 50, at most 200). Pass `next_cursor` as `cursor` for the next page; it's `null` on the last one. Filter with `?name=` and `?status=` (comma-separated, e.g. `?status=ready,paused`). ## Pause, resume and release | Call | What happens | | - | - | | `POST /v1/machines/{id}/pause` | Stops GPU billing and keeps the disk. Files and installed software are there when it resumes. | | `POST /v1/machines/{id}/resume` | Starts it again (`202`). Running a command or moving files resumes a paused machine by itself. | | `DELETE /v1/machines/{id}` | Releases it: billing stops, the disk is deleted, and the response is the final machine with its total `cost`. | > [!WARNING] > > Release deletes the machine's disk. Pull your outputs first, or save a snapshot. Pause, resume, release, run and snapshot accept an `Idempotency-Key` too. Idle machines pause by themselves after `idle_timeout`. A paused machine doesn't bill for the GPU, but release machines you're finished with. ## Snapshots `POST /v1/machines/{id}/snapshots` (optional body `{"name"}`) saves the machine's disk and returns `{id, status, created_at, next}`, with an `snp_…` id. Lease a new machine with `"from_snapshot": ""` to start with everything that was on it, for example after a long `vork setup` or a big dependency install. CLI: `voyager-cloud snapshot `. ## Errors Errors use the API's [error envelope](/api/errors), with UPPER\_SNAKE codes such as `PLAN_REQUIRED` and `MACHINE_NOT_READY`; the [reference](/api/machines/reference#errors) lists them. `429` and `503` responses send `Retry-After`. Retry only when `retryable` is `true`, with the same `Idempotency-Key`. Billing refusals carry `details.upgrade_url`, the link to show the person who manages the workspace. # Cloud machines over MCP Source: https://docs.voyager.so/api/machines/mcp Add the Voyager Cloud GPUs MCP server to Claude Code, Codex or Claude.ai so your agent can lease GPUs, run commands, move files and release machines as tools. The **Voyager Cloud GPUs** MCP server gives an agent the same things as the CLI and API, as tools: lease a machine, run commands, upload and download files, open ports, pause and release, plus a Vork guide. It signs in with your Voyager account; there's no API key to paste. ```text theme={"system"} https://mcp.voyager.so/mcp/machines ``` > [!NOTE] > > **Before you start:** a paid Voyager workspace (Starter or above). Machines bill by the minute until they're released. This is a separate server from the main Voyager MCP server (`https://mcp.voyager.so/mcp`, see [Connect your AI](/connect/overview)); add both if you want both. > [tab] Claude Code > > ```sh theme={"system"} > claude mcp add --transport http voyager-cloud-gpus https://mcp.voyager.so/mcp/machines > ``` > > Start Claude Code, type `/mcp`, choose **voyager-cloud-gpus** and sign in with your Voyager account in the browser window that opens. > [tab] Codex > > ```sh theme={"system"} > codex mcp add voyager-cloud-gpus --url https://mcp.voyager.so/mcp/machines > ``` > > Or add it to `~/.codex/config.toml`: > > ```toml theme={"system"} > [mcp_servers.voyager-cloud-gpus] > url = "https://mcp.voyager.so/mcp/machines" > ``` > > Codex opens your browser to sign in the first time it uses the server (or run `codex mcp login voyager-cloud-gpus`). > [tab] Claude.ai > > 1. Open [**Settings → Connectors**](https://claude.ai/settings/connectors) and choose **Add custom connector**. > 2. Name it **Voyager Cloud GPUs** and paste `https://mcp.voyager.so/mcp/machines`. > 3. Click **Connect** and sign in with your Voyager account. Choose the workspace whose plan pays. > 4. In a chat, open **+ → Connectors** and turn it on. ## Tools | Tool | What it does | | - | - | | `list_presets` | Presets, GPUs and their prices | | `create_machine` | Lease a machine | | `get_machine` | One machine, optionally waiting until it's ready | | `list_machines` | Your machines | | `run_command` | Run a command, optionally waiting for its output | | `get_job` / `job_logs` / `cancel_job` | Follow, read and stop a long command | | `upload_files` | Send files: inline content, or a URL for the machine to fetch | | `download_files` | Get files back: inline when small, links when large | | `open_port` | Open a port at a `run.voyager.computer` link anyone with it can reach | | `pause_machine` / `resume_machine` / `release_machine` | Stop billing for now, come back, or finish | | `snapshot_machine` | Save the machine's disk | | `vork_guide` | The guide to rendering with [Vork](/api/machines/vork) | ## Check it worked Ask your agent: *List the Voyager cloud GPU presets and their prices.* It should call `list_presets` and show `render`, `render-lite` and `compute`. Ask it to release machines when it's done. If it forgets, idle machines pause themselves after 15 minutes; release them from the CLI with `voyager-cloud list` and `voyager-cloud release `. # Cloud machines Source: https://docs.voyager.so/api/machines/overview Lease a Voyager cloud GPU by the minute, run commands on it, move files in and out, and release it when you're done, from the voyager-cloud CLI, the REST API or MCP. A **cloud machine** is a Linux computer with a GPU in Voyager's cloud that you lease by the minute. You or your coding agent start one, run commands on it, copy files in and out, and release it. It's built for GPU work your own computer can't do quickly: renders with [Vork](/api/machines/vork), simulations, CUDA jobs and big exports. You can drive cloud machines three ways. They all do the same things on the same account: | Way | Best for | Start here | | - | - | - | | **`voyager-cloud` CLI** | You, in a terminal, or a coding agent like Claude Code or Codex | [Quickstart](/api/machines/quickstart) | | **REST API** at `https://api.voyager.so/v1/machines` | Your own code and services | [Reference](/api/machines/reference) | | **MCP server** at `https://mcp.voyager.so/mcp/machines` | Agents that work through MCP tools, including Claude.ai | [MCP setup](/api/machines/mcp) | > [!NOTE] > > **Who can use it:** a paid Voyager workspace, Starter or above, with a completed payment. On a free workspace, requests are refused with an error that carries the billing link (`details.upgrade_url`). Machines bill your workspace's Voyager credits per second while they run. See [voyager.so/pricing](https://voyager.so/pricing) for plans. ## Presets A **preset** picks the GPU and the software image. Pick one when you lease a machine; `render` is the default. | Preset | GPU | VRAM | Ray tracing | Runs Vork | Use it for | | - | - | - | - | - | - | | `render` (default) | NVIDIA RTX PRO 6000 | 96 GB | Yes | Yes | Final renders and heavy GPU work | | `render-lite` | NVIDIA L4 | 24 GB | Yes | Yes | Drafts, previews and lighter jobs, for less | | `compute` | NVIDIA H100 | 80 GB | No | No | CUDA compute, training and simulation that don't need ray tracing | All three start from the same image, with CUDA, Python, FFmpeg, Blender tools and Vork already installed. List the presets, GPUs and images with their live prices: ```sh theme={"system"} voyager-cloud presets voyager-cloud gpus voyager-cloud images ``` Each preset and GPU shows `credits_per_minute` and `usd_per_minute`. Prices change; read them from the API rather than hard-coding them. ## Billing and auto-sleep * A machine bills **per second from when it's ready until you pause or release it**. Start-up time isn't charged. A paused machine keeps its disk and doesn't bill for the GPU. * **Idle machines pause by themselves** after 15 minutes without a command or file transfer (`idle_timeout`, 900 seconds by default; set it from 30 seconds to 7 days when you lease). * Running a command or moving files on a paused machine **resumes it** first. * Set a `budget_usd` when you lease and the machine stops once it has spent that much. * **Release** a machine when you're done. Release returns the final machine with its total `cost` (`credits` and `usd`). > [!WARNING] > > A machine you forget keeps billing until it pauses itself. Release it at the end of every session: `voyager-cloud release `. ## How a session goes 1. **Lease** a machine and wait until its `status` is `ready`. 2. **Push** your files to it. 3. **Run** commands. A command waits and prints its output by default; long ones run as a **job** you can follow. 4. **Pull** the results back. 5. **Release** the machine, or pause it to come back later. Save a **snapshot** first if you want to start the next machine from this disk. Machine `status` is one of `starting`, `ready`, `paused`, `released` or `failed`. Every machine and job response has a `next` field with a plain-English hint for what to do next, for example `Machine ready. Run a command: POST /v1/machines/{id}/run`. ## Next > [card] [Quickstart](/api/machines/quickstart) > > Install `voyager-cloud`, sign in and run your first command on a GPU. > [card] [Render with Vork](/api/machines/vork) > > The render loop for Vork scenes on Voyager cloud GPUs, with a prompt for your agent. # Cloud machines quickstart Source: https://docs.voyager.so/api/machines/quickstart Install the voyager-cloud CLI, sign in, lease a GPU, run a command, copy files and release the machine in five minutes. When you finish, you'll have run a command on a Voyager cloud GPU and released it. > [!NOTE] > > **Before you start:** a paid Voyager workspace (Starter or above). The machine bills Voyager credits by the minute until you release it; this quickstart takes a few minutes on `render-lite`, the cheapest preset. **1. Install the CLI** > [tab] macOS / Linux > > ```sh theme={"system"} > curl -fsSL https://voyager.so/cloud/install.sh | sh > ``` > > It installs `voyager-cloud` for your user (no `sudo`) and checks the download against its published checksum. > [tab] Windows (PowerShell) > > ```powershell theme={"system"} > irm https://voyager.so/cloud/install.ps1 | iex > ``` Check it: `voyager-cloud --version`. Later, `voyager-cloud update` updates it. **2. Sign in** ```sh theme={"system"} voyager-cloud login ``` Your browser opens; sign in with your Voyager account. Check who you are and which workspace pays with `voyager-cloud whoami` (switch with `voyager-cloud whoami --workspace `). On a server or in CI, set `VOYAGER_API_KEY` to an API key from [voyager.so/dashboard/api](https://voyager.so/dashboard/api) instead, or run `voyager-cloud login --key`, which reads it from that variable. Credentials are kept in one private file in your user config folder, never in the system keychain. `voyager-cloud logout` signs out and revokes them. **3. Lease a machine** ```sh theme={"system"} voyager-cloud lease render-lite --name first-try --wait ``` `--wait` returns once the machine is `ready`, usually within a couple of minutes. Note its id (`mch_…`); the commands below take the id or the name. **4. Run a command** ```sh theme={"system"} voyager-cloud exec first-try -- nvidia-smi ``` `exec` waits, streams the output and exits with the command's exit code, so scripts and agents can check it. Everything after `--` runs on the machine. **5. Move files** ```sh theme={"system"} mkdir -p hello && echo "hi from my laptop" > hello/note.txt voyager-cloud push first-try hello/ voyager-cloud exec first-try -- sh -c 'cat hello/note.txt > hello/reply.txt; echo "and from the GPU" >> hello/reply.txt' voyager-cloud pull first-try hello/reply.txt cat reply.txt ``` `push` skips files that haven't changed, so pushing the same folder again is quick. **6. Release it** ```sh theme={"system"} voyager-cloud release first-try ``` Release prints what the machine cost. It stops billing straight away. ## Check it worked `voyager-cloud list` shows your machine as `released`, with its cost. If you forget to release a machine, it pauses itself after 15 minutes idle; it doesn't bill for the GPU while paused, but release it when you're done. ## Commands Every command takes `--json`, which prints the API's objects unchanged, so scripts and agents can read every field. | Command | What it does | | - | - | | `voyager-cloud login` / `logout` / `whoami` | Sign in, sign out, show the account and workspace | | `voyager-cloud presets` / `gpus` / `images` | What you can lease, with prices | | `voyager-cloud lease [preset] [--gpu] [--name] [--idle-timeout] [--wait]` | Lease a machine | | `voyager-cloud list` | Your machines | | `voyager-cloud status [--wait]` | One machine, its status and cost so far | | `voyager-cloud exec [--detach] -- ` | Run a command; waits and streams output unless `--detach` | | `voyager-cloud wait ` / `logs [--follow]` / `cancel ` | Follow a detached job | | `voyager-cloud push [remote]` | Copy files or a folder to the machine | | `voyager-cloud pull [local]` | Copy files or a folder back | | `voyager-cloud port ` | Open a port at an `https://…run.voyager.computer/` link anyone with it can reach | | `voyager-cloud snapshot ` | Save the machine's disk | | `voyager-cloud pause` / `resume` / `release ` | Stop billing for now, come back, or finish | | `voyager-cloud help` / `help vork` | Help, and the Vork guide for agents | | `voyager-cloud update` / `--version` | Update the CLI, show its version | Environment: `VOYAGER_API_KEY` (use a key instead of signing in) and `VOYAGER_API_URL` (default `https://api.voyager.so`). ## If something went wrong > [accordion] Access refused: needs a paid plan > > Cloud machines need a paid workspace, Starter or above, with a completed payment. The error includes the billing link; owners and admins can upgrade at [voyager.so/dashboard/billing](https://voyager.so/dashboard/billing). If you belong to more than one workspace, check `voyager-cloud whoami` shows the one with the plan. > [accordion] `voyager-cloud: command not found` after installing > > Open a new terminal so it picks up the install folder, or add the folder the installer printed to your `PATH`. > [accordion] The lease takes a long time or fails > > GPUs are sometimes all in use. `failed` machines don't bill. Try again, or lease another preset (`render-lite` is often free sooner). ## Next > [card] [Machines and cost](/api/machines/machines) > > Leasing options, pausing, snapshots and what a machine costs. > [card] [Render with Vork](/api/machines/vork) > > The render loop for Vork scenes. # Cloud machines API reference Source: https://docs.voyager.so/api/machines/reference Every /v1/machines endpoint: presets, GPUs, images, machines, commands and jobs, files, ports and snapshots, with their fields and error codes. Base URL `https://api.voyager.so/v1/machines`. Authenticate with `Authorization: Bearer $VOYAGER_API_KEY`, or as `voyager-cloud` does after `voyager-cloud login`. Every endpoint, with full request and response schemas, is also in the generated **API reference** group in the sidebar and in the OpenAPI document at [api.voyager.so/v1/openapi.json](https://api.voyager.so/v1/openapi.json). Every route that takes a machine id (`mch_…`) also takes its name. | Method and path | What it does | | - | - | | `GET /presets` | `{presets: [{id, name, gpu, vram_gib, ray_tracing, image, credits_per_minute, usd_per_minute, for, default}]}` | | `GET /gpus` | GPUs you can lease: `{gpus: [{gpu, vram_gib, ray_tracing, credits_per_minute, usd_per_minute, default}]}` | | `GET /images` | `{images: [{id, name, description, default, includes}]}` | | `POST /` | Lease a machine. Body: `preset` (default `render`), `name`, `gpu`, `image`, `idle_timeout` (seconds, default `900`, `30` to `604800`), `budget_usd`, `from_snapshot`. Send `Idempotency-Key`. Returns the machine, `202`. | | `GET /` | `{machines, next_cursor}`, newest first. Query: `name`, `status` (comma-separated), `limit` (default 50, max 200), `cursor`. | | `GET /{id}?wait=N` | The machine: `{id, name, status, gpu, image, preset, created_at, ready_at, idle_timeout, cost: {credits, usd}, error, next}`. `wait` holds up to `N` seconds (max 60) for it to become ready. | | `POST /{id}/pause` | Pause: stop GPU billing, keep the disk. | | `POST /{id}/resume` | Resume a paused machine (`202`). | | `DELETE /{id}` | Release: billing stops and the disk is deleted. Returns the final machine with its `cost`. | | `POST /{id}/run` | Body `{command` or `argv, cwd, env, timeout, wait}`. With `wait: true`: `{job_id, status, exit_code, stdout, stderr, truncated, resumed, next}` within about 60 s, else the running job (`202`). Without `wait`: the job (`202`). | | `GET /jobs/{job}?wait=N` | The job: `{id, machine_id, status, exit_code, output_tail, started_at, ended_at, resumed, next}`. | | `GET /jobs/{job}/logs` | `{text, next_cursor, eof}`. Query: `cursor`; `follow=true` streams plain text until the job ends. | | `POST /jobs/{job}/cancel` | Stop the job. | | `POST /{id}/files/upload` | Body `{root, files: [{path, size, sha256, content_base64}]}`. Each file comes back `unchanged`, `written`, or `upload` with an `upload_url` to `PUT` and an `upload_id`. | | `POST /{id}/files/upload/complete` | Body `{root, files: [{path, sha256, upload_id}]}`. Commits uploaded files; each comes back `written` or `committing`. | | `POST /{id}/files/download` | Body `{root, paths: [...]}`, files or folders. Each file: `{path, size, sha256}` plus `content_base64` (small) or `download_url` (valid 2 hours). | | `POST /{id}/ports` | Body `{port}` → `{port, url, expires_at}`; `url` is `https://.run.voyager.computer/`, reachable by anyone with the link. | | `POST /{id}/snapshots` | Optional body `{name}` → `{id, status, created_at, next}`. Lease from it with `from_snapshot`. | `root` defaults to `/project`, which is also the default `cwd` for commands. Run and file calls on a paused machine resume it first and say `resumed: true`. Pause, resume, release, run and snapshot accept an `Idempotency-Key`. ## Values | Field | Values | | - | - | | Machine `status` | `starting`, `ready`, `paused`, `released`, `failed` | | Job `status` | `running`, `succeeded`, `failed`, `canceled` | | `preset` | `render` (RTX PRO 6000, default), `render-lite` (L4), `compute` (H100, no ray tracing) | | Ids | machines `mch_…`, jobs `mjb_…`, snapshots `snp_…` | ## Errors Errors use the API's [error envelope](/api/errors) (`{"error": {"code", "message", "retryable", "details", …}}`). Machine error codes are UPPER\_SNAKE. `429` and `503` responses send `Retry-After`. Retry only when `retryable` is `true`, with the same `Idempotency-Key`. | Status | Codes | What to do | | - | - | - | | `400` | `INVALID_REQUEST` | Fix the request; `message` says what's wrong. | | `401` | | The key or sign-in is missing or invalid. Sign in again or check `VOYAGER_API_KEY`. | | `402` | `INSUFFICIENT_CREDITS` | Not enough credits. Show `details.upgrade_url`. | | `403` | `PLAN_REQUIRED`, `VERIFICATION_REQUIRED` | The workspace needs a paid plan (Starter or above) with a completed payment, or the key lacks a scope. Show `details.upgrade_url`. | | `404` | `NOT_FOUND` | No such machine, job or path. | | `409` | `MACHINE_NOT_READY`, `MACHINE_RELEASED` | The machine is in the wrong state: wait until it's `ready`, or lease a new one. Also returned when an `Idempotency-Key` was used for a different request. | | `429` | | Rate limited: wait `Retry-After` seconds. | | `500` | `INTERNAL_ERROR` | Retry if `retryable` is `true`. | | `503` | `UPSTREAM_UNAVAILABLE` | No capacity or a temporary outage: wait `Retry-After` seconds and retry. | A machine that fails while starting has `status: failed` and an `error` with a `code` and `message`. A failed machine doesn't bill. # Render with Vork on Voyager cloud GPUs Source: https://docs.voyager.so/api/machines/vork Run Vork renders on a Voyager cloud GPU: which GPUs work, vork setup, the push-render-pull loop, render profiles, long renders, and a copy-paste prompt for your agent. [Vork](https://github.com/voyager-so/vork) renders scenes on a ray-tracing GPU. Voyager runs Vork on its cloud GPUs, so you or your agent can render from any computer, including one without a GPU. > [!NOTE] > > **Before you start:** a paid Voyager workspace (Starter or above) and the `voyager-cloud` CLI ([quickstart](/api/machines/quickstart)). The machine bills by the minute until you release it. ## Which GPUs run Vork Vork needs ray tracing. | Preset | GPU | Use it for | | - | - | - | | `render` (default) | RTX PRO 6000 | Final renders | | `render-lite` | L4 | Drafts and previews, for less | The `compute` preset (H100) and A100 GPUs have no ray-tracing cores and **can't run Vork**. Use them for CUDA compute, not renders. ## Give this to your agent Paste this into Claude Code, Codex or any coding agent. The same text is on [voyager.so/vork/cloud](https://voyager.so/vork/cloud) and in `voyager-cloud help vork`. ```text theme={"system"} Render with Vork (https://github.com/voyager-so/vork) on Voyager cloud GPUs. Needs a paid Voyager workspace (Starter or above). If access is refused, show me the billing link from the error. 1. Install the CLI (if voyager-cloud isn't installed yet): macOS / Linux: curl -fsSL https://voyager.so/cloud/install.sh | sh Windows (PowerShell): irm https://voyager.so/cloud/install.ps1 | iex 2. Sign in: voyager-cloud login (opens my browser). If VOYAGER_API_KEY is set, use it instead. Never ask me to paste a key. 3. Read the guide: voyager-cloud help vork 4. Lease one GPU and wait until it is ready: voyager-cloud lease render --wait --json (render-lite is cheaper for drafts) Keep the machine id. Reuse this one machine for the whole session; don't lease one per render. 5. Once per machine: voyager-cloud exec -- vork setup (up to a few minutes with no output; it is not hung) Then voyager-cloud exec -- vork help for the scene format. 6. Loop: edit the scene locally → voyager-cloud push scene/ → voyager-cloud exec -- vork render scene/shot.json --profile std/previs --out out/preview.png (exec waits and prints the output; a non-zero exit means the render failed) → voyager-cloud pull out/ → look at the image → revise. Use std/previs or std/draft while iterating; std/final (or std/path) only for the final render. Long renders: voyager-cloud exec --detach -- vork render … prints a job id; then voyager-cloud logs --follow and voyager-cloud wait before pulling. 7. When done: pull the final outputs, then voyager-cloud release . It bills until it is released or paused (idle machines pause by themselves after 15 minutes). Tell me the cost (release prints it). Using MCP instead? Add https://mcp.voyager.so/mcp/machines to your agent; it has the same steps as tools. ``` ## Do it yourself **1. Lease a GPU** ```sh theme={"system"} voyager-cloud lease render --name vork --wait ``` Use one machine for the whole session. Leasing a new one for each render repeats the setup and costs more. **2. Set up Vork, once per machine** ```sh theme={"system"} voyager-cloud exec vork -- vork setup voyager-cloud exec vork -- vork help ``` `vork setup` can take a few minutes with no output; it isn't stuck. `vork help` describes the scene format. To skip setup next time, save a [snapshot](/api/machines/machines#snapshots) afterwards and lease from it. **3. Render, look, revise** ```sh theme={"system"} voyager-cloud push vork scene/ voyager-cloud exec vork -- vork render scene/shot.json --profile std/previs --out out/preview.png voyager-cloud pull vork out/ ``` `exec` waits and prints Vork's output. A non-zero exit means the render failed; the output says why. Edit the scene on your computer and repeat. `push` sends only what changed. **4. Final render and release** ```sh theme={"system"} voyager-cloud exec vork -- vork render scene/shot.json --profile std/final --out out/final.png voyager-cloud pull vork out/ voyager-cloud release vork ``` Release prints what the session cost. ## Render profiles | Profile | Use it for | | - | - | | `std/previs` | Fast checks of framing, layout and motion while you iterate | | `std/draft` | Better-looking drafts, still quick | | `std/final` | The final render | | `std/path` | An alternative final-quality profile; `vork help` explains when to pick it | Iterate on `std/previs` or `std/draft`, on `render-lite` if you like, and switch to `std/final` or `std/path` on `render` only for the last render. ## Long renders ```sh theme={"system"} job=$(voyager-cloud exec --detach vork -- vork render scene/shot.json --profile std/final --out out/final.png) voyager-cloud logs $job --follow voyager-cloud wait $job voyager-cloud pull vork out/ ``` A running render keeps the machine awake. When nothing is running, it pauses itself after 15 minutes. ## If something went wrong > [accordion] Vork fails to start on the machine > > Check the preset with `voyager-cloud status `. If it is `compute` (H100) or another GPU without ray tracing, release it and lease `render` or `render-lite`. > [accordion] `vork setup` prints nothing for minutes > > That's normal on a new machine. Let it finish. If it fails, run it again and read its error output. > [accordion] A render exits with an error > > `exec` exits with Vork's exit code and prints its error. Fix the scene and render again. For a detached render, read the error with `voyager-cloud logs `. # Models Source: https://docs.voyager.so/api/models Discover the models your workspace can run with GET /v1/models, and read each model's input_schema and operations before you create a job. The model list changes as Voyager adds models, so read it from the API instead of hard-coding it. `GET /v1/models` lists what you can run; `GET /v1/models/{id}` tells you exactly what `input` a model takes. ## List models ```bash theme={"system"} curl "https://api.voyager.so/v1/models?type=video" \ -H "Authorization: Bearer $VOYAGER_API_KEY" ``` | Parameter | Type | Description | | - | - | - | | `type` | `string` or `null` | Only models of this job type. One of `image`, `video`, `speech`, `music`, `sound_effect`, `3d`, `segment`. | | `operation` | `string` or `null` | Only models that run this operation. | | `q` | `string` or `null` | Words in the id, name or description. Up to 100 characters. | | `limit` | `integer` | 1–100. Default `50`. | | `cursor` | `string` or `null` | Up to 400 characters. | The list includes models above your plan, marked `available: false`, so you can see what an upgrade adds. `available` is `null` when it isn't known yet; creating the job then decides. The response below is an **illustrative example of the shape**, not a real or complete list: ```json theme={"system"} { "object": "list", "data": [ { "id": "example-video-model", "object": "model", "name": "Example Video Model", "type": "video", "summary": "Short cinematic clips from text or an image.", "best_for": "Product shots and image-to-video", "default": false, "status": "active", "operations": ["text-to-video", "image-to-video"], "available": true, "unavailable_reason": null, "required_plan": "starter", "price": { "basis": "rate", "unit": "second", "estimated_charge": …, "estimated_charge_max": … } } ], "has_more": false, "next_cursor": null } ``` | Field | Type | Description | | - | - | - | | `object` | `string` | Always "model". Always `model`. | | `id` | `string` | Pass as `model` to POST /v1/jobs. | | `name` | `string` | The model's display name. | | `type` | `string` | The kind of output it makes. One of `image`, `video`, `speech`, `music`, `sound_effect`, `3d`, `segment`. | | `summary` | `string` or `null` | One line on what the model is. | | `best_for` | `string` or `null` | What the model is good for. | | `default` | `boolean` | Whether this is Voyager's recommended model for its type (a suggestion only: `model` is always required). | | `status` | `string` | active, preview or retired. | | `operations` | array of `string` | Operations this model runs, e.g. text-to-image, edit. | | `available` | `boolean` or `null` | Whether this workspace can run it now; null when not known (decided when the job is accepted). | | `unavailable_reason` | `string` or `null` | Why not, when available is false. One of `plan_locked`, `access_required`, `access_pending`, `access_denied`, `update_required`, `unavailable`, `retired`. | | `required_plan` | `string` or `null` | The lowest Voyager plan that runs it, when known. | | `price` | `Price` or `null` | Expected charge; null when not known. POST /v1/estimate is authoritative. | `price` is an expected charge in Voyager credits per `unit`, never a cap. Use [`POST /v1/estimate`](/api/jobs#credits) for your exact request; prices are on [voyager.so/pricing](https://voyager.so/pricing). | Field | Type | Description | | - | - | - | | `basis` | `string` | rate: an exact per-unit charge; example: the charge at the settings in points\[].when. One of `rate`, `example`. | | `unit` | `string` | What one charge buys: image, second, video, request, 1k\_chars, minute, track… | | `estimated_charge` | `number` or `null` | Expected credits per unit at the cheapest listed settings. An estimate, never a cap. | | `estimated_charge_max` | `number` or `null` | Expected credits per unit at the dearest. | ## Read a model ```bash theme={"system"} curl https://api.voyager.so/v1/models/example-video-model \ -H "Authorization: Bearer $VOYAGER_API_KEY" ``` The response adds `operation_details`: for each operation, the JSON Schema of `input`, its defaults and a ready-to-send example, plus price detail. Again an illustrative example: ```json theme={"system"} { "id": "example-video-model", "object": "model", "name": "Example Video Model", "type": "video", "default": false, "status": "active", "operations": ["text-to-video", "image-to-video"], "available": true, "unavailable_reason": null, "required_plan": "starter", "operation_details": [ { "operation": "text-to-video", "input_schema": { "type": "object", "required": ["prompt"], "properties": { "prompt": { "type": "string" }, "duration_seconds": { "type": "integer", "enum": [5, 10] }, "aspect_ratio": { "type": "string", "enum": ["16:9", "9:16", "1:1"] }, "cast": { "type": "array", "maxItems": 4, "items": { "type": "string" } } }, "additionalProperties": false }, "defaults": { "duration_seconds": 5, "aspect_ratio": "16:9" }, "example": { "model": "example-video-model", "operation": "text-to-video", "input": { "prompt": "a paper boat drifting down a rainy street" } } }, { "operation": "image-to-video", "input_schema": { "type": "object", "required": ["prompt", "image"], "properties": { "prompt": { "type": "string" }, "image": { "type": "string", "contentMediaType": "image/*", "description": "A file_ id from POST /v1/files, or an https URL." } }, "additionalProperties": false }, "defaults": {}, "example": { "model": "example-video-model", "operation": "image-to-video", "input": { "prompt": "the boat drifts away", "image": "file_…" } } } ], "price": { "basis": "rate", "unit": "second", "estimated_charge": …, "estimated_charge_max": …, "points": [ { "credits": …, "when": { "duration_seconds": 5 } } ], "as_of": "2026-11-05" } } ``` The example is illustrative: its values aren't real limits. Model detail fields: | Field | Type | Description | | - | - | - | | `object` | `string` | Always "model". Always `model`. | | `id` | `string` | Pass as `model` to POST /v1/jobs. | | `name` | `string` | The model's display name. | | `type` | `string` | The kind of output it makes. One of `image`, `video`, `speech`, `music`, `sound_effect`, `3d`, `segment`. | | `summary` | `string` or `null` | One line on what the model is. | | `best_for` | `string` or `null` | What the model is good for. | | `default` | `boolean` | Whether this is Voyager's recommended model for its type (a suggestion only: `model` is always required). | | `status` | `string` | active, preview or retired. | | `operations` | array of `string` | Operations this model runs, e.g. text-to-image, edit. | | `available` | `boolean` or `null` | Whether this workspace can run it now; null when not known (decided when the job is accepted). | | `unavailable_reason` | `string` or `null` | Why not, when available is false. One of `plan_locked`, `access_required`, `access_pending`, `access_denied`, `update_required`, `unavailable`, `retired`. | | `required_plan` | `string` or `null` | The lowest Voyager plan that runs it, when known. | | `price` | `PriceDetail` or `null` | Expected charge; null when not known. | | `operation_details` | array of `ModelOperation` | Each operation's input schema, defaults and an example request. | Each entry in `operation_details`: | Field | Type | Description | | - | - | - | | `operation` | `string` | The operation. | | `input_schema` | `object` | JSON Schema of `input` for this operation. | | `defaults` | `object` | Values used for inputs you leave out. | | `example` | `object` | A ready-to-send POST /v1/jobs body. | | `cast_capabilities` | `object` or `null` | With X-Voyager-Cast-Version: 1: what Elements (input.cast) do on this operation — strategy, limits, prompt fallback and policies. Absent otherwise. | Price detail: | Field | Type | Description | | - | - | - | | `basis` | `string` | rate: an exact per-unit charge; example: the charge at the settings in points\[].when. One of `rate`, `example`. | | `unit` | `string` | What one charge buys: image, second, video, request, 1k\_chars, minute, track… | | `estimated_charge` | `number` or `null` | Expected credits per unit at the cheapest listed settings. An estimate, never a cap. | | `estimated_charge_max` | `number` or `null` | Expected credits per unit at the dearest. | | `points` | array of `PricePoint` | Expected charges at specific settings (when, in canonical input names). | | `as_of` | `string` or `null` | Date the price was read. | ## Build a request * **Pick an operation.** Pass `operation` on create. It's required when the model lists more than one in `operations`; only a single-operation model can leave it out. A missing or wrong one is `400` [`invalid_request`](/api/errors#invalid_request) with the model's operations in `details.operations`. Your plan never changes which operation runs: if it doesn't include the model, you get [`model_not_in_plan`](/api/errors#model_not_in_plan). * **Start from `example`.** Each operation's `example` is a complete `POST /v1/jobs` body you can send as is. * **Build `input` from that operation's `input_schema`.** Missing optional fields use its `defaults`. Validation is strict: an unknown field or a value the schema refuses is [`invalid_input`](/api/errors#invalid_input), before anything is charged. * **Cast** works on image and video models whose `input_schema` has a `cast` field. See [Cast](/api/cast). A job pins the model version and schema it was accepted with, so a later model update doesn't change a job already in flight. ### Input fields `input` uses Voyager's own field names, the same on every model, whatever the model calls them. The table lists the shared fields. `GET /v1/models/{id}` serves each model's full input schema in these names: the shared fields it supports, with its own values, plus any settings of its own. Image sizes are `aspect_ratio` values (`"16:9"`, `"4:3"`, `"1:1"` and so on); a model that takes an exact size also has an `image_size` object with `width` and `height`. Media fields take a `file_…` ID from [uploads](/api/jobs#uploads) or an earlier output, or a public `https` URL, which Voyager imports into your workspace when the job is created. More fields and settings will be added over time. | Field | Type | Description | | - | - | - | | `prompt` | `string` | The instruction; `caption` only where it is a string. | | `negative_prompt` | `string` | Negative prompt. | | `text` | `string` | The words spoken. | | `aspect_ratio` | `string` | Unit: "W:H" or "auto". | | `resolution` | `string` | Lowercase; others as-is. One of `360p`, `480p`, `540p`, `720p`, `768p`, `1080p`, `1440p`, `2k`, `4k`, `0.5k`, `1k`, `1.5k`. | | `duration_seconds` | `number` | The model's values or range; "auto" where the model takes it. Unit: seconds. | | `count` | `integer` | Count. | | `seed` | `integer` | Seed. | | `generate_audio` | `boolean` | Generate audio. | | `voice_id` | `string` | Voice id. | | `image` | `string` (image/\*) | A file\_ id from POST /v1/files, or an https URL (imported into your workspace first). | | `images` | array of `string` (image/\*) | A file\_ id from POST /v1/files, or an https URL (imported into your workspace first). | | `end_image` | `string` (image/\*) | A file\_ id from POST /v1/files, or an https URL (imported into your workspace first). | | `video` | `string` (video/\*) | A file\_ id from POST /v1/files, or an https URL (imported into your workspace first). | | `audio` | `string` (audio/\*) | A file\_ id from POST /v1/files, or an https URL (imported into your workspace first). | | `cast` | any | API only: cst\_ ids, at most 4. | ## Voices Speech models take a voice as `input.voice_id`, from `GET /v1/voices`: Voyager's premade voices, or your workspace's voice clones. A voice works only with the models in its `compatible_models`. **Speech on Voyager's managed voices requires `voice_id`**: those models' `input_schema` marks it required, and a `tts` job without one is refused with `422` [`voice_required`](/api/errors#voice_required). Pick a voice whose `compatible_models` includes the model, and pass the words as `input.text`. ```bash theme={"system"} curl "https://api.voyager.so/v1/voices?source=premade&q=warm" -H "Authorization: Bearer $VOYAGER_API_KEY" ``` Your own voice clones (`source=mine`) are on the Ultra and GigaMax plans ([`voice_cloning_unavailable`](/api/errors#voice_cloning_unavailable) otherwise); clones are made in the Voyager app. | Parameter | Type | Description | | - | - | - | | `source` | `string` | premade: the managed catalog; mine: your voice clones in this workspace. One of `premade`, `mine`. Default `premade`. | | `q` | `string` or `null` | Search premade voices. Up to 200 characters. | | `language` | `string` or `null` | Up to 16 characters. | | `gender` | `string` or `null` | Up to 16 characters. | | `provider` | `string` or `null` | One of `elevenlabs`, `fishaudio`, `inworld`. | | `limit` | `integer` | 1–100. Default `50`. | | `cursor` | `string` or `null` | Up to 1024 characters. | | Field | Type | Description | | - | - | - | | `object` | `string` | Always "voice". Always `voice`. | | `id` | `string` | Pass as input.voice\_id to a speech job. | | `name` | `string` or `null` | The voice's display name. | | `source` | `string` | premade (the model's own) or mine (made in this workspace). One of `premade`, `mine`. | | `provider` | `string` or `null` | The engine it renders on. | | `compatible_models` | array of `string` | Speech models that can use it. | | `preview_url` | `string` or `null` | A short sample of the voice, when there is one. | | `labels` | `object` or array of any | Descriptive labels (accent, age, gender...). | ## Related * [Jobs and polling](/api/jobs) * [Cast](/api/cast) * [Plans and credits](/account/plans-and-credits) # Voyager API Source: https://docs.voyager.so/api/overview Generate images, video, speech, music, sound effects and 3D over HTTP with the same models and Voyager credits as the Voyager app. The Voyager API is a REST API for paid Voyager workspaces. It runs the same models as the Voyager app, at the same prices, and draws from the same Voyager credits. Create a job, wait for it or receive a webhook, then download the result. > [!NOTE] > > Building with a coding agent such as Claude Code, Codex or Cursor? Start at [Set up with your coding agent](/api/coding-agents): it has a prompt you can paste that wires the API into your project. ## Base URL ```text theme={"system"} https://api.voyager.so/v1 ``` Every request is HTTPS and JSON. Send your API key as a Bearer token: ```text theme={"system"} Authorization: Bearer vy_live_... ``` Keep the key in the `VOYAGER_API_KEY` environment variable. Create one at [voyager.so/dashboard/api](https://voyager.so/dashboard/api); see [Authentication](/api/authentication). ## Quick example ```bash theme={"system"} curl https://api.voyager.so/v1/jobs \ -H "Authorization: Bearer $VOYAGER_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{"model": "nano-banana-2.1", "operation": "text-to-image", "input": {"prompt": "a red fox in snow", "aspect_ratio": "16:9"}}' ``` The response is a [job](/api/jobs) with `status: "queued"`. Call `GET /v1/jobs/{id}?wait=25` until it is `succeeded`, then download `outputs[].url`. The [Quickstart](/api/quickstart) does this end to end in curl, Python and JavaScript. ## What you can do | Area | Endpoints | What for | | - | - | - | | **Models** | `GET /models`, `GET /models/{id}` | Find a model and read the `input_schema` its `input` must match. See [Models](/api/models). | | **Estimates** | `POST /estimate` | Check what a job would cost, and whether it can run, before you create it. | | **Jobs** | `POST /jobs`, `GET /jobs/{id}`, `GET /jobs`, `POST /jobs/{id}/cancel` | Generate, wait, list and cancel. See [Jobs and polling](/api/jobs). | | **Files** | `POST /files`, `POST /files/{id}/complete`, `GET /files/{id}`, `GET /files/{id}/content`, `DELETE /files/{id}` | Upload reference images, audio or video; download results. | | **Cast** | `GET /cast`, `POST /cast`, `GET`, `PATCH`, `DELETE /cast/{id}`, references | Saved characters, locations and props for consistent shots. See [Cast](/api/cast). | | **Voices** | `GET /voices` | Voices for speech jobs, including your workspace's voice clones. | | **Account** | `GET /account` | Your workspace, plan, credits available and limits. | Job types are `image`, `video`, `speech`, `music`, `sound_effect` and `3d`. The type comes from the model you pick. ## Conventions * **IDs** are prefixed strings: `job_…`, `file_…`, `cst_…`, `evt_…`, `key_…`. Treat them as opaque. * **Times** are ISO 8601 in UTC. * **Lists** return `{"object": "list", "data": [...], "has_more": true, "next_cursor": "..."}`. Pass `?cursor=` for the next page and `?limit=` (up to 100) for page size. * **Retries** are safe on every `POST` when you send an `Idempotency-Key` header: a retry returns the original result instead of buying a second one. See [Idempotency](/api/jobs#idempotency). * **Errors** share one envelope with a stable `code`. See [Errors](/api/errors). * **Request IDs**: every response carries `X-Request-ID`. Include it when you contact support. ## Plans and credits The API is on paid Voyager plans, trials included. Every job is paid from your workspace's Voyager credits, the same balance the Voyager app uses. Model prices and plans are on [voyager.so/pricing](https://voyager.so/pricing); `POST /estimate` and `GET /v1/models` give you a model's cost in credits before you run it. If your workspace moves to Free, you can still read jobs, download results, cancel work already accepted, and list or revoke keys. New paid work returns `402 paid_plan_required` until you upgrade. ## Next steps > [card] [Authentication](/api/authentication) > > Create a key and keep it safe. > [card] [Quickstart](/api/quickstart) > > Generate and download your first image. > [card] [Jobs and polling](/api/jobs) > > Statuses, waiting, credits, cancel and uploads. > [card] [Set up with your coding agent](/api/coding-agents) > > A prompt your agent can follow, plus docs it can read. # Quickstart Source: https://docs.voyager.so/api/quickstart Create an image job, wait for it to finish, and download the result in curl, Python or JavaScript. In a few minutes you'll generate an image with the Voyager API and save it to disk. > [!NOTE] > > **Before you start:** you need a Voyager API key from a paid plan (trials count) in the `VOYAGER_API_KEY` environment variable. See [Authentication](/api/authentication). The job is paid from your workspace's Voyager credits; prices are on [voyager.so/pricing](https://voyager.so/pricing). ## The three calls 1. **Create** a job with `POST /v1/jobs`. Send an `Idempotency-Key` so a retry never buys twice. 2. **Wait** with `GET /v1/jobs/{id}?wait=25`. The server holds the request for up to 25 seconds and answers as soon as the job finishes. Repeat while the status is `queued` or `running`. 3. **Download** `outputs[].url`, a signed link that works for 1 hour without your key. ```bash curl theme={"system"} # Needs curl, jq and uuidgen. API=https://api.voyager.so/v1 AUTH="Authorization: Bearer $VOYAGER_API_KEY" # 1. Create JOB_ID=$(curl -sf "$API/jobs" \ -H "$AUTH" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{"model": "nano-banana-2.1", "operation": "text-to-image", "input": {"prompt": "a red fox in snow", "aspect_ratio": "16:9"}}' \ | jq -r .id) echo "created $JOB_ID" # 2. Wait while :; do JOB=$(curl -sf "$API/jobs/$JOB_ID?wait=25" -H "$AUTH") STATUS=$(echo "$JOB" | jq -r .status) [ "$STATUS" = queued ] || [ "$STATUS" = running ] || break done echo "status: $STATUS" [ "$STATUS" = succeeded ] || { echo "$JOB" | jq .error; exit 1; } # 3. Download curl -sf -o fox.png "$(echo "$JOB" | jq -r '.outputs[0].url')" echo "$JOB" | jq .credits ``` ```python Python theme={"system"} # pip install requests import os import time import uuid import requests API = "https://api.voyager.so/v1" AUTH = {"Authorization": f"Bearer {os.environ['VOYAGER_API_KEY']}"} # 1. Create response = requests.post( f"{API}/jobs", headers={**AUTH, "Idempotency-Key": str(uuid.uuid4())}, json={"model": "nano-banana-2.1", "operation": "text-to-image", "input": {"prompt": "a red fox in snow", "aspect_ratio": "16:9"}}, timeout=30, ) response.raise_for_status() job = response.json() print("created", job["id"]) # 2. Wait while job["status"] in ("queued", "running"): response = requests.get(f"{API}/jobs/{job['id']}", headers=AUTH, params={"wait": 25}, timeout=60) response.raise_for_status() job = response.json() if job["status"] in ("queued", "running") and job.get("poll_after_ms"): time.sleep(job["poll_after_ms"] / 1000) if job["status"] != "succeeded": raise SystemExit(f"{job['status']}: {job['error']}") # 3. Download output = job["outputs"][0] extension = output["mime_type"].split("/")[-1] download = requests.get(output["url"], timeout=120) download.raise_for_status() # fails on an expired link: GET the job again for a fresh URL with open(f"fox.{extension}", "wb") as file: file.write(download.content) print("saved", f"fox.{extension}", "credits", job["credits"]) ``` ```javascript JavaScript theme={"system"} // Node 18+; save as quickstart.mjs and run: node quickstart.mjs import { randomUUID } from "node:crypto"; import { writeFile } from "node:fs/promises"; const API = "https://api.voyager.so/v1"; const AUTH = { Authorization: `Bearer ${process.env.VOYAGER_API_KEY}` }; async function call(path, init = {}) { const response = await fetch(`${API}${path}`, { ...init, headers: { ...AUTH, ...init.headers } }); const body = await response.json(); if (!response.ok) throw new Error(`${response.status} ${body.error?.code}: ${body.error?.message}`); return body; } // 1. Create let job = await call("/jobs", { method: "POST", headers: { "Content-Type": "application/json", "Idempotency-Key": randomUUID() }, body: JSON.stringify({ model: "nano-banana-2.1", operation: "text-to-image", input: { prompt: "a red fox in snow", aspect_ratio: "16:9" }, }), }); console.log("created", job.id); // 2. Wait while (job.status === "queued" || job.status === "running") { job = await call(`/jobs/${job.id}?wait=25`); if ((job.status === "queued" || job.status === "running") && job.poll_after_ms) { await new Promise((resolve) => setTimeout(resolve, job.poll_after_ms)); } } if (job.status !== "succeeded") throw new Error(`${job.status}: ${JSON.stringify(job.error)}`); // 3. Download const output = job.outputs[0]; const file = `fox.${output.mime_type.split("/")[1]}`; const download = await fetch(output.url); // Fails on an expired link: GET the job again for a fresh URL. if (!download.ok) throw new Error(`download failed: ${download.status}`); await writeFile(file, Buffer.from(await download.arrayBuffer())); console.log("saved", file, "credits", job.credits); ``` ## Check it worked You have an image file next to your script, and the job printed its `credits`. `credits.charged` is what the job cost. If `credits.state` is still `pending`, the final amount isn't confirmed yet: `credits.estimated` is the estimate, and `GET /v1/jobs/{id}` will show the final charge later. See [Credits](/api/jobs#credits). > [!TIP] > > For a fast model, add the header `Prefer: wait=30` to the create request (up to 60 seconds). If the job finishes in time, the create response is `200 OK` with the finished job and the loop in step 2 ends at once. ## If something went wrong > [accordion] 401 invalid\_api\_key > > The key is missing, mistyped or revoked. Check `echo $VOYAGER_API_KEY` starts with `vy_live_`, and that the key is still listed on [voyager.so/dashboard/api](https://voyager.so/dashboard/api). > [accordion] 402 paid\_plan\_required or insufficient\_credits > > The workspace isn't on a paid plan, or doesn't have enough Voyager credits for this job. Open `error.details.upgrade_url`. See [Errors](/api/errors#insufficient_credits). > [accordion] 400 invalid\_input > > The `input` doesn't match the model's `input_schema`, or has a field the model doesn't take. Read `error.details`, then check the schema with `GET /v1/models/nano-banana-2.1`. See [Models](/api/models). > [accordion] The job failed > > Read `job.error.code` and look it up on [Errors](/api/errors). A failed job releases its held credits unless its type's [settlement rule](/api/jobs#how-each-type-is-charged) says otherwise. ## Next > [card] [Jobs and polling](/api/jobs) > > Statuses, credits, cancel, uploads and idempotency. > [card] [Models](/api/models) > > Find video, speech, music and 3D models and their inputs. # Rate limits and usage Source: https://docs.voyager.so/api/rate-limits Request limits per key, parallel generations per person shared with the Voyager app, the job queue, and where to see credits and usage. Two separate limits apply: how many **requests** a key can send per minute, and how many **generations** you can run at once. ## Request limits | Requests | Limit | | - | - | | Creating jobs, estimates, uploads and other writes (`POST`, `PATCH`, `DELETE`) | 120 per minute, per key | | Reads (`GET`) | 600 per minute, per key | Every response carries: | Header | Meaning | | - | - | | `X-RateLimit-Limit` | Requests allowed in the current window for this kind of request. | | `X-RateLimit-Remaining` | Requests left in the window. | | `X-RateLimit-Reset` | Seconds until the window resets. | Over the limit you get `429` [`rate_limited`](/api/errors#rate_limited) with a `Retry-After` header in seconds. Wait that long, then retry with the same `Idempotency-Key`. A long-poll (`GET /v1/jobs/{id}?wait=25`) is one request however long it waits, so it's the cheapest way to wait for a job. ## Concurrency You can run as many generations at once as your plan's **parallel generations**. The limit is **per person**, not per key or per workspace, and it's **shared with the Voyager app**: jobs you start from the app, the dashboard, a connected AI and the API all count toward the same number. | Plan | Parallel generations | | - | - | | Starter | 6 | | Creator | 12 | | Ultra | 24 | | GigaMax | 36 | [voyager.so/pricing](https://voyager.so/pricing) has the current plans. `GET /v1/account` returns your limit as `limits.concurrency.parallel_generations`. Speech and 3D jobs also share a workspace-wide cap that counts every member's jobs together, on top of your own limit: `limits.concurrency.workspace.speech` and `limits.concurrency.workspace.3d`. A job over either cap waits `queued`. ### The queue Creating a job while you're at your limit doesn't fail: the job is accepted as `queued` and starts when one of yours finishes. * You can have up to **100** active jobs (queued plus running) at once, counted per person across all your workspaces. Past that, create returns `429` [`queue_full`](/api/errors#queue_full) and nothing is accepted; the `Idempotency-Key` stays reusable. * A job that waits more than **1 hour** without starting is `canceled` with `error.code` [`queue_timeout`](/api/errors#queue_timeout). Nothing is charged. ## Credits and your account `GET /v1/account` shows the workspace, plan, credits available and your limits: ```bash theme={"system"} curl https://api.voyager.so/v1/account -H "Authorization: Bearer $VOYAGER_API_KEY" ``` An example (values are illustrative): ```json theme={"system"} { "object": "account", "workspace": { "id": "team_01JB…", "name": "Northlight Films" }, "api_key": { "id": "key_01JC…", "name": "my-app-prod" }, "plan": { "key": "creator", "name": "Creator", "paid": true }, "credits": { "available": …, "unit": "credits" }, "limits": { "requests_per_minute": { "write": 120, "read": 600 }, "concurrency": { "scope": "user", "parallel_generations": 12, "workspace": { "speech": …, "3d": … } }, "queue": { "max_queued": 100, "max_queued_age_seconds": 3600 } } } ``` | Field | Type | Description | | - | - | - | | `object` | `string` | Always "account". Always `account`. | | `workspace` | `Workspace` | The workspace this key belongs to. | | `api_key` | `ApiKeyInfo` | The key making this request. | | `plan` | `Plan` | The workspace's Voyager plan. | | `credits` | `Credits` | The workspace's credit balance. | | `limits` | `Limits` | Rate, concurrency and queue limits that apply to this key. | `plan`: | Field | Type | Description | | - | - | - | | `key` | `string` or `null` | free, starter, creator, ultra or gigamax; null when the workspace has none. | | `name` | `string` or `null` | The plan's name; null without one. | | `paid` | `boolean` | Whether new generations and uploads are allowed through the API. | `credits`: | Field | Type | Description | | - | - | - | | `available` | `integer` or `null` | The workspace's credit balance, as its Voyager dashboard shows it; null when it could not be read. | | `unit` | `string` | Always "credits". Always `credits`. | `limits`: | Field | Type | Description | | - | - | - | | `requests_per_minute` | `RequestsPerMinute` | Requests this key may make per minute. | | `concurrency` | `Concurrency` | Jobs that may run at once. | | `queue` | `Queue` | Jobs that may wait at once, and for how long. | `limits.requests_per_minute`: | Field | Type | Description | | - | - | - | | `write` | `integer` | Per key: creates, estimates, uploads and other writes. | | `read` | `integer` | Per key: every GET. | `limits.concurrency`: | Field | Type | Description | | - | - | - | | `scope` | `string` | Counted per person across the app, the MCP and every one of their keys; not per workspace. Speech and 3D jobs are also bounded by a workspace-wide cap on those job types. Always `user`. | | `parallel_generations` | `integer` or `null` | Generations running at once; more wait queued. | | `workspace` | `WorkspaceConcurrency` | Speech and 3D jobs also share a workspace-wide cap. | `limits.concurrency.workspace`: | Field | Type | Description | | - | - | - | | `speech` | `integer` | Speech jobs running at once across the workspace. | | `3d` | `integer` | 3D jobs running at once across the workspace. | `limits.queue`: | Field | Type | Description | | - | - | - | | `max_queued` | `integer` | Active jobs (queued plus running) one person may have at once, across workspaces; a create beyond it is 429 queue\_full and nothing is accepted. | | `max_queued_age_seconds` | `integer` | A job queued longer is canceled (error.code queue\_timeout). | Credits are shared across the workspace: the app, the dashboard, connected AIs and the API all draw from the same Voyager credits. Running jobs hold credits until they settle, so `credits.available` drops when a job starts. Prices are on [voyager.so/pricing](https://voyager.so/pricing). ## Usage per key The **API** tab on [voyager.so/dashboard/api](https://voyager.so/dashboard/api) shows credits used by each key over the last 30 days and when each key was last used. Every job created with a key is counted against that key, including its later settlement and any refunds. Workspace-wide usage, across the app and the API, is on the dashboard's [usage page](https://voyager.so/dashboard/usage). ## Avoid hitting limits * Wait with `?wait=25` or [webhooks](/api/webhooks), not tight polling loops. Honor `poll_after_ms` and `Retry-After`. * Read `X-RateLimit-Remaining` and slow down before you reach zero. * Batch work by creating jobs at a steady pace; extra jobs queue on their own. * Use separate keys per app so one busy integration doesn't use up another's request limit. They still share your parallel generations. # Versioning Source: https://docs.voyager.so/api/versioning How the Voyager API is versioned: the /v1 path, additive changes, and a dated Voyager-Version header for future breaking changes. The version is in the path: `https://api.voyager.so/v1`. ## What can change in v1 Within `v1`, changes are **additive** only. Voyager may: * add endpoints, optional request fields and query parameters, * add fields to responses and objects, * add new error codes, event types, job types, model operations and enum values (such as a model `status`), * add, update and retire models in [`GET /v1/models`](/api/models). Write clients that ignore fields they don't know and handle unknown enum values and error codes gracefully. Model availability isn't part of the API version: read the model list instead of hard-coding it. Voyager won't, within `v1`: remove or rename a field, change a field's type or meaning, make an optional field required, or rename an error code. ## Breaking changes If a breaking change is ever needed, it will come behind a dated `Voyager-Version` request header (for example `Voyager-Version: 2027-01-15`). You'll opt in to a new version by sending the header; requests without it keep the behavior described in these docs. The header doesn't exist yet; you don't need to send anything today. ## Stay current * The OpenAPI document at [api.voyager.so/v1/openapi.json](https://api.voyager.so/v1/openapi.json) always describes the live API. * Changes are announced in the [Voyager Discord](https://discord.gg/voyagerai). # Webhooks Source: https://docs.voyager.so/api/webhooks Get an HTTPS callback when a job succeeds, fails or is canceled, signed per Standard Webhooks with your key's whsec_ secret. Pass a `webhook_url` when you create a job and Voyager sends it a signed `POST` when the job finishes. Use webhooks to avoid holding a poll open for long jobs such as video and 3D. ```bash theme={"system"} curl https://api.voyager.so/v1/jobs \ -H "Authorization: Bearer $VOYAGER_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{ "model": "nano-banana-2.1", "operation": "text-to-image", "input": { "prompt": "a red fox in snow" }, "webhook_url": "https://example.com/hooks/voyager" }' ``` `webhook_url` must be a public `https://` URL of up to 2,048 characters, with no credentials and not a private or local address. Voyager checks it when you create the job (`400` [`invalid_webhook_url`](/api/errors#invalid_webhook_url) if it isn't) and again on every delivery. It doesn't follow redirects: a `3xx` counts as a failed delivery. ## Events | Event | When | | - | - | | `job.succeeded` | A job finished with its outputs. | | `job.failed` | A job failed (error.code says why; outcome\_unknown means a new submission may charge again). | | `job.canceled` | A job was canceled (error.code queue\_timeout when it waited in the queue too long). | Webhooks fire once per job, when it reaches a terminal status (`job.failed` with [`outcome_unknown`](/api/errors#outcome_unknown) means Voyager couldn't confirm the generation: ask for its status again, and never submit it again, or it may be charged twice). They don't fire for `queued` or `running`, and they don't fire again when the job's charge settles later: read `credits.state` with `GET /v1/jobs/{id}` if you need the final charge. ## Payload ```json theme={"system"} { "id": "evt_01JC4QC2T6W8Y0A3C5E7G9J1LN", "type": "job.succeeded", "created_at": "2026-11-05T21:09:56Z", "data": { "id": "job_01JC4Q8ZK3V0B7M2X9T5R6N4PA", "object": "job", "type": "image", "model": "nano-banana-2.1", "operation": "text-to-image", "status": "succeeded", "input": { "prompt": "a red fox in snow" }, "outputs": [ { "id": "file_01JC4QB3N8D5H1W6Y2K7M0F9EC", "object": "file", "type": "image", "mime_type": "image/png", "url": "https://…", "url_expires_at": "2026-11-05T22:09:56Z" } ], "credits": { "estimated": …, "held": …, "charged": null, "released": null, "state": "pending", "charge_ref": "…" }, "error": null, "metadata": { "shot": "12" }, "created_at": "2026-11-05T21:09:41Z", "started_at": "2026-11-05T21:09:42Z", "completed_at": "2026-11-05T21:09:55Z", "poll_after_ms": null, "links": { "self": "/v1/jobs/job_01JC4Q8ZK3V0B7M2X9T5R6N4PA", "cancel": "/v1/jobs/job_01JC4Q8ZK3V0B7M2X9T5R6N4PA/cancel" } } } ``` `data` is the full [job](/api/jobs#the-job-object), rendered fresh for each delivery attempt. Its output links expire one hour after that; if you download later, call `GET /v1/jobs/{id}` for fresh ones. ## Headers Voyager follows the [Standard Webhooks](https://www.standardwebhooks.com/) specification: | Header | Value | | - | - | | `webhook-id` | The event's id (`evt_…`, the body's `id`), stable across retries: deduplicate on it. | | `webhook-timestamp` | Unix seconds when this attempt was sent. Reject old timestamps to stop replays. | | `webhook-signature` | `v1,` keyed with the base64-decoded part of the key's `whsec_` secret. May hold several space-separated signatures; accept the request if any one matches. | ## The signing secret Each API key has its own webhook secret, `whsec_…`, shown once next to the key when you create it on [voyager.so/dashboard/api](https://voyager.so/dashboard/api). Jobs created with a key are signed with that key's secret. Store it like the key itself. If you lose it, create a new key. ## Verify the signature Always verify before trusting the body. Use the **raw** request body: parsing and re-serializing the JSON changes the bytes and breaks the signature. ```python Python theme={"system"} # pip install standardwebhooks flask import os from flask import Flask, request from standardwebhooks.webhooks import Webhook, WebhookVerificationError app = Flask(__name__) webhook = Webhook(os.environ["VOYAGER_WEBHOOK_SECRET"]) # whsec_... @app.post("/hooks/voyager") def voyager_hook(): try: event = webhook.verify(request.get_data(), dict(request.headers)) except WebhookVerificationError: return "", 400 job = event["data"] print(event["type"], job["id"], job["status"]) return "", 204 ``` ```javascript JavaScript theme={"system"} // npm install standardwebhooks express import express from "express"; import { Webhook } from "standardwebhooks"; const app = express(); const webhook = new Webhook(process.env.VOYAGER_WEBHOOK_SECRET); // whsec_... app.post("/hooks/voyager", express.raw({ type: "application/json" }), (req, res) => { let event; try { event = webhook.verify(req.body.toString("utf8"), { "webhook-id": req.header("webhook-id"), "webhook-timestamp": req.header("webhook-timestamp"), "webhook-signature": req.header("webhook-signature"), }); } catch { return res.sendStatus(400); } console.log(event.type, event.data.id, event.data.status); res.sendStatus(204); }); app.listen(3000); ``` Both libraries reject timestamps more than 5 minutes from your clock, which stops replayed requests. ### Verify by hand The signature is HMAC-SHA256 over `{webhook-id}.{webhook-timestamp}.{raw body}`, keyed with the base64-decoded part of the secret after `whsec_`, and base64-encoded: ```python Python theme={"system"} import base64 import hashlib import hmac import time def verify(secret: str, headers: dict, body: bytes) -> bool: msg_id = headers["webhook-id"] timestamp = headers["webhook-timestamp"] if abs(time.time() - int(timestamp)) > 300: return False key = base64.b64decode(secret.removeprefix("whsec_")) signed = f"{msg_id}.{timestamp}.".encode() + body expected = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest()).decode() for signature in headers["webhook-signature"].split(" "): version, _, value = signature.partition(",") if version == "v1" and hmac.compare_digest(value, expected): return True return False ``` ## Respond and retries Return any `2xx` within 10 seconds, then do the work. Any other response, a redirect, or no answer in 10 seconds counts as a failure, and Voyager retries with backoff for up to **24 hours**. After that the delivery is dropped; the job itself is unaffected. * Deliveries can arrive more than once and out of order. Deduplicate on `webhook-id`, and check `data.status` rather than assuming order. * **Revoking a key stops its deliveries**: webhooks for its jobs that haven't been delivered yet are dropped. * **`GET /v1/jobs/{id}` is authoritative.** If you miss a webhook, or need the final charge, poll. # Add Voyager to ChatGPT Source: https://docs.voyager.so/connect/chatgpt Add Voyager to ChatGPT from its listing, sign in with your Voyager account, and ask @Voyager for videos, images and audio in any chat. When you finish, you can type **@Voyager** in a ChatGPT chat and ask for a video clip, an image, a voiceover, music or a 3D model. > [!NOTE] > > **Before you start** > > * **A ChatGPT account** on the web, at [chatgpt.com](https://chatgpt.com). > * **A Voyager account.** If you don't have one, you can sign up during the steps below. > * **Cost:** adding Voyager is free. What you make uses Voyager credits from your workspace; video and 3D need a paid Voyager plan. See [Plans and credits](/connect/overview#plans-and-credits). > * This page is about using Voyager inside ChatGPT. To run the Voyager desktop app on your ChatGPT plan instead, see [Connect ChatGPT](/setup/connect-chatgpt). ## Add Voyager **1. Open the Voyager listing** Open [Voyager in ChatGPT](https://chatgpt.com/plugins/plugin_asdk_app_6ae3982d27b4819184ac134a3c1d1307), or choose **Add to ChatGPT** on the **MCP** tab of your [Voyager dashboard](https://voyager.so/dashboard/mcp). Add it to your ChatGPT account. **2. Allow the connection** A Voyager page opens and names the app asking to connect. Check it, then choose **Continue**. **3. Sign in and choose a workspace** Sign in with your Voyager account, or sign up. If you belong to more than one workspace, choose the one whose plan and credits this connection should use. The connection stays with that workspace. **4. Use it in a chat** Start a new chat in ChatGPT, type **@Voyager** and pick it, then ask for what you want. ## Check it worked Ask: *@Voyager what's my Voyager plan and how many credits do I have?* Voyager answers with your workspace, plan and credit balance. Then try something small: *@Voyager design a gig poster for Friday, tangerine on navy.* The image appears in the chat with the model's name and the credits it used. ## Set it up by hand instead If you can't use the listing, you can add Voyager as a custom server. Your ChatGPT workspace must allow custom connections. **1. Add a custom server** In ChatGPT on the web, open **Plugins**, choose **+**, then **Add custom MCP server**. **2. Enter Voyager's address** Name it **Voyager**, paste this URL and choose **OAuth**: ```text theme={"system"} https://mcp.voyager.so/mcp ``` **3. Sign in** Sign in with your Voyager account, then pick **@Voyager** in a new chat. ## If something went wrong > [accordion] I can't add Voyager or a custom server > > If your ChatGPT account belongs to a company workspace, an admin may control which apps and custom connections are allowed. Ask them to allow Voyager. > [accordion] You need a seat in this workspace > > The workspace you chose has a Voyager plan, but no seat for you. Ask one of its admins to add you, then connect again. Or connect again and choose your personal workspace. > [accordion] Voyager says a request needs a paid plan or more credits > > Your workspace's plan or credits don't cover it. Voyager links to your plan and credit details. Owners and admins can upgrade or add credits at [voyager.so/dashboard/billing](https://voyager.so/dashboard/billing). Then ask again. > [accordion] I want to use a different workspace > > A connection stays with the workspace you chose. Revoke it in **Settings → Connected apps** on your dashboard, then add Voyager again and choose the other workspace. ## Next > [card] [What Voyager can do in your chat](/connect/tools) > > Everything you can ask for, and what Voyager needs from you. # Add Voyager to Claude Source: https://docs.voyager.so/connect/claude Add Voyager as a custom connector in Claude on the web or desktop, or with one command in Claude Code, and make videos, images and audio from your chats. When you finish, you can ask Claude for a video clip, an image, a voiceover, music or a 3D model, and Voyager makes it. Voyager isn't in Claude's connector directory yet, so you add it yourself. It takes four steps in Claude, or one command in Claude Code. > [!NOTE] > > **Before you start** > > * **Claude** on the web, the Claude desktop app, or Claude Code. > * **A Voyager account.** If you don't have one, you can sign up during the steps below. > * **Cost:** adding Voyager is free. What you make uses Voyager credits from your workspace; video and 3D need a paid Voyager plan. See [Plans and credits](/connect/overview#plans-and-credits). > * This page is about using Voyager inside Claude. To run the Voyager desktop app on your Claude plan instead, see [Connect Claude](/setup/connect-claude). > [tab] Claude on the web or desktop > > **1. Open Connectors** > > In Claude, open [**Settings → Connectors**](https://claude.ai/settings/connectors). > > **2. Add a custom connector** > > Choose **Add custom connector**, name it **Voyager** and paste this URL: > > ```text theme={"system"} > https://mcp.voyager.so/mcp > ``` > > **3. Connect and sign in** > > Click **Connect**. On the Voyager page that opens, check the app it names and choose **Continue**, then sign in with your Voyager account. If you belong to more than one workspace, choose the one whose plan and credits this connection should use. > > **4. Turn it on in a chat** > > In a new chat, open **+ → Connectors** and turn on **Voyager**. > [tab] Claude Code > > **1. Add Voyager** > > In your terminal, run: > > ```sh theme={"system"} > claude mcp add --transport http voyager-cloud https://mcp.voyager.so/mcp > ``` > > **2. Sign in** > > Start Claude Code, type `/mcp`, choose **voyager-cloud** and sign in. Finish signing in with your Voyager account in the browser window that opens, and choose a workspace if asked. > > In Claude Code, Voyager can also use a file on your computer as a reference. Name the file in your request, for example *use ./photo.jpg as the start frame*. ## Check it worked Ask: *What's my Voyager plan and how many credits do I have?* Claude uses Voyager to answer with your workspace, plan and credit balance. Then try something small: *Use Voyager to design a gig poster for Friday, tangerine on navy.* The image comes back with the model's name and the credits it used. ## If something went wrong > [accordion] I don't see Add custom connector > > Your Claude plan or organization may not allow custom connectors. If you use Claude through your company, ask your Claude admin. Claude Code works without this setting. > [accordion] Claude doesn't use Voyager > > Check that **Voyager** is turned on under **+ → Connectors** in this chat, then mention Voyager in your request. In Claude Code, run `/mcp` and check that **voyager-cloud** is connected. > [accordion] You need a seat in this workspace > > The workspace you chose has a Voyager plan, but no seat for you. Ask one of its admins to add you, then connect again. Or connect again and choose your personal workspace. > [accordion] Voyager says a request needs a paid plan or more credits > > Your workspace's plan or credits don't cover it. Owners and admins can upgrade or add credits at [voyager.so/dashboard/billing](https://voyager.so/dashboard/billing). Then ask again. ## Next > [card] [What Voyager can do in your chat](/connect/tools) > > Everything you can ask for, and what Voyager needs from you. # Add Voyager to Codex Source: https://docs.voyager.so/connect/codex Add Voyager to Codex with two terminal commands, sign in with your Voyager account, and ask Codex for videos, images, audio and 3D models. When you finish, you can ask Codex for a video clip, an image, a voiceover, music or a 3D model, and Voyager makes it. > [!NOTE] > > **Before you start** > > * **Codex** installed, with a terminal you can type commands into. > * **A Voyager account.** If you don't have one, you can sign up during the steps below. > * **Cost:** adding Voyager is free. What you make uses Voyager credits from your workspace; video and 3D need a paid Voyager plan. See [Plans and credits](/connect/overview#plans-and-credits). > * This page is about using Voyager inside Codex. To run the Voyager desktop app on your ChatGPT plan through Codex instead, see [Connect ChatGPT](/setup/connect-chatgpt). ## Add Voyager **1. Add Voyager in your terminal** Run these two commands: ```sh theme={"system"} codex mcp add voyager-cloud --url https://mcp.voyager.so/mcp codex mcp login voyager-cloud ``` The name `voyager-cloud` keeps this connection apart from anything else named Voyager in Codex. **2. Sign in** A browser window opens. On the Voyager page, choose **Continue**, then sign in with your Voyager account. If you belong to more than one workspace, choose the one whose plan and credits this connection should use. **3. Check it in Codex** Start Codex and type `/mcp`. **voyager-cloud** should be in the list. Then ask for a shot. ## Check it worked Ask: *What's my Voyager plan and how many credits do I have?* Codex uses Voyager to answer with your workspace, plan and credit balance. Then try something small: *Use Voyager to make a 5-second clip of hands pouring coffee in morning light.* Video needs a paid Voyager plan; on Free, try an image instead. Voyager can also use a file on your computer as a reference. Name the file in your request, for example *use ./photo.jpg as the start frame*. ## If something went wrong > [accordion] The browser didn't open, or sign-in didn't finish > > Run `codex mcp login voyager-cloud` again and finish signing in in the browser window that opens. > [accordion] voyager-cloud isn't in /mcp > > Run `codex mcp list` in your terminal. If it isn't there, run both commands from [Add Voyager](#add-voyager) again, then restart Codex. > [accordion] You need a seat in this workspace > > The workspace you chose has a Voyager plan, but no seat for you. Ask one of its admins to add you, then run `codex mcp login voyager-cloud` again. Or sign in again and choose your personal workspace. > [accordion] Voyager says a request needs a paid plan or more credits > > Your workspace's plan or credits don't cover it. Owners and admins can upgrade or add credits at [voyager.so/dashboard/billing](https://voyager.so/dashboard/billing). Then ask again. ## Next > [card] [What Voyager can do in your chat](/connect/tools) > > Everything you can ask for, and what Voyager needs from you. # Use Voyager from ChatGPT, Claude or Codex Source: https://docs.voyager.so/connect/overview Connect Voyager to the AI chat you already use and ask it for videos, images, voiceover, music, sound effects and 3D models, paid for with your Voyager credits. You can add Voyager to ChatGPT, Claude or Codex. Then, in the chat you already use, you can ask for a video clip, a poster, a voiceover or a 3D model, and Voyager makes it. The result comes back into your chat, ready to play or download. For example, in ChatGPT you could type: *@Voyager design a gig poster for Friday, tangerine on navy.* ## Who it's for It's for people who already work in ChatGPT, Claude or Codex and want to make media there without switching apps. You don't need the Voyager desktop app, and you don't need to be a developer. You connect once, sign in with your Voyager account, and that's it. There are no keys to copy. ## Set it up > [card] [ChatGPT](/connect/chatgpt) > > Add Voyager from its ChatGPT listing. > [card] [Claude](/connect/claude) > > Add a custom connector, or one command in Claude Code. > [card] [Codex](/connect/codex) > > Two commands in your terminal. The **MCP** tab at [voyager.so/dashboard/mcp](https://voyager.so/dashboard/mcp) has the same steps with copy buttons. ## What it can make * **Images**, from a prompt or by editing an image you give it. * **Short videos**, from a prompt or from a photo. * **Speech**, in a premade voice or your own voice clone if your plan includes voice cloning. * **Music** and **sound effects**. * **3D models** you can download, such as GLB files. It can also read your workspace's **brand kits** (colors, fonts and logos), use images you share as **references**, and keep recurring characters, places and props as **Cast** so they look the same from shot to shot. See [What Voyager can do in your chat](/connect/tools) for the full list. If you don't name a model, Voyager picks a good default for each kind of media and tells you which it used. If you name one, it uses exactly that model, and asks you if it isn't available rather than switching. ## Plans and credits Generating uses Voyager credits from the workspace you choose when you sign in. The connection doesn't come with its own credits, and chatting in ChatGPT, Claude or Codex doesn't use Voyager credits. * **Video and 3D need a paid Voyager plan.** Voyager Free includes some image and voice models. * **Ask what it will cost.** Voyager can give an estimate before it starts. An estimate isn't the final charge. * **Cancelling is best effort.** Work that already finished can still be charged. * If your plan or credits don't cover a request, Voyager tells you in one sentence and links to your plan and credit details. You can't buy credits or upgrade from inside the chat. Do that at [voyager.so/dashboard/billing](https://voyager.so/dashboard/billing). See [Plans and credits](/account/plans-and-credits) and [Voyager pricing](https://voyager.so/pricing). ## How it differs from the desktop app | | In ChatGPT, Claude or Codex | Voyager desktop app | | - | - | - | | **What runs it** | Your AI chat, with Voyager as a connected tool | Voyager's own agent | | **What it makes** | Single images, short clips, audio and 3D models | Whole finished videos, edits and motion graphics | | **Your computer** | No access to your files, folders or creative apps | Works in your creative apps and project folders | | **Cast** | Its own Cast, kept in your workspace | Cast kept in each desktop project | Cast you make through the connection and Cast in your desktop projects are separate. They don't sync. Want to build Voyager into your own code instead? See the [Voyager API](/api/overview). ## Your files and how long they're kept * **References** you share are kept for 7 days, unless you save them into a Cast card. * **Results** stay available to download for 30 days. * **Cast** you save stays until you delete it. * Preview and download links expire after a few minutes. Ask Voyager for the result again to get a fresh link. You can ask Voyager to delete a reference, a result or a Cast card at any time. See [Privacy](/help/privacy) and the [Voyager privacy policy](https://voyager.so/privacy#remote-plugin). ## Disconnect an app **1. Open Connected apps** Go to **Settings → Connected apps** at [voyager.so/dashboard/connected-apps](https://voyager.so/dashboard/connected-apps). **2. Revoke the connection** Find the app and its workspace, choose **Revoke**, then **Revoke access**. Do this even if you already removed Voyager in ChatGPT, Claude or Codex. Removing it there may leave its access to your Voyager account active. Revoking stops new requests. Work already accepted may still finish, and your saved Cast and downloaded files are kept. # What Voyager can do in your chat Source: https://docs.voyager.so/connect/tools Every tool Voyager adds to ChatGPT, Claude and Codex: what each one does, what it needs from you, and which ones spend Voyager credits. When you connect Voyager to ChatGPT, Claude or Codex, your chat gets a set of Voyager tools. You don't call them yourself: you ask in plain words, and the chat picks the tool. This page lists them, so you know what you can ask for and what Voyager needs from you. Tools marked **Spends credits** use Voyager credits from your workspace. Everything else is free to use. ## Account, models and cost | Tool | What it does | Important inputs | | - | - | - | | `account_status` | Shows the workspace this connection uses, its plan and your credit balance. | None | | `list_models` | Lists Voyager's recommended models for each kind of media, with the default marked. It can also search for a model you name, or show one model's settings and credit rates. | Kind of media; a model name to search for | | `estimate_generation` | Estimates the credits for a generation without starting it. Voyager uses it when you ask what something costs or give a budget. An estimate isn't the final charge. | Kind of media, model, prompt, length, count and other settings | | `load_skill` | Loads Voyager's guide for a kind of media, so the chat writes better prompts and picks sensible settings. | Which guide: general, image, video, audio or 3D | ## Make media Each of these starts a job and **spends credits**. If you don't name a model, Voyager uses its default for that kind of media and tells you which model it used. If you name a model, Voyager uses exactly that one, or asks you if it isn't available. | Tool | What it makes | Important inputs | | - | - | - | | `generate_image` | Images, from a prompt or by editing images you give it. | Prompt, model, aspect ratio (such as 1:1, 16:9 or 9:16), how many; reference images; up to 4 Cast cards | | `generate_video` | Short video clips, from a prompt or from images. **Needs a paid Voyager plan.** | Prompt, model, aspect ratio, length in seconds (one the model offers), sound on or off where the model supports it; reference images such as a start or end frame; up to 4 Cast cards | | `generate_speech` | A voiceover that speaks your exact words. | The words to speak, the voice, the model | | `list_voices` | Finds voices for speech: premade voices, or your own voice clones if your plan includes voice cloning. Clones are made in the Voyager app. Free to use. | Search words, language, gender; premade or your own | | `generate_music` | Music, such as a background bed. | Description (genre, mood, instruments, tempo), length, model | | `generate_sound_effect` | Sound effects. | Description of the sound, length, model | | `generate_3d` | A textured 3D model from a description or one image, or a new texture for a 3D model it already made. Results include GLB and other formats you can download. | Description or one reference image; the earlier 3D job to retexture | Some models have more settings. Voyager reads them from the model and fills them in for you. The generation tools also accept a repeat-safe key, so the same request sent twice makes one job and charges once. ## Jobs and results | Tool | What it does | Important inputs | | - | - | - | | `get_job` | Checks a job and returns the result when it's done, with fresh links to view and download it and the credits charged. | Job ID | | `list_jobs` | Lists your recent jobs in this workspace, newest first. | Kind of media | | `cancel_job` | Asks to stop a queued or running job. Best effort: work already done can still be charged, and a finished job is unchanged. | Job ID | | `get_asset` | Gets a reference or result by its ID, with fresh view and download links. | File ID | | `delete_asset` | Permanently deletes one of your references or results. | File ID | Keep a job's ID if you might close the chat: you can ask for it again later. View and download links expire after a few minutes, so ask again for a fresh one. Results stay available for 30 days. ## References A reference is an image, video clip or audio file you give Voyager to work from, such as a start frame, a product photo or a logo. | Tool | What it does | Important inputs | | - | - | - | | `import_reference` | Brings in one file you shared as a private reference. It's kept for 7 days unless you save it into a Cast card. | A file you attached in the chat, a link starting with https\://, or an uploaded file | | `create_upload` | In Claude Code or Codex, uploads one file from your computer that you named, so it can be used as a reference. | The file's name | Voyager only imports files you give it. ## Brand kits | Tool | What it does | Important inputs | | - | - | - | | `list_brand_kits` | Lists the brand kits in your workspace. | Search words | | `get_brand_kit` | Reads a brand kit's colors, fonts and logos, so Voyager can use them in prompts and add a logo as a reference. | Brand kit | Brand kits are read-only here. Create and edit them in the Voyager app. ## Cast Cast cards keep a character, location or prop looking the same across images and videos. Each card holds reference images and, for a character, an optional voice. Cast made through ChatGPT, Claude or Codex is kept in your workspace. It's separate from the Cast in your desktop projects. | Tool | What it does | Important inputs | | - | - | - | | `list_cast` | Lists your workspace's Cast cards. | None | | `get_cast` | Reads one Cast card, with links to its reference images. | Card name or ID | | `generate_cast` | Makes reference images from a description and saves them as a new Cast card. **Spends credits.** | Name; character, location or prop; description of fixed features; photoreal or stylized; optional voice | | `save_cast` | Creates a Cast card from images you already have, or replaces an existing card. | Name; kind; description; style; the images and what each shows | | `add_cast_reference` | Adds one of your images to a Cast card. | Card; image; what it shows: main image, full body, an angle, an expression, an outfit, a background plate or a style | | `remove_cast_reference` | Removes an image from a Cast card. | Card; image | | `delete_cast` | Deletes a Cast card and the reference images no other card uses. Jobs already started keep theirs. | Card | ## What Voyager can't do here * It can't see your computer's folders, open your creative apps or edit a timeline. Use the [Voyager desktop app](/get-started/how-it-works) for that. * It can't create a voice clone, change your plan or buy credits. Do those in the Voyager app or at [voyager.so/dashboard](https://voyager.so/dashboard). * It makes media only. It doesn't read calendars, email or other data. # Find your finished file Source: https://docs.voyager.so/first-video/find-your-file Use Reveal, Save video and Copy full path to find and keep the finished version of your work. The video Voyager delivers is already a file on your computer. There is no **Export** button to press after the agent has rendered it. Have the finished video open in the chat, **Assets**, or the project's **Outputs**. If you only have a design preview, ask the agent to render a video file first. ## Get the video **1. Open the version you want** Play the video in the chat to check it is the finished version. In a project, click its name in the sidebar and look under **Outputs**. Click an output to open its latest version. If it has several versions, click its **v2**, **v3** or other version badge to open the list, then choose **Open** beside the one you want. ![A project page with the Teaser output's versions panel open, newest first. Each version, v2 and v1, has Open and Reveal buttons.](https://mintcdn.com/voyager/dzNfJ3ErXafJEG4z/images/screenshots/first-video-get-file.light.png?fit=max\&auto=format\&n=dzNfJ3ErXafJEG4z\&q=85\&s=a5672bb85d4d46847c556f662186d1e8) The versions list lets you open or reveal a specific version, including an earlier one. **2. Reveal the original or save a copy** Right-click the video to open its file actions. | Action | What it gives you | | - | - | | **Save video** | A copy of the video through the save/download flow. | | **Copy full path** | The original file's complete location, ready to paste. | | **Reveal** in a project's versions list | The original file selected in your file manager. | The right-click reveal label depends on your platform: > [tab] macOS > > Choose **Reveal in Finder** to locate the video in Finder. > [tab] Windows > > Choose **Reveal in File Explorer** to locate the video in File Explorer. > [tab] Linux > > Choose **Reveal in Files** to locate the video in your file manager. **3. Open it outside Voyager** Open the saved or revealed file in your usual video player. Check the beginning, end and sound, then use that file wherever you want to share or upload the video. To get feedback on it first, open the file in the side panel's file viewer, click the share button in its header and choose **Share for review**. See [share a video for review](/guides/share-for-review) and [files and previews](/guides/files-and-previews). ## Choose a delivery folder Open **Settings → Creative → Delivery folder** to choose where the agent should save finished videos, images and exports. Working files and drafts stay in the project. Leave the field empty to keep finished work there too. ![The Delivery folder setting in Creative settings, with \~/Videos/Northwind deliveries entered, a folder button beside the field, and Saved below the description.](https://mintcdn.com/voyager/dzNfJ3ErXafJEG4z/images/screenshots/files-delivery-folder.light.png?fit=max\&auto=format\&n=dzNfJ3ErXafJEG4z\&q=85\&s=8e3772164f46c9a622890a6a082ddde1) Set a Delivery folder if you want finished work in one predictable place. This tells the agent where to save its next deliveries. It does not move videos you have already made. For a one-off destination, name the folder in your request. ## Where the other files live | Work | Where to look | | - | - | | Work in a project | The folder chosen when you created the project. Open its **… → Copy folder path** action to copy that location. | | A chat without a project | Its own subfolder under **Settings → General → Advanced → Conversation files folder**. New installs default to the `Voyager` folder in your home folder; older installs may use `Documents/Voyager`. | | Generated source images and clips | The `takes` folder inside the chat or project folder, unless you asked for another folder. Older work may be in a `generated` folder. These may be ingredients rather than the finished cut. | | Editable motion or editing source | The working folder used for the piece. Ask the agent to show the editable source if it is not clear which file to open. | Changing **Conversation files folder** affects new chats without a project. Existing folders stay where they are. ## Common problems > [accordion] I found several videos and do not know which is final > > Use the final reply or the project's **Outputs** to open the delivered version. The `takes` folder can contain individual shots. Ask “Show me the final assembled video and its full path” if you need help identifying it. > [accordion] The result is missing from Outputs > > **Outputs** lists work the agent has presented. Ask it to show the finished file in the chat and add it as a project output. You can still find existing files through **Files**. > [accordion] I need MP4, but received another format > > Tell the agent where you will use the video and ask for MP4. On Linux, MP4 encoding depends on what is available on the computer; Voyager may offer WebM. See [platform requirements](/get-started/requirements). > [accordion] The preview says the file is missing > > Check whether the original file or project folder was moved or deleted. Tell the agent its new location if you moved it. A saved copy can still be opened even if the original preview no longer works. > [card] [Next: choose your next project](/first-video/next-steps) > > Build on your first result with footage, generated scenes or a reusable visual style. # Make your first video Source: https://docs.voyager.so/first-video/make-your-first-video Make a short motion graphic without media credits, review it, and find the finished video. Make an eight-second animated title, then change one detail and save the finished video. > [!NOTE] > > **Before you start:** [Finish setup](/setup/overview) and connect a chat account. You can use your > own Claude or ChatGPT; a paid Voyager plan is optional. This exercise uses text, shapes and local > rendering, so it needs no media credits or media keys. Your chat account's normal usage limits > still apply. Chat through Voyager models uses Voyager credits. You do not need footage, a logo or a separate video editor. On Linux, the finished file may be WebM if MP4 encoding is unavailable. See [platform requirements](/get-started/requirements). ## Make a motion graphic **1. Start a chat** Click **New chat** in the sidebar. You can leave this chat without a project: Voyager gives it a folder for its files when you send your first message. Just finished setup? The chat it opened may already have a starter prompt from the [Create step](/setup/create) in the message box. Send that instead if you like, or replace it with the request below. Check the model picker below the message box. Choose your connected Claude or ChatGPT account if you want to use your own. ![A new Voyager chat asking What would you like to create?, with the message box, the model picker and New chat in the sidebar.](https://mintcdn.com/voyager/rEfw7LKCPAGvufOx/images/screenshots/first-video-new-chat.light.png?fit=max\&auto=format\&n=rEfw7LKCPAGvufOx\&q=85\&s=42d442f7268ab0ec66789f1b8db09358) Start with an empty chat and check which account will answer. **2. Choose how to answer questions** Click the questions control below the message box (it shows **Wait, then go ahead** by default) and choose **Always ask**. This lets you answer any creative questions yourself while you learn. You can change this later. **Wait, then go ahead** counts down, then picks the recommended answer; **Don't ask** selects it immediately, including answers that approve paid generation, and asks you to confirm first. See [approvals and spending](/guides/approvals-and-spending). **3. Describe the result** Paste this request, then click the send arrow or press Enter: ```text theme={"system"} Make an 8-second motion graphic in 16:9 using Remotion. Use only text and simple shapes, rendered locally. No generated images, video, music or voiceover, and no paid media generation. On a dark navy background, animate a mint line into a circle. Reveal the words “Make room for ideas.” in large cream lettering. Keep the final words readable for the last 2 seconds. Deliver a silent MP4 and keep the editable source. If MP4 is unavailable on this computer, deliver WebM and tell me. ``` ![The eight-second motion graphic request in the message box, with Always ask selected and the send arrow ready.](https://mintcdn.com/voyager/rEfw7LKCPAGvufOx/images/screenshots/first-video-motion-prompt.light.png?fit=max\&auto=format\&n=rEfw7LKCPAGvufOx\&q=85\&s=43951b1fed0c13c2900c0eefeccadc94) A short request can specify the words, look, timing and finished file. Under your message you may briefly see **Consulting Voyager expert…** while Voyager checks its own creative guidance for your request. You don't need to do anything. If this is your first motion project, Voyager may need to download tools before it can render. Read any setup question and let that work finish. **4. Follow the work** Read the updates in the chat. Answer any questions about the design or setup. If the agent shows a preview first, give feedback or ask it to render the finished video. Renders and other long jobs show in the **Activity** tray at the bottom right, above the message box. For more detail, open **Background** in the right panel and filter by **Agents**, **Jobs** or **Shells**. A queued job is waiting to start; you do not need to send the same request again. **5. Watch the result** Play the video in the reply. Check that the wording is correct, the circle moves smoothly, and the final title stays on screen long enough to read. ![Voyager's reply showing the completed navy, mint and cream motion graphic as a playable video.](https://mintcdn.com/voyager/rEfw7LKCPAGvufOx/images/screenshots/first-video-motion-result.light.png?fit=max\&auto=format\&n=rEfw7LKCPAGvufOx\&q=85\&s=5614db6aa95627e1920ec41cb19ae419) Play the finished video before asking for a revision. **6. Make one revision** Send a small, specific change in the same chat: ```text theme={"system"} Make the title larger and slow its entrance down slightly. Keep the colors, circle and 8-second length. Save a new version and keep the original. ``` Play the new result. You can also point to a frame or draw around a detail with [video review](/first-video/review-and-revise). **7. Find the finished file** Right-click the finished video and choose **Save video** to save a copy, or use the reveal action to find the original in your file manager. **Copy full path** gives you its location. Voyager has no **Export** button for this step: the agent has already rendered a video file. [Find your file](/first-video/find-your-file) explains the folder and version controls. ## Try generated video instead For a scene that needs newly generated footage, connect a [generation provider](/account/generation-providers). You can use your own media keys, which need no Voyager plan, or Voyager credits from a plan. Your Claude subscription does not cover media generation. A connected ChatGPT account can cover supported image generation within its plan allowance, but generated video needs a generation provider. See [current plans and pricing](https://voyager.so/pricing). > [!WARNING] > > Generated stills, animation and additional takes can cost money. Choose **Always ask** for this walkthrough, and review the estimate before approving. **Don't ask** can approve generation immediately, even above your spend limit. > > If a provider is out of credits, rejects its sign-in or is down, Voyager can try the next one in your list. That may bill a different account. To turn this off, open **Apps & Models → Providers**, click **Change order** to open **Image, video and voice order**, and switch off **If one can't finish, try the next provider**. You can also ask Voyager to pin a provider for this job. 1. Start a new chat and choose **Always ask** from the questions control below the message box. Voyager picks the image and video models for you (**Auto**). To choose them yourself, click the **Preferred creative apps and media models** button beside the model picker; see [choose models and apps](/guides/choose-models-and-apps). 2. Ask for a short, two-shot video: ```text theme={"system"} Make a 10-second vertical video about a seedling growing toward sunlight: first a close-up of the leaves, then a wider view of the pot by a window. Keep the look warm and natural, with no audio. Estimate the stills before generating them and wait for my approval. Then show one still per shot, with the animation cost and time estimate. Wait for me to approve the stills before animating. ``` 3. Approve the still-image work after reading its estimate. When the stills appear in the question card, step through them and check the subject, composition and consistency between shots. 4. Choose an answer. The card waits for you; it doesn't count down. * **Animate** with the number of stills, such as **Animate 4**, animates every still. It shows the estimated cost and time. * To redo some stills, click **Redo** on each one and type what to change, or leave the note empty for a fresh take. Then click **Send review**, which shows how many you flagged. Voyager redraws the flagged stills and animates the rest. * To revisit the look, choose **Change the overall direction** and type the new direction in the same card. 5. Follow progress in the **Activity** tray, then play, revise and save the finished video as above. ![A still review card: the second still shown large with a filmstrip of the four, Redo pressed with the note Move in closer on the beans, Send review · Redo 1, and Change the overall direction.](https://mintcdn.com/voyager/rEfw7LKCPAGvufOx/images/screenshots/first-video-approve-stills.light.png?fit=max\&auto=format\&n=rEfw7LKCPAGvufOx\&q=85\&s=7bf21b1351d3a38e2dc8292b8f508a6d) Flag any still to redo with a note, then send the review to animate the rest. Voyager asks before spending more than your limit (in **Wait, then go ahead** and **Always ask**). The limit is a preference the agent follows, not a hard spending cap. [Set your preferences](/guides/approvals-and-spending) before a larger project. ## Check it worked You should have a playable video, a revision in the same chat, and a file you can open outside Voyager. For the motion graphic, the editable source should also be available in **Files**. ## If something went wrong > [accordion] The agent asks for a media account or credits > > Check whether you chose Voyager models for chat or asked for generated media. For the motion > exercise, choose your own connected Claude or ChatGPT account and repeat that you want only > text, shapes and a local render. See [accounts and agents](/account/accounts-and-agents). > [accordion] I have a preview but no video file > > Ask: “Render this approved version to a video file and show me the result.” A preview lets you > review the design; the finished video still needs rendering. > [accordion] The work appears to be waiting > > Look for a question or approval card in the chat, then check the **Activity** tray. Queued work may be > waiting for a free slot. If generation failed, read the error before starting another paid > attempt; [generation problems](/help/generation-problems) explains the next steps. > [card] [Next: review and revise](/first-video/review-and-revise) > > Leave a note on the exact frame or time range you want to change. # Choose your next project Source: https://docs.voyager.so/first-video/next-steps Choose a creative workflow and save the context that helps Voyager build on your first result. Now that you have made, revised and found a video, choose the kind of work you want to make next. ## Pick a starting point > [card] [Animate a message](/guides/motion-graphics) > > Make titles, explainers, charts and branded motion with editable source. > [card] [Generate a scene](/guides/generate-images-and-video) > > Create new images or footage, approve the look, and build a finished cut. > [card] [Edit your footage](/guides/edit-footage) > > Turn recordings and existing clips into highlights, captioned edits or vertical cutdowns. > [card] [Write a clearer request](/guides/write-a-request) > > Give Voyager the audience, format, references and constraints it needs. For example, you could turn your first title animation into three sizes, use it as an opening for an interview clip, or make a second video with the same colors and type. For ideas, open **Techniques** in the sidebar. It shows techniques from voyager.so that you can try in a new chat. > [card] [Share your video for feedback](/guides/share-for-review) > > Send a link so a client or teammate can leave timed notes in their browser, then have Voyager address them. ## Keep related work together Create a [project](/guides/chats-and-projects) when several pieces share a campaign, brand or set of files. Add the audience and creative brief to the project's **Brief**, which every chat in the project reads when it starts. Choose a [brand kit](/setup/brand) when colors, fonts and logos should carry across the work; your brand kits, voices and elements are in **Library** in the sidebar. See [Library](/guides/library). Use a new chat in that project for a distinct piece. Continue the existing chat when you are revising its result. ## Set your working preferences Before you start a larger job: * Choose how often to be asked with the questions control below the message box. Read [approvals and spending](/guides/approvals-and-spending), especially before using **Don't ask**. * Set **Delivery folder** in **Settings → Creative** if you want finished work in a particular place. * Choose the models and creative apps Voyager uses, or leave them on **Auto**. Click the **Preferred creative apps and media models** button beside the model picker to change them for a chat, and click **Save as *project* default** to keep them for the project. To set defaults for all your projects, open **Apps & Models → Models → Default models** or **Apps & Models → Apps → Preferred apps** and choose **All projects**. A project's or chat's own choices take precedence over these defaults. See [choose models and apps](/guides/choose-models-and-apps) and [creative app setup](/setup/creative-apps). You can keep using your own Claude or ChatGPT and your own media keys. A paid Voyager plan is optional; [pricing](https://voyager.so/pricing) explains the current options. Local motion and editing can use no media credits when the work uses only local tools and existing assets. Generating new media usually costs money: a connected ChatGPT account can cover supported images within its plan allowance, and other images, video, voice and music use your media keys or Voyager credits. ## When you need help Tell the agent what you expected and what happened instead. Include the file or a [review comment](/first-video/review-and-revise) when the problem is visible in the result. For an app or account problem, right-click the chat in the sidebar and choose **Send feedback…**, or use the [help guide](/help/get-help). # Review and revise your video Source: https://docs.voyager.so/first-video/review-and-revise Leave comments on a frame or time range, send them to Voyager, and compare the next version. Point to the exact moment or detail you want changed, then send your notes to the agent in the same chat. You need a video you can open in Voyager, such as the result from [your first video](/first-video/make-your-first-video). You can also revise it with an ordinary message: “Make the final title larger and keep everything else.” ## Leave a review **1. Open the video for review** Click the video in the agent's reply, or hover over it and click the pencil button, which reads **Comment**. You can also right-click it and choose **Review video**. ![A video in a Voyager reply with the pencil Comment button in its top corner.](https://mintcdn.com/voyager/rEfw7LKCPAGvufOx/images/screenshots/first-video-result-inline.light.png?fit=max\&auto=format\&n=rEfw7LKCPAGvufOx\&q=85\&s=54f43b4395a6c98b5bbcffeaae6b2fa9) Comment opens a player where notes can point to the picture and its timing. **2. Find the moment and mark it** Play or pause with Space. Use the left and right arrow keys to move a frame at a time, or hold Shift to move 10 frames. Use the pin tool to point to a detail, the pen to draw, or the box tool to surround an area. Their shortcuts are P, D and B. Write a concrete note, such as “Make this title about a third larger, keeping it centered,” then click **Save note**. ![The review player with a pin note being written, a drawn box, and Save note and Add to chat (1) in the comment box.](https://mintcdn.com/voyager/rEfw7LKCPAGvufOx/images/screenshots/first-video-review-pin.light.png?fit=max\&auto=format\&n=rEfw7LKCPAGvufOx\&q=85\&s=be574ce3d2980570a6727903b3956612) A mark and a specific note tell Voyager what to change in this frame. **3. Use a time range for pacing or sound** For a change that covers several seconds, use **Select time range** at the timeline. Set **In** and **Out**, then add your note. You can use I and O to set the range while reviewing. For example: “Slow this entrance down, but keep the title fully visible for the final two seconds.” A range is more useful than a single frame for pacing, transitions or audio. ![The review time-range controls showing In, Out and Length for a selected section of video.](https://mintcdn.com/voyager/rEfw7LKCPAGvufOx/images/screenshots/first-video-review-range.light.png?fit=max\&auto=format\&n=rEfw7LKCPAGvufOx\&q=85\&s=64688feaff780d0fd135f854003896e4) A range comment applies to the span between In and Out. **4. Add your notes to the chat and send** > [!WARNING] > > A revision that generates new images, clips, music or voice can cost money. Review the new estimate and your [question-answer mode and spend limit](/guides/approvals-and-spending) before approving paid work. Click **Send now** with the note count, such as **Send now (3)**, to send every note to the agent at once. After it goes, the button reads **Sent**. To add instructions first, open the arrow beside **Send now** and choose **Add to chat without sending**. The review appears in the message box. Add your instruction and send it: ```text theme={"system"} Apply these notes. Keep the parts I haven't commented on. Save a new version and keep the original. ``` If you've already typed something in the message box, **Send now** adds the review beside your words instead of sending them, so you can finish the message. **Add to chat (1)** in a comment box saves that one note and adds it to the chat. When the agent puts several files up for review, **Send now** in the For your review popup sends the notes on all of them together. ![The For your review popup on its second item with Send now (1) and the arrow beside it.](https://mintcdn.com/voyager/FA-YyLZmdgqk9PG-/images/screenshots/first-video-review-send-all.light.png?fit=max\&auto=format\&n=FA-YyLZmdgqk9PG-\&q=85\&s=194f41178118f0ca7677ca1ff8772046) Send now sends the notes waiting on every file the agent put up for review. ![A review with three comments added to the Voyager message box, and the review's button showing Added.](https://mintcdn.com/voyager/FA-YyLZmdgqk9PG-/images/screenshots/first-video-review-attach.light.png?fit=max\&auto=format\&n=FA-YyLZmdgqk9PG-\&q=85\&s=1807a87811ca250c6b91d7e6089959db) The review is in the message box, ready for your next message; send it when your instructions are complete. ## Get feedback from someone else To have a client or teammate leave notes too, click the share button at the top of the file viewer and choose **Share for review**, then click **Create link** and **Copy link** once it uploads. Anyone with the link can open it in a browser to watch and leave notes, and their notes come back into this review. See [share a video for review](/guides/share-for-review). ![The Share dialog for the video, with Share for review and the other ways to share it.](https://mintcdn.com/voyager/rEfw7LKCPAGvufOx/images/screenshots/first-video-share-review.light.png?fit=max\&auto=format\&n=rEfw7LKCPAGvufOx\&q=85\&s=aff4d69aca9488b03775c5bd39c5efb8) Share for review creates a link others can open in a browser to leave timed notes. ## Compare the result Open **Assets** in the right panel and select the output. When it has suitable versions to compare, click **Compare** and choose the two versions. | View | Use it to check | | - | - | | **Side by side** | Both versions at once. | | **Wipe** | Differences across the same picture using a divider. | | **Flip** | One version at a time, switching between them. | ![Two versions of a video in Assets with Compare open in Wipe mode.](https://mintcdn.com/voyager/rEfw7LKCPAGvufOx/images/screenshots/first-video-v2-compare.light.png?fit=max\&auto=format\&n=rEfw7LKCPAGvufOx\&q=85\&s=7411efecdd356bc6d194e30ecdd1d16b) Compare versions of the same output before choosing the one to keep using. Play the revised section and the complete video. A title change may look right in one frame but arrive too early in motion. Keep giving feedback in the same chat so the agent has the earlier decisions. ## Common problems > [accordion] I added notes to the chat, but nothing happened > > **Add to chat without sending** only puts the review in the message box. Add an instruction and click the send arrow there, or use **Send now** in the review to send it straight away. > [accordion] The agent changed the wrong version > > Open the intended version and add a review from that file to the chat. Name the version in your message and say what should stay unchanged. > [accordion] Compare is missing > > Check that you selected an output with more than one comparable version in **Assets**. If the revision is a separate output, ask the agent to present it as the next version of the original. > [card] [Next: find your file](/first-video/find-your-file) > > Open the finished version in your file manager or save a copy. # Choose your setup Source: https://docs.voyager.so/get-started/choose-your-setup Decide which agent you'll chat with and who pays for generated media, so you know what to connect during setup. Before you install, make two choices: which AI you'll chat with, and who pays when Voyager generates new images, video or audio. You can change both later in **Apps & Models → Providers**. > [!NOTE] > > Every setup starts with a free Voyager account, which you create or sign in to during setup. A > paid Voyager plan is optional: you can finish setup and do all your work with your own Claude or > ChatGPT and your own media keys. ## Choice 1: Which agent you chat with | If you have… | Choose | What it costs | Set it up | | - | - | - | - | | A Claude Pro or Max plan | **Claude** | Nothing extra from Voyager. Uses your Claude plan's limits. | [Connect Claude](/setup/connect-claude) | | A ChatGPT Plus or Pro plan | **ChatGPT** | Nothing extra from Voyager. Uses your ChatGPT plan's limits. | [Connect ChatGPT](/setup/connect-chatgpt) | | A Google account or a Gemini API key | **Gemini**, through Antigravity | Nothing extra from Voyager. Uses your Google account's limits, or Google bills your key per use. | [Set up Gemini](/setup/voyager-models#gemini) | | An Anthropic, OpenAI, Gemini or xAI API key | **Use an API key instead** | Nothing extra from Voyager. The provider bills your key per use. | [Your own API key](/setup/voyager-models#your-own-api-key) | | None of these, or you want one bill | **Voyager** | Each chat turn uses your Voyager plan's credits. [Voyager Free](/account/plans-and-credits#voyager-free) includes some models. | [The Voyager row](/setup/voyager-models#the-voyager-row) | **Not sure?** If you already pay for Claude or ChatGPT, use it. It's the cheapest way to chat, and for heavy use of the most capable models it's usually the better deal. You can connect more than one and switch in any chat from the model picker. If you connect both Claude and ChatGPT during setup, new chats start on Claude. Change the default any time in **Settings → General → Chats → AI for new chats**. **New chat** starts on the model you last picked until you change that default. > [!TIP] > > If Claude Code or the Codex CLI on your computer is already signed in with an API key, setup > accepts it like a subscription. You can add or replace API keys later in **Apps & Models → > Providers**. ## Choice 2: Who pays for generated media Your chat subscription doesn't pay for generated media, with one exception: images made on your own ChatGPT plan through Codex use that plan's Codex usage (and any OpenAI credits on your account once it runs out). Everything else, including video shots, voiceover, music and sound effects, is billed separately, by whoever makes it. | You want… | Choose | How you pay | | - | - | - | | To use accounts you already have with media services | **Your own keys or sign-ins**: Higgsfield, fal, Google, ElevenLabs, Runway, Fish Audio, Inworld, BytePlus, Sume, an OpenAI API key, or images on your ChatGPT plan through Codex | Each service bills your account with them directly. | | One bill and nothing to set up | **Voyager credits** | Credits from your Voyager plan. Change plan or add credits in **Settings → Account**, or at [voyager.so/dashboard/billing](https://voyager.so/dashboard/billing). | | No generated media | **Nothing** | Editing your own footage, captions and most motion graphics run on your computer and cost nothing. | You can connect several. Voyager tries them in the order you set with **Image, video and voice order** on **Apps & Models → Providers**. > [!WARNING] > > **Trying the next provider is on by default.** If the provider at the top of your order is out of > credits, rejects its sign-in or is down, Voyager tries the next one, which may bill a different > account. To stop this, open **Image, video and voice order** and turn off **If one can't finish, > try the next provider**, or tell the agent which provider to use for a job. See [Generation providers](/account/generation-providers). Some things only come from Voyager credits. Voyager's managed voices, for example, always use credits. Plans also let you run more generations at once. Which models you can use depends on the plan. See [voyager.so/pricing](https://voyager.so/pricing) for what each plan includes. ## Common setups > [accordion] I have Claude or ChatGPT and want to spend nothing extra > > Connect your subscription during setup. Skip media keys for now. You can edit your own footage, > make motion graphics and work with your files right away. When you want generated media, add a > key for a provider you already use, or get a plan. > [accordion] I have Claude or ChatGPT and keys for media services > > Connect your subscription, then add your keys on the [Video & images](/setup/media) step of > setup (under **Already pay for other providers?**), or later in **Apps & Models → Providers**. In **Image, video and voice order**, put the provider you want > billed first at the top. > [accordion] I have Claude or ChatGPT and want simple media billing > > Connect your subscription for chat and get a Voyager plan for media. Keep **Voyager** in your > **Image, video and voice order**, and turn off or move down any provider you don't want billed. > [accordion] I don't have Claude or ChatGPT > > Chat on Voyager models. Voyager Free includes some of them, and a paid plan covers more models > and media generation from one balance of credits. ## What the agent does before spending However you pay, the agent tells you what a paid step is likely to cost. Whether it waits for you depends on the question mode in each chat, set with the **Questions and permissions** control below the message box: * **Wait, then go ahead** (the default) waits for you when a step would cost more than your limit. Otherwise it counts down and picks the recommended answer. * **Always ask** always waits for you. * **Don't ask** picks the recommended answer immediately, including paid generation above your limit. You choose the limit. It's an instruction the agent follows, not a hard cap on spending. Set it in **Settings → Creative → Limits**. See [Approvals and spending](/guides/approvals-and-spending). ## Next > [card] [Check the requirements](/get-started/requirements) > > Make sure your computer can run Voyager, then install it. # How Voyager works Source: https://docs.voyager.so/get-started/how-it-works The five ideas behind Voyager: the agent, chats and projects, files on your disk, generation providers and Voyager credits. Voyager is built around five ideas. Once they click, the rest of the app is easy to find your way around. ```mermaid theme={"system"} flowchart LR you([You]) -- "request, notes" --> chat["Chat
(in a project)"] chat <--> agent["Agent
Claude, ChatGPT, Gemini or Voyager models"] agent -- "makes and edits" --> files[("Files on your disk")] agent -- "new images, video, audio" --> providers["Generation providers
your keys or Voyager credits"] providers -- "finished media" --> files files -- "preview and review" --> you ``` ## 1. The agent does the work The **agent** is the AI you talk to. It reads your request, plans the piece, uses tools to make it, and checks its own result before showing you. You choose which AI powers the agent: * **Claude**, signed in with your Claude subscription or an Anthropic API key. * **ChatGPT**, signed in with your ChatGPT subscription or an OpenAI API key. * **Gemini**, through Antigravity, signed in with your Google account or a Gemini API key. * **Voyager models**, open models that run through your Voyager account and use your plan's credits, including [Voyager Free](/account/plans-and-credits#voyager-free). You can also chat with your own Anthropic, OpenAI, Gemini or xAI API key, added in **Apps & Models → Providers**. Using your own Claude, ChatGPT or Gemini costs nothing extra from Voyager. With an API key, the provider bills you per use. You can switch models from the model picker in any chat. Before a paid step, the agent shows you an estimate. Whether it waits for your answer depends on how you've set [approvals and spending](/guides/approvals-and-spending). ## 2. You work in chats, grouped into projects A **chat** is one conversation with the agent. You write a request, the agent replies, and you keep going until the piece is done. A **project** groups related chats around one folder, with its own brand kit and a short brief the agent reads every time. Use a project for anything you'll come back to, like a product launch or a client. A quick one-off can live in a chat without a project. > **Example:** A "Spring launch" project holds a chat for the teaser, a chat for the social cutdowns and a chat for the thumbnail. All three see the same logo, colors and brief. Learn more in [Chats and projects](/guides/chats-and-projects). ## 3. Your work is ordinary files on your disk Everything the agent makes is saved as normal files in a folder on your computer: videos, images, audio, and the editable source behind them. There's no special library to export from. * A chat without a project saves to its own folder inside **\~/Voyager** (you can change this in **Settings → General → Advanced → Projects & chats → Conversation files folder**). * A project saves to the folder you chose when you created it. You can open these files in any app, back them up, or move them like any other file. See [Where your files are](/first-video/find-your-file) and [Data locations](/reference/data-locations). ## 4. Generation providers make new media When the agent needs something that doesn't exist yet, like a generated video shot, an image or a voiceover, it asks a **generation provider** to make it. Providers are services such as Higgsfield, fal, Google, ElevenLabs, Runway, Fish Audio, Inworld, BytePlus and Sume. You decide who pays, in **Apps & Models → Providers**: * **Your own media keys or sign-ins.** The provider bills your account with them directly. No Voyager plan needed. * **Voyager credits.** Voyager makes the request and takes credits from your plan. ![The Apps & Models page on its Providers tab, with Voyager and ChatGPT listed as connected, and more providers, including Claude, below.](https://mintcdn.com/voyager/yRytHenCA6FFAhzA/images/screenshots/connectors-overview-providers.light.png?fit=max\&auto=format\&n=yRytHenCA6FFAhzA\&q=85\&s=a53c67a6a2c27e57abff0b50d8e2cc26) Apps & Models → Providers lists what you've connected, for chat and for media. Voyager tries your providers in the order you set. If one is out of credits, rejects its sign-in or is down, Voyager tries the next one, which may bill a different account. To stop this, choose **Image, video and voice order** on the **Providers** tab and turn off **If one can't finish, try the next provider**. Or tell the agent which provider to use for a job and it will stick to that one. See [Generation providers](/account/generation-providers). Plenty of work needs no provider at all. Editing your own footage, cutting clips together, captions and most motion graphics run on your computer. ## 5. Voyager credits pay for Voyager's services **Voyager credits** come with a Voyager plan. They pay for media generated through Voyager and for chats that use Voyager models. They don't pay for your own Claude, ChatGPT or Gemini, and your Claude or ChatGPT doesn't pay for media, except images you ask to make on your own ChatGPT plan through Codex, which use that plan's Codex usage. A paid plan is optional. You can use Voyager with only your own Claude or ChatGPT and your own media keys. Plan names, prices and how many credits each includes are on [voyager.so/pricing](https://voyager.so/pricing). Change your plan or buy credits in **Settings → Account**, or at [voyager.so/dashboard/billing](https://voyager.so/dashboard/billing). See [Plans and credits](/account/plans-and-credits). ## How the pieces fit | You want to… | What's involved | | - | - | | Ask for a cut of your own footage | Agent + files on your disk. No generation, no credits. | | Generate a 15-second teaser from an idea | Agent + a generation provider (your keys or Voyager credits). | | Use Voyager models instead of your own agent | Your Voyager plan, including Free. Chats use your plan's credits. | | Pick up a project next week | Open the project. Its chats, brief and files are all still there. | ## Next > [card] [Choose your setup](/get-started/choose-your-setup) > > Decide which agent to use and who pays for generated media. # Install on Linux Source: https://docs.voyager.so/get-started/install-linux Install Voyager on 64-bit Linux as an AppImage or a .deb package. When you're done, Voyager is installed and open on its welcome screen, ready for setup. > [!NOTE] > > **Before you start** > > * A 64-bit Intel or AMD PC running a desktop Linux distribution. Arm isn't supported. > * A **Secret Service keyring**, such as GNOME Keyring or KWallet, installed and unlocked. Voyager saves your sign-ins there. Most GNOME and KDE desktops have one already. > * A few features differ from the Mac: recording your screen, letting the agent use other apps and some creative-app features aren't available on Linux. For MP4 export, Voyager downloads one extra library itself (see below). See [Requirements](/get-started/requirements). > * Voyager is free to download. ## Choose a package | | AppImage | `.deb` | | - | - | - | | Works on | Most distributions | Debian, Ubuntu and their derivatives | | Updates | Updates itself from inside Voyager | Install each new version by hand | | Install | Make it executable and run it | Install with `apt` | If you're not sure, use the AppImage. ## Install Voyager > [tab] AppImage > > **1. Download the AppImage** > > Sign in at voyager.so, or create a free account, then go to **[Download](https://voyager.so/dashboard/download)** in your dashboard. Choose **Linux** (x64 · AppImage). Move it somewhere you'll keep it, such as `~/Applications`. Voyager updates this file in place, so don't leave it in a folder you clear out. > > **2. Make it executable** > > In a terminal, in the folder where you saved it: > > ```bash theme={"system"} > chmod +x Voyager-*.AppImage > ``` > > Or open the file's **Properties** in your file manager and allow it to run as a program. > > **3. Open Voyager** > > Double-click the AppImage, or run it from the terminal: > > ```bash theme={"system"} > ./Voyager-*.AppImage > ``` > [tab] .deb (Debian, Ubuntu) > > **1. Download the package** > > Sign in at voyager.so, or create a free account, then go to **[Download](https://voyager.so/dashboard/download)** in your dashboard. Choose **Linux** (x64 · .deb package). > > **2. Install it** > > In a terminal, in the folder where you saved it: > > ```bash theme={"system"} > sudo apt install ./Voyager-*.deb > ``` > > `apt` installs anything else Voyager needs, including the keyring library. > > **3. Open Voyager** > > Open **Voyager** from your applications menu, or run `voyager` in a terminal. ## Check it worked Voyager opens on its welcome screen with a **Set up** button. Clicking it starts setup, beginning with signing in to your Voyager account in your browser. The AppImage updates itself: new versions download in the background and install when you restart Voyager. With the `.deb`, download new versions from your [dashboard](https://voyager.so/dashboard/download) and install each one the same way. See [Updates](/help/updates). ## MP4 export on Linux Linux has no built-in MP4 (H.264) encoder, and Voyager can't include one. Instead, the first time it exports an MP4, Voyager downloads Cisco's OpenH264 library from Cisco. You don't need to install anything. To stop Voyager downloading and using it, turn off **Settings → General → Advanced → Video export → MP4 export on Linux**. If it's off, or the download fails, the agent offers WebM or image frames instead. WebM plays in browsers, most video players and most upload sites. ## If something went wrong > [accordion] The AppImage doesn't start > > AppImages need FUSE. Install your distribution's FUSE package (for example `libfuse2` or `fuse3`) and try again. Or start Voyager without FUSE: > > ```bash theme={"system"} > ./Voyager-*.AppImage --appimage-extract-and-run > ``` > [accordion] Sign-in fails and mentions your credential store or keyring > > Voyager couldn't save your sign-in. Make sure a Secret Service keyring such as GNOME Keyring or KWallet is installed, running and unlocked, and that you allow Voyager access when it asks. Then sign in again. > [accordion] "Automatic updates on Linux require running the AppImage build." > > You installed the `.deb`, which doesn't update itself. Install new versions by hand from your [dashboard](https://voyager.so/dashboard/download), or switch to the AppImage. > [accordion] "Voyager could not start its local server." > > Click **Try Again** first. If the message says your disk is full, free up some space, then try again. If it offers **Repair and Start**, click it: Voyager sets the damaged data aside and keeps everything it can read. If none of that works, [get help](/help/get-help). ## Next > [card] [Set up Voyager](/setup/overview) > > Sign in, connect your agent and finish the welcome steps. # Install on macOS Source: https://docs.voyager.so/get-started/install-macos Download Voyager for Mac, move it to Applications and open it for the first time. When you're done, Voyager is in your Applications folder and open on its welcome screen, ready for setup. > [!NOTE] > > **Before you start** > > * A Mac with Apple silicon (M1 or later) running **macOS 15 or later**. Check under → **About This Mac**. > * About 10 minutes, including setup. > * Voyager is free to download. See [Requirements](/get-started/requirements) for what each feature needs. ## Install Voyager **1. Download the installer** Sign in at voyager.so, or create a free account, then go to **[Download](https://voyager.so/dashboard/download)** in your dashboard. Choose **macOS** (Apple silicon · .dmg). **2. Open the disk image** Double-click the downloaded `.dmg`. A window opens with the Voyager icon and a shortcut to your Applications folder. ![The Voyager installer window, with the Voyager app icon on the left and an Applications folder shortcut on the right.](https://mintcdn.com/voyager/dzNfJ3ErXafJEG4z/images/screenshots/install-mac-dmg.light.png?fit=max\&auto=format\&n=dzNfJ3ErXafJEG4z\&q=85\&s=15783da1964997866f27e4884c527fc8) Drag the Voyager icon onto the Applications folder. **3. Drag Voyager to Applications** Drag the **Voyager** icon onto **Applications**. If an older Voyager is open, quit it first, then choose **Replace** when asked. **4. Eject the disk image** In Finder's sidebar, click the eject button next to **Voyager**. You can delete the `.dmg` file afterwards. **5. Open Voyager** Open your **Applications** folder and double-click **Voyager**. Open it from Applications, not from the disk image. The first time, macOS asks whether you want to open an app downloaded from the internet. Voyager is signed and notarized by Apple, so this is expected. Click **Open**. ![A macOS dialog saying Voyager is an app downloaded from the internet, with an Open button.](https://mintcdn.com/voyager/dzNfJ3ErXafJEG4z/images/screenshots/install-mac-first-open.light.png?fit=max\&auto=format\&n=dzNfJ3ErXafJEG4z\&q=85\&s=6a8c6a61558253abc5b319f4736af895) A normal first-launch confirmation. Click Open. ## Check it worked Voyager opens on its welcome screen with a **Set up** button. Clicking it starts setup, beginning with signing in to your Voyager account in your browser. ![Voyager's welcome screen with the Voyager wordmark, the line The open harness for creative work, a Set up button, and under it: Sign in or create a free Voyager account in your browser, then come back here.](https://mintcdn.com/voyager/yRytHenCA6FFAhzA/images/screenshots/setup-splash.light.png?fit=max\&auto=format\&n=yRytHenCA6FFAhzA\&q=85\&s=793c0ab32172e743a4394e4b4c0893ec) The welcome screen. Set up starts sign-in. Voyager updates itself. New versions download in the background, and install when you restart Voyager or the next time you quit and reopen it. See [Updates](/help/updates). ## If something went wrong > [accordion] macOS says Voyager can't be opened on this version > > Voyager needs macOS 15 or later. Update macOS in **System Settings → General → Software Update**, then open Voyager again. > [accordion] macOS says Voyager is damaged or can't be verified > > The download was probably interrupted or changed. Move Voyager from Applications to the Trash, download the installer again, and repeat the steps. Don't turn off macOS security checks to get around this. If it happens again, [contact support](/help/get-help) with the exact message and the file name you downloaded. > [accordion] macOS asks for your password to let Voyager use the Keychain > > Voyager saves your sign-ins in your macOS Keychain. Check that the request names Voyager, enter your Mac login password and choose **Always Allow**, so it doesn't ask again. > [accordion] "Voyager could not start its local server." > > Click **Try Again** first. If the message says your disk is full, free up some space, then try again. If it offers **Repair and Start**, click it: Voyager sets the damaged data aside and keeps everything it can read. If none of that works, [get help](/help/get-help). ## Next > [card] [Set up Voyager](/setup/overview) > > Sign in, connect your agent and finish the welcome steps. # Install on Windows Source: https://docs.voyager.so/get-started/install-windows Install Voyager on Windows 11, check Smart App Control, and get past a first-launch warning if Windows shows one. When you're done, Voyager is installed and open on its welcome screen, ready for setup. > [!NOTE] > > **Before you start** > > * A PC with **Windows 11** on a 64-bit Intel or AMD processor. Windows on Arm isn't supported. > * A few features differ from the Mac: recording your screen and footage search aren't available on Windows, and some creative apps work only in part. The agent can use other apps on your computer. See [Requirements](/get-started/requirements). > * Voyager for Windows is code signed. Voyager is free to download. ## Install Voyager **1. Check Smart App Control** Open **Windows Security → App & browser control → Smart App Control** and note whether it's **On**, **Evaluation** or **Off**. Usually there's nothing to do; if it's on, read [Smart App Control](#smart-app-control) below so you know what to look for. **2. Download the installer** Go to [voyager.so/download/windows](https://voyager.so/download/windows) and download the Windows installer (`.exe`). You can also sign in at voyager.so and use **Download** in your dashboard. **3. Run the installer** Open the downloaded `.exe`. If Windows shows **Windows protected your PC**, click **More info**, check that the app is Voyager, then click **Run anyway**. The installer installs Voyager for your Windows account and opens it. You don't need administrator rights. **4. Read the welcome screen** Voyager opens on its welcome screen. If Smart App Control is on or in evaluation, a notice under **Set up** says so, with a **Learn more** link. ## Smart App Control Smart App Control is a Windows 11 security feature that blocks apps and files it can't verify. It has three states: * **Off:** nothing blocks Voyager. * **On:** Windows checks every part of Voyager before it runs. Voyager for Windows is code signed so that Smart App Control can verify it. Older, unsigned versions were blocked in places, including sign-in, the terminal and media tools. * **Evaluation:** Windows is watching how you use your PC and may switch Smart App Control on by itself later. When Smart App Control is on or in evaluation, Voyager's welcome screen shows a notice under **Set up**. If Voyager works normally, you can carry on. If Windows still blocks part of Voyager, for example sign-in fails with **Windows Smart App Control blocked Voyager's credential storage component.**: 1. Update to the latest Voyager from [voyager.so/download/windows](https://voyager.so/download/windows) and try again. 2. If it's still blocked, the remaining option is to turn off Smart App Control in **Windows Security → App & browser control → Smart App Control**. It can't be turned off for just one app, and on some Windows versions turning it back on means reinstalling Windows, so it's your call. 3. Still stuck? [Get help](/help/get-help) and include the exact Windows message. ## Check it worked Voyager is open on its welcome screen with a **Set up** button. Under **Set up**, a line says to sign in or create a free Voyager account in your browser, then come back. Voyager is in your Start menu for next time. Voyager updates itself. New versions download in the background and install when you restart Voyager, or the next time you quit and reopen it. See [Updates](/help/updates). ## If something went wrong > [accordion] There's no Run anyway button > > Click **More info** first; **Run anyway** appears after it. If your PC is managed by an organization, its policy may not allow new apps. Ask your administrator. > [accordion] Sign-in fails: "Windows Smart App Control blocked Voyager's credential storage component." > > Smart App Control is blocking the part of Voyager that saves your sign-in. See [Smart App Control](#smart-app-control) above for what to do. > [accordion] Sign-in fails: "A Windows Application Control policy blocked Voyager's credential storage component." > > A policy on this PC, usually one your organization set, is blocking parts of Voyager. Ask your administrator whether Voyager can be allowed. > [accordion] "Voyager could not start its local server." > > Click **Try Again** first. If the message says your disk is full, free up some space, then try again. If it offers **Repair and Start**, click it: Voyager sets the damaged data aside and keeps everything it can read. If none of that works, [get help](/help/get-help). ## Next > [card] [Set up Voyager](/setup/overview) > > Sign in, connect your agent and finish the welcome steps. # Requirements Source: https://docs.voyager.so/get-started/requirements Which computers run Voyager, what's different on Windows and Linux, and which features need extra setup. Voyager runs on Macs with Apple silicon, Windows 11 and Linux. Most features work everywhere, and a few are Mac-only or work differently on Windows and Linux. Check the table below before you install. ## Supported computers | | macOS | Windows | Linux | | - | - | - | - | | **Version** | macOS 15 (Sequoia) or later | Windows 11 | A recent 64-bit desktop distribution | | **Processor** | Apple silicon (M1 or later) | 64-bit Intel or AMD (x64) | 64-bit Intel or AMD (x64) | | **Download** | `.dmg` | `.exe` installer | AppImage or `.deb` | | **Signed** | Signed and notarized by Apple | Code signed | Not signed | Not supported: Macs with Intel processors, Windows on Arm, and Linux on Arm. Hit a rough edge on any platform? Please [tell us](/help/get-help). ## What you don't need The Voyager download includes everything it needs to run, edit and assemble media. You don't need to install a programming language, a command-line tool, FFmpeg, Git or a separate video editor. Some things are separate and optional: * **Your agent's subscription or API key.** Claude or ChatGPT, if you use one. Setup walks you through installing and signing in to the matching tool. See [Choose your setup](/get-started/choose-your-setup). * **Creative apps** you want the agent to work in, like DaVinci Resolve, Premiere Pro or After Effects. You need your own copy and license. * **Local models** for features like footage search and voice input. On macOS and Linux, Voyager downloads its speech models in the background soon after you first open it, if your disk has room to spare. Other models download the first time you use the feature. You'll need an internet connection to sign in, chat with the agent and generate media. ## Features by platform | Feature | macOS | Windows | Linux | | - | - | - | - | | Chat, projects, files and previews | ✓ | ✓ | ✓ | | Generate images, video and audio | ✓ | ✓ | ✓ | | Edit and assemble video | ✓ | ✓ | ✓ | | Export MP4 (H.264) video | ✓ | ✓ | ✓ (Voyager downloads Cisco's OpenH264 the first time) | | Review videos with comments | ✓ | ✓ | ✓ | | Voice input (dictation) | ✓ | ✓ (processor must support AVX2) | ✓ (AVX2 processor, glibc 2.34 or later) | | Record your screen, camera and microphone | ✓ | — | — | | Let the agent use other apps on your computer | ✓ | ✓ | — | | Search your footage by what's said or shown | ✓ | — | ✓ | | Find your installed creative apps automatically | ✓ | Some apps, such as Blender | Some apps, such as Blender | | Work in DaVinci Resolve | ✓ | DaVinci Resolve Studio only | Partial | | Work in After Effects | ✓ | ✓ | — | | Work in Illustrator | ✓ | — | — | | Work in Ableton Live | ✓ | ✓ (you export the audio from Live) | — | | Work in Photoshop | ✓ | — | — | | Work in Premiere Pro | ✓ | Untested | — | | In-app updates | ✓ | ✓ | AppImage only (the `.deb` doesn't update itself) | | **Settings → Advanced → Permissions** page | ✓ | — | — | > [!NOTE] > > On Windows "N" editions, MP4 export needs Microsoft's Media Feature Pack. On Linux, Voyager can't include an MP4 encoder, so it downloads Cisco's OpenH264 from Cisco the first time it exports MP4. To stop this, turn off **Settings → General → Advanced → Video export → MP4 export on Linux**. The agent then delivers WebM or image frames instead. ## Storage space Voyager itself is a normal-sized app. Plan for extra space for: * **Your projects.** Generated video and renders add up. Each project's files live in its own folder. * **Speech models**, for transcription and searching what's said. On macOS and Linux they download in the background after you first open Voyager, unless that would leave your disk nearly full. * **Footage search** models for visuals, downloaded the first time you turn it on: a few gigabytes. * **Voice input** model, downloaded the first time you use the mic if it needs one of its own. ## Platform notes > [tab] macOS > > * Voyager needs **macOS 15 or later**. On an older version, macOS won't open it. > * Recording and letting the agent control other apps need macOS permissions, such as **Screen & System Audio Recording** and **Accessibility**. Voyager asks only when you use those features. See [Allow computer control](/guides/computer-control). > * Voyager saves sign-ins in your macOS Keychain. > [tab] Windows > > * Voyager for Windows is code signed. If Windows still shows a warning the first time you open the installer, see [Install on Windows](/get-started/install-windows). > * If **Smart App Control** is on, check [Smart App Control](/get-started/install-windows#smart-app-control) before you install. > * Computer control works without the Mac permission steps. See [Allow computer control](/guides/computer-control) for its controls and limits. > * Voyager saves sign-ins in Windows Credential Manager. > [tab] Linux > > * Voyager saves sign-ins in your system keyring through the Secret Service, such as GNOME Keyring or KWallet. It must be installed and unlocked. > * The `.deb` works on Debian, Ubuntu and their derivatives. The AppImage runs on most other distributions. > * Only the AppImage updates itself. With the `.deb`, install each new version by hand. ## Next > [card] [Install on macOS](/get-started/install-macos) > [card] [Install on Windows](/get-started/install-windows) > [card] [Install on Linux](/get-started/install-linux) # Control approvals and spending Source: https://docs.voyager.so/guides/approvals-and-spending Choose how Voyager answers questions, set spending preferences, and review requests for permission. Choose how much Voyager should decide on its own, and when it should wait for you. Creative questions, spending preferences and permission to run actions have separate controls. Choosing **Always ask** for creative questions does not change the agent's permission mode. > [!WARNING] > > **Don't ask** takes the agent's recommended answer immediately, including approval for paid > generation above your spend limit. The agent also picks the AI video model without waiting for > you. Choose **Wait, then go ahead** or **Always ask** when you want Voyager to wait before exceeding that > limit. In every mode, an element of a real person or of someone else's character (a brand mascot, > a film or game character) waits for you to give permission in the Elements panel. ## Choose how questions are answered **1. Open the questions control** Below the chat's message box, at its right, click the questions control. It shows the current mode (**Wait, then go ahead** by default). Under **When Voyager has a question**, choose a mode. | Mode | What happens | | - | - | | **Don't ask** | Goes with its suggestion right away, including answers that approve paid generation above the spend limit. The agent picks the AI video model. A question without a recommendation is left to the agent to decide. | | **Wait, then go ahead** | Recommended, and the default. Counts down (60 seconds by default), then closes the question unanswered so the agent carries on; click **Choose now** to send the recommended answer instead. Spend above your generation limit waits for you. | | **Always ask** | Waits for your answer every time. | The same menu also has a **Commands & files** row for the permission mode, a **This conversation** list of what you allowed for this chat (click **Revoke** to take one back), and **Change defaults in Settings…**. The default question mode is **Settings → General → When the agent asks you something**. In **Wait, then go ahead**, a question without a recommended answer still counts down when its first option is a plain choice, and **Choose now** picks that option. It waits for you when it is a review or approval question, when the answer needs you to type something, or when it asks to approve spend or a slow media model. Choosing **Don't ask** first asks you to confirm: **Let Voyager decide on its own?** Click **Don't ask** to switch, or **Cancel** to keep the current mode. ![The Let Voyager decide on its own? dialog with Cancel and Don't ask buttons.](https://mintcdn.com/voyager/193F9fREXJhp2PWx/images/screenshots/questions-control-dont-ask-confirm.light.png?fit=max\&auto=format\&n=193F9fREXJhp2PWx\&q=85\&s=6b84987558f410a067c09f348facbfb3) Voyager checks before it stops asking you questions in this chat. ![The questions menu showing Always ask, Wait, then go ahead (Recommended) and Don't ask with their descriptions.](https://mintcdn.com/voyager/193F9fREXJhp2PWx/images/screenshots/approvals-question-modes.light.png?fit=max\&auto=format\&n=193F9fREXJhp2PWx\&q=85\&s=4eb2ff358ca48cdf57cb09fe31cb0424) Choose the mode for this chat before starting work that may spend money. **2. Set your spending and rendering preferences** Open **Settings → Creative → Limits**. * **Ask before spending more than** tells the agent when to ask about a paid generation batch. It starts at $5. Set it to $0 to ask before any paid generation in **Wait, then go ahead** or **Always ask**. * **Ask before renders longer than** tells the agent when to ask about a local render expected to take longer. It starts at 10 minutes. Voyager asks before spending more than your limit (in **Wait, then go ahead** and **Always ask**). The spend limit is a preference the agent follows, not a hard spending cap or an account balance. An estimate is not a guaranteed final charge. ![Creative settings showing Ask before renders longer than and Ask before spending more than under Limits.](https://mintcdn.com/voyager/dzNfJ3ErXafJEG4z/images/screenshots/approvals-limits.light.png?fit=max\&auto=format\&n=dzNfJ3ErXafJEG4z\&q=85\&s=123c64177d7d449dcf93c77e74059e72) These limits tell the agent when to ask before a paid batch or a long local render. **3. Read the question before continuing** Check what the recommendation will approve. For generated video, this can include the stills, the shots to animate, and an estimated cost and time. In **Wait, then go ahead**, click **Wait** to stop the countdown or **Choose now** to accept the recommendation immediately. You can choose another option instead. A question asking to approve paid work without an estimate also waits for you. Story and breakdown review cards count down too. When the countdown ends they are approved as shown; click **Approve now** to approve sooner, or **Wait** to keep the card open. Cards that lead to paid generation still wait for you. ## Know which account pays Your selected chat account pays for the agent's chat usage. Generated images, video, music and voice use a generation account separately. Your Claude subscription does not cover those media charges. ChatGPT covers them only for images, and only when you set up **Images through ChatGPT** as a generation provider; see [generation providers](/account/generation-providers). You can use your own Claude or ChatGPT and your own media keys after signing in and finishing setup. A paid Voyager plan is optional. For Voyager credits and plan options, see [plans and credits](/account/plans-and-credits) and [current pricing](https://voyager.so/pricing). > [!WARNING] > > Fallback is on by default. If a generation provider is out of credits, rejects its sign-in or is > down, Voyager tries the next one in your list. That may bill a different account. It may also > adjust settings slightly to match what the next provider supports. To review the order or turn fallback off, open **Apps & Models → Providers** and click **Image, video and voice order**. In that dialog, the switch **If one can't finish, try the next provider** controls fallback. You can also ask the agent to pin a provider for a particular job, for example: “Use only my FAL account for this generation; stop if it cannot run.” See [generation providers](/account/generation-providers). ## Choose permissions for commands and file changes Open **Settings → General → How much the agent can do on its own**, or choose a mode under **Commands & files** in the questions control below the message box. Either way you change the default: in a project, it applies to every chat in that project; otherwise to every chat. Chats pick it up from their next message. | Mode | What to expect | | - | - | | **Full access** | Runs commands and edits files without asking. Recommended, and the default. | | **Files only** | Edits files; asks before commands. | | **Ask if unusual** | Asks only about unusual actions. Supported agents approve routine actions; others still ask. | | **Ask every step** | Asks before every command and file edit; slower. | These modes concern actions the agent takes. They do not replace the question mode, your spending preferences, or your computer's own permissions. On macOS, **Settings → Advanced → Permissions** is a different page for access such as screen recording; see [Allow computer control](/guides/computer-control). When an approval card appears, read the action. **Allow once** permits this one action; **Allow for this chat** permits it for the rest of the chat; **Deny** refuses it and the agent carries on without it. **More approval options** (**⋯**) has **Deny and stop**, which refuses and stops the turn. The choices can vary by agent. What you allowed for the chat is listed under **This conversation** in the questions control, where **Revoke** takes it back. ![An approval card above the message box with Deny, Allow for this chat and Allow once buttons and a More approval options menu.](https://mintcdn.com/voyager/193F9fREXJhp2PWx/images/screenshots/approvals-approval-card.light.png?fit=max\&auto=format\&n=193F9fREXJhp2PWx\&q=85\&s=102c60d41ca4eecd4c158fc551f271fb) Allow once is the main button; the ⋯ menu holds Deny and stop. ## Check your settings Return to the chat and confirm the mode shown on the questions control. Check your saved limits before starting a paid batch. If you want to review every creative choice and paid-work question yourself, use **Always ask**. ## Common problems > [accordion] Voyager answered before I could review the question > > Check for **Don't ask**, or a **Wait, then go ahead** countdown that ran out. Switch to **Always ask** for > future questions. Changing the mode does not undo work already approved or submitted. > [accordion] My spend limit did not stop Don't ask > > **Don't ask** immediately accepts the recommended answer, including above-limit spending. Switch > to **Wait, then go ahead** or **Always ask**. The spend limit guides when the agent asks; it is not a > hard account cap. > [accordion] I chose Always ask, but file edits did not ask for permission > > **Always ask** controls question cards. To request approval for commands and file changes, > choose **Ask every step** under **Commands & files** in the questions control, or under **Settings → > General → How much the agent can do on its own**. > [accordion] The job used a different account than I expected > > Open **Apps & Models → Providers → Image, video and voice order** to check the order and the > fallback switch. Turn fallback off or pin the intended provider for future work. Ask the agent to identify which account > handled the existing job before trying it again. > [card] [Generate images and video](/guides/generate-images-and-video) > > Review the look and cost before animating shots. > [card] [Generation problems](/help/generation-problems) > > Handle failed, queued or uncertain work without paying twice. # Organize chats and projects Source: https://docs.voyager.so/guides/chats-and-projects Create a project, keep related chats together, and share a brief, brand and files across your work. Use a chat to work through a request. Use a project to keep related chats, files and finished outputs together. For example, a launch project might hold one chat for a teaser, another for product images, and a third for social cutdowns. They share the same project folder, brief and brand kit. You can start with **New chat** without creating a project. Voyager gives that chat its own folder on your first send, named after the chat's title, and lists it under **Recents**. ## Create a project **1. Open the project dialog** In the sidebar, hover **Projects** and click **Add project**. You can also open the project chooser above a new chat and select **New project**, or click **New project** on the Projects page. **2. Name the work** Fill in **Name**. Use **What are you making?** for a short brief: the outcome, audience, look and anything to avoid. If you have a brand kit, choose it under **Brand kit**. Voyager copies the kit's colors, fonts and logos into the project. Voyager makes a new folder for the project. To work in a folder you already have, click **Save in a specific folder…** and choose it. **Change** picks another folder, and **Use default** goes back to a new one. Click **Create**. ![The New project dialog with Name, What are you making? and Brand kit filled in for a launch project, and the Save in a specific folder link below.](https://mintcdn.com/voyager/193F9fREXJhp2PWx/images/screenshots/first-video-new-project.light.png?fit=max\&auto=format\&n=193F9fREXJhp2PWx\&q=85\&s=eafbf666a4f3bc4b2eda913f09894b3a) The name, brief and optional brand kit give the project its starting context. **3. Start the first chat** Send a request from the project page's message box. Voyager opens a chat in that project. To start another, open the project's **⋯** menu in the sidebar and choose **New chat**, or pick the project in the chooser above a new chat. **New chat** opens in the project you were last working in. Continue the same chat for revisions to its existing work. ## Give each chat the same brief Click the project name in the sidebar to open its page. In the **Brief** row, click **Add** or **Edit** and write what every chat should know. ```text theme={"system"} We're making a launch campaign for Northwind, a small outdoor brand. Audience: people planning their first weekend camping trip. Keep the tone welcoming and practical. Use the project brand kit. Avoid extreme-sports imagery and unverified product claims. ``` Every chat in the project reads the brief when it starts. Keep piece-specific instructions, such as one video's timing, in that chat's request. ![A project page with its title, Play, a message box, Outputs, and the Project rows Brief, References, Brand kit and Memory.](https://mintcdn.com/voyager/193F9fREXJhp2PWx/images/screenshots/projects-page.light.png?fit=max\&auto=format\&n=193F9fREXJhp2PWx\&q=85\&s=434a9119a5db3e4b9e21bb58ca8f6110) The project page keeps finished work, chats and the shared details in one place. The other rows on the project page: | Row | What it holds | | - | - | | **References** | Logos, footage, scripts and examples the agent can use in every chat in this project. It won't change or delete them. | | **Brand kit** | The project's colors, fonts and logos. | | **Memory** | Decisions the agent remembers for this project. Click **View** to read them or **Forget** one. | | **Editors** | The apps the agent uses for this project's work. | | **Storage** | How much space the project folder uses. **Clean up renders** moves older versions nothing uses to the Trash and keeps the newest of each. | The top of the page shows the files the agent has delivered, with their versions, and the project's chats. ## See all your projects Click **Projects** in the sidebar to see every project as a card with its latest output, a line of its brief, and how many chats and outputs it holds. Switch between **Grid view** and **List view**, sort the projects, or start a **New project**. ![The Projects page with project cards in a grid, each with a recent output and its brief when it has them, and counts of chats and outputs.](https://mintcdn.com/voyager/193F9fREXJhp2PWx/images/screenshots/guides-projects-grid.light.png?fit=max\&auto=format\&n=193F9fREXJhp2PWx\&q=85\&s=8f080a1b105be8c428815d167a3f9823) The Projects page shows every project at a glance. Click a project in the sidebar to open its page; click it again to show or hide its chats. Its **⋯** menu has **New chat**, **Pin project**, **Rename**, **Copy Path**, **Project settings** and **Archive**. ## Find and organize chats Click **Search** at the top of the sidebar, or press ⌘ K (Ctrl K), to search everything. Tabs narrow the results to **Chats**, **Projects** or **Routines**. Expand a project to see its chats; **Recents** holds chats without a project. Right-click a chat for its actions: | Action | When to use it | | - | - | | **Pin** | Keep a chat easy to reach under **Pinned**. | | **Rename** | Give it a more useful name. | | **Move to project** | Put the chat into the right project. Choose **No project** to take it out of one. | | **Mark as unread** | Come back to it later. | | **More → Snooze** | Put it aside until the chosen time; look under **Snoozed** to find it. | | **More** | Also has **Regenerate title**, **Copy path** and **Copy chat ID**. | | **Archive** | Remove it from the sidebar while keeping the chat in **Settings → Advanced → Archived chats**. | | **Delete** | Remove the chat and its history for good. | > [!WARNING] > > **Delete** removes the chat and its history for good. To hide a chat but keep it, use **Archive**; you can restore it from **Settings → Advanced → Archived chats**. To start a new chat outside a project, click the **X** beside the project's name above the message box. **New chat** then stays outside any project until you open one again. For a chat outside a project, you can rename its folder: open the chat's project panel and use **Rename folder**. Your files stay connected to the chat. **Settings → Appearance → Sidebar** lets you show project and chat icons, and turn **Detailed cards** (the latest reply under each chat title) on or off. ## Use a private chat A private chat stays out of your chat history and search, and doesn't use or update memory. Use it for a quick question you don't want to keep. Click the ghost button at the top of a new chat (**Start a private chat**), or choose **New private chat** from ⌘ K (Ctrl K). The message box shows a dashed outline while you're in one. > [!WARNING] > > A private chat is deleted when you leave it. Files it made stay in its folder, but the conversation is gone. Private chats can't be pinned or archived. ## Check the result Your project should appear in **Projects**, with its chats underneath. Open its page to check the **Brief** and delivered outputs. Use the page's **⋯ → Copy folder path** when you need the project folder's location. ## Common problems > [accordion] My chat is in Recents instead of the project > > Right-click it, choose **Move to project**, and select the project. When starting the next chat, check the project chooser above the message box before sending. > [accordion] Renaming the project did not rename its folder > > Renaming changes the project name in Voyager. The folder stays where it is. Use **Copy folder path** to find it. > [accordion] The output is missing from the project page > > Ask the agent to present the finished file as an output. **Files** can contain drafts and working files that don't appear among the project's outputs. > [accordion] I want to put a project away without losing it > > Open the project's **⋯** menu and choose **Project settings → Archive project**, or use **⋯ → Archive project** on the project page. This hides the project from the sidebar and keeps its chats and files. Restore it from **Settings → Advanced → Archived chats**. > [card] [Write a request](/guides/write-a-request) > > Turn the project brief into a concrete first task. > [card] [Files and previews](/guides/files-and-previews) > > Browse working files and delivered versions. # Choose models and apps Source: https://docs.voyager.so/guides/choose-models-and-apps Pick which image, video and audio models and which creative apps Voyager uses for a chat, a project or every project. Voyager picks a model for each image, video or sound it makes, and an app for each kind of job, such as motion graphics or video editing. When you have a favorite, set it once and Voyager uses it whenever a chat doesn't name one. > [!NOTE] > > **Before you start:** you don't have to choose anything. Every choice starts on **Auto**: Voyager picks, using your subscriptions before credits. A model you choose still needs a provider that can run it; see [Choose your generation providers](/account/generation-providers). ## Choose for a chat **1. Open Preferred models and apps** In the message box, click the button just before the agent model picker (its tooltip reads **Preferred creative apps and media models**). It shows small media icons while everything is on **Auto**, and the marks of your choices once you set some. **2. Pick a model or app** Under **Models**, click a kind: **Image**, **Image edit**, **Video**, **Voice**, **Music**, **Sound effects** or **3D**. Under **Apps**, click a job: **Motion graphics**, **Video editing**, **Design**, **Slides**, **3D**, **Music** or **Games**. Search the list and choose one. Anything you leave alone stays on **Auto**. **3. Keep it for the project, if you like** Changes apply to this chat and your next new chat. To make them the project's default, click **Save as … default** (it shows your project's name). ![The Preferred models and apps panel above the message box, with Models and Apps columns, rows set to Auto, a Choices for menu set to This chat, Reset, Save as project default and Manage in Apps & Models.](https://mintcdn.com/voyager/193F9fREXJhp2PWx/images/screenshots/composer-preferences-panel.light.png?fit=max\&auto=format\&n=193F9fREXJhp2PWx\&q=85\&s=899b5be91182c206bd5be22e8d9c5cf9) Preferred models and apps: one row per kind of model and per kind of app, with the scope at the top. ## Choose for a project or every project Use the menu at the top of the panel to change whose choices you're editing: | Choice | What it changes | | - | - | | **This chat** | This chat, and the starting choices for your new chats. | | **This project** | The project's default, used by new chats in this project. Shown when the chat is in a project. | | **All projects** | The default for every project that doesn't set its own. | Each chat keeps its own copy of the choices it started with, so changing a project's or the All projects defaults affects new chats, not ones you already have. **Reset** goes back one level: a chat goes back to its project's choices, a project to the All projects settings, and All projects to **Auto** everywhere. You can name a model or app in your message at any time. That wins for that request. ## Manage them in Apps & Models Click **Manage in Apps & Models**, or open **Apps & Models** in the sidebar: * **Apps & Models → Models → Default models**: the model Voyager uses when a chat doesn't name one, for **All projects** or a single project. * **Apps & Models → Apps → Preferred apps**: the app new chats start with, with the same scope choice. ![The Apps & Models page on the Models tab, with the Default models popup open showing a row per kind of model, a scope menu set to All projects and Reset.](https://mintcdn.com/voyager/193F9fREXJhp2PWx/images/screenshots/guides-connectors-preferred-models.light.png?fit=max\&auto=format\&n=193F9fREXJhp2PWx\&q=85\&s=f8bbfa9b856206e414ed55db51e547ce) Apps & Models → Models, with Default models open. To try a model on its own before you ask for it in a chat, click **Try** on its row in **Apps & Models → Models**, or **Open playground** at the top of the tab. See [Model playground](/guides/model-playground). ## Check the result The button in the message box shows the marks of the models and apps you chose. In the panel, a row changed only in this chat reads **Changed in this chat**, and a row that comes from the project reads **… default** with the project's name. ## Common problems > [accordion] A model says “Connect … to use” or “Sign in to … to use” > > No provider you've set up can run that model yet. Connect or sign in to the provider in **Apps & Models → Providers**, or leave the row on **Auto**. > [accordion] An app says “Install … to use” > > The app isn't on this computer. Install it, or choose another app or **Auto**. > [accordion] A changed default didn't reach my chat > > A new chat starts from your latest chat choices, or from its project's or the All projects defaults if you haven't made any. Changing a default doesn't change chats that already exist. To change an existing chat, set it under **This chat** or click **Reset**. ## Related * [Model playground](/guides/model-playground): run an image, video, voice, music, sound or 3D model directly. * [Choose your generation providers](/account/generation-providers): which provider Voyager tries first and what happens when one can't finish. * [Write a useful request](/guides/write-a-request) * [Connect your creative apps](/setup/creative-apps) # Allow computer control Source: https://docs.voyager.so/guides/computer-control Let the agent click, type and see your screen in your other apps: grant the macOS permissions when the chat asks, and control or turn off computer control on macOS and Windows. With **computer control**, the agent works in your other apps the way you would: it clicks, types and looks at your screen. It only does this when you ask it to. This page shows how to allow it on a Mac, how it works on Windows, and how to stop or turn it off. ## What you need * **macOS or Windows.** Computer control isn't available on Linux, and its setting doesn't appear there. See [Requirements](/get-started/requirements). * **On a Mac:** two macOS permissions, **Accessibility** and **Screen & System Audio Recording**. Voyager asks for them in the chat the first time the agent needs them, not during setup. * **On Windows:** nothing extra. Apps running as administrator can't be controlled. * An agent that supports it, such as Claude or ChatGPT. If yours doesn't, the chat says so. ## Allow computer control on a Mac | Permission | What it lets Voyager do | | - | - | | **Accessibility** | Lets the agent click and type in your apps when you ask. | | **Screen & System Audio Recording** | Lets the agent see your screen. | The first time the agent needs computer control, a card titled **Allow computer control** appears in that chat, above the message box: "To work in your other apps, the agent needs these macOS permissions. It only uses them when you ask." Making a screen recording asks for its own access when you start one. **1. Allow Accessibility** Next to **Accessibility**, click **Allow**. macOS asks whether Voyager may control your computer and opens **System Settings → Privacy & Security → Accessibility**, and a small Voyager panel appears that says **↑ Drag Voyager into the list above**. If Voyager is already in the list, turn it on. If it isn't, drag the Voyager icon from the panel into the list, then turn it on. macOS may ask for your password. ![macOS System Settings open at Accessibility. Below the window, a small Voyager panel reads ↑ Drag Voyager into the list above, with a draggable Voyager icon.](https://mintcdn.com/voyager/dzNfJ3ErXafJEG4z/images/screenshots/setup-mac-permission-helper.light.png?fit=max\&auto=format\&n=dzNfJ3ErXafJEG4z\&q=85\&s=41bd34abfe0dd887393783cb44e2ca49) Voyager's helper panel. Drag the icon into the list in System Settings. **2. Allow Screen & System Audio Recording** Back in Voyager, next to **Screen & System Audio Recording**, click **Allow**. The first time, macOS asks to let Voyager record the screen and adds Voyager to the list; turn it on, or drag it in from the helper panel. > [!WARNING] > > macOS only applies Screen Recording after Voyager restarts. When macOS offers **Quit & Reopen**, choose it, or quit Voyager yourself and open it again. Voyager reopens on the same chat, with the card showing what's allowed, so nothing is lost. **3. Ask the agent to try again** Each row you granted shows **Allowed** with a check; Voyager checks every couple of seconds, so you don't need to refresh. Once both are allowed, the card says **Computer control is ready. Ask the agent to try again.** Click **Done** and ask the agent to carry on. Not ready? Click **Not now**. The chat asks again the next time the agent needs computer control. You can also grant or remove these at any time in **Settings → Advanced → Permissions**, which covers the camera, microphone, automation and file access Voyager may ask for later too. ## Computer control on Windows Computer control works on Windows without the Mac permission steps. Agents select and switch windows themselves, without asking for approval each time. Apps running as administrator can't be controlled. ## Watch, pause or stop While the agent controls an app, a bar in the chat names the app and shows **Pause** and **Stop**. Use them at any time. * **Visible cursor** uses your real mouse and keyboard. If you use the keyboard or mouse yourself, the agent stops and the chat says **Computer control paused**. Click **Resume**, then tell the agent to continue. * In the background mode, the agent works in the selected window without moving your cursor. Some actions need **Visible cursor**. ## Turn computer control off Computer control is on by default. To turn it off, open **Settings → Advanced → Labs** and switch off **Control other apps** under **Computer use**. Labs features are experimental. On a Mac, the same section shows whether Accessibility and Screen Recording are granted, with buttons to open each in System Settings. ## Check it worked * On a Mac, the **Allow computer control** card shows **Allowed** for both permissions. * When you ask the agent to work in another app, the computer-control bar appears in the chat with that app's name. ## If something went wrong > [accordion] “Could not open System Settings. Open Privacy & Security yourself.” > > Open **System Settings**, go to **Privacy & Security**, then **Accessibility** or **Screen & System Audio Recording**, and turn on Voyager there. > [accordion] I allowed Screen Recording, but Voyager still can't see my screen > > Quit Voyager completely (choose **Quit Voyager** from the Voyager menu, or hold ⌘ Q) and open it again. macOS only applies this permission after a restart. > > If Voyager is switched on in **Screen & System Audio Recording** but still can't see your screen after it reopens, macOS is holding an old entry, often one left by an earlier copy of Voyager. Restarting again won't fix it. Instead, in System Settings, select **Voyager** in that list and click **−** to remove it. Then click **+**, choose **Voyager** in your Applications folder, switch it on, and quit and reopen Voyager. > > If it still can't see your screen after that, run `tccutil reset ScreenCapture design.moda.voyager` in Terminal, then quit and reopen Voyager and allow Screen Recording when it asks. Still stuck? Use **Send feedback**. > [accordion] Voyager isn't in the list and dragging doesn't work > > Click the **+** button under the list, choose **Voyager** in your Applications folder, and turn it on. Make sure it's the copy of Voyager in Applications, not one still on the installer disk image. > [accordion] The agent can't control an app on Windows > > The app may be running as administrator. Reopen it normally, then ask the agent to try again. ## Related > [card] [Approvals and spending](/guides/approvals-and-spending) > > Choose how much the agent does on its own. > [card] [Privacy](/help/privacy) > > What Voyager keeps on your computer and what it sends. # Computers, phones and cloud GPUs Source: https://docs.voyager.so/guides/computers-and-cloud-gpus Use Voyager from your phone or a browser, keep work going on a cloud computer, and let the agent borrow a cloud GPU for heavy renders. Voyager runs on your computer, but your work doesn't have to stop there. You can: * **Use Voyager from your phone or another browser**, talking to the Voyager on your computer. * **Add a cloud computer**: your own computer in the cloud, running Voyager, that keeps working when your laptop is closed. * **Use Cloud GPUs**: let the agent borrow a powerful GPU for a heavy render, simulation or export, then hand it back. All three are in **Settings → Devices & sharing**, except Cloud GPUs, which are in **Settings → Creative**. > [!NOTE] > > **Before you start:** sign in to your Voyager account. Each feature needs a paid plan: > > | Feature | Plans | > | - | - | > | Cloud computer | Starter and up | > | Cloud GPUs | Starter and up; higher plans can use more GPUs at once | > | Phone and browser access, and reaching your other computers | Creator and up | > > On a plan that doesn't include a feature, Voyager shows an **Upgrade** button instead. See [voyager.so/pricing](https://voyager.so/pricing) for plans. Cloud computers and Cloud GPUs use your plan's Voyager credits while they run. > [!TIP] > > If **Devices & sharing** shows **Upgrade your chats to use other devices**, click **Upgrade chats**. It's a quick one-time upgrade: Voyager restarts once to move your chat history. ## Use Voyager from your phone or a browser **1. Turn it on** On the computer running Voyager, open **Settings → Devices & sharing** and turn on **Use Voyager from another device**. **2. Choose how other devices reach this computer** Under **How other devices reach this computer**, choose **Works anywhere** to connect from any Wi‑Fi or mobile data through a private link, or **Home Wi‑Fi only** to allow only a phone on the same Wi‑Fi. **3. Connect your phone** With **Works anywhere**, scan the code with your phone's camera, or open **app.voyager.so** in any browser. Sign in with your Voyager account, then choose this computer. With **Home Wi‑Fi only**, click **Show a code for your phone** and scan it with your phone on the same Wi‑Fi. **4. Get alerts, if you like** On your phone, turn on **Get alerts on this phone** in **Settings → Devices & sharing** to hear when a chat needs you. On an iPhone, first tap **Share**, then **Add to Home Screen**, and open Voyager from there. Your computer needs to be on and running Voyager for your phone to reach it. Turn on **Keep this computer awake while a device is connected** to stop it sleeping while you work from your phone. **Ask on this computer before a new device connects** and **Tell me when a device connects** let you approve and watch new devices. Every phone and browser that signed in is listed under **Connected devices**. Click **Remove** to sign one out. If you use Voyager on more than one computer with the same account, **Your other computers** lists them, and your phone at app.voyager.so shows all of them. ## Add a cloud computer A cloud computer is a computer in the cloud that runs Voyager for you. Work keeps going when your own computer is closed or asleep, with more room for big projects. It sleeps when you're not using it and wakes in a minute or two. **1. Start adding one** Open **Settings → Devices & sharing** and click **Add cloud computer** under **Cloud computer**. You can also choose **Add a cloud computer** in the computer menu below the message box on a new chat. **2. Choose its settings** Give it a **Name** and pick a **Size**; tick **Add a graphics card** if you need one. Set **Sleep when idle** and, if you like, a monthly **Spending limit** in credits. Each size shows its credits an hour. You can change the size later; your files and chats stay. **3. Create it** Click **Create cloud computer**. Then choose **Set up providers**: the Voyager model is ready straight away, and you can sign in with your Claude or ChatGPT plan, use an API key, or copy keys from this computer. Click **Skip for now** or **Done** when you're finished. **4. Move a project onto it, if you like** Pick a project to move now, or later from the project's menu in the sidebar with **Move to cloud computer…**. Moving a project starts from the desktop app. Your cloud computer keeps itself up to date. If the Voyager app you're using needs an update to work with it, the chat shows an **Update** button. ### Run a chat on your cloud computer On a new chat, click the computer menu below the message box (**Run this chat on**) and choose your cloud computer instead of **This computer**. If it's asleep, Voyager asks before waking it, because waking starts billing. Inside a project, work runs wherever the project is. If you have a cloud computer and open a chat whose computer is offline, for example from your phone while your laptop is closed, the chat offers **Continue on cloud computer**. That starts a new chat on your cloud computer with the conversation. The files stay on the original computer until it's back. ### Control what it costs In **Settings → Devices & sharing → Cloud computer** you can see **This month**'s spending, **Sleep now** or **Wake** it, **Change size**, set **Sleep when idle** and a **Spending limit**, and see **Spending alerts** at 50, 75 and 90% of your monthly credits. It comes out of your plan's credits, like everything else. **Delete…** removes it. ## Let the agent use Cloud GPUs For heavy work, such as a long Blender render, a simulation or work that needs a CUDA GPU, the agent can start a cloud GPU, run the job, bring the results back and release the GPU. 1. Open **Settings → Creative** and find **Cloud GPUs**. 2. Choose when to use them: **Ask** (the agent asks first, with the time and credits), **Always for heavy work**, or **Never** (all work stays on your computer). 3. Choose how many GPUs one task may use, up to your plan's limit, or let the agent ask. The same choice applies on all your computers. You can also flip **Let the agent use Cloud GPUs** in the computer menu below the message box on a new chat. While a GPU is working, its card in the chat shows what it's doing and whether it's still billing. Want to use a cloud GPU outside the app, from a terminal or a coding agent like Claude Code or Codex? See [Cloud machines](/api/machines/overview), including [rendering with Vork](/api/machines/vork). ## Common problems > [accordion] “Cloud computers aren't available on your account right now” > > Cloud computers need a paid plan (Starter and up) and a seat on it. Check that you're signed in with the account that has your plan, and, on a Team, that you have a seat. See [voyager.so/pricing](https://voyager.so/pricing). If it still shows, contact support with **Send feedback** in the app. > [accordion] My phone can't reach my computer > > Make sure the computer is on, awake and running Voyager, and that **Use Voyager from another device** is on. With **Home Wi‑Fi only**, the phone must be on the same Wi‑Fi; choose **Works anywhere** to connect from elsewhere. > [accordion] The chat asks me to update Voyager to use my cloud computer > > Your cloud computer is on a newer version than this app. Click **Update**, then restart Voyager when it's ready. > [accordion] Heavy work runs on my computer instead of a Cloud GPU > > Check **Settings → Creative → Cloud GPUs** isn't set to **Never**, and that your plan includes Cloud GPUs. On a plan without them, heavy work runs on your computer until you upgrade. ## Related * [Plans and credits](/account/plans-and-credits) * [Approvals and spending](/guides/approvals-and-spending) * [Routines and activity](/guides/routines-and-activity) * [Cloud machines from a terminal or agent](/api/machines/overview) # Edit your footage Source: https://docs.voyager.so/guides/edit-footage Turn existing clips and recordings into a finished edit with trims, captions, reframing and review. Give Voyager your clips and an editing brief to make highlights, remove pauses, add captions or create a shorter cut for another format. You need a connected chat account and footage available on your computer. Voyager can make local edits without a separate video editor. If you want to use Resolve, Premiere Pro or another supported app, [set it up](/setup/creative-apps) and name it in your request. Available integrations differ by [platform](/get-started/requirements). Local editing with existing assets does not require media credits. Chat usage still applies. Generated voice, music, replacement footage or hosted transcription may cost money; ask for local processing if that is a requirement. ## Make an edit **1. Put the footage within reach** Create or open a [project](/guides/chats-and-projects) for the edit. Keep a copy of the original footage and place the working clips in the project folder. To add a clip, use the round **+** below the message box, then **Upload or add files**, or **Add folder** for a whole folder. For long recordings, keep them in the project folder and reference them with `@`, or right-click a file in **Files** and choose **Add to chat**. **2. Say what to keep and what to change** Name the source files, target length, audience and shape. Include the important quotes or moments and any material to leave out. ```text theme={"system"} Turn interview.mp4 into a 30-second vertical highlight. Use the section where Maya explains why she started the project. Remove long pauses, but keep her meaning and natural delivery. Keep her face in the frame. Add readable captions and use her original voice. Use local transcription if a transcript is needed. Do not generate new video, music or speech, or use paid services. Show me a rough cut. Keep the source unchanged and save the edit as a new file. ``` You can choose **Edit existing footage** under **Making:**, then a kind such as **Highlights** or **Shorts and vertical**. **3. Review the rough cut** Watch the whole cut before focusing on individual frames. Check that it preserves the speaker's meaning, starts at a useful point and ends cleanly. Check captions against the audio. For a vertical crop, watch moving subjects through the whole shot rather than checking only the first frame. **4. Send precise changes** Open **Review** on the result. Use a time-range note for a cut or pacing change, and a pin or box for captions and framing. ```text theme={"system"} Keep the opening. At 8–12 seconds, shorten the pause without cutting off her breath. Move the captions above the bottom edge. Keep the rest unchanged and save another version. ``` **5. Request the final delivery** Ask for the finished format and any other files you need. For example: “Deliver the MP4, the caption file and the editing source.” The source format depends on the editing workflow. Play the final file, then use **Save video** or the reveal action to [find it on disk](/first-video/find-your-file). ## Edit talking footage by its words For an interview, talk or tutorial, ask Voyager to edit the recording by text. It transcribes the recording and opens an **Edit by text** card in the chat, with the transcript beside the edited cut. * Select words in the transcript and delete them. The cut updates to match, and you can restore anything you removed. * Clean up filler words, long pauses and retakes in one click. * Fix a misspoken phrase in the speaker's own voice. * Export the finished video with captions. > [!WARNING] > > Fixing words in the speaker's voice generates new speech and can cost money. Review the estimate > before approving it. ```text theme={"system"} Edit talk.mp4 by text. Remove filler words and long pauses, then let me cut the rest myself. ``` ## Find moments in a longer recording Name the files or folder to search and ask for the moment you need: “Find where Maya talks about the first prototype,” or “Find a wide shot of the room in these event clips.” Open **Apps & Models → Providers → This computer**. Under **Voice and search**, **Media search** has **Speech** and **Visual** rows; choose **Download** on the one you need and let it finish. Search analyzes selected footage locally and does not use media credits. Search availability depends on your computer. Searching footage by what's said or shown doesn't work on every platform; check the [platform table](/get-started/requirements) before relying on this workflow. You can still supply the timestamps or a transcript yourself for an edit. Review the suggested matches. Speech search looks for words and phrases; visual search finds similar-looking shots. A matching image does not prove that the action you wanted happens throughout the clip. ## Work in an existing editor project Tell Voyager the editor and project you want to continue. Existing Resolve and Premiere projects stay in their native workflows. Name the intended timeline or sequence and the result you want. > [!WARNING] > > Save your current work before asking the agent to change an existing editor project. Ask it to create a new version when you need to preserve the current edit. Generating replacement media or speech can also cost money; review the estimate before approving it. To get feedback from people outside Voyager, [share the cut for review](/guides/share-for-review). If your team reviews in Frame.io, connect it under **Apps & Models → Apps → Frame.io** then open the rendered video's review, choose **Share** and pick **Frame.io**. To send a revision, choose **Send as vN** there, or ask Voyager to upload it; it goes up as a new version, and reviewers' comments come back into the review. For simple trims and cutdowns, you can ask Voyager to use its local editing tools. For designed or animated captions, ask for [motion graphics](/guides/motion-graphics) as part of the edit. ## Check the result Play the delivered file from beginning to end with sound. Check lip sync, cut boundaries, caption spelling and timing, the crop, and the final frame. Confirm that the original footage remains available before sharing the result. ## Common problems > [accordion] A long recording takes a while to add > > Put it in the project folder and reference it from **Files** or with `@` instead of uploading it. > [accordion] Voyager cannot find the moment I mean > > Give the source filename, approximate time, a phrase the speaker uses, or an existing transcript. If local media search asks for setup, finish that setup before searching again. > [accordion] The crop cuts off the subject or captions > > Attach a review note over the affected time range and say what must remain visible. Ask for reframing through the shot, or a different caption position, rather than only a new overall crop. > [accordion] My editor is installed but Voyager cannot use it > > Check [creative app setup](/setup/creative-apps) and the [platform requirements](/get-started/requirements). Installation alone may not complete the app's connection or permissions. If you only need a simple cut, ask the agent whether it can use local editing instead. > [card] [Review and revise](/first-video/review-and-revise) > > Send comments tied to the right version and time range. > [card] [Files and previews](/guides/files-and-previews) > > Keep source clips, drafts and delivered work easy to find. # Browse files and previews Source: https://docs.voyager.so/guides/files-and-previews Use Files, Assets and Background to inspect working files, review delivered versions and follow progress. Open work beside the chat to inspect it, play it, or refer to it in your next message. Start from a chat that has files. For a new chat without a project, send the first request so Voyager creates its working folder. ## Choose the right panel | Surface | What it is for | | - | - | | **Files** | Browse the chat or project folder, including sources, drafts and finished files. | | **Assets** | Find presented work and its versions, with filters for the current chat or a wider scope. | | **Background** | Follow the chat's background work: helper agents, media jobs and shells. | | Project **Outputs** | Return to delivered work from the project's page. | The project page's details (**Brief**, **References**, **Brand kit**, **Memory**, **Editors** and **Storage**) are separate from the right panel used for previews. ## Open and inspect a file **1. Open Files** Open the right panel and choose **Files**. If the panel already has tabs, use its **+** button, labeled **Add panel surface**, to choose **Files**. The right-panel shortcut is ⌥ ⌘ B on Mac (Ctrl Alt B on Windows/Linux). **2. Select a file** Browse or search the file tree, then click the file. Voyager can preview images, video, audio, PDFs and several document formats beside the chat. ![The Files panel with the project tree: a dimmed generated job folder, and in renders the teaser marked Asset · v2 beside v1.](https://mintcdn.com/voyager/fNRH-gH21vuRhf5W/images/screenshots/review-files-panel.light.png?fit=max\&auto=format\&n=fNRH-gH21vuRhf5W\&q=85\&s=762694af122861b2f27e53a01575c2b2) The file tree includes working material as well as finished assets. **3. Use the file header** The header above an open file shows its name; hover the name to see the full path. From the header you can: * Step through the other files in the same folder with the previous and next arrows, which show where you are ("3 of 12"). With the viewer focused, \[ and ] do the same. * **Download a copy**, or **Show in Finder** (**Show in File Explorer** on Windows) to find the original on disk. * **Share** a video, audio file or image for review. See [share for review](/guides/share-for-review). * Open **⋯** (More) for the file menu. The file menu has **Copy path**, **Copy relative path**, **Open in** an editor (for code files), **Rename…** and **Move to Trash** (**Move to Recycle Bin** on Windows). After a move to the Trash, click **Undo** on the notice to bring the file back. The same menu opens when you right-click the file's tab or the file in **Files**. ![An open video with previous and next arrows, its name, 2 of 4, Download and Share in the header, and the More menu open showing Copy path, Copy relative path, Rename and Move to Trash.](https://mintcdn.com/voyager/193F9fREXJhp2PWx/images/screenshots/files-viewer-header.light.png?fit=max\&auto=format\&n=193F9fREXJhp2PWx\&q=85\&s=3686354901c4fba67f13e1232915280f) Rename, copy the path or move the file to the Trash from the file menu. **4. Point the agent to it** Right-click a file and choose **Add to chat**, or drag it into the message box. This references the file; it does not move it. Add a request such as “Use this as the reference for the lighting,” or “Make a shorter cut from this video.” For visual feedback, open the media's review controls and [attach comments](/first-video/review-and-revise). ## Find a delivered version Open **Assets** and choose **This chat**, **Project**, or **All chats**. **Project** is available when the chat belongs to a project. Select an asset to see its versions, then open the one you need. ![The Assets panel with a grid of delivered work and This chat, Project and All chats scope controls.](https://mintcdn.com/voyager/193F9fREXJhp2PWx/images/screenshots/review-assets-panel.light.png?fit=max\&auto=format\&n=193F9fREXJhp2PWx\&q=85\&s=5c26e44ae9e93b1e733a70cb4c3cf1e3) Change the scope when the file you want came from another chat. Use **Compare** when there are suitable versions to compare. In a project, the project page's **Outputs** lists delivered work too; a version's menu has **View** and **Save**. A preview may follow a newer version delivered by the agent. Watch for **Showing the agent's latest version**. Use the **Back to** link to return to the earlier file, or **Keep this version** to stay on the new one. ## Edit a text file Text files open read-only. To change one, click **Edit file** (the pencil) in the header, press E, or double-click the text. The header then shows **Editing**. Press Esc to stop editing. > [!WARNING] > > While editing, changes save to the actual file as you type (**Editing · Saved**); there is no > separate Save button. Keep a copy first if you need the original unchanged. For a file type Voyager can't preview, use **Open in default app** when available, or **Show in Finder** to open it from your file manager. ## Follow unfinished work The **activity tray** above the message box shows generations, renders, exports and downloads while they run, across every chat. Click an item to open it, **Clear finished** to tidy the list, or **View all activity** for the last 7 days, including what you cleared. Its **⋯** menu has **Show in the tray**, to choose which kinds of work it lists. If the list can't load, click **Try again**. The tray appears by itself when work starts. To change that, or what it shows, open **Settings → Creative → Activity tray**. Hidden kinds still run. For one chat's work, open the **Background** panel from the right panel. Filter by **All**, **Agents**, **Jobs** or **Shells**; running work is listed first, then finished work. **Queued** means a job is waiting; sending the request again is not needed to move it forward. ![The Background panel beside a chat, with All, Agents, Jobs and Shells filters, a Running list and a Finished list, and View all activity at the bottom.](https://mintcdn.com/voyager/193F9fREXJhp2PWx/images/screenshots/guides-background-panel.light.png?fit=max\&auto=format\&n=193F9fREXJhp2PWx\&q=85\&s=3674f79dc137fc2c87d84472400b702e) Filter the Background panel by All, Agents, Jobs or Shells. If a paid job fails or its outcome is uncertain, ask the agent to check that existing job before starting a new attempt. See [generation problems](/help/generation-problems). ## Check the result Confirm the filename and version before sending feedback. To keep the finished file outside Voyager, use **Download a copy** in the file header, or see [find your file](/first-video/find-your-file). ## Common problems > [accordion] The file is in Files but not Assets > > **Files** shows the folder's contents; **Assets** shows presented work. Ask the agent to present the file as an output if you want it in **Assets** or the project's **Outputs**. > [accordion] A generated clip is not the final video > > A generation may produce one ingredient for a larger edit. Look for the assembled result in the agent's final reply, or ask it to finish and present the cut. > [accordion] The preview cannot open the file > > Reveal it in your file manager and check that it still exists. Try its normal application if the format cannot be previewed in Voyager. If it was moved, tell the agent the new location. > [card] [Review and revise](/first-video/review-and-revise) > > Attach feedback to an exact frame or time range. > [card] [Find your file](/first-video/find-your-file) > > Save a copy or locate the original on disk. # Generate images and video Source: https://docs.voyager.so/guides/generate-images-and-video Create images or generated footage, approve stills before animation, and keep track of cost and revisions. Describe an image, a single moving shot or a finished video, and let Voyager turn the request into media you can review and revise. You need a connected chat account and a [generation provider](/account/generation-providers) that supports the work. Bring your own media keys, which need no Voyager plan, or use Voyager credits from a plan. Connecting a chat account doesn't by itself pay for generated media; each generation connection has its own billing. See [current pricing](https://voyager.so/pricing). > [!WARNING] > > Generating images, clips, audio and new takes can cost money. Still images used to plan an > animation can also cost money. Choose **Always ask** in the questions control below the message > box if you want to review each question yourself, and read [approvals and > spending](/guides/approvals-and-spending) before starting. ## Generate an image **1. Describe the picture and its use** Include the subject, setting, style and shape. If you need an exact size, transparent background or particular model, say so. ```text theme={"system"} Create a square product image of the attached ceramic mug on a pale stone table, with soft morning light and a warm editorial look. Keep the mug's shape and blue glaze. Leave room above it for a headline, but do not add text yet. Show me the estimated cost before generating. ``` **2. Attach and explain references** Use the round **+** below the message box, then **Upload or add files**, or reference a project file with `@`. Give each reference a purpose: the actual product, the desired lighting, the composition, or the image to edit. For an edit, identify what should change and what should remain. “Remove the object on the left; keep the subject, lighting and framing” is more precise than “clean this up.” **3. Review the result** Open the image and inspect the important details. Check the subject, product shape, spelling and crop. Send a specific correction in the same chat, referring to that image. When it is ready, right-click it and choose **Save image**, or use the reveal action to locate the file. ### Change part of an image Open an image from your project in **Files**. Pin or draw on the image to leave a note about what should change, such as “make this sign say Open” or “warmer light on the face”. Add as many notes as you need. Then choose **Regenerate**, or press ⌘ ↵ (Ctrl Enter). Voyager makes a new version and keeps the original, so you can compare them. The arrow beside **Regenerate** opens **Model and options**, where you can pick the model and the number of variants and see the estimated cost. **FLUX.3 Klein** is a fast, inexpensive choice for small edits such as changing text, relighting or placing a product in a mockup. For a design with exact words or a logo, tell Voyager that the picture and layout both matter. It can build the lettering and layout around the image instead of relying on generated lettering alone. ## Make a video from several shots **1. Describe the story and delivery** Give the audience, length, shape, sequence of ideas and audio needs. Name any footage or stills that should be reused. ```text theme={"system"} Make a 12-second vertical teaser for a quiet weekend cabin. Three shots: the cabin in morning mist, a warm interior detail, then a view from the porch. Keep the same natural, understated look throughout. No music or voiceover. Estimate the still-image work first. Show me one still per shot, then the animation cost and time estimate. Wait for my approval before animating. Deliver the assembled video, not just the clips. ``` **2. Approve the look in stills** For a new video with multiple shots, Voyager's workflow starts with a still for each shot before animation. Review composition, subject identity and consistency across the set. The approval card shows every still with an estimated cost and time for the animation. You then have three choices: * Choose **Animate N** (for example **Animate 4**), then **Submit**, to approve every still and start the animation. * To revise only some shots, flag each one with **Redo** (or press R) and add an optional note on what to change. Then choose **Send review · Redo N**. Voyager redraws those stills, keeps the rest, and shows you the set again. * Choose **Change the overall direction**, type the new direction in the answer box below the card, then **Submit**. All the stills are redrawn to it. This question has no recommended answer, so it waits for you even when questions are set to **Wait, then go ahead**. Nothing is animated until you choose. **3. Follow generation and assembly** After approval, Voyager animates the approved stills and assembles the requested video. Running work appears in the **Activity** tray above the message box. For more detail, open the **Background** panel on the right and choose **Jobs**. Waiting for a free slot is queueing, not a reason to start the job again. **4. Review the finished cut** Play the assembled result, including its sound if requested. Check shot order, continuity, pacing and text. Use [review comments](/first-video/review-and-revise) to request changes. Say which shots to keep so the agent can reuse approved work. New generations may cost more; an edit that reuses existing clips can avoid new media generation. ## Make a story film Ask for a story, such as “a two-minute story of a robot who learns to paint”. Voyager starts by writing the story with you before it makes any video. Each scene follows from the one before, and every shot carries its part of the story. Voyager shows the story and the shot breakdown as review cards in the chat. Approve them as they are, or say what to change. With questions set to **Wait, then go ahead**, these story and breakdown cards count down too and approve as shown if you step away. Choose **Wait** to stop the countdown, or **Approve now** to skip it. A card that would start paid generation always waits for you. ## Keep people and places consistent A project's **Elements** keep its people, places and things looking the same in every shot. To add someone, open **Library → Elements**, choose the project in the **Project** menu, then **Add element** (or **Choose photos** when it has no elements yet) and pick a photo. Voyager reads the photo and fills in the description and kind, so you only add a name. You can also open a project image in **Files** and choose **Add to Elements**. Provider safety filters still apply. On Voyager credits, photoreal faces in Seedance video need Voyager Ultra or GigaMax™; on other plans, Voyager stops before anything is sent or charged and suggests another model. See [Library](/guides/library#elements) for more. ## Make a single clip For one fully described clip, you can ask directly. If you supply a still to animate, describe how it should move and what must remain unchanged. These requests do not necessarily need a separate still-approval stage. Avoid asking Voyager to skip approvals if you want to review the look first. To try a model by hand, without a chat, open it in the [Model playground](/guides/model-playground). ## Control which generation account is used Open **Apps & Models → Providers** to check your connections. Choose **Image, video and voice order** at the top to move providers up or down into the order Voyager tries them. > [!WARNING] > > With **If one can't finish, try the next provider** on, if a provider is out of credits, rejects > its sign-in or is down, Voyager tries the next one in your order. That may bill a different > account. You can turn this off in the same dialog, or ask the agent to pin a provider for the job. For example: “Use only my fal account for these shots; stop if it cannot run.” A model you name and an account you want billed are different choices, so state both when both matter. ## Check the result The agent should present the final image or assembled video in the chat. Open it at a useful size, check the details, and [save or reveal the file](/first-video/find-your-file). Keep the source stills and clips if you expect more revisions. ## Common problems > [accordion] My chat subscription works, but media generation asks for payment > > Chat and media use separate accounts. Connect your own supported media provider in **Apps & Models > → Providers**, or check your Voyager plan and credits under **Settings → Account**. See > [generation providers](/account/generation-providers). > [accordion] A shot failed or has an uncertain outcome > > Check the job in the **Activity** tray or the **Background** panel first. A delayed or missing > result does not prove that the provider did no work. If Voyager loses track of a generation it > sent on Voyager credits, it checks what happened instead of sending it again, so you are not > charged twice. Ask > the agent to check the existing job before making a fresh attempt, and follow [generation > troubleshooting](/help/generation-problems). > [accordion] A request returns the same image or clip > > Voyager can reuse an identical earlier generation instead of paying for it again. If you want a > different take, ask for a new take explicitly and review its cost. > [accordion] I only received individual clips > > Ask for the assembled video, with the shot order, pacing and audio you want. A completed > generation job can be one part of the finished piece. > [card] [Approvals and spending](/guides/approvals-and-spending) > > Choose the question mode and spending preferences for your work. > [card] [Make motion graphics](/guides/motion-graphics) > > Animate type and shapes with editable source and local rendering. > [card] [Library](/guides/library) > > Brand kits, voices, elements and widgets you can reuse. # Library: brand kits, voices, elements and widgets Source: https://docs.voyager.so/guides/library Find the brand kits, voices, elements and widgets you reuse across chats and projects in one place. The **Library** keeps the things you reuse from one piece to the next: your brand kits, the voices you like, each project's elements, and the interactive cards Voyager can show in a chat. Open **Library** in the sidebar. It has four tabs: **Brand kits**, **Voices**, **Elements** and **Widgets**. ## Brand kits A brand kit holds a brand's logo, colors and fonts. When a project has one, Voyager uses it for titles, captions and graphics. Brand kits come from your Voyager account, so you need to be [signed in](/setup/sign-in). ![The Library's Brand kits tab with three kit cards showing names and websites, one marked Default and one Team default, a search box and a New brand kit button.](https://mintcdn.com/voyager/foXFRaWsXnaWJOMw/images/screenshots/library-brand-kits.light.png?fit=max\&auto=format\&n=foXFRaWsXnaWJOMw\&q=85\&s=3a7beea90089282c5cb9f6c7d34d6c31) Library → Brand kits lists your kits and marks the default for new projects. * **Open a kit** by clicking its card to see its description, colors and fonts. * **Set the default for new projects**: open the card's menu (**⋯**) and choose **Set as default**, or use **Set as default** on the kit's page. New projects start with that kit, and its card shows **Default**. Choose **Remove as default** to clear it. A kit marked **Team default** is your team's default in your Voyager account. * **Make a new kit**: choose **New brand kit**. Voyager opens a new chat with the request started; finish it with your website or attach your logo, fonts or brand guide, then send. To use a different kit in one project, change the **Brand kit** on the project's page. See [set up your brand](/setup/brand). ## Voices **Voices** lists the voices Voyager can use for narration and voiceover. * **Your voices** shows voices you've cloned. Choose **Clone your voice** to make one from a recording of your own voice. Voice cloning is included with Voyager Ultra and GigaMax™; on other plans, **See plans** shows the options. * In the **Voice library**, play a voice to hear it, and star the ones you like to find them under **Favorites**. You choose a voice where it's used: in a chat's **Voice** panel, choose **Use voice** on a voice. To set the voice Voyager uses when you don't name one, go to **Settings → Creative → Default voice**. ## Elements A project's **Elements** (formerly Cast) keep its characters, locations and props looking the same in every shot. Elements live in each project on your computer. The tab shows **All projects**; use the **Project** menu at the top to show one. * **Add from a photo**: choose **Add element** (or **Choose photos** when the project has no elements yet) and pick one or more photos. Voyager reads each photo and fills in the description and kind, so you only add a name. * **Describe someone instead**: choose **Describe one instead**, and the agent drafts an element from your description. * You can also open a project image in **Files** and choose **Add to Elements**. New elements are ready to use right away. Provider safety filters still apply, and a provider can refuse a shot. On Voyager credits, photoreal faces in Seedance video need Voyager Ultra or GigaMax™; on other plans, Voyager says so before anything is sent or charged, and you can use another model or a stylized version of the element. ## Widgets Widgets are interactive cards the agent can show in a chat: for example, picking shots, reviewing clips one by one, comparing two images or approving a cost. Built-in widgets are always available, and widgets you or the agent save appear here too. ![The Library's Widgets tab showing widget cards with previews, a search box, an All, Built-in and Custom filter, and Import and Settings buttons.](https://mintcdn.com/voyager/foXFRaWsXnaWJOMw/images/screenshots/library-widgets.light.png?fit=max\&auto=format\&n=foXFRaWsXnaWJOMw\&q=85\&s=58daa185ef0c0c501a7087422edaad1f) Library → Widgets lists built-in and saved widgets, with Import and Settings at the top. * **Use** opens a widget in a chat you pick, or in a **New conversation**. * **Preview** lets you try a widget with sample data. Nothing is saved or sent. * A widget's menu has **Edit with agent**, **View source**, **Export**, **Duplicate**, **Turn off** and **Remove**. * **Import** adds a widget someone exported for you (a `.json` file). Choose **Settings** on the tab to open **Widget settings**: * **Allow agent-created widgets** lets the agent make and revise widgets, within the permissions it already has. * **Save reusable widgets automatically** keeps widgets the agent makes in your Library so you can use them again. **Settings → Advanced → Widgets** opens this same tab. ## Techniques **Techniques**, also in the sidebar, collects tested ways to make things with Voyager, such as animated posters, product films and voiceovers. Search or filter by what you want to make, read a technique in the app, then start a new chat with it attached. > [card] [Set up your brand](/setup/brand) > > Add a brand kit and choose it for a project. > [card] [Generate images and video](/guides/generate-images-and-video) > > Use your elements and brand in generated work. # Connect tools and services Source: https://docs.voyager.so/guides/mcp-and-connectors Connect Figma, Frame.io, Notion, Dropbox and other services to Voyager, or add any MCP tool server by its address. Connect the services you already use so the agent can work with them: read a brief in Notion, pull files from Dropbox, check comments in Frame.io or look at a Figma design. Everything lives in **Apps & Models → Apps**. > [!NOTE] > > **Before you start:** Figma needs you signed in to your Voyager account. Each service uses your own account with that service, so you need one there too. ## Connect a listed service **1. Open Apps** Click **Apps & Models** in the sidebar and choose the **Apps** tab. Use the chips, such as **Design**, **Video** or **Libraries & files**, or search. **2. Open the service and click Connect** Click the service's tile. For most services, click **Connect**, sign in on the service's own site, and pick what Voyager can see. **3. Ask for something** Back in a chat, ask: "Read the brief in our Notion launch page and suggest three title cards." Services you'll find there include: * **Figma**: design files and live edits. Connect your Figma account, and optionally the Figma desktop app. * **Frame.io**: review links and comments. Click **Connect** and approve in your browser. * **Notion**, **Canva**, **Dropbox** and **Airtable**: connect in one step on their own sites. * **Google Drive**, **OneDrive**, **Box**, **Vimeo** and **YouTube**: Voyager sets these up with you in a chat. * **Roblox** and **Freesound**: add your API key on the tile. Voyager uses Roblox when you upload to Roblox, and Freesound for sound effects. * Free asset libraries, such as **Poly Haven**, **ambientCG**, **Kenney**, **game-icons.net** and **Incompetech**, are **Built into Voyager**. There's nothing to set up. The **Connected** chip shows everything you've connected. **Needs attention** shows anything that needs you to sign in again or replace a token. ## Add a service that isn't listed **1. Click Add an app or service** It's at the top of the **Apps** tab. **2. Type its name** If Voyager lists it, click it. If not, choose **Set up "…" with Voyager**. Voyager looks the service up and asks you a few questions in a chat. **3. Finish in the chat** Paste any keys the agent asks for into the secure field it shows you, not into the message. When setup is done, the service shows under **Added by you** with a **Connected** status. Keys you add are saved in this computer's secure storage. Open the service under **Added by you** to see its sign-in details, check the connection, or **Remove service**. ## Add an MCP server An MCP server is a tool server that gives the agent new tools. If a service gives you an MCP address, add it directly. **Settings → Advanced → MCP** brings you to the same place. **1. Open the tool server form** In **Apps & Models → Apps**, click **Add an app or service**, then **Add a tool server by its address**. **2. Fill it in** Give it a **Name**. Under **Connect with**, choose **An address** and paste the server's **Address**. For a server that runs as a program on your computer, choose **A command on this computer** and enter the **Command** and its arguments. **3. Choose how it signs in** Open **More options**. Under **Sign-in**, choose **On its site** to sign in through your browser, **Access token** to paste a token the service gave you, or **None**. **4. Pick projects and add it** Under **Projects**, keep **Every project on this computer** or choose specific projects. Click **Add server**. If it signs in on its site, finish signing in on the page that opens. Open the server's tile to turn **Use in chats** on or off, see its tools and untick any you don't want the agent to use, **Check** the connection, **Sign in again**, or **Remove** it. ## Check it worked The tile shows **Connected**. Start a chat and ask the agent to use the service by name. ## Common problems > [accordion] A tile says Needs you to sign in > > The service signed you out. Open the tile and click **Sign in again** (or **Reconnect**). > [accordion] A tool server says it needs a new access token > > The token expired or was revoked. Open the tile, choose **Edit**, and paste a new token in **Access token**. > [accordion] Voyager can't reach a tool server > > Check the address and your internet connection, then click **Check again**. If you don't use it any more, remove it. > [accordion] Figma desktop isn't answering > > Open a design file in the Figma desktop app, switch to Dev Mode (Shift D), and turn on the desktop server in the inspect panel. Your Figma account needs access to Dev Mode. ## Related * [Connect your creative apps](/setup/creative-apps) * [Choose models and apps](/guides/choose-models-and-apps) * [Use and manage skills](/guides/skills) # Try a model in the playground Source: https://docs.voyager.so/guides/model-playground Run an image, video, voice, music, sound effect or 3D model directly, without a chat, and save the results to a project. The playground lets you run one model yourself: type a prompt, set its options, click **Run** and see the result. Use it to compare models, try a prompt before you use it in a chat, or make a single image or sound quickly. > [!NOTE] > > **Before you start:** each run costs the same as the same generation in a chat. The price shows next to **Run** before you start: Voyager credits, **Included in your plan**, or **Free on this computer** for a model that runs locally. A model that needs a provider you haven't connected says so and links to the setup. See [Plans and credits](/account/plans-and-credits) and [voyager.so/pricing](https://voyager.so/pricing). ## Run a model **1. Open a model** Click **Apps & Models** in the sidebar and open the **Models** tab. Click **Open playground**, or click **Try** on an image, video, voice, music, sound effect or 3D model. The model's page opens on **Playground**. **2. Choose where results go** Under **Save to**, pick a project, or **New project**. If you don't save to a project, unsaved runs are kept for 7 days. **3. Write a prompt and set options** Type your prompt, or click one of the example prompts under **Try**. Some models have a **Mode**, such as text-to-video or image-to-video, and take an image, video or audio file as input. **More settings** holds the rest. **4. Run it** Check the price and time next to the button, then click **Run**. You can leave the page: the run keeps going and shows in **Activity**. ## Use the result When the run finishes, the result plays or shows on the page. You can: * **Download** it (for 3D, **Download model**). * **Save to project…** if you didn't choose one before. * Add an image to your **Elements**. * Under **More actions**: **Use these settings** to run again with the same options, or **Use as input** to feed the result into the next run. To work on it with the agent instead, click **Use in chat**. Voyager starts a chat that uses this model. The **Details** tab says what the model is good at, what it takes and who can run it. ## Check the result Saved results are in the project's files, like anything the agent makes. A run that isn't in a project says **Not in a project** and the date it will be deleted. ## Common problems > [accordion] “Connect … to run …” > > No provider you've set up can run this model. Click the setup button, or connect one in **Apps & Models → Providers**. See [Choose your generation providers](/account/generation-providers). > [accordion] Run says Add credits > > You don't have enough Voyager credits for this run. Add credits, choose a cheaper model, or connect your own provider. > [accordion] “We don't have pricing information for this run” > > Voyager can't estimate this run's cost. It may still cost you. Click **Run anyway** only if you're happy with that. > [accordion] A chat model has no playground > > The playground runs image, video, voice, music, sound effect and 3D models. Chat models show **Chat** instead of **Try**. ## Related * [Generate images and video](/guides/generate-images-and-video) * [Choose models and apps](/guides/choose-models-and-apps) * [Routines and activity](/guides/routines-and-activity) # Make motion graphics Source: https://docs.voyager.so/guides/motion-graphics Create animated titles, explainers and graphics with editable source, then refine their design and timing. Make animated type, shapes, charts or explainers that you can revise without generating new footage for every change. You need a connected chat account, a message to communicate, and any logos, fonts or data the piece should use. Voyager can prepare a local motion project for you; the first use of a tool may require downloads. You can also use a supported creative app you already have [set up](/setup/creative-apps). Text and shapes rendered locally do not use media credits. Your chat account's usage still applies, and chat through Voyager models uses Voyager credits. Generated images, music or narration are separate paid additions. ## Build the first draft **1. Describe the content through time** Say what the audience should understand, then describe the main beats. Include exact wording, duration, shape and any visual references. ```text theme={"system"} Make a 10-second square motion graphic for a workshop invitation. Use Remotion, text and simple shapes, rendered locally. First reveal “Make something new.” Then bring in “Saturday studio” and “10 am–1 pm”. Use a warm cream background, dark brown type and one orange shape that carries through the transitions. Keep the final information readable for 3 seconds. No generated media or audio. Show a draft, then deliver a silent video and keep the editable source. ``` You can choose **Motion graphics or explainer** under **Making:**, or simply describe the piece. **2. Supply brand assets and data** Attach the actual logo and any required fonts or images with the round **+** below the message box. For a chart, attach the data and name the comparison you want viewers to understand. When a project has a [brand kit](/setup/brand), Voyager uses its colors, fonts and logos for titles, captions and graphics. Drop a brand font or logo into the chat and the next video uses it; Voyager tells you if the font can't write your language or the logo has no transparent background. If you share a video of your brand, Voyager can also follow how it moves: its pacing, cuts and how titles appear. Browse and choose kits in [Library → Brand kits](/guides/library#brand-kits). If the work must stay in a particular editor, name it. Otherwise, Voyager chooses a suitable available tool. Installed creative apps can have their own licenses and setup requirements. **3. Review layout and motion** Open the preview or video the agent presents. Check the design while paused, then watch it in motion. Look for readable text, useful pauses and transitions that connect the ideas. ![A locally rendered motion graphic playing in Voyager, with animated lettering and simple shapes.](https://mintcdn.com/voyager/rEfw7LKCPAGvufOx/images/screenshots/first-video-motion-result.light.png?fit=max\&auto=format\&n=rEfw7LKCPAGvufOx\&q=85\&s=5614db6aa95627e1920ec41cb19ae419) A playable draft lets you judge the timing as well as the layout. **4. Revise the specific beat** Give the time or attach a [review comment](/first-video/review-and-revise). Describe both the change and what to keep: ```text theme={"system"} At 4 seconds, let the orange shape arrive before the workshop title. Make the title larger, and keep the date and time still. Keep the total length and palette unchanged. Save a new version. ``` **5. Ask for the finished files** When the draft is right, ask the agent to render the final video and show its editable source. Name the destination and format, especially for transparent overlays or a particular publishing platform. Use **Save video** or the reveal action on the finished result. Set **Delivery folder** in **Settings → Creative** if you want final files in a particular place. ## Preview before rendering Some workflows can show an interactive preview before making the final video. If you receive a preview, you can ask for changes before requesting the rendered file. For Remotion and HyperFrames, the optional **Settings → Advanced → Labs → Review compositions live** setting lets you scrub and comment on the composition in **Files**. It is experimental and off by default. Start a new chat after enabling it if an existing chat does not offer the workflow. With it enabled, ask for the final render when you approve the composition. ## Keep control of time and cost Set **Ask before renders longer than** under **Settings → Creative → Limits**. The agent estimates longer local renders before proceeding. ### Render on Cloud GPUs On paid plans, Voyager can run heavy work, such as a long Blender render, a simulation or work that needs a CUDA graphics card, on a Cloud GPU. It starts the machine, brings the results back and releases it. > [!WARNING] > > GPU work uses Voyager credits. With **Ask**, the agent shows the time and credits before it starts. Voyager Free doesn't include Cloud GPUs. See [plans and credits](/account/plans-and-credits) and [Computers and Cloud GPUs](/guides/computers-and-cloud-gpus). Choose when under **Settings → Creative → Cloud GPUs**: * **Ask**: Voyager asks before using a GPU. * **Always for heavy work**: Voyager uses one when the work needs it. * **Never**: all work stays on your computer. > [!WARNING] > > Adding generated artwork, video, music or narration can introduce media charges. Ask for an > estimate before adding them and check your [question-answer mode](/guides/approvals-and-spending). > **Don't ask** can approve the recommended paid work immediately. For another size, ask the agent to adapt the layout for that shape. For example, ask for a vertical version with repositioned titles instead of a crop that cuts off the words. ## Check the result Play the exported video outside Voyager. Check spelling, timing, edges and the final held frame. Confirm that the editable source is available in **Files** so you can request future changes. ## Common problems > [accordion] The agent starts making AI-generated footage > > Clarify that you want editable type and shapes with local rendering. Name **Remotion** if you > want to follow the simple workflow in [your first video](/first-video/make-your-first-video), > and say whether any paid media generation is allowed. > [accordion] I have a preview but no file to upload > > Ask the agent to render the approved composition into the format you need. An interactive > preview and a rendered video are different outputs. > [accordion] The local render is taking too long > > Ask for a short or lower-resolution draft first, or simplify the most expensive effects. Set > **Ask before renders longer than** so the agent asks before a longer render. Check the **Activity** tray > or the **Background** panel before starting it again. > [accordion] MP4 is unavailable on Linux > > On Linux, Voyager downloads an MP4 encoder the first time it exports MP4. If you turned off > **Settings → General → Advanced → Video export → MP4 export on Linux**, or the download failed, > the agent delivers WebM or image frames instead. Tell the agent your required delivery format. > See [platform requirements](/get-started/requirements). > [card] [Review and revise](/first-video/review-and-revise) > > Mark a detail or a time range in your draft. > [card] [Edit footage](/guides/edit-footage) > > Combine graphics with clips you already have. # Routines and activity Source: https://docs.voyager.so/guides/routines-and-activity Run a prompt on a schedule with routines, and see every generation, render and download from the last week on the Activity page. **Routines** run a prompt for you on a schedule: a nightly render of the current cut, a Monday roundup of new footage, a reminder to review drafts. The **Activity** page shows everything Voyager made, rendered or downloaded across all your chats in the last 7 days. ## Create a routine The quickest way is to ask in any chat: "Every Monday at 9 AM, look through this project's newest footage and suggest a rough cut." The agent sets it up for you. To set one up yourself: **1. Open Routines** Press ⌘ K (Ctrl K) and choose **Open routines**. Then click **New routine**. **2. Say what it does** Give it a **Name** and write the **Prompt**, just as you would in a chat. **3. Choose when** Under **When**, choose **Once** and a date and time, or **Schedule** with a preset such as **Every weekday at 9:00 AM** or **Every hour**, or **Custom time…** and **Custom interval…**. **Next runs** shows when it will run. **4. Choose where results go** Pick a **Project**. Under **Results go to**, keep **New conversation each run (recommended)**, or choose **Continue a conversation**. Pick a **Model**. **5. Save it** Click **Create routine**. > [!WARNING] > > **Routines run only while Voyager is running.** If Voyager is closed or your computer is asleep at the scheduled time, that run is missed. When Voyager starts again, each routine catches up once if a run was missed in the last few hours. On a Mac, closing the window keeps Voyager running in the Dock; quitting stops routines. On Windows and Linux, closing the last window quits Voyager, so minimize it instead. Each run can use credits, just like the same request in a chat. If a run needs your approval, it waits in its conversation; if nobody answers in time, it stops as **Timed out**. To let runs finish unattended, change the project's permissions as described in [Approvals and spending](/guides/approvals-and-spending). ## Manage routines The Routines page lists each routine with its next run and its last result. Filter by project, or by **Active**, **Paused** and **Needs attention**. * Use the switch to turn a routine on or off. * **Run now** runs it straight away. * Under **More actions**: **Edit**, **History**, **Open last conversation** and **Delete routine**. **History** shows every run, including missed and skipped ones and why. A routine pauses itself after 3 failed runs in a row, or when its conversation or project is gone. The page says why; fix the cause and turn it back on. A project's menu in the sidebar shows **Scheduled tasks** when the project has routines, and opens them filtered to that project. ## Check the Activity page The **Activity** tray shows work that's running now. The **Activity** page keeps the last 7 days, from every chat. Clearing the tray never removes anything here. To open it, click **View all activity** in the tray, choose **View → Activity** in the menu bar, or press ⌘ ⌥ A (Ctrl Alt A). Search titles and prompts, or filter by: * **Kind**: **Generations**, **Flow runs**, **Renders & exports**, **Downloads** and **Setup downloads**. * **State**: **Running and queued**, **Needs you**, **Failed or unknown**, **Stopped** and **Finished**. * **Project** and **Conversation**. From a row you can open the result, **Stop** work that's running, or **Retry** something that failed. Retry shows its cost first. ## Common problems > [accordion] A routine says Missed > > Voyager wasn't running, or your computer was asleep, at the scheduled time. Keep Voyager open (minimized is fine) at the times your routines run. > [accordion] A routine is Paused after 3 failed runs > > Open **History** to see the error, for example a model that isn't available. Fix it, then turn the routine back on. > [accordion] Something I made isn't on the Activity page > > The page keeps 7 days. Older results are still in their chat and in your project's files. ## Related * [Chats and projects](/guides/chats-and-projects) * [Files and previews](/guides/files-and-previews) * [Computers, phones and cloud GPUs](/guides/computers-and-cloud-gpus) # Share a video for review Source: https://docs.voyager.so/guides/share-for-review Send a link so anyone can watch your video and leave timed notes, then have Voyager address them. Get feedback from a client or teammate who doesn't use Voyager. They open a link in their browser, watch, and leave notes on exact moments. Their notes come back to your review in Voyager, ready to send to the agent. > [!NOTE] > > **Before you start:** sign in to Voyager. Review links work for video, audio and image files. For a motion graphic or web page, use **Share → Render to video, then share** and share the video when it's ready. ## Create a link **1. Open the share options** Open the video, audio or image in the file viewer. Click **Share** in the file's header, then choose **Share for review**. **2. Create the link** Click **Create link**. Voyager uploads the file, which can take a while for a large video. You can close the window while it uploads; Voyager tells you when the link is ready. **3. Name and copy it** Give the link a **Title** if you like, so reviewers know what they're looking at. Click **Copy link** and send it to your reviewers. ![The share options open from the file header over a video, with Copy link, a Title field, the Email me about new comments switch and a Send to section listing Frame.io.](https://mintcdn.com/voyager/fNRH-gH21vuRhf5W/images/screenshots/share-review-popover.light.png?fit=max\&auto=format\&n=fNRH-gH21vuRhf5W\&q=85\&s=2f33882f5d487834ae405019656e2f8f) The share options for a video: the link, its title, comment alerts and Send to Frame.io. Anyone with the link can view and leave comments. They don't need an account. The link stays live until you turn it off. ### Other ways to share a file **Share** in a file's header lists every way that file can go out: | Option | When you see it | | - | - | | **Share for review** | Video, audio and image files. Becomes **Manage review link** once shared. | | **Render to video, then share** | Web pages and compositions. Asks the agent to render an MP4 you can then share for review. | | **Publish game** | A page Voyager recognizes as a game. Publishes a page anyone with the link can play. | | **Download a copy** | Any file. Saves a copy to send however you like. | ## What your reviewers do Reviewers enter their name, or click **Sign in instead** to comment with their Voyager account. Then they pause on a moment and leave a note. They can drop a pin, draw, box an area or select a time range, just as you can in Voyager. They see each other's notes and can reply to them. ## Bring the feedback back Reviewers' notes appear in your review with their name and **Guest**. A check beside the name means they signed in with Voyager. You can **Reply** to a guest's note from the review; they see your reply on their page. Once there are notes, click **Add to chat (N)** below the player to add them all to the chat, then press **Send**. See [Review and revise your video](/first-video/review-and-revise). When a note is resolved, reviewers see it marked **Resolved** on their page. ### Get told about new comments In the Share options, turn on: * **Email me about new comments**: at most one email every 10 minutes. * **Notify the agent of new comments**: ask the agent in a chat to watch this link, and it tells you when notes are waiting. Notes then wait for your approval before the agent acts on them; signed in on the review page, you approve them with **Approve**. This needs a paid Voyager plan ([see plans](https://voyager.so/pricing)) and **Tell me about new review notes** turned on in **Settings → General → Notifications**. ## Share a new version After you change the file, Voyager shows **Update shared version** in the file's header, and the Share options say guests still see the older version. Click **Update shared version**, or **Share latest version** in the Share options. Voyager adds the new version to the same link. Reviewers see the newest version, can switch back to earlier ones, and each note stays with the version it was left on. ## Send to Frame.io If your team reviews in Frame.io, send the video there instead. **1. Connect Frame.io** Open **Apps & Models → Apps**, find **Frame.io** and click **Connect**. You can also click **Connect** next to Frame.io in the Share options. **2. Send the video** In the Share options, under **Send to**, click **Send** next to **Frame.io**, then choose the folder. A **Frame.io** chip then appears beside **Share** with the version your team sees and its open notes. After you change the video, click **Send as v2** (or the next number) to upload a new version. Notes from Frame.io sync back into your review. ## See all your links Open **Settings → Devices & sharing** and look under **Active links**, at the end of the page, to see every link that's live. Each shows the file, how many versions it has, how many guest notes are open and how many are new. From there you can **Copy link**, turn **Email** alerts on or off, **Update** a link whose file has changed, and use the **⋯** menu to **Open review**, **Open in browser** or **Turn off link**. ![Settings, Share links page, with one active link showing its version count, guest notes, Email and Copy link buttons and a more menu.](https://mintcdn.com/voyager/fNRH-gH21vuRhf5W/images/screenshots/share-settings-links.light.png?fit=max\&auto=format\&n=fNRH-gH21vuRhf5W\&q=85\&s=96132f1361fcae712d80e0b3d95d9c68) Settings → Devices & sharing lists every live link at the end of the page. ## Turn off a link Click **Share** in the file's header, choose **Manage review link**, then **Turn off link**. Or turn it off from **Settings → Devices & sharing**. The page stops working right away. Notes you already received stay in your review. To share the file again, click **Create new link**; this makes a new link. ## Check the result Open the copied link in a private browser window. You should see the file and be able to leave a note. The link is listed in **Settings → Devices & sharing**. ## Common problems > [accordion] Share is grayed out > > Hover it to see why. Review links work for video, audio and image files; render a composition or web page to video first, and convert other formats to MP4, MP3, WAV, PNG or JPEG. > [accordion] The link wasn't created > > Check your internet connection and click **Create link** again. Very large files (over 5 GB) can't be shared. ## Related * [Review and revise your video](/first-video/review-and-revise) * [Files and previews](/guides/files-and-previews) # Use and manage skills Source: https://docs.voyager.so/guides/skills Start a chat from a skill with $, turn skills on or off for the agent, and create or import your own. A skill is a saved workflow: instructions that tell the agent how to do one kind of job well, such as making a motion graphic, cutting a video or working in DaVinci Resolve. Voyager comes with a set of skills, and you can add your own. You don't have to pick a skill. Ask for what you want and the agent chooses the right one. Skills are there when you want to start a particular workflow yourself, or change which ones the agent may use. ## Start a chat from a skill **1. Type \$ in the message box** The skill picker opens. Skills are grouped: **Create** (things to make, like images, music and motion graphics), **Your skills**, **Voyager skills**, and a folded **More commands and skills** row. **2. Pick one and finish your request** Keep typing to search. Choose a skill, then write the rest of your request after it, for example `$make-motion-graphics a 10-second title card for our launch`. You can also start from **Settings → Advanced → Skills**: click a skill, then **Use in chat**. Voyager opens a new chat with that skill ready in the message box. ## See and manage your skills Open **Settings**, expand **Advanced**, and click **Skills**. The page lists every skill the agent can use, with its status and an **Agent can use** menu. Use the source menu to filter the list: | Source | What it is | | - | - | | **Bundled** | Skills that ship with Voyager. They update with the app. | | **Added** | Skills you created or imported. | | **Learned** | Workflows the agent saved from your finished work (see [Skills the agent learns](#skills-the-agent-learns)). | | **External** | Skills that come from your Claude or ChatGPT setup. Voyager shows them as **Managed externally**. | ### Turn a skill on or off In a skill's **Agent can use** menu, choose **On**, **Off**, or the default. Changes start at your next message. Turning a skill off stops the agent from following it; it doesn't change what the agent is allowed to do in **Approvals**. When a project is open, the page edits that project's choices, which win over the app defaults. With more than one project or computer, pick which one you're changing in the menu at the top of the page. ### Set up the software a skill needs Some skills need an app on your computer. A skill shows **Ready**, **Set up** or **Unavailable**. Click **Set up** to see what's missing. Open **Software & availability** at the bottom of the page to see what Voyager found on this computer, download free tools, and click **Refresh availability** after you install something. ## Add your own skill > [tab] Create one > > 1. Click **Create skill**. > 2. Give it a **Name** and write the instructions: when the workflow is useful and the steps to follow. > 3. Click **Save skill**. > > To start from a Voyager skill, click it and choose **Make a copy**. The original stays unchanged. > [tab] Import a folder > > 1. Click **Import folder**. > 2. Enter the path to a folder on this computer that contains a `SKILL.md` file. > 3. Click **Import**. > > Voyager copies the text files. It doesn't run scripts during import, and it skips images and other binary files. Skills you add show under **Added**, and in the `$` picker under **Your skills**. To change one later, click it and choose **Edit**. ## Skills the agent learns Voyager can save a way of working as a skill so it can reuse it next time. Turn this on in **Settings → Creative → Memory & learning**, under **Skill learning**: * **Off**: the agent doesn't learn new skills. Skills you have still work. * **When I ask**: type `/learn`, or ask the agent to save what it just did as a skill. * **Automatic**: the agent learns reusable skills from finished work. Skills you edited need your OK before they change. Learned skills show under **Learned** on the Skills page. ## Common problems > [accordion] A skill shows Set up or Unavailable > > The skill needs an app or tool this computer doesn't have. Click **Set up**, or open **Software & availability**, install what's listed, then click **Refresh availability**. > [accordion] I turned a skill off but the chat still uses it > > Changes apply from your next message. Instructions the agent already read earlier in the chat stay in that chat; start a new chat for a clean start. > [accordion] I can't edit a Voyager skill > > Bundled skills can't be edited, so updates can reach them. Click **Make a copy** and edit the copy, then turn the original **Off** if you only want yours. ## Related * [Write a useful request](/guides/write-a-request) * [Connect tools and services](/guides/mcp-and-connectors) * [Choose models and apps](/guides/choose-models-and-apps) # Write a useful request Source: https://docs.voyager.so/guides/write-a-request Describe the result, attach references, and guide Voyager while it works. Tell Voyager what someone should see, hear or understand when the work is finished. You can describe the result in ordinary language. Start with a connected chat account and any files you want to use. You do not need to choose a creative tool unless you have a preference. ## Give the agent a clear starting point **1. Name the result and audience** Say what you are making, who it is for, and where it will appear. Include the duration and shape when they matter: “a 15-second vertical video for people seeing our product for the first time.” For an image, give the size or intended use. For an edit, say which footage to use and which moment or message matters most. **2. Add the content and look** Include exact words that must appear, the order of the main ideas, and the visual style. Describe references by role: “Use this photo for the product, and this other image for the colors.” Say what to preserve during a revision. “Keep the music and timing; replace only the final title” gives the agent a clear boundary. **3. Attach the inputs** Click the round **+** below the message box and choose **Upload or add files**, drag files into the message box, or paste an image. Check the attachments before sending. The **+** menu also has **Add folder**, to give the agent a whole folder, and **Record screen**, to record your screen and attach the recording. The **Memory** switch turns **Memory & learning** (in **Settings → Creative**) on or off: for the whole project in a project's chat, or for the whole app in a chat outside a project. ![The + menu open above the message box with Upload or add files, Add folder, Record screen and the Memory switch.](https://mintcdn.com/voyager/193F9fREXJhp2PWx/images/screenshots/composer-add-menu.light.png?fit=max\&auto=format\&n=193F9fREXJhp2PWx\&q=85\&s=279040eadf86247baf53a074307d6fd4) The + menu adds files, folders and screen recordings to your message. To refer to a file already in the working folder, type `@` and choose the file. You can also drag it from **Files** into the message box; this adds a reference and does not move the file. ![The message box with the + button, the model picker, the preferred models and apps button, voice input and Send, and the questions control set to Wait, then go ahead.](https://mintcdn.com/voyager/193F9fREXJhp2PWx/images/screenshots/composer-anatomy.light.png?fit=max\&auto=format\&n=193F9fREXJhp2PWx\&q=85\&s=5275f46b77f6168455215385e4754a61) Check the attachments, selected model and question mode before sending. The numbers mark **+** (1), the agent model picker (2), **Preferred creative apps and media models** (3), the questions control (4) and **Send** (5). **4. State the constraints and send** Name anything the agent needs to respect: an existing editor, approved footage only, no voiceover, a required file format, or a budget. Press Enter or click **Send**. Use Shift+Enter to add a new line without sending. You can also speak your request. See [Speak instead of typing](#speak-instead-of-typing). ## A request you can adapt ```text theme={"system"} Make a 15-second vertical product teaser for first-time customers. Use the attached bottle photo and logo. Keep the product's shape and label accurate. Start with “Meet your daily companion.” End with “Made to go places.” Use cream backgrounds, dark green type and calm, deliberate motion. Keep text away from the top and bottom edges. Use the supplied assets and local motion graphics only, with no new paid media or audio generation. Show me a draft before the final render. Deliver an MP4 and keep the editable source. ``` You can also start small: “Trim this clip to the strongest 20 seconds and add readable captions.” Add details when the first result shows what needs changing. ## Choose a workflow when it helps The chips under a new chat's message box describe the kind of output, such as **Motion graphics or explainer**, **AI-generated video**, **Image**, or **Edit existing footage**. Choose one if it matches your task; you can also describe the task without choosing a chip. For a specific workflow, type `$` to open the skill picker. Type `/` to see available commands. These are optional shortcuts; an ordinary request is enough to begin. The model picker chooses the agent answering your chat. To choose which image, video, voice or music model, or which creative app, Voyager uses, click the **Preferred creative apps and media models** button beside it; see [Choose models and apps](/guides/choose-models-and-apps). You can also name a model in your message. [Chat accounts and generation accounts](/account/accounts-and-agents) pay for different parts of the work. ## Speak instead of typing Click the microphone in the message box (**Voice input**) or press ⌘ ⇧ Space (Ctrl Shift Space), speak, then click or press it again to stop. You can also hold the shortcut while you talk and let go when you're done. Your words appear in the message box, ready to edit before you send. Speech is turned into text on your computer; the audio never leaves it. To hide the microphone, or to choose the language and microphone, open **Settings → General → Advanced → Voice input**. ## Guide work already in progress You can send a follow-up while the agent is working. **Settings → General → Advanced → Messages sent while it's working** controls what happens: | Choice | Behavior | | - | - | | **Redirect now** | Send the follow-up into the current turn. This is the default. | | **Wait until done** | Hold the follow-up until the current turn finishes. | A queued message waits in the chat until it sends. Click **Send now** on one to stop the agent's current step and send it next. Queued messages are saved: they come back after a reload, a quit or a crash. Use **Stop** if you need the agent to stop its current turn. Check the **Background** panel or the activity tray above the message box as well if it has already started a generation or render; stopping the chat is not a promise that submitted work has been cancelled. ## Check that Voyager understood Read the first response or plan. Check the format, source files, text and paid work before continuing. If you want to answer every question yourself, choose **Always ask** in the questions control below the message box. ## Common problems > [accordion] An image is “too large to attach, even after compression” > > Voyager shrinks large images to fit when you attach them, but a very large image can still be > refused. Other files have no size limit. Put the image in the project folder and reference it > from **Files** or with `@`, or use **+ → Add folder**. > [accordion] The result feels generic > > Add a concrete audience, exact wording and one visual reference. Describe what makes that > reference useful, such as its lighting or pacing, rather than asking only for something > “professional.” > [accordion] The agent wants to generate media I do not need > > Say which existing assets it should use and whether paid generation is allowed. For text and > shapes, ask for [motion graphics](/guides/motion-graphics). Set your [approval and spending > preferences](/guides/approvals-and-spending) before continuing. > [card] [Approvals and spending](/guides/approvals-and-spending) > > Decide when questions wait for your answer. > [card] [Review and revise](/first-video/review-and-revise) > > Give feedback on the exact frame or moment. # Fix generation and credit problems Source: https://docs.voyager.so/help/generation-problems Use the card or notification Voyager shows to resolve credit limits, provider failures, and waiting generations. When Voyager can't run a request, the chat shows a card with the reason and the buttons that fix it, and the agent says what is blocked in one sentence. Your request is kept, so you can continue once it's fixed. Check the **Activity** tray above the message box, or the **Background** panel, before trying a generation again. Model names, plan names, workspaces, and times vary in the messages below. > [!WARNING] > > A new attempt can create a new charge. If a notification says **Continued on** another provider (for example **Higgsfield is out of credits**, **Continued on Voyager credits**), check that generation first. Voyager may already have kept the work going on a different account. ## Free's 5-hour limit reached Your workspace is on [Voyager Free](/account/plans-and-credits#voyager-free) and this request doesn't fit in its 5-hour limit, which also counts generations still running. The card says when Voyager picks up again. If it says **This month's free credits are used**, the monthly allowance is used up until the date shown. 1. Choose **Retry at** the time shown to have Voyager wait, or, in chat, the option that waits and sends on its own. 2. To keep going now, choose **Continue in a new chat with Claude** (or with ChatGPT or your API key, whichever you have connected). Voyager moves your request to a new chat on that account. 3. To raise the limits, choose the upgrade option. Free has no credit packs or auto-reload. **Check:** The request runs at the time shown, or in the new chat on your own account. **Still stuck:** Send the card's title and the workspace through **Send feedback…**. ## Veo 4 starts on Starter The model name and plan vary. The model you asked for isn't on your plan. On Free the card also says what Free covers (some images and stock narrations a month) and what Starter adds. Video, music, sound effects and custom voices need a paid plan or your own key; managed voices, cloud computers and Cloud GPUs need a paid plan. 1. Choose **See plans** to upgrade to the plan named. On the top plans the button reads **Plan & billing**. 2. Or choose **Use my own key** and connect a [generation provider](/account/generation-providers), such as fal or ElevenLabs, then ask the agent to use it. 3. Or ask the agent to choose a model your plan includes. This is not an out-of-credits problem. Adding credits alone does not unlock the model, and Voyager does not switch to your own keys unless you ask. **Check:** The selected model is on your plan or account and the generation begins. **Still stuck:** Send the model name, the plan shown in Voyager, and the card through **Send feedback…**. ## Out of credits The workspace doesn't have enough Voyager credits for this request. The card can say how many it needs and what your balance is. 1. Choose **Add credits** to buy a pack, or **Turn on auto-reload**. 2. Or wait for credits to reset, or connect your own media key. 3. When credits are back, choose **Resume after adding credits** (or **Retry**) on the card. **Check:** The request runs. Earlier completed results remain usable. **Still stuck:** Use **Send feedback…** from the chat's menu and include the job ID, workspace, and the card. ## Your payment didn't go through The last Voyager payment failed, which pauses work on Voyager credits. 1. Choose **Update payment** and follow the steps. 2. Retry the request, or choose your own Claude or ChatGPT subscription to continue. **Check:** The card clears and chat or generation through Voyager responds again. **Still stuck:** Send the warning to support privately, without card details. ## A Voyager seat is needed You're in this workspace, but you don't have a seat on its Voyager plan. The sidebar and **Settings → Account** show **Needs a seat**. 1. Choose **Open seats**, or ask a workspace admin to give you a seat. In **Settings → Account** you can also choose **Ask for a seat**. 2. If you have another workspace with a plan, choose **Switch to** that workspace. 3. Or select your own Claude or ChatGPT subscription for chat and your own media keys for generation. If the card says the workspace's plan is for one person, an admin can choose **Switch to Team**; others can choose **Ask to switch to Team**. See [Team plans](/account/plans-and-credits#team-plans). **Check:** The card clears for the intended workspace. **Still stuck:** Include the workspace name and card in a private support request. ## Chat through Voyager is paused An admin turned off chat through Voyager for this workspace, or chat reached the monthly limit an admin set. 1. Ask a workspace admin to turn chat back on or raise its limit in the [billing dashboard](https://voyager.so/dashboard/billing). From the app, **Settings → Account → Manage billing** opens it. 2. Or select your own Claude or ChatGPT subscription in the model picker. **Check:** Chat responds after the setting changes or you choose another account. Buying credits alone does not change an admin's chat setting or limit. **Still stuck:** Send the card and workspace name through **Send feedback…**. ## Voyager couldn't run this request Voyager refused the request for a reason the other cards don't cover, such as the workspace's daily spending limit or no plan. 1. Choose **Plan & billing** to check what the request needs. 2. Retry only the stopped work afterward. Don't keep buying credit packs to fix a limit that is not the balance. **Check:** A new request is accepted after the limit clears or the plan change takes effect. **Still stuck:** Include the card and workspace in **Send feedback…**. ## “Higgsfield is out of credits”, “Continued on Voyager credits” A provider in your list ran out of credits, and Voyager moved the generation to the next one. The title names the provider that ran out, such as **fal is out of credits**. The line below starts **Continued** and names where the work went. For a batch it reads, for example, **3 generations continued on Voyager credits**. 1. Don't submit the work again: it is already running on the next provider. Check it in **Activity**. 2. Choose **Open Apps & Models** to top up the provider that ran out, or change the order with **Image, video and voice order** in **Apps & Models → Providers**. 3. If you don't want work to move to another account, turn off **If one can't finish, try the next provider** in that dialog. See [Generation providers](/account/generation-providers). **Check:** The job finishes, and the next generation uses the provider you intended. **Still stuck:** Include the job ID and the full notification in **Send feedback…**. ## Automatic fallback is off, so nothing was generated The chosen provider ran out of credits, and Voyager stopped rather than using another account, because **If one can't finish, try the next provider** is off. 1. Read the notification title to identify the provider. It may say **Out of Voyager credits** or, for example, **fal is out of credits**. 2. Choose **Open Apps & Models** and check that provider in **Apps & Models → Providers**. 3. Add funds to that account, or deliberately change which provider should pay before trying the stopped work again. > [!WARNING] > > Turning **If one can't finish, try the next provider** on allows Voyager to try other providers in your list, including accounts with separate bills. See [Generation providers](/account/generation-providers). **Check:** The next attempt uses the provider you intended. For a batch, the notification may instead say how many generations didn't run. **Still stuck:** Include the notification and provider name in a support request. ## Higgsfield plan credits ran out Voyager used up the available Higgsfield plan credits and continued on another connection. 1. Read the rest of the notification. It names where the generation continued, such as your Higgsfield API key. 2. Inspect the existing job; do not submit another copy if it is progressing. 3. Before the next generation, review the Higgsfield card in **Apps & Models → Providers** and the [Higgsfield plan and API key](/account/generation-providers) difference, and change the order or your saved connections if needed. **Check:** The current result finishes, and the next job uses the account you chose. **Still stuck:** Include the job ID and the full fallback notification in **Send feedback…**. ## Voyager sign-in expired Voyager can no longer use the saved account sign-in. A Higgsfield connection can show **Higgsfield sign-in expired** instead. 1. Choose **Reconnect** in the notification, or open **Settings → Account** (Voyager) or the Higgsfield card in **Apps & Models → Providers**. 2. Finish signing in through the browser and choose the intended workspace if asked. 3. Check the existing job: it may already have continued on another provider. **Check:** The account is connected again, and new work can use it. **Still stuck:** Follow [Setup problems](/help/setup-problems), then send the sign-in error and affected job through **Send feedback…**. ## fal rejected your key The provider did not accept its saved API key. The same notification can name Google, ElevenLabs, or another key-based connection. 1. Choose **Update key**, or open that provider's card in **Apps & Models → Providers**. It is listed under **Needs attention**. 2. Check the key in your provider account. If it has expired, been revoked, or belongs to the wrong account, choose **Replace API key** and paste the new one. 3. Review any **Continued** notification before retrying the generation. **Check:** The card moves back to **Connected**, and a new job can use the intended account. **Still stuck:** Tell support the provider and exact error. Never send the API key. ## fal is unavailable The provider could not handle the request. The notification may name another provider or say it **is busy**. 1. Read whether Voyager continued on another provider. 2. If it did, watch the existing job in **Activity**. 3. If it stopped, wait before retrying or choose another provider after reviewing its billing. **Check:** The original job completes, or a later attempt progresses after the provider recovers. **Still stuck:** Send the model, provider, job ID, and time of the failure through **Send feedback…**. ## No provider available Your chat account (Claude, ChatGPT or another agent) failed to start or failed its check. Voyager keeps retrying it in the background and checks again when you come back to the window, so it usually recovers without a restart. 1. Choose **Retry** beside the message to check right away. 2. If it still can't run, choose **Open provider settings** and follow what its card in **Apps & Models → Providers** says, such as **Sign in again** or **Update**. **Check:** The message clears and you can send to the chat. **Still stuck:** See [Setup problems](/help/setup-problems). ## Waiting for a free slot… Your plan's available parallel generations are already running. The message can include how many are running. 1. Leave the waiting job in place; it starts automatically when a slot opens. 2. Check **Activity** to see which generations are running. 3. If Voyager eventually stops waiting, let a running generation finish before asking it to start the stopped work again. That wait is not a second generation, and the refused attempt has not been charged. Plans allow different amounts of parallel work; see [pricing](https://voyager.so/pricing). Chat through Voyager has a similar wait, **Waiting for a free chat slot…**, when the workspace's other agents are busy. **Check:** The status changes from waiting to running when a slot is available. **Still stuck:** Include the waiting message, job ID, and the other jobs' statuses in **Send feedback…**. ## Waiting for auto-reload to top up credits… Auto-reload is buying credits so this job can start. 1. Let the existing job wait; do not start a replacement. 2. Check the auto-reload rule in **Settings → Account → Credits, usage and invoices → Credits** if the wait continues. 3. If the job stops with **Auto-reload did not top up the workspace's Voyager credits in time.**, fix the purchase or buy a credit pack, then ask the agent to restart the stopped work. **Check:** The balance increases and the waiting job starts, or the replacement starts after the original has stopped. A request refused while waiting for the top-up was not charged. **Still stuck:** Send the job ID and the auto-reload status to support. Do not send payment card details. ## The media provider rejected this request (provider\_rejected) The provider refused the inputs. The rest of the message may name an input or say that Voyager could not read a reason. 1. Read the full error and keep any **Voyager request ID** it includes. 2. Ask the agent to check the named input against the selected model's requirements, such as supported image size, video duration, or file format. 3. Make a changed attempt only when there is a specific input to fix. If the reason is unclear, stop and ask support rather than resubmitting unchanged inputs. Voyager does not try the next provider to fix rejected inputs. **Check:** The revised request is accepted and begins generating. **Still stuck:** Use **Send feedback…** and include the complete error, model, and Voyager request ID. ## The app stopped while submitting this generation. The provider may have accepted the generation before Voyager could confirm it. 1. Reopen the affected chat and inspect the original job in **Activity** or **Background**. 2. Check that provider account's generation history when available. 3. Ask the agent to inspect or collect the existing job before starting another paid generation. **Check:** You have a confirmed result or confirmed failure for the original job before making another attempt. **Still stuck:** Send the original job ID, approximate submission time, provider, and error through **Send feedback…**. # Get help and send feedback Source: https://docs.voyager.so/help/get-help Send feedback or ask the Voyager team for help, and review a support bundle before it is sent. Use **Send feedback** when you want the Voyager team to help with a specific problem or hear what could be better. For general questions, join the [Voyager Discord](https://discord.gg/voyagerai) or email [support@voyager.so](mailto:support@voyager.so). ## Find Send feedback Every entry point opens the same **Send feedback** dialog: * **Sidebar button:** beside your account at the bottom of the sidebar, the **Send feedback** button (a question-mark icon). When the sidebar is collapsed, the same button floats at the bottom left of the window. * **Account menu:** click your account at the bottom of the sidebar and choose **Send feedback…**. The menu also has **Community on Discord**, which opens the Voyager Discord, and **What's new**, which shows the latest changes in Voyager. * **Chat menu:** right-click a chat in the sidebar, or open its ⋯ menu, and choose **More → Send feedback…**. * **Command palette:** open it with ⌘ K (Ctrl K) and choose **Send feedback**. Searching for "help" or "support" finds it too. ![The open account menu at the bottom of the sidebar: the signed-in email, then Settings, Usage & credits and Appearance, then Send feedback…, Community on Discord and What's new, and Sign out.](https://mintcdn.com/voyager/gEgW5f4IO2eEELDK/images/screenshots/help-account-menu.light.png?fit=max\&auto=format\&n=gEgW5f4IO2eEELDK\&q=85\&s=aaa5003e0bb5d2b054d100e92e858824) The account menu at the bottom of the sidebar has Send feedback…. ## Send feedback about a chat 1. Open the chat, or start from that chat's menu, and choose **Send feedback**. **Attach this conversation** starts ticked. 2. In **What happened**, describe what you expected, what happened instead, and the last action before the problem. 3. Choose a **Category**, such as **I need help with a conversation**, **Something broke**, **It keeps failing**, or **Something was confusing**. 4. Leave **Attach this conversation** on if you want to share its support bundle, or untick it to send only your report and selected details. 5. Choose **Review files** and read the contents before sending. ![Send feedback dialog with Attach this conversation enabled and the support bundle files open for review.](https://mintcdn.com/voyager/dzNfJ3ErXafJEG4z/images/screenshots/help-dialog-bundle.light.png?fit=max\&auto=format\&n=dzNfJ3ErXafJEG4z\&q=85\&s=09c26e339e3fd09cc4a196159918d01b) Review the conversation bundle before sharing it with support. The bundle contains the chat transcript, tool-call summaries, errors, and diagnostics for this conversation. It does not attach original project files or media. Text you typed or pasted into the chat is included, as are file and folder names inside the project. Voyager removes paths, keys, and tokens it recognizes. If you see content you do not want to share, untick **Attach this conversation** and describe the problem without the bundle. 6. Choose **Send** to share the reviewed report with the Voyager team. If the reviewed bundle expires, Voyager rebuilds it and asks you to review the files again. The agent can suggest using **Send feedback**, but cannot send the bundle for you. ## Send feedback without a conversation If you open **Send feedback** without a chat, there is nothing to attach. You can also reach it from **Settings → Advanced → Privacy**. 1. Fill in **What happened**. 2. Choose a **Category**. 3. If you opened feedback from a chat, review **Include details from this chat**. It can include the app version, chat identifier, provider and model, and recent errors. 4. Choose **Send**. Your written feedback is sent with your Voyager account. Without an attached conversation, it does not include a chat transcript or your files. ## Rate a reply Under each of the agent's replies, choose **Helpful** (thumbs up) or **Not helpful** (thumbs down). **Not helpful** asks **What went wrong?**, with reasons such as **Didn't do what I asked** or **Wrong or made up**, and an optional comment; choose **Send**. A rating is sent with the chat's details, never its messages. The thumbs are hidden when **Help improve Voyager** is off in **Settings → Advanced → Privacy**. ## If you cannot sign in or send the report When signed out, the dialog offers **Save bundle…** for an attached conversation or **Copy report** for plain feedback. It also offers **Open Discord** and **Connect Voyager**. Save or copy the report, then contact [support@voyager.so](mailto:support@voyager.so). You can also reach the team through the [Voyager Discord](https://discord.gg/voyagerai). > [!NOTE] > > Send support bundles privately by email or direct message. Do not post them in a public Discord channel. If the app will not open, email support directly. Include the startup message and any relevant log named in its dialog. See [Setup problems](/help/setup-problems) for startup recovery. ## What helps us investigate * What you were trying to make and what you expected to happen. * The exact error message and approximate time it appeared. * Your app version from **Settings → General → Updates**, plus your operating system. * The selected agent, model, and generation provider, if relevant. * The job or Voyager request ID shown with a failed generation. * Whether the problem happens every time or only with this chat or file. Keep passwords, API keys, sign-in links, and payment details out of your report. ## We may have received this. Check with us before sending again. Voyager could not confirm whether the report arrived. 1. Do not immediately send another copy. 2. Contact the team by email or Discord with the approximate send time and a short description. **Check:** The team confirms whether the original report arrived before you resend it. For more about optional reporting and what stays on your computer, see [Privacy](/help/privacy). # Understand what Voyager shares Source: https://docs.voyager.so/help/privacy See what stays on your computer, what connected services receive, and how to control optional sharing. Voyager keeps your working files on your computer and sends information to the connected services needed for the work you request. For example, a local recording is saved on your computer. Asking an online model to use that recording can send it, or information from it, to that service. Keeping files locally does not mean every AI task runs locally. ## Your files and connected services Chats, settings, and project files have local storage locations. See [Data locations](/reference/data-locations) to find them. Your chosen chat provider receives the conversation and context needed to answer. A media provider receives the prompt and inputs needed for a generation. The provider you use has its own terms and data practices. With [**If one can't finish, try the next provider**](/account/generation-providers#understand-automatic-fallback) on, a generation can go to another provider in your list. API keys added through the account controls are saved in your system's secure storage, not in project files. Other connected tools can manage their own credentials separately. ## Control optional sharing Open **Settings → Advanced → Privacy**. It has three checkboxes: **Help improve Voyager**, **Let Voyager change features for me** and, under **Feedback**, **Let the agent report problems with Voyager**. All three are on by default. Setup shows the usage and agent-report choices as switches, with the second labelled **Let the agent report problems to the Voyager team**. You can change them at any time. ![Settings → Privacy. Three checkboxes, all checked: Help improve Voyager, Let Voyager change features for me and Let the agent report problems with Voyager, each with a short description. Under the first are a Clear recommendation history button and a collapsed See what's collected section; the last sits under a Feedback heading.](https://mintcdn.com/voyager/gEgW5f4IO2eEELDK/images/screenshots/privacy-page.light.png?fit=max\&auto=format\&n=gEgW5f4IO2eEELDK\&q=85\&s=4aad7912ab35565576fc311436a22e30) Settings → Privacy, with all three checkboxes ticked and See what's collected expanded. ### Help improve Voyager This shares feature usage, performance, and error information associated with your Voyager account. It is account-linked data, not anonymous usage statistics. Usage events include the app version, operating system and interface language, when the app is open and how many minutes it is in active use, provider and integration categories, which Voyager skills and commands the agent used, export file types, billing buttons clicked, how long operations take, their outcomes, and sanitized error codes. These events do not include your conversation text, prompts, recordings, file contents, API keys, file paths, or command arguments. Sign-in failure events sent before an account is connected use an installation identifier. When you sign in and when it checks your credit balance, Voyager sends a one-way hash of this computer's system ID, so Voyager can limit free plans to one per computer. The ID itself isn't sent. This happens whether or not usage statistics are shared. The same option controls crash reports. These describe the error, where it happened in Voyager, and the app and operating system versions. Crash reports also record the IP address they came from and a rough location based on it. A crash of the app itself can also include a snapshot of the crashed process's memory, which may contain information that was in memory at the time. Turning this option off clears unsent usage events and stops optional usage and crash reporting. Necessary service and billing records remain separate, as do other providers' own reporting settings. ### Clear recommendation history Voyager suggests techniques for new chats from your setup answers and the techniques you use. That history stays on this computer. Choose **Clear recommendation history** to start fresh; Voyager confirms with **Recommendation history cleared.** ### Let Voyager change features for me This lets Voyager turn features on or off for you without an app update, using your Voyager account ID. When it's off, Voyager never checks, and every feature keeps the setting built into your version. ### Let the agent report problems with Voyager When this is on, the agent can send the Voyager team a short note about repeated failures or frustration with the app. The note uses the agent's own words and includes the chat's identifier, model, app version, and recent errors. Paths are shortened. These reports require a Voyager sign-in. Each one appears as a tool call in the chat. This setting is separate from **Help improve Voyager**: turn off both if you want to disable both kinds of optional sharing. ## Check the Voyager expert setting too **Settings → Creative → Voyager expert** is on by default. When you start a chat, and when the agent asks it later in the chat, Voyager sends your message, attachment names and types, the recent conversation and the context the agent already gets (project brief, creative preferences, memory and connected apps) through your Voyager account to a model that suggests how to make what you asked for. Turn this setting off if you do not want that advice. It is separate from usage statistics; turning off **Help improve Voyager** does not turn it off. The message still goes to whichever chat provider you choose when you send it. ## Local recording and voice input Screen recordings are saved locally; recording alone does not send or edit them automatically. Voice input transcribes speech on your device, and its audio stays there. When you send the transcribed text as a chat message, it goes to your selected agent like other chat text. Local media search processes footage on your computer. Choosing a separate hosted transcription or generation service sends the inputs needed for that request. ## Feedback and support bundles **Send feedback** sends your written report with your Voyager account. It can include app and error details. Opened without a chat, there is nothing to attach. Rating a reply **Helpful** or **Not helpful** sends the rating, any reason or comment you add, and the chat's details, never its messages. The rating buttons appear only while **Help improve Voyager** is on. **Send feedback…** from a chat opens with **Attach this conversation** ticked. The support bundle includes the transcript, tool-call summaries, errors, and diagnostics for that chat. It does not attach your original files or media, but text you typed or pasted into the conversation is included. File and folder names inside the project can also appear. Voyager removes paths, keys, and tokens it recognizes. Always use **Review files** before sending: automatic redaction is not a substitute for checking your own content. An agent cannot send a support bundle on your behalf. See [Get help](/help/get-help) for the review and sending steps. If you save a bundle to share manually, send it privately to the Voyager team rather than posting it in a public channel. # Fix setup and sign-in problems Source: https://docs.voyager.so/help/setup-problems Resolve common problems opening Voyager, completing setup, connecting accounts, and finding models. Match the message below to the one in Voyager. If the app opens, check your Voyager sign-in in **Settings → Account**, and Claude, ChatGPT and other providers in **Apps & Models → Providers**. ## Complete signing in on the web Voyager is waiting for the browser sign-in to finish. 1. Switch to the browser window opened by Voyager and finish signing in or creating your account. 2. If the page did not open, choose **Reopen sign-in** in Voyager. If the browser still doesn't open, click **Copy link** under **Browser didn't open?** and paste the link into a browser on this computer. 3. Finish the browser flow on the same computer, then return to Voyager. 4. If you are asked to **Choose a workspace**, select the workspace you want to use. ![The Voyager sign-in screen reading Complete signing in on the web, with the line Voyager opened sign-in in your browser. Come back here once you've signed in or created your account., and Reopen sign-in and Cancel buttons.](https://mintcdn.com/voyager/yRytHenCA6FFAhzA/images/screenshots/setup-signin-waiting.light.png?fit=max\&auto=format\&n=yRytHenCA6FFAhzA\&q=85\&s=832d172417f33324d93186178d82ccf8) Finish in the browser; Reopen sign-in brings the page back if you closed it. **Check:** Voyager shows your account and lets you continue setup. **Still stuck:** Tell [support](/help/get-help) whether the browser reported success and what Voyager shows afterward. Do not send the sign-in URL. ## Voyager login timed out. Try connecting again. The browser sign-in did not finish before the attempt expired. 1. Close the old sign-in tab. 2. Start a fresh sign-in from Voyager. In **Settings → Account**, use **Sign in**, or **Sign in again** from the **Account actions** menu (**⋯**) under **Signed in**. 3. Complete the newest browser attempt, then choose a workspace if requested. The messages **The workspace choice timed out. Sign in again.** and **That workspace choice expired. Sign in again.** need the same fix. **Check:** The **Voyager** card shows your account and workspace rather than a waiting message. **Still stuck:** Send the exact error and approximate time of the failed attempt to [support](/help/get-help). ## No agent connected yet Voyager is signed in, but no chat agent is ready yet. On the **AI agent** step: * If the **Voyager** row is usable, click **Continue with Voyager** to go on with Voyager's own models. * Otherwise click **Skip for now** to finish setup without an agent, then connect one later in **Apps & Models → Providers**. That includes local models (for example Ollama or LM Studio) through an **API models** provider. To connect one during setup: 1. On the **AI agent** step, click **Set up** on [Claude](/setup/connect-claude), [ChatGPT](/setup/connect-chatgpt) or [Gemini](/setup/voyager-models#gemini), or click **Use an API key instead**. 2. Follow the steps in the dialog. If Voyager opens an installation terminal, press Enter to run the command shown and wait for it to finish. 3. Wait for the row to show **Connected**, then click **Done** and **Continue**. A paid Voyager plan is optional. A workspace on Voyager Free can use Voyager's models as its agent, and your own Claude, ChatGPT or Gemini, or your own API key, becomes your default agent on any plan. A media key alone does not connect a chat agent. **Check:** The agent's row shows **Connected**, or setup moves on to **Video & images** when you continue without one. **Still stuck:** Send support the status shown next to the agent you tried to connect and any installation error. ## Setup is stuck checking agents The AI agent step shows a spinner on a row, and the buttons at the bottom stay off. 1. Wait a moment: Voyager checks the agents installed on your computer when the step opens. 2. Click **Refresh** above the agent list to check again. 3. If a check never answers, **Skip for now** turns on after about 15 seconds. Use it, then connect the agent later in **Apps & Models → Providers**. **Check:** Each row shows **Connected** or **Set up**, and a button at the bottom is available. **Still stuck:** Send support the name of the agent whose row keeps spinning. ## Upgrade Claude Code or Codex Voyager found your own Claude Code or Codex install, but its version is too old for Voyager, has a known problem, or is missing newer features. In setup, its row in the **Set up** dialog shows **Needs upgrade**; after setup, a notice such as **Upgrade Claude Code** appears. 1. Choose **Upgrade** (or **Upgrade in Voyager**) on the row, or **Upgrade now** on the notice. 2. Wait for **Upgrading…** to finish. If it can't upgrade it for you, choose **Upgrade in a terminal instead** and run the command shown. 3. Return to setup or the chat. **Check:** The row shows the agent as ready, without **Needs upgrade**. **Still stuck:** Send support the version shown and any upgrade error. ## A provider couldn't start A banner says a provider such as Claude or ChatGPT can't run right now. This can happen after a network drop, a sleep or an update. 1. Wait a moment. Voyager checks again on its own, and again when you come back to the window. 2. To check now, choose **Retry** on the banner. 3. If it still fails, open that provider in **Apps & Models → Providers** and follow what its card says. **Check:** The banner goes away and the chat can send. You don't need to restart Voyager. **Still stuck:** Use **Send feedback…** from the chat's menu and include the provider name and the banner text. ## Voyager could not use your system's secure storage. Unlock it and try again. Voyager cannot read or save the credentials it needs. > [tab] macOS > > 1. Unlock your login keychain in Keychain Access if it is locked. > 2. Return to **Settings → Account** and choose **Check connection** from the **Account actions** menu (**⋯**), or start sign-in again. > [tab] Windows > > 1. Read the full error. If it names Smart App Control or Application Control, follow the next section. > 2. Otherwise, restart Voyager in your usual Windows user session and try the connection again. > [tab] Linux > > 1. Make sure a Secret Service keyring is available and unlocked in your desktop session. > 2. Reopen Voyager in that session and retry the connection. **Check:** The account no longer shows **Credential storage unavailable**. **Still stuck:** Send support the complete error and your operating system. Do not delete your saved profile to repair a sign-in. ## Windows Smart App Control blocked Voyager's credential storage component. Windows has blocked part of the app; repeating sign-in will not remove that block. 1. Update to the latest Voyager, which is code signed, and try again. If it's still blocked, see [Smart App Control](/get-started/install-windows#smart-app-control) for the remaining option. 2. If the message says **A Windows Application Control policy blocked Voyager's credential storage component.**, ask the administrator of the PC whether Voyager can be allowed. 3. Once the block has been resolved, reopen Voyager and try sign-in again. **Check:** Voyager can save the sign-in without the same block message. **Still stuck:** Send support the exact Windows message, your Voyager version and whether the PC is managed by your organization. ## Still connecting Voyager has not been able to finish opening the workspace. 1. Choose **Reload** on the recovery screen. 2. If it returns, quit and reopen Voyager. 3. If startup fails with a dialog, follow **Voyager could not start its local server.** below. **Check:** Your chats or the setup screen appear. **Still stuck:** Send support a screenshot of the recovery screen and your app version. ## Could not read settings Voyager could not load your saved settings. 1. Choose **Retry**. 2. If the same message returns, quit and reopen Voyager. 3. Contact [support](/help/get-help) before deleting or resetting your profile. **Check:** Settings and the main app open normally. **Still stuck:** Include the exact message and whether it began after an update, a restart, or a settings change. ## Voyager could not start its local server. Voyager could not open the local workspace it needs to run. 1. Read the details in the dialog and choose **Try Again** once. 2. If it fails again, choose **Open Profile Folder** to locate the saved data and the logs named in the dialog. 3. If **Repair and Start** is offered, read the repair confirmation before deciding whether to continue. > [!WARNING] > > Repair preserves the damaged data, but parts that cannot be recovered may leave earlier chats and projects missing from the app. Your project folders and files are not affected. Contact support first if you need help deciding. **Check:** Voyager opens and your expected chats are visible. Check your project folders separately if repair could not recover the app's history. **Still stuck:** Email [support@voyager.so](mailto:support@voyager.so) with the dialog details and relevant logs. Do not send your entire profile unless support specifically asks for it. ## ChatGPT usage limit reached The selected ChatGPT account has reached a usage limit for Voyager. 1. Choose **Manage usage** and review that account's usage and credit settings in ChatGPT. 2. Wait for available usage or make the change offered by ChatGPT. 3. Try the chat again, or deliberately choose another connected account or model. **Check:** The next request completes using the account you selected. Voyager does not automatically retry this chat error with another payer. **Still stuck:** Use **Send feedback…** from the affected chat's menu and include the account and model names. ## Claude usage or spend limit reached A chat stops with a message such as “You've hit your monthly spend limit” or “You've hit your session limit”. Your Claude account has used up its plan's usage, its monthly spend limit or its usage credits, or Claude is briefly rate limiting it. The message under the chat says when the limit resets. 1. To keep going on another Claude account or subscription, click **Switch account**. If you use a Claude Code install you signed in to yourself, the button reads **Provider settings** instead. Sign in to the other account from the **Claude** card in **Apps & Models → Providers**. Your browser opens on Claude's sign-in page. Sign in with the other account (if the browser is already signed in to the limited one, switch accounts there first), then come back to Voyager. 2. To raise the limit instead, click **Open usage settings**. It opens your account's usage page on claude.ai. 3. Click **Retry** (or **Continue**) to carry on, or wait until the limit resets. If the message says Claude is using a token from your shell environment, **Switch account** isn't offered: Claude Code uses that token ahead of any sign-in. Remove the variable it names from your shell profile, then quit and reopen Voyager (see [Connect Claude](/setup/connect-claude)). **Check:** The next reply arrives. After switching account, the **Claude** card in **Apps & Models → Providers** shows you signed in. **Still stuck:** Use **Send feedback…** from the affected chat's menu and include the limit message. ## Reconnect your ChatGPT account Voyager needs a renewed sign-in for the ChatGPT account selected in this chat. 1. Click **Reconnect** on the message in the chat. It opens the ChatGPT card in **Apps & Models → Providers**. 2. Choose **Reconnect account** and finish the browser flow. 3. If the browser does not return to Voyager, follow the sign-in panel's instruction to paste the final page address there. Keep that address private. **Check:** The account shows **Signed in as** with the expected account, and the chat can continue. **Still stuck:** Send the connection error through **Send feedback…** without including the sign-in address. ## ChatGPT didn't allow this request Voyager's access to your ChatGPT plan does not cover this request. 1. Choose another available model or account in the model picker. 2. Send the request using that selection. Signing in again does not change this permission. **Check:** The request runs on your chosen model. Switching providers can continue in a new chat. **Still stuck:** Include the refused model and the full message in **Send feedback…**. ## ChatGPT plan unavailable for this account The account, workspace, or its policy does not currently allow this use of the ChatGPT plan. 1. Check that you selected the intended ChatGPT account. 2. Choose another connected agent account to continue. If the message specifically suggests your existing Codex CLI, follow [Connect ChatGPT](/setup/connect-chatgpt) to use that connection. **Check:** The request runs using an available account. This message does not by itself mean your saved sign-in was lost. **Still stuck:** Send the full message, account type, and selected model through **Send feedback…**. ## A model is missing The account's model list depends on its plan, connection, installed version, and your display settings. 1. In **Apps & Models → Providers**, confirm the intended account is connected and signed in. 2. Turn on **Show every AI option** in **Settings → General → Advanced → AI choices** if you need the full model list. 3. In the model picker, click **Not seeing the models you expect?** to open **Model troubleshooting**. Each account shows its status. If an account is out of date, click its **Update to …** button (or **Copy update command** and run it). Otherwise click **Open in Providers** to check that account's sign-in and plan. 4. Choose **Check again** after changing the connection or updating. **Check:** The model appears under the intended account in the picker. Check the account before sending: the same model available through Voyager can use Voyager credits. **Still stuck:** Send support the missing model name, account type, and the status shown on **Model troubleshooting**. # Find the right fix Source: https://docs.voyager.so/help/troubleshooting Start with the symptom you see and find the next step for setup, accounts, generation, or updates. Start with the message or symptom you see. If a generation may already be running, check the chat's **Background** panel before trying it again. ## I cannot open Voyager or finish setup An installation, sign-in, or agent connection needs attention. 1. Check that your computer meets the [requirements](/get-started/requirements). 2. Open [Setup problems](/help/setup-problems) and follow the section matching your message. 3. If Windows mentions Smart App Control, see [Install on Windows](/get-started/install-windows) and the Smart App Control section of [Setup problems](/help/setup-problems). **Check:** Setup lets you continue once you are signed in to Voyager and an agent is ready. Your own Claude or ChatGPT, with a subscription or an API key, is enough; a paid Voyager plan is optional. **Still stuck:** Send support the exact message, your operating system, and the setup step where it appears. ## My agent cannot answer, or a model is missing The selected agent account may need a sign-in, an update, or available usage. 1. Check the account selected in the chat's model picker, then open **Apps & Models → Providers** and look at that provider's card. For a Voyager model, check your sign-in in **Settings → Account**. 2. If a banner says a provider couldn't start, wait a moment or choose **Retry**. Voyager checks again on its own, so you don't need to restart the app. 3. Follow [Setup problems](/help/setup-problems) for ChatGPT limits, reconnecting, or missing models. 4. If a card in the chat names Voyager credits, a plan, a seat or a limit, find it in [Generation problems](/help/generation-problems). Check your plan and credits in **Settings → Account**. **Check:** Send a short text request with the intended account selected and confirm the agent answers. **Still stuck:** Use **Send feedback…** from the affected chat's menu and include the account and model names. ## A generation failed, is waiting, or used a different account Media generation has its own accounts, balances, and availability. 1. Read the notification and the job's status in the chat's **Background** panel. 2. Find that message in [Generation problems](/help/generation-problems). 3. Check [Generation providers](/account/generation-providers) if the notification says the job continued elsewhere. > [!WARNING] > > Starting another generation may create another charge. If Voyager cannot confirm whether the first request started, inspect the existing job and provider history before retrying. **Check:** Confirm whether the original job completed, stopped, or is still waiting before continuing the batch. **Still stuck:** Send the job or Voyager request ID, exact error, selected model, and approximate time through [Send feedback](/help/get-help). ## I cannot find my finished video The result is a file in your chat or project folder, or in your chosen delivery folder. 1. Look for the finished video in the chat or project **Outputs**. 2. Follow [Find your file](/first-video/find-your-file) to open or reveal it. 3. If the generation completed but the agent has not presented a final video, ask it to locate the completed outputs and finish the edit. **Check:** Open the file from its folder and play it. **Still stuck:** Include the chat and the name of the missing result in a support request. ## Screen recording or an app connection is unavailable Some features need an installed creative app, permission, or a supported platform. 1. Check the feature's platform in [Requirements](/get-started/requirements). 2. On Mac, follow [Allow computer control](/guides/computer-control) for screen access or recording. 3. For a creative app, check [Connect creative apps](/setup/creative-apps). **Check:** Open the recording control or connected app again after completing its setup. **Still stuck:** Tell support which app or feature you tried, your platform, and the exact permission or connection message. ## An update will not download or install The download may have failed, or your installation may need a manual update. 1. Open **Settings → General → Updates** and read the status. 2. Follow [Update Voyager](/help/updates) for the matching message and platform. **Check:** After reopening Voyager, verify the version in **Updates**. **Still stuck:** Include the version before the update, the version offered, and the error in your [support request](/help/get-help). # Update Voyager Source: https://docs.voyager.so/help/updates Download and install Voyager updates, get early versions, and recover from update problems. Voyager downloads updates in the background by default and lets you choose when to restart. ## Install an update 1. Open **Settings → General → Updates** to see your current version and update status. 2. Choose **Check for Updates**. If automatic downloads are off, choose **Download** when an update is available. The notification calls this **Download update**. 3. Keep working while the download completes. The notification shows its progress. If a download drops, Voyager tries again by itself a few times before it reports a failure. > [!WARNING] > > Restarting can interrupt active work. Finish your recording or local render and save any unsent message before continuing. 4. When you see **Update ready to install**, choose **Restart to update**. To leave it for now, choose **Remind me tomorrow**. You can also quit normally and get the update on the next launch. ![The Update ready to install notification with Restart to update and Remind me tomorrow buttons.](https://mintcdn.com/voyager/gEgW5f4IO2eEELDK/images/screenshots/update-toast-ready.light.png?fit=max\&auto=format\&n=gEgW5f4IO2eEELDK\&q=85\&s=c1fb4cd58ed6b0b881a02a1f4a03a983) Restart when you are ready to install the downloaded update. While an update waits, the bottom of the sidebar shows **Update available**, or **Update ready · Restart** once it has downloaded. Click it to download or to restart and install. ![The bottom of the sidebar with an Update ready · Restart button above the account menu.](https://mintcdn.com/voyager/gEgW5f4IO2eEELDK/images/screenshots/help-sidebar-update.light.png?fit=max\&auto=format\&n=gEgW5f4IO2eEELDK\&q=85\&s=ad9cebc39e4a7e964a9cd75ac4cd7bce) The sidebar button stays until you restart, even after you close the notification. On Windows, Voyager closes while the installer runs. A small window says **Voyager is updating. It opens by itself when the update finishes.** Wait for Voyager to reopen. **Check:** Return to **Settings → General → Updates** after reopening. The version should match the update you installed. You can also check through **Voyager → Check for Updates...** on macOS or **Help → Check for Updates...** on Windows and Linux. ## Choose when to download Turn **Download updates automatically** on or off in **Settings → General → Updates**. Turning it off does not cancel a download already in progress. Downloading an update does not restart Voyager while you work. After a download, the same section's button reads **Restart Voyager**. ![The About section of Settings → General: Version with an Up to Date button, the Download updates automatically switch turned on, and Community with an Open Discord button.](https://mintcdn.com/voyager/gEgW5f4IO2eEELDK/images/screenshots/update-about-section.light.png?fit=max\&auto=format\&n=gEgW5f4IO2eEELDK\&q=85\&s=3a9f478e3e7580ca5ebae4d1b0865ccc) Version, automatic downloading and the update button are in General's Updates section. Nightly builds also show **Get early versions**, a switch in **Settings → General → Advanced**, under **About**. Turned on, Voyager follows Nightly; turned off, it follows Stable. Regular builds don't show it and always follow Stable. ## Intel build on Apple Silicon If your Mac has Apple silicon but you installed the Intel build, the sidebar shows **Intel build on Apple Silicon**. Choose **Download ARM build** to get the native build through the next update, then **Restart Voyager** once it has downloaded. ## Update manually Download the installer for your computer from [voyager.so/download](https://voyager.so/download), or sign in at voyager.so and use **[Download](https://voyager.so/dashboard/download)** in your dashboard. > [tab] macOS > > 1. Finish active work and quit Voyager. > 2. Open the new disk image and replace Voyager in **Applications**. > 3. Open the copy in **Applications**. > [tab] Windows > > 1. Finish active work and quit Voyager. > 2. Run the new Windows installer. > 3. Open Voyager after installation. If Windows blocks part of Voyager, see [Smart App Control](/get-started/install-windows#smart-app-control). > [tab] Linux > > The AppImage supports in-app updates. A `.deb` installation needs a manual update: when a new version is out, **Updates** says **Voyager … is available. Download the new .deb and install it to update.** > > 1. Finish active work and quit Voyager. > 2. Download the new AppImage or `.deb` for your installation. > 3. Replace your AppImage and make it executable, or install the new `.deb` using your package manager. > 4. Open the new version. See [Install on Linux](/get-started/install-linux) if it will not start. Replace the application; keep your profile and project folders. See [Data locations](/reference/data-locations) if you want to locate them before updating. ## Voyager's install is incomplete Some of Voyager's files are missing or were blocked, so it can't start. 1. On Windows, choose **Repair Voyager**. Voyager downloads its installer and reinstalls itself. Your chats, settings and projects stay. 2. On macOS and Linux, choose **Download Voyager** and install it again with the manual steps above. **Check:** Voyager opens normally. **Still stuck:** Send support the list of missing files shown in the message. ## Update download failed Voyager could not finish downloading the update. 1. Check your internet connection and available disk space. 2. Choose **Retry download**. 3. If the same failure returns, use the manual download above. **Check:** The notification reaches **Update ready to install**, or the manually installed version appears in **Updates**. **Still stuck:** Send [support](/help/get-help) your current version, offered version, operating system, and exact download error. ## Automatic updates are not available because no update feed is configured. This installation cannot obtain updates from inside the app. 1. Open [Download Voyager](https://voyager.so/dashboard/download). 2. Install the latest build for your platform using the manual steps above. **Check:** The new version appears in **Updates**. Linux `.deb` installations continue to need manual updates. **Still stuck:** Send support your version and which installer you used. ## Automatic updates on Linux require running the AppImage build. In-app Linux updates apply to the AppImage. 1. If you use `.deb`, install the latest `.deb` manually. 2. If you use AppImage, quit Voyager and open the downloaded AppImage itself. **Check:** Your version updates, or the AppImage's update controls become available. **Still stuck:** Include the installer filename and update message in your support request. # What is Voyager Source: https://docs.voyager.so/index Voyager is a desktop app where an AI agent makes videos, motion graphics and design assets with you, then keeps refining them from your feedback. Voyager is a desktop app for creative work. You describe what you want to make, and an AI agent makes it: a launch video, a motion graphic, a cut of your own footage, a set of social images. You watch the result, point at what needs to change, and the agent makes the next version. ![The Voyager window. The sidebar lists Apps & Models, Techniques and Library above your chats. In the middle, a chat shows a finished video in an inline preview. At the bottom is the message box, with its + button, the model picker and the Questions and permissions control set to Wait, then go ahead.](https://mintcdn.com/voyager/yRytHenCA6FFAhzA/images/screenshots/overview-workspace.light.png?fit=max\&auto=format\&n=yRytHenCA6FFAhzA\&q=85\&s=79a2179f6d8cd0e47a2d05a8ddd32e4f) Your chats in the sidebar, the finished video in the chat, and the message box at the bottom. ## What you can make > [card] Videos from an idea > > Generated shots, voiceover, music and titles, cut together into one video you can download. > [card] Edits of your own footage > > Trims, selects, captions and new aspect ratios from clips you already have. > [card] Motion graphics > > Kinetic type, title cards, explainers and overlays, with editable source you can change later. > [card] Images and design assets > > Stills, social posts and brand assets that follow your colors, fonts and logo. ## How you work with it 1. **Ask.** Write a request in a chat, like you would brief a person. Attach footage, a logo or a reference if you have one. 2. **Watch it work.** The agent plans the piece, asks you about anything it needs, and, depending on how you set questions, checks with you before it spends credits. See [Approvals and spending](/guides/approvals-and-spending). 3. **Review.** Play the result in Voyager. Comment on a moment, a time range or a spot in the frame. 4. **Revise.** Send your notes. The agent makes a new version and keeps the old one so you can compare. 5. **Keep the file.** Everything is saved as ordinary files in a folder on your computer. You don't need to know how to edit video or write code. You also don't need Git, a terminal or any developer tools. Not sure where to start? **Techniques**, in the sidebar, collects tested ways to make things, like animated posters, product films and voiceovers. Open one and start a chat with it. **Library**, just below it, keeps the brand kits, voices and elements you reuse across projects. ## What you need * **A Mac with Apple silicon** running macOS 15 or later, or a Windows 11 or Linux PC. A few features differ by platform; see [Requirements](/get-started/requirements). * **A Voyager account.** It's free to create, and you sign in during setup. * **An agent to chat with.** Use your own Claude, ChatGPT or Gemini, signed in with a subscription, your Google account or an API key, at no extra cost from Voyager. Or chat on Voyager models, which use your Voyager plan's credits, including [Voyager Free](/account/plans-and-credits#voyager-free). * **A way to pay for generated media**, if you want new images, video or audio made for you. Use your own media keys, or Voyager credits from a plan. Editing footage you already have doesn't need this. A Voyager plan is optional. See [Choose your setup](/get-started/choose-your-setup) to decide, and [voyager.so/pricing](https://voyager.so/pricing) for plans and prices. ## Start here > [card] [How Voyager works](/get-started/how-it-works) > > Five ideas that make everything else make sense. > [card] [Choose your setup](/get-started/choose-your-setup) > > Pick an agent and decide who pays for media. > [card] [Install Voyager](/get-started/requirements) > > Check requirements, then install on macOS, Windows or Linux. > [card] [Make your first video](/first-video/make-your-first-video) > > A guided first project, from request to finished file. # Where Voyager keeps your data Source: https://docs.voyager.so/reference/data-locations Where Voyager saves your projects, chat files, app data, logs and sign-ins on macOS, Windows and Linux. Voyager keeps two kinds of data in different places: * **Your work**: the videos, images, audio and source files the agent makes. These are ordinary files in folders you can see, open and back up. * **App data**: your chat history, settings, logs and connections. This lives in Voyager's profile folder, which you rarely need to open. ## Your work ### Chats without a project Each chat that isn't in a project gets its own folder the first time you send a message. The folders are named `conversation-…` and are created inside your **conversation files folder**: | | Default location | | - | - | | macOS and Linux | `~/Voyager` | | Windows | `C:\Users\\Voyager` | If you used an early version of Voyager, yours may be `~/Documents/Voyager` instead. Voyager keeps using it so your chats stay together. To use a different folder, go to **Settings → General → Advanced → Conversation files folder**. The change applies to new chats. Existing chats and their files stay where they are. ### Projects A project saves to the folder you picked when you created it. If you didn't pick one, Voyager makes a folder named after the project inside your conversation files folder. Renaming a project in Voyager doesn't rename its folder. Removing a project from Voyager removes it and its chats from the app, but **doesn't delete any files** on disk. ### Inside a project or chat folder You'll see your finished files, plus a few folders the agent uses as it works: | Folder | What's in it | | - | - | | `generated/` | Raw output from generation providers, one folder per job. Voyager dims it in the Files panel because you rarely need to open it. | | `brand/` | The brand kit files Voyager copied in for this project. | | `AGENTS.md` | The project's **Context**: the brief the agent reads at the start of every chat. Edit it from the project page. | Finished videos and images sit alongside the editable source the agent used to make them, so you can ask for changes later. ### Delivery folder To collect finished videos, images and exports in one place, set a **Delivery folder** in **Settings → Creative**. The agent saves finished work there and keeps working files in the project. Leave it empty to keep everything in the project. To find any file, right-click it in a chat and choose **Reveal in Finder** (**Reveal in File Explorer** on Windows, **Reveal in Files** on Linux), **Copy full path** or **Save video**. See [Find your file](/first-video/find-your-file). ### Free up space in a chat A chat without a project keeps every version, frame and working file the agent made. To clear what you no longer need, right-click the chat in the sidebar and choose **Keep only the finals…**. If the chat has no finished piece yet, the item is **Clear older versions and frames…**. * **Keep only the finals** keeps each finished piece, the files used to make it, your brand kit, voices and anything you brought in. Older versions and working files go. * **Clear older versions and frames** removes only what can be made again: frames already turned into a video, older versions of a file and temporary files. The dialog lists what stays and what moves before anything happens. Choose **Move to Trash** to go ahead. Files go to your computer's Trash, where you can put them back until you empty it. Voyager also offers this for chats you haven't used in two weeks, with a **Free up … from older chats?** notice. Choose **Review** to see each chat, or **Not now**. ## App data Voyager's profile folder holds your chat history, settings, logs, generation job records, caches and downloaded models. | | Profile folder | | - | - | | macOS | `~/Library/Application Support/Voyager` | | Windows | `%LOCALAPPDATA%\Voyager` (for example `C:\Users\\AppData\Local\Voyager`) | | Linux | `~/.local/share/voyager` (or `$XDG_DATA_HOME/voyager` if you set it) | Useful places inside it: | Path inside the profile folder | What's there | | - | - | | `voyager/userdata/settings.json` | Your app settings. Change them in **Settings**, not by hand. | | `voyager/userdata/keybindings.json` | Your custom keyboard shortcuts. | | `voyager/userdata/logs/` | App logs. Support may ask for these. | | `voyager/userdata/logs/support/` | Support bundles you saved from **Send feedback** while signed out. | To open the profile folder quickly, go to **Settings → General**, open **Advanced**, and under **Settings files** click **Show file** next to a file. > [!WARNING] > > Don't delete or edit files in the profile folder while Voyager is open. Deleting it erases your chat history and settings. Your project and chat files are elsewhere and aren't affected. ## Sign-ins and keys Voyager saves your Voyager sign-in and the media keys you add in your system's secure storage: | | Secure storage | | - | - | | macOS | Keychain | | Windows | Windows Credential Manager | | Linux | Your Secret Service keyring, such as GNOME Keyring or KWallet | Some connections, such as a ChatGPT account you connected with **Continue with ChatGPT**, are saved in the profile folder, readable only by your user account. **Claude and Codex keep their own sign-ins.** If you connected Claude, or your own Codex CLI, Voyager uses the login those tools already have. They store it in their own folders (`~/.claude` for Claude Code and `~/.codex` for Codex, unless you changed them). Signing out of Voyager doesn't sign you out of them. To disconnect an account while Voyager is running: * **Voyager:** open **Settings → Account** and choose **Sign out** under **Signed in**. You can also choose **Sign out** from the account menu at the bottom of the sidebar. * **Claude, ChatGPT and other providers:** open **Apps & Models → Providers**, open the provider's card, and choose **Sign out** or **Remove API key** from the menu beside the account or key. An account that is already signed out offers **Remove this account**. * **Apps and services such as Figma:** open **Apps & Models → Apps**, open the app, and choose **Sign out**. Deleting the app alone doesn't remove saved sign-ins. ## Removing Voyager completely **1. Sign out first** Sign out of Voyager in **Settings → Account**. Then sign out of providers and remove saved keys in **Apps & Models → Providers**, and sign out of apps such as Figma in **Apps & Models → Apps**. See [Sign-ins and keys](#sign-ins-and-keys). **2. Delete the app** * **macOS:** drag **Voyager** from Applications to the Trash. * **Windows:** **Settings → Apps → Installed apps → Voyager → Uninstall**. * **Linux:** delete the AppImage, or run `sudo apt remove voyager` for the `.deb`. **3. Delete app data (optional)** Delete the profile folder listed above. This erases your chat history and settings for good. **4. Keep or delete your work** Your projects and your conversation files folder (`~/Voyager` by default) are untouched. Keep them, move them, or delete them yourself. # Open Voyager from a link Source: https://docs.voyager.so/reference/deep-links Use voyager:// links to open a new Voyager chat with a prompt ready, or to start a technique from voyager.so. A `voyager://` link opens the Voyager desktop app from a web page, a note or a message. Voyager must be installed on the computer where you click it. ## Start a new chat with a prompt ```text theme={"system"} voyager://open/new-chat?prompt=A%2015-second%20product%20teaser%20for%20my%20mug ``` Clicking the link opens Voyager and shows **A link wants to start a chat with this prompt**, with the prompt as plain text. Choose **Use prompt** to put it in a new chat's message box, or **Dismiss** to drop it. Nothing is sent until you press **Send** yourself. | Part | What it does | | - | - | | `prompt` | The text for the message box, URL-encoded, up to 3,000 characters. Leave it out to open an empty chat. | | `kind` | Optional: `video`, `image` or `audio`, to suggest what the chat makes. | | `model` | Optional: a model's id, to suggest that model in the chat. Voyager ignores a model it doesn't know. | If you aren't signed in or haven't finished setup yet, Voyager keeps the prompt and offers it once you're ready. ## Start a technique from voyager.so **Open in Voyager** on a technique on voyager.so uses a `voyager://open/technique` link. It opens a new chat with that technique attached. See [Library](/guides/library#techniques) for the **Techniques** page inside the app. ## If the link does nothing * Check that Voyager is installed. Open it once so your computer knows which app handles `voyager://` links. * Some apps and websites block links that open other apps. Copy the link into your browser's address bar instead. * A prompt longer than the limit doesn't open a chat. Shorten it and try again. # Choose a brand Source: https://docs.voyager.so/setup/brand Pick the brand kit new projects and chats start with on the Brand setup step, or start from your website. When you finish, new projects and chats start with your brand's colors, fonts and logos. This is the **Brand** step. It's optional, and setup skips it when your workspace already has a default brand kit. > [!NOTE] > > **Before you start** > > * **A brand kit** holds a brand's colors, fonts and logos. Kits are saved to your Voyager account, not to your computer. > * You don't need one. Click **Skip for now** to go on without a brand. > * To start from your website instead, you only need its address. Voyager reads your brand from it. ## Choose a kit or use your website **1. Pick a kit from the list** The **Brand kits** list shows the kits in your workspace, each with its website underneath. Click a kit to choose it. With many kits, only the first few show. Click **Show all N** above the list to see every kit and pick one. If your workspace has no kits, there's no list: the step says **…Make one from your website.** and shows only **Create from website**. Go to the next step. **2. Or start from your website** Under **Create from website**, type your site's address, for example `https://yourcompany.com`, and click **Create**. Your site appears at the top of the list straight away, already selected. Voyager reads the brand from it when you finish setup. **3. Click Continue** Click **Continue** to go on to **Create**, the last step. **Continue** is available only when something is selected. With nothing selected, use **Skip for now**. * **A kit from the list** becomes your default straight away, so every new project and chat starts with it. * **Your website:** when you finish setup, Voyager makes a project named after your site and captures your brand into it in the background, which can take a little while. Your first chat opens in that project. This brand belongs to that project only: it isn't saved as a kit or as your default. ### Skip for now Click **Skip for now** to go on to **Create** without choosing a brand. Nothing is saved, so you can pick a brand any time later. ## Change your brand later Set the kit new projects start with in either place: * **Library → Brand kits**: open a kit's menu and choose **Set as default**. That kit shows a **Default** badge. * **Settings → Creative**: choose a kit under **Default brand kit** in the **Brand** section. Each new project's folder, or new chat's, starts with that kit's colors, fonts and logos in a `brand` folder. Folders you already have are left alone. ## Check it worked * The setup bar shows a check next to **Brand**, and you're on **Create**. * **A kit from the list:** after setup, **Library → Brand kits** shows it with a **Default** badge. * **Your website:** after setup, a project named after your site appears in the sidebar, and its `brand` folder fills in once the capture finishes. ## If something went wrong > [accordion] The brand from my website didn't appear > > If Voyager can't read your site, a message pops up saying why. Check the address opens in your browser and starts with `https://`. Your project is still there; you can choose a kit for new projects later in **Library → Brand kits** or **Settings → Creative**. > [accordion] “Could not create the … project” > > Setup is still finished, but Voyager couldn't make the project for your website's brand. Create a project from the sidebar, then ask the agent to capture your brand from your site. > [accordion] My kits don't appear, or I see a sign-in error > > Voyager loads kits from your workspace, so it needs your Voyager sign-in. Check you chose the right workspace on the [Workspace step](/setup/sign-in). You can also skip for now and choose a kit later in **Settings → Creative**. > [card] [Next: Choose your first project](/setup/create) > > Tell Voyager what you're making first, and get a prompt ready to send. # Connect ChatGPT Source: https://docs.voyager.so/setup/connect-chatgpt Use your ChatGPT plan as Voyager's agent: sign in with ChatGPT from the AI agent step, and Voyager sets up Codex for you. When you finish, Voyager's agent can run on your own ChatGPT plan, through Codex. This is part of the **AI agent** step. > [!NOTE] > > **Before you start** > > * **A ChatGPT Plus or Pro plan.** See [ChatGPT's plans](https://chatgpt.com/pricing). > * **Cost:** chatting through your ChatGPT plan costs nothing extra from Voyager. Your usage counts against your ChatGPT plan's own limits. You don't need a Voyager plan. > * You don't need to install Codex. Voyager downloads its own copy and keeps it separate, so any Codex you already use stays exactly as it is. > * **Paying per use with an OpenAI API key?** Click **Use an API key instead** on the same step (see [Your own API key](/setup/voyager-models#your-own-api-key)), or later in **Apps & Models → Providers**. OpenAI bills you per use. If the Codex CLI on your computer is already signed in with an API key, Voyager detects it like a subscription. > * Connecting Claude or Gemini instead? See [Connect Claude](/setup/connect-claude) or [Other agents](/setup/voyager-models). You can connect more than one. ## The ChatGPT row On the **AI agent** step, the **Agent** list has a row for **ChatGPT**, described as **Your ChatGPT Plus or Pro plan**. It shows **Connected** when ChatGPT is ready, or **Set up** when it isn't. Click **Set up** to open **Set up ChatGPT**. The dialog shows one of two things: * **ChatGPT — Your ChatGPT plan, through the Codex CLI** with a **Detected** check. Voyager found Codex already installed and signed in on your computer. Click **Done**; skip to [Check it worked](#check-it-worked). * Two steps, **Sign in to your ChatGPT account** ("Opens chatgpt.com in your browser. No install needed.") and **Check it's ready for Voyager**, with a ChatGPT row and a **Sign in** button under them. Follow the steps below. ## Sign in with ChatGPT **1. Click Sign in** In **Set up ChatGPT**, click **Sign in**. The button reads **Preparing…** for a moment. The first time, Voyager downloads its own copy of Codex. You don't install anything. The row shows **Downloading Codex…** with its progress, then **Installing Codex…** and **Checking Codex…**, and the sign-in page opens when this finishes. **2. Sign in on the OpenAI page** Voyager opens OpenAI's sign-in page in your browser, and the row reads **Finish signing in on the page that opened in your browser.** Sign in with the ChatGPT account that has your plan, and approve Voyager's request to use your ChatGPT plan. Closed the tab? Click **Reopen sign-in page**. Changed your mind? Click **Cancel**. **3. Go back to Voyager** When you approve, the browser says **Return to Voyager to continue. You can close this tab.** In Voyager, the row briefly says **Finishing sign-in…**, then shows **Signed in as** your email, with a **Connected** check. **4. Click Done, then Continue** Click **Done** to close the dialog, then **Continue** at the bottom right. Voyager saves your setup and moves on to **Video & images**. ### More than one ChatGPT account Once one account is connected, a **Connect another ChatGPT account** link appears under it. Use it if, for example, you have both a personal and a work ChatGPT plan. Each account appears as its own entry in the model picker. ## Which model Voyager uses Setup doesn't ask you to pick a model. If ChatGPT is your only connected agent, new chats start on **GPT-6 Astra**. If Claude is also connected, Claude comes first. ChatGPT comes before Gemini. To use something else, pick a different model in the chat box: new chats then start on the model you last picked. To change the default, go to **Settings → General**, under **Chats → AI for new chats**. ## Check it worked * The **ChatGPT** row on the AI agent step shows a **Connected** check. * **Continue** at the bottom of the step is available. * After setup, your ChatGPT account appears in **Apps & Models → Providers**. ## If something went wrong > [accordion] The browser didn't come back to Voyager > > Under the ChatGPT row, click **Having trouble signing in?**. Copy the address of the last page the browser showed, paste it into the field, and click **Connect**. > [accordion] “The ChatGPT callback port is in use on this computer.” > > Another ChatGPT or Codex sign-in is open, for example in a terminal. Close it and click **Sign in** again, or paste the redirect address as described above. > [accordion] “ChatGPT plan use isn't allowed for” your email > > You signed in but didn't approve Voyager using your ChatGPT plan. Click **Allow ChatGPT plan** and approve the request on the OpenAI page. > [accordion] “Couldn't prepare ChatGPT sign-in. Try again.” > > Voyager couldn't save the new account. Click **Sign in** again. If it keeps failing, restart Voyager and return to setup. > [card] [Next: Other agents](/setup/voyager-models) > > Gemini, Voyager's own models and your own API key, and what the Voyager row means. # Connect Claude Source: https://docs.voyager.so/setup/connect-claude Use your Claude subscription as Voyager's agent: install Claude Code and sign in from the AI agent step. When you finish, Voyager's agent runs on your own Claude account, through Claude Code. This is part of the **AI agent** step. > [!NOTE] > > **Before you start** > > * **A Claude Pro or Max plan** (see [Claude's plans](https://claude.com/pricing)). Paying per use instead? Add an Anthropic API key with **Use an API key instead** on the same step; see [Your own API key](/setup/voyager-models#your-own-api-key). > * **Cost:** nothing extra from Voyager. Usage counts against your Claude plan's own limits. You don't need a Voyager plan. > * You don't need to install anything yourself. If Claude Code isn't on your computer, Voyager downloads it into its own folder for you. It doesn't need Node, a terminal or any other developer tools. > * Prefer ChatGPT or Gemini? See [Connect ChatGPT](/setup/connect-chatgpt) or [Other agents](/setup/voyager-models). You can connect more than one. ## The AI agent step The **AI agent** step asks **Which AI should Voyager think with?** Its **Agent** list has a row for **Claude**, described as **Your Claude Pro or Max plan**. The right side of the row shows **Connected** when Claude is ready, a spinner while Voyager checks, or **Set up** when there's something left to do. Click **Set up** to open **Set up Claude**. It lists what's left, in order, and marks what's already done: 1. **Install Claude on this computer** 2. **Sign in to your Claude account** (opens your browser) 3. **Check it's ready for Voyager** (automatic) Under the steps, the Claude row shows what to do next: | You see | It means | Do this | | - | - | - | | A check, **Detected** | Claude Code is installed and signed in. | Click **Done**. Skip to [Check it worked](#check-it-worked). | | **Install** | Claude Code isn't on this computer yet. | Follow all the steps below. | | **Sign in** | Claude Code is installed but not signed in. | Start at step 2 below. | | **Needs upgrade** | Your Claude Code is too old to work with Voyager. | Click the upgrade button under the row. When it's done, Voyager signs you in if needed. | | A spinner | Voyager is still checking. | Wait a moment, or close the dialog and click **Refresh** above the list. | | **Turned off in Settings** | Claude is switched off in Voyager. | Turn it back on in **Apps & Models → Providers**, then click **Refresh**. | ## Install Claude Code and sign in **1. Click Install** In **Set up Claude**, click **Install** on the Claude row. Voyager downloads Claude Code from Anthropic. The row shows **Downloading Claude Code…** with its progress, then **Installing Claude Code…** and **Checking Claude Code…**. Changed your mind? Click **Cancel** next to the spinner. **2. Sign in to Claude in your browser** When the install finishes, Voyager starts sign-in by itself. (If the row showed **Sign in** to begin with, click it.) The row reads **Opening your browser…**, then **Finish signing in on the page that opened in your browser.** In the browser, sign in with the Claude account that has your plan, and approve the request. Browser didn't open? Click **Browser didn't open?** under the row, then **Open the sign-in page** or **Copy link**. If the page shows a code after you sign in, paste it into the field and click **Connect**. **3. Come back to Voyager** The row reads **Finishing sign-in…**, then shows a check labelled **Detected**. You don't need to click anything else in the browser. **4. Click Done, then Continue** Click **Done** to close the dialog. The Claude row on the list now shows **Connected**. Click **Continue** at the bottom right. Voyager saves your setup and moves on to **Video & images**. > [accordion] The install failed: use Try again, or a terminal > > If the download fails, the row says why and offers **Try again**. If it keeps failing, click **Install in a terminal instead** (it may be inside **Technical details**). A terminal opens under the agent list with Anthropic's own installer typed in: > > ```bash macOS and Linux theme={"system"} > curl -fsSL https://claude.ai/install.sh | bash > ``` > > ```powershell Windows theme={"system"} > irm https://claude.ai/install.ps1 | iex > ``` > > 1. Click in the terminal and press Enter. When it's done, the status line reads **Installed. Continue to sign in to your account.** > 2. Click **Continue to sign in**, then press Enter to run `claude auth login`, and sign in in the browser. > 3. When the status line reads **Connected. Your subscription is ready to use.**, click **Use subscription**. > > Closing the terminal stops anything still running in it. ## Which model Voyager uses Setup doesn't ask you to pick a model. If Claude is connected, Voyager starts new chats on **Claude Opus 5.5**, even if you also connect ChatGPT or Gemini or have a Voyager plan. To use something else, pick a different model in the chat box: new chats then start on the model you last picked. To change the default, go to **Settings → General**, under **Chats → AI for new chats**. ## Check it worked * The **Claude** row on the AI agent step shows a **Connected** check, and **Continue** is available. * After setup, **Apps & Models → Providers** lists Claude under **Connected**. * Your first chat opens on a Claude model. ## If something went wrong > [accordion] Sign-in finished, but the row still says Sign in > > Close the dialog and click **Refresh** above the agent list. Voyager re-checks Claude Code. If the row still doesn't change, open **Set up** again, click **Sign in** and make sure you use the Claude account that has your plan. > [accordion] The row shows a warning instead of a check > > Claude Code is installed but something needs attention, for example an expired sign-in. The warning text says what. Usually clicking **Sign in** and signing in again fixes it. > [accordion] “Claude is using a token from your shell environment” > > A variable such as `CLAUDE_CODE_OAUTH_TOKEN` or `ANTHROPIC_API_KEY` is set in your shell, and Claude Code uses it ahead of your sign-in. Signing in and **Refresh** appear to work but change nothing, so you can hit limit or billing errors from an old token while your signed-in account is fine. Delete the line that sets the variable from your shell profile (for example `~/.zshenv`, `~/.zshrc` or `~/.bash_profile`; on Windows, your user environment variables), then quit and reopen Voyager. Keep the variable only if you meant Claude to use it. > [accordion] I can't finish connecting Claude right now > > If the dialog offers **Continue with Voyager instead**, click it to go on with Voyager's own models. Otherwise close the dialog and click **Skip for now**. A sign-in or install that's still running carries on by itself. You can finish connecting Claude later in **Apps & Models → Providers**. Not adding ChatGPT? See [Other agents](/setup/voyager-models) for Gemini, Voyager's models and API keys, or go straight to [Video & images](/setup/media). > [card] [Next: Connect ChatGPT (optional)](/setup/connect-chatgpt) > > Add your ChatGPT account too. # Choose your first project Source: https://docs.voyager.so/setup/create The last setup step: tell Voyager what you're making first, and your first chat opens with a prompt ready to send. When you finish, setup closes and your first chat opens with a prompt for what you want to make, ready for you to edit and send. This is the **Create** step, the last one. It's optional. > [!NOTE] > > **Before you start** > > * Nothing is needed. Your answer only writes the first prompt; you can make anything later. > * Sending the prompt starts real work. If it generates images, video or audio, that's billed as usual by your own media services or your Voyager credits, and the agent tells you what a paid step will cost first. See [Approvals and spending](/guides/approvals-and-spending). ## Pick what you're making **1. Choose one** The step asks **What are you making first?**: "We'll write your first prompt for it. Pick one, you can make anything later." Pick one card: | Card | For | | - | - | | **A product or explainer video** | Launches, demos, how-tos | | **An edit of my own footage** | Cut and caption your clips | | **AI-generated video** | Scenes made from a prompt | | **Something else** | Ads, social, design, audio | **2. Click Continue** Click **Continue**. The button reads **Opening…** while Voyager finishes setup. A new chat opens with a starter prompt in the message box, for example "Cut my footage into a 60-second highlight video with music and captions." for **An edit of my own footage**. Edit it to fit what you want, attach any files, then send it. If you chose to start from your website on the [Brand step](/setup/brand), the chat opens in the project Voyager made for your site, so it uses your brand. Not ready to choose? Click **I'll start later**. Setup closes and a new chat opens with an empty message box. ## Check it worked * Setup is closed and won't appear again. * A new chat is open. If you picked a card, its prompt is waiting in the message box. ## If something went wrong > [accordion] “Could not save your answer. Try again.” > > Click **Continue** again. If it keeps failing, click **I'll start later** and type your own first request. > [accordion] The chat opened without my website's brand > > Voyager couldn't make the project for your site, and a message said why. Create a project from the sidebar, then ask the agent to capture your brand from your site. See [Choose a brand](/setup/brand). > [card] [Next: Make your first video](/first-video/make-your-first-video) > > Send your first request and watch the agent make it. # Connect your creative apps Source: https://docs.voyager.so/setup/creative-apps Tell Voyager which creative apps you use, such as DaVinci Resolve or Blender, on the Apps setup step, and learn your way around Apps & Models. When you finish, Voyager knows which creative apps you use, and the agent can use them alongside Voyager's built-in tools. This is the **Apps** step. It's optional. > [!NOTE] > > **Before you start** > > * **Nothing is required.** If you don't have any creative apps, Voyager's built-in tools cover every job. > * Voyager uses the apps you already have, with your own licences. It doesn't install or buy apps for you. > * **Platform:** which apps the agent can drive live depends on your system. For example, After Effects works on macOS and Windows. See [Requirements](/get-started/requirements). Some apps, such as DaVinci Resolve, need a setting turned on inside the app first. ## Pick your apps **1. Wait for Voyager to look for apps** The step asks **What do you create with?**: "Voyager connects to 100+ creative apps. Pick all you use." Beside a short animation of the agent working in an editor, Voyager looks for creative apps on your computer. The **Continue** button reads **Finding apps…** until it's done. **2. Check the apps found on your computer** Apps Voyager found are listed first, under **On your computer**, and start picked (a check after the name). With many, **+N more** shows the rest. Click an app to unpick it. **3. Pick any other apps you use** Rows for **Video**, **Motion**, **Design**, **Audio** and **Games** suggest a few popular apps each. Click every one you use. Can't see yours? Type in **Search apps** under **More**, or pick **Other**. A note under the list says Voyager's own tools, such as **Voyager Video** and **Voyager Design**, are always included. **4. Click Continue** Click **Continue**. Your picks tell Voyager what you work with; nothing is installed or bought. Voyager doesn't lock in an app for each job: the agent picks per request and tells you which. Choices you saved earlier are kept. If a built-in tool needs to download or finish setting up, Voyager does it in the background and shows a message such as **Setting up … in the background**. You can follow progress in the sidebar, under **Apps**. To connect an app, check what it needs, or switch it on or off, open **Apps & Models → Apps** after setup. Some apps, such as DaVinci Resolve, need a setting turned on inside the app first; the app's page there tells you what to change. ## Apps & Models at a glance Open **Apps & Models** in the sidebar to change anything from setup later. It has three tabs. > [tab] Providers > > Your agents, API keys and media services. Cards are grouped as **Needs attention**, **Connected** and **More providers**. > > * Click a card to open it and see how it's connected and the models it gives you. > * A card that needs you names the fix, such as **Sign in** or **Replace API key**. > * **Image, video and voice order** opens a dialog where you choose which service Voyager tries first, and whether it tries the next one if one can't finish. Inside a media provider's card, **Change order** opens the same dialog. > > ![The Apps & Models page on the Providers tab. A search box and an Image, video and voice order button sit above provider cards grouped under Connected and More providers.](https://mintcdn.com/voyager/yRytHenCA6FFAhzA/images/screenshots/connectors-overview-providers.light.png?fit=max\&auto=format\&n=yRytHenCA6FFAhzA\&q=85\&s=a53c67a6a2c27e57abff0b50d8e2cc26) > > Apps & Models → Providers. > [tab] Apps > > Creative apps and services the agent can use. Filter with the chips below the search box (such as **Connected**, **Video** or **3D**), or search. > > * Click an app to set it up, check it, or switch it on or off. > * **Preferred apps** sets the app Voyager uses for each job when a chat doesn't name one, for all projects or just one. Anything left on **Auto** is the agent's choice. > * **Add an app or service** adds one that isn't listed. > > ![The Apps & Models page on the Apps tab. A search box, a Preferred apps button and an Add an app or service button sit above filter chips with Video selected, and tiles for Voyager's own Video editing and Motion graphics tools and video apps such as DaVinci Resolve and Premiere Pro.](https://mintcdn.com/voyager/yRytHenCA6FFAhzA/images/screenshots/connectors-overview-apps.light.png?fit=max\&auto=format\&n=yRytHenCA6FFAhzA\&q=85\&s=4bc2a7f2e1729db008c3835562507105) > > Apps & Models → Apps. > [tab] Models > > Every model your providers offer, for chat and for media. > > * Search, or narrow the list by model type with the chips below the search box, and by maker or provider with the checkboxes beside the list (in a narrow window, open **Filters**). **Available to me** shows only models you can use now. > * Sort by **Recommended**, **Newest** or **A–Z**. > * **Default models** sets the model Voyager uses for each kind of media, such as **Image**, **Video** or **Voice**, when a chat doesn't name one. > > ![The Apps & Models page on the Models tab. A search box, an Available to me switch, a sort menu set to Recommended and a Default models button sit above model cards.](https://mintcdn.com/voyager/yRytHenCA6FFAhzA/images/screenshots/connectors-overview-models.light.png?fit=max\&auto=format\&n=yRytHenCA6FFAhzA\&q=85\&s=30008fb93d950afcda1d2f48271f8abb) > > Apps & Models → Models. ### Choose models and apps for one chat In a chat, the button just before the model picker (its tooltip reads **Preferred creative apps and media models**) opens **Preferred models and apps**. Pick a model for each kind of media and an app for each job; anything you leave on **Auto** is Voyager's choice, using your subscriptions before credits. The menu at the top of the panel sets where they apply: **This chat**, **This project** or **All projects**. Changes in a chat apply to that chat and your next new chat. **Manage in Apps & Models** opens the full lists. ## Check it worked * The setup bar shows a check next to **Apps**, and you're on **Brand** (or **Create**, if your workspace already has a default brand kit). * After setup, **Apps & Models → Apps** shows the apps Voyager can use. ## If something went wrong > [accordion] An app I have isn't under On your computer > > Voyager finds apps in their usual install location. Pick it from its row or **Search apps**, then click **Continue**. After setup, open **Apps & Models → Apps** to find the app and see what it needs. If you installed the app while setup was open, restart Voyager so it looks again. > [accordion] “Could not save your apps. Try again.” > > Click **Continue** again. If it keeps failing, quit and reopen Voyager. Your setup is already saved, so Voyager opens on this step again, and you can also choose your apps in **Apps & Models → Apps**. > [card] [Next: Choose a brand](/setup/brand) > > Pick the colors, fonts and logos new projects start with. # Choose how images and video are made Source: https://docs.voyager.so/setup/media The Video & images setup step: stay on Voyager Free, pick a Voyager plan, or connect the media services you already pay for with your own keys. When you finish this step, you'll know who makes your images, video and audio, and who pays for them. This is the **Video & images** step. It's optional, and setup already counts as done. > [!NOTE] > > **Before you start** > > * **You don't need to buy anything.** You can continue on Voyager Free, and connect your own media keys or sign-ins now or later. > * **Your own keys** are billed by that service, to your account with them. **Voyager credits** come from your workspace's Voyager plan. Plan names and prices are on [voyager.so/pricing](https://voyager.so/pricing). > * Editing your own footage, captions and most motion graphics run on your computer and don't need either. ## What the step shows The step looks different depending on your workspace's plan: | Your workspace | The step says | What you see | | - | - | - | | On Voyager Free, and you can manage its plan | **Make video and images for less** | Plan cards, from **Free** (marked **Current plan**) to paid plans, with **Monthly** and **Annual** prices, and a collapsed **Already pay for other providers?** row for your own services. | | On a paid plan | **Video and images are covered** | Your plan's card, with **Manage plan**, and your own services listed under it. | | A team workspace, or a plan you can't change | **How should Voyager make images and video?** | A **Voyager** row, then your own services under **Or use your own plans**. | ## Choose a plan, or stay on Free **1. Stay on Free, or pick a plan** To stay on Free, do nothing here: the button at the bottom right reads **Continue free**. Free makes some images each month but no video. To pick a plan instead, choose **Monthly** or **Annual**, then click the **Get** button on a plan card (for example **Get Creator**). A payment page opens in your browser, and the card shows **Finish payment** until you're done; click it to reopen the page. When you've paid, the step changes to **You're all set on** your plan. **Compare all plans, including Teams** opens the full pricing page. > [!WARNING] > > A paid plan charges your card. You don't need one to finish setup or to work with your own Claude, ChatGPT and media keys. **2. Connect services you already pay for (optional)** Click **Already pay for other providers?** (or look under **Or use your own plans**). Each service has a row with what it makes and a **Set up** button. Click **Set up**, then follow the steps in the dialog: paste your API key and click **Save**, or sign in to your account in the browser. Voyager checks the key or plan, then the row shows a check. The first few services are listed; **More media providers (N)** opens the rest. Every change saves straight away. **3. Click Continue** Click **Continue free** (or **Continue**). You move on to **Apps**. ## Media services you can connect | Service | What it makes | How to connect | | - | - | - | | **Higgsfield** | Video and images on your Higgsfield plan | Sign in with your Higgsfield account in the browser. | | **fal** | The widest model catalog | API key | | **Google** | Gemini images and speech | API key | | **ElevenLabs** | Voices, music and sound effects | API key | | **Fish Audio** | Voices, including featured creator voices | API key | | **Inworld** | Fast, low-cost voices and voice clones | API key | | **BytePlus** | Seedance video and Seedream images | API key | | **Runway** | Gen-4.5, Aleph and Act-Two video | API key | | **Sume** | Seedance, Veo, MiniMax and Nano Banana, on your Sume balance | API key | | **OpenAI** | GPT Image on your OpenAI API key | API key | | **ChatGPT plan** | Images on your ChatGPT plan, through Codex | Sign in to the Codex CLI with `codex login` in a terminal. | Each service's dialog tells you where to get its key. You can add, replace or remove keys later in **Apps & Models → Providers**. ## Who pays for a generation When the agent makes an image, video or clip, Voyager uses the first connected service in your order that offers the model it needs. Voyager credits cover anything you don't connect. The note **You can configure model routing in Settings.** points to where you change that order: **Apps & Models → Providers → Image, video and voice order**. > [!WARNING] > > **Automatic fallback is on by default.** If a service is out of credits, rejects its sign-in or is down, Voyager tries the next one in your order. That can bill a different account, for example your Voyager credits instead of your own fal key. You can turn off **If one can't finish, try the next provider**, change the order, or ask the agent to use a particular provider for a job. See [Generation providers](/account/generation-providers). ## Check it worked * Any service you connected shows a check on its row. * After setup, **Apps & Models → Providers** lists it under **Connected**. ## If something went wrong > [accordion] A key won't save > > Voyager checks each key when you save it. Make sure you copied the whole key from the service's dashboard, with no spaces, and that your account with that service is active. > [accordion] I bought a plan, but the step still shows the plan cards > > Finish checkout in the browser, then come back to Voyager. The step reads your plan again when you return to it; click **Back** and **Continue** to reopen it. Your plan also shows in **Settings → Account**. > [accordion] Free ran out of credits > > Connect your own service for the kind of media you need, or upgrade on your [billing page](https://voyager.so/dashboard/billing). See [Plans and credits](/account/plans-and-credits). > [card] [Next: Connect your creative apps](/setup/creative-apps) > > Tell Voyager which creative apps you use. # Set up Voyager Source: https://docs.voyager.so/setup/overview What each setup step does, what you need before you start, and which steps you can skip. The first time you open Voyager, a short setup walks you through a few steps. When you finish, you'll have a signed-in Voyager account, an agent to chat with, and a first chat waiting with a prompt ready to send. Most people are done in a few minutes. > [!NOTE] > > **Before you start** > > * **A Voyager account.** Setup opens a sign-in page in your browser, where you can sign in or create a free account. You don't need to pay to create one. > * **An agent to chat with.** Any of these works: > * **Claude**, with your Claude Pro or Max plan, or > * **ChatGPT**, with your ChatGPT Plus or Pro plan, or > * **Gemini**, with your Google account or a Gemini API key, or > * your own **Anthropic, OpenAI, Gemini or xAI API key**, or > * **Voyager**'s own models, included with [Voyager Free](/account/plans-and-credits#voyager-free) or a paid plan. > * **A paid Voyager plan is optional.** With your own Claude or ChatGPT and your own media keys, you can finish setup and do all your work without one. See [pricing](https://voyager.so/pricing) for what a plan adds. > * **Voyager installed.** If you haven't installed it yet, start with [Install on macOS](/get-started/install-macos), [Windows](/get-started/install-windows) or [Linux](/get-started/install-linux). ## The steps Setup opens on a welcome screen with a **Set up** button. After you sign in, a bar across the top shows the steps: **Workspace**, **AI agent**, **Video & images**, **Apps**, **Brand** and **Create**. You can click a step you've already finished to go back to it. Steps that are already done are left out. If you're already signed in, there's no **Workspace** step, and if your workspace already has a default brand kit, there's no **Brand** step. | Step | What it does | Required? | Guide | | - | - | - | - | | **Workspace** | Signs you in to Voyager and picks the workspace Voyager uses. You can add a promo code here. | Yes | [Sign in to Voyager](/setup/sign-in) | | **AI agent** | Connects the AI you'll chat with: Claude, ChatGPT, Gemini, Voyager's own models, or your own API key. | Recommended | [Connect Claude](/setup/connect-claude), [Connect ChatGPT](/setup/connect-chatgpt), [Other agents](/setup/voyager-models) | | **Video & images** | Shows how Voyager makes images and video for you, and connects media services you already pay for. | No | [Choose how media is made](/setup/media) | | **Apps** | Asks which creative apps you use, such as DaVinci Resolve or Blender. | No | [Connect your creative apps](/setup/creative-apps) | | **Brand** | Picks the brand kit (colors, fonts and logos) that new projects and chats start with, or uses your website. | No | [Choose a brand](/setup/brand) | | **Create** | Asks what you're making first, and writes your first prompt for it. | No | [Choose your first project](/setup/create) | Setup doesn't ask your computer for any access. On a Mac, Voyager asks for screen and accessibility access in the chat the first time the agent needs it. See [Allow computer control](/guides/computer-control). ## What you'll pay for Setup itself is free. What you pay depends on how you choose to work: * **Chat with your own Claude, ChatGPT or Gemini** costs nothing extra from Voyager. A subscription's usage counts against its own limits; an API key is billed per use by the provider. * **Chat with Voyager's models** uses your Voyager plan's credits, including Voyager Free's. * **Images, video and audio** are billed by whichever service makes them: your own provider account (when you add your own key or sign in), or your Voyager credits. Voyager asks before it spends more than your spend limit when questions are set to **Wait, then go ahead** or **Always ask**. **Don't ask** doesn't wait, even above the limit. See [Approvals and spending](/guides/approvals-and-spending) and [Plans and credits](/account/plans-and-credits). ## Setup counts as done after AI agent Once you continue from **AI agent**, Voyager saves your setup as complete. The steps after it are optional. If you quit Voyager during **Video & images**, **Apps**, **Brand** or **Create**, setup opens on that same step next time, so you can finish or skip it. You can also change each choice later in the app: | Setup step | Change it later in | | - | - | | Account, workspace, promo code | **Settings → Account** | | Agents and API keys | **Apps & Models → Providers** | | Media services | **Apps & Models → Providers** | | Creative apps | **Apps & Models → Apps** | | Default brand kit | **Settings → Creative**, in the **Brand** section, or **Library → Brand kits** | | Mac screen access | **Settings → Advanced → Permissions** (Mac only) | | Usage statistics and problem reports | **Settings → Advanced → Privacy** | Open Settings with ⌘ , (Ctrl ,) or from **Settings** at the bottom of the sidebar. **Advanced** is a group at the bottom of the Settings list; click it to open it. **Apps & Models** and **Library** are in the main sidebar. ## Platform differences Setup is the same on macOS, Windows and Linux, with one exception: * **Windows:** if Windows Smart App Control is on or in evaluation mode, the welcome screen shows a notice under **Set up**. See [Smart App Control](/get-started/install-windows#smart-app-control). See [Requirements](/get-started/requirements) for the full platform table. ## If something went wrong > [accordion] Voyager shows “Still connecting” instead of setup > > Voyager's local service is slow to start. Click **Reload**. If you see **Could not read > settings**, click **Retry**. If it keeps happening, see [Setup problems](/help/setup-problems). > [accordion] I don't have Claude, ChatGPT or a Voyager plan > > Click **Continue with Voyager** on the AI agent step: a new account is set up on Voyager Free, > which includes chat with Voyager's models. ChatGPT also needs no install: click **Set up** on its > row and sign in. If neither works for you, click **Skip for now** and connect an agent later in > **Apps & Models → Providers**. See [Other agents](/setup/voyager-models). > [accordion] The AI agent step keeps showing a spinner > > Voyager is still checking the agents on your computer. Wait a moment, or click **Refresh** above > the list. If a check hangs, **Skip for now** turns on after about 15 seconds. > [accordion] I quit before finishing the optional steps > > That's fine. Next time you open Voyager, setup reopens on the step you left. Or use the table > above to set them up later. > [card] [Next: Sign in to Voyager](/setup/sign-in) > > Start setup and sign in or create your Voyager account. # Sign in to Voyager Source: https://docs.voyager.so/setup/sign-in Start setup, sign in or create your Voyager account in the browser, choose a workspace and add a promo code. When you finish this step, Voyager is signed in to your account and knows which workspace to use. This is the first setup step, **Workspace**. If Voyager is already signed in, setup skips it. > [!NOTE] > > **Before you start** > > * Voyager is installed and open. See [Install on macOS](/get-started/install-macos), [Windows](/get-started/install-windows) or [Linux](/get-started/install-linux). > * You can use the browser you already have. Creating a Voyager account is free. > * **Windows:** if the welcome screen shows a Smart App Control notice, read [Smart App Control](/get-started/install-windows#smart-app-control) first. > * **Linux:** Voyager stores your sign-in in your system keyring (for example GNOME Keyring or KWallet). Make sure it's unlocked. ## Sign in **1. Click Set up** The first time you open Voyager, you see the welcome screen with one button. Under it, a line reads **Sign in or create a free Voyager account in your browser, then come back here.** Click **Set up**. ![Voyager's welcome screen: the Voyager wordmark on a starfield, the line The open harness for creative work, a Set up button, and under it the line Sign in or create a free Voyager account in your browser, then come back here.](https://mintcdn.com/voyager/yRytHenCA6FFAhzA/images/screenshots/setup-splash.light.png?fit=max\&auto=format\&n=yRytHenCA6FFAhzA\&q=85\&s=793c0ab32172e743a4394e4b4c0893ec) The welcome screen. Set up opens sign-in in your browser. On Windows, a Smart App Control notice may appear under the button. See [Smart App Control](/get-started/install-windows#smart-app-control). **2. Sign in or create an account in your browser** Voyager opens a sign-in page in your default browser and shows **Complete signing in on the web** while it waits. In the browser, sign in to your Voyager account, or create one. When you're done, the browser page says **You're signed in** (or **Choose a workspace**) and takes you back to Voyager. If your browser asks whether to open Voyager, allow it. Voyager moves on by itself; you don't need to click anything. ![The welcome screen showing Complete signing in on the web, with the text Voyager opened sign-in in your browser, Reopen sign-in and Cancel buttons, and under them Browser didn't open? with Copy link.](https://mintcdn.com/voyager/yRytHenCA6FFAhzA/images/screenshots/setup-signin-waiting.light.png?fit=max\&auto=format\&n=yRytHenCA6FFAhzA\&q=85\&s=832d172417f33324d93186178d82ccf8) Voyager waits here while you sign in. It continues on its own when the browser hands back. > [!TIP] > > Closed the tab by accident? Click **Reopen sign-in** to bring the same page back. Browser didn't open at all? Click **Copy link**, next to **Browser didn't open?**, and paste the link into a browser on this computer. **Cancel** returns you to the welcome screen. On a Mac, macOS may ask whether Voyager can use your keychain. Allow it: that's where Voyager keeps your sign-in. **3. Choose your workspace** Back in Voyager, the **Workspace** step shows **Choose your workspace** and, at the bottom, **Signed in as** the email you used. * If your account has one workspace, it's already selected under **Workspace**. * If you belong to several, pick one under **Choose a workspace**. With more than five, a search box helps you find it. Projects, brand kits and credits live in a workspace. You can switch workspaces later from the sidebar. **4. Add a promo code (optional)** If you have a promo code, click **Have a promo code?** and type it in **Promo code (optional)**. Voyager applies it when you click **Continue**, and shows the result on the next step, under the agent list, for example **Code applied** or a message that a trial has started. A code that doesn't work never stops setup. You can try it again later in **Settings → Account**, under **Promo code**. **5. Click Continue** Click **Continue**. The button reads **Setting up…** while Voyager checks your account, then you move to **AI agent**. Signed in to the wrong account? Click **Use a different account** instead. The browser asks you to sign in again, so you can pick another account. ## Check it worked * The setup bar shows a check next to **Workspace**, and you're on **AI agent**. * Later, **Settings → Account** shows your Voyager sign-in, workspace and plan. ## If something went wrong > [accordion] “Sign-in didn't finish” or “Voyager login timed out. Try connecting again.” > > The browser sign-in has to finish within about five minutes, and choosing a workspace within a few minutes after that. Click **Try again** and complete the browser page without leaving it open in the background. If you see **The workspace choice timed out. Sign in again.**, start sign-in again and pick your workspace straight away. > [accordion] “Voyager could not access macOS Keychain to save your Voyager connection.” > > Voyager couldn't save your sign-in. Unlock your login keychain (signing out of macOS and back in usually does this), allow Voyager access when macOS asks, then click **Try again**. > > On Linux the message mentions your system credential store: unlock your keyring, such as GNOME Keyring or KWallet, and allow Voyager access. > [accordion] Windows: “Windows Smart App Control blocked Voyager's credential storage component.” > > Smart App Control blocked the part of Voyager that saves your sign-in. Update to the latest Voyager, which is code signed, and try again. If it still happens, see [Smart App Control](/get-started/install-windows#smart-app-control). > [accordion] Continue shows “Sign in to Voyager to continue.” > > Your sign-in ended or wasn't confirmed. Click **Sign in** on the Workspace step and sign in again in the browser. More fixes are in [Setup problems](/help/setup-problems). Using ChatGPT instead of Claude? Go to [Connect ChatGPT](/setup/connect-chatgpt). ChatGPT needs no install, so it's the quickest way to get an agent. For Gemini, Voyager's own models or an API key, see [Other agents](/setup/voyager-models). > [card] [Next: Connect Claude](/setup/connect-claude) > > Connect Claude with your Claude Pro or Max plan on the AI agent step. # Use Gemini, Voyager models or an API key Source: https://docs.voyager.so/setup/voyager-models The other ways to get an agent on the AI agent step: Gemini through Antigravity, Voyager's own models, or your own API key, and what to do when none is ready. When you finish this page, you'll know every way to get an agent besides Claude and ChatGPT, and how to leave the **AI agent** step whatever you have. > [!NOTE] > > **Before you start** > > * **A paid Voyager plan is optional.** Gemini and your own API key are billed by Google or the key's provider, never by Voyager. Voyager's own models use Voyager credits; a new workspace is usually set up on [Voyager Free](/account/plans-and-credits#voyager-free) within a few minutes, which includes them. > * Plan names and prices are on [voyager.so/pricing](https://voyager.so/pricing). The **AI agent** step lists **Claude**, **ChatGPT**, **Gemini** and **Voyager** under **Agent**, with **Use an API key instead** under the list. Claude and ChatGPT have their own pages: [Connect Claude](/setup/connect-claude) and [Connect ChatGPT](/setup/connect-chatgpt). ## Gemini The **Gemini** row is described as **Your Google account**. It runs through Antigravity, Google's app for Gemini, which Voyager can install for you. You need a Google account, or a Gemini API key. **1. Click Set up** On the **Gemini** row, click **Set up**. **Set up Gemini** lists the steps: **Install Antigravity on this computer**, **Sign in to your Google account** and **Check it's ready for Voyager**. **2. Install Antigravity** If the Antigravity row shows **Install**, click it. Voyager downloads it, with its progress on the row, then goes on to sign-in. **3. Sign in with Google, or use a key** Click **Sign in with Google** and finish signing in in your browser. Prefer a key? Click **Use a Gemini API key**, paste your key into **Gemini API key** and click **Save**. **Get a key in Google AI Studio** opens the page where you make one. The row then reads **Your Gemini API key, through Antigravity**. **4. Click Done** When the row shows a **Connected** check, click **Done**. The Gemini row on the list shows **Connected** too. ## Your own API key Click **Use an API key instead**, under the agent list. **Use an API key** opens, for **Your own Anthropic, OpenAI, Gemini or xAI key, billed by that provider**. **1. Click Add key** On the **API key** row, click **Add key**. Four fields open, one per provider: **Anthropic API key**, **OpenAI API key**, **Gemini API key** and **xAI API key**. **2. Paste a key and click Save** Paste your key into the field for its provider, and click **Save** next to it. The row then shows a **Connected** check, and the link under the agent list reads **API key connected**. You can add more keys, or replace one, later in **Apps & Models → Providers**. ## The Voyager row The **Voyager** row offers open models run by Voyager, paid for from your workspace's Voyager credits. There's nothing to connect. The row reflects your workspace's plan: | The row says | What it means | | - | - | | **…on Voyager Free**, marked **Included** | Your workspace is on Free: chat on Voyager's models uses Free's credits, within its usage limits. | | **…from your plan credits**, marked **Included** | Your plan includes chat with Voyager's models. Each turn uses some of your plan's credits. | | **…billed separately at cost**, marked **Billed at cost** | Your workspace pays for Voyager chat separately from its plan. | | **…with a Voyager plan**, no check | Your workspace has no plan. Voyager's models aren't available until you get one. Use another agent now. | | **Setting up your free plan…** | Voyager is still setting up Free for this workspace. Chat through Voyager turns on by itself in a few minutes. Use your own agent meanwhile. | | **This workspace has no plan, and Free isn't available for it.** | Use your own agent now, or get a plan any time. | | A message explaining why, with a button that names the fix | Chat through Voyager is paused for this workspace, for example because Free's limit is reached, it's out of credits, a payment failed, you don't have a seat, or an admin turned chat off or capped it. The button opens your billing page. You can carry on with another agent. | Higher plans add more models; see [pricing](https://voyager.so/pricing). ## Leave the AI agent step The buttons at the bottom right depend on what's ready: | What's ready | Buttons | What happens | | - | - | - | | Claude, ChatGPT, Gemini or an API key | **Continue** | Voyager saves your setup and moves on to **Video & images**. | | None of your own, but the Voyager row is usable | **Continue with Voyager** | New chats start on Voyager's models. You can connect your own agent later. | | Nothing usable yet | **Skip for now**, and **Continue** (off until an agent is ready) | **Skip for now** finishes setup without an agent. Connect one later in **Apps & Models → Providers**, including local models through an **API models** provider. | While Voyager is still checking the agents on your computer, the buttons wait. If a check never answers, **Skip for now** turns on after about 15 seconds. Inside a **Set up** dialog, **Continue with Voyager instead** does the same as **Continue with Voyager**. A sign-in or install that's still running carries on by itself. ## Which agent new chats start on Setup doesn't ask you to pick. New chats start on the first agent that's ready, in this order: 1. Claude 2. ChatGPT 3. Gemini 4. Your own API key 5. Voyager's models If you click **Continue with Voyager**, new chats start on Voyager's models. Switch models in any chat from the model picker, or change the default in **Settings → General**, under **Chats → AI for new chats**. ### Get a plan or use a promo code * Click the button on the Voyager row (for example **Get a Voyager plan**), or go to [voyager.so/dashboard/billing](https://voyager.so/dashboard/billing). When your plan is active, click **Refresh** above the agent list. * Have a promo code? Go **Back** to the Workspace step and enter it, or add it later in **Settings → Account**. Some codes start a trial plan. ## Check it worked * At least one row under **Agent** shows a check, and **Continue** or **Continue with Voyager** is available. * After setup, your first chat opens on the agent you connected. ## If something went wrong > [accordion] The Voyager row says “Get a Voyager plan to chat through Voyager.” > > Your workspace has no plan. Connect [Claude](/setup/connect-claude), [ChatGPT](/setup/connect-chatgpt), Gemini or your own API key to continue now, or get a plan and click **Refresh**. > [accordion] “Free's limit is reached for now.” > > Your workspace reached one of Free's usage limits. Wait until the time the message names, use your own subscription now, or choose **See plans** to upgrade. > [accordion] “This workspace is out of Voyager plan credits.” > > Buy a credit pack or turn on auto-reload on your [billing page](https://voyager.so/dashboard/billing), or use your own Claude or ChatGPT subscription now. > [accordion] “Ask a workspace admin to give you a Voyager seat” > > Your workspace has a plan, but you don't have a seat on it. Ask an admin to add you, or use your own subscription now. > [accordion] A key won't save, or Google did not accept it > > Voyager checks each key when you save it. Make sure you copied the whole key from the provider's dashboard, with no spaces, and that your account with that provider is active. For Gemini, **Google did not accept this key. Check it and save it again.** means the Gemini key was refused. > [card] [Next: Choose how media is made](/setup/media) > > See how Voyager makes images and video, and connect media services you already pay for. # Use your Voyager dashboard Source: https://docs.voyager.so/web/dashboard Find your way around voyager.so/dashboard: generate in the browser, connect Voyager to your AI chat apps, and manage your plan, credits, team and devices. Your dashboard at [voyager.so/dashboard](https://voyager.so/dashboard) is Voyager on the web. Sign in with the same account you use in the desktop app. You can generate media there, connect Voyager to the AI chat you already use, and manage your account. The full agent, which works in your creative apps and with files on your computer, runs in the desktop app. The dashboard links to it wherever that matters. > [!NOTE] > > **Before you start** > > * **A Voyager account.** Sign in or sign up at [voyager.so/dashboard](https://voyager.so/dashboard). A paid plan is optional. > * **Cost:** browsing the dashboard is free. Generating media uses Voyager credits from your workspace. See [Plans and credits](/account/plans-and-credits). ## The top bar Along the top (along the bottom on a phone) you'll find: * **Explore**: your home page. It shows what Voyager can do, techniques to start from and the models you can use. **Open in app** buttons hand a starting request to the desktop app. * **Video**, **Image** and **Audio**: generate in the browser with Voyager credits. See [Generate in your browser](/web/generate). * **Games**: games other people made with Voyager, ready to play or remix in the app. See [Make browser games](/web/games). * **MCP**: connect Voyager to ChatGPT, Claude or Codex so you can generate from those chats. See [Connect your AI](/connect/overview). On a phone, **MCP** is in the account menu. * **API** (paid plans): create keys for the Voyager API. See [Voyager API](/api/overview). On the right are **Search**, your workspace's credit balance and your account menu. Search finds pages, models, workspaces and actions. The account menu has **Settings**, **Usage & credits**, **Your generations**, **Docs**, **Download the app**, your workspaces, the light or dark appearance, and **Sign out**. ## Settings Open **Settings** from the account menu. Its pages are: | Page | What it's for | | - | - | | **Overview** | Your workspace's plan, credits and what the team made this month. | | **Plan & billing** | Change your plan, buy credits and manage payment. Only workspace owners and admins can upgrade. See [Plans and credits](/account/plans-and-credits). | | **Usage & credits** | Credits used from your workspace's balance, by day, kind of media and model. | | **Team** | Invite people to your workspace and manage their seats. | | **Devices** | Computers where Voyager is signed in to your account. Choose **Sign out** to sign a device out. | | **Connected apps** | ChatGPT, Claude and Codex connections you've allowed. Choose **Revoke** to stop one. See [Connect your AI](/connect/overview#disconnect-an-app). | | **Voyager account** | Your profile, security and desktop sign-ins. | ## Workspaces Everything on the dashboard belongs to one workspace at a time: its plan, credits, team and generations. If you're in more than one workspace, switch from your account menu or search for the workspace by name. ## Voyager in the browser on the go The dashboard isn't the only web version of Voyager. If you use Voyager away from your computer, [app.voyager.so](https://app.voyager.so) opens the Voyager app itself in your browser. See [Computers and cloud GPUs](/guides/computers-and-cloud-gpus). On a Free account, the browser version shows **You're using the limited web version of Voyager**. In the browser, Voyager can't use apps on your computer, such as DaVinci Resolve or Adobe apps, or open files stored on it. Choose **Download the desktop app** for the full experience. ## Related pages > [card] [Generate in your browser](/web/generate) > > Make video, images and audio without installing anything. > [card] [Connect your AI](/connect/overview) > > Use Voyager from ChatGPT, Claude or Codex. # Make browser games Source: https://docs.voyager.so/web/games Play games made with Voyager on the dashboard's Games tab, then describe your own in the desktop app and publish it to a voyager.site link anyone can play. Voyager's agent can build a small game you play in a web browser, playtest it, and publish it to a link anyone can open. The **Games** tab on [voyager.so/dashboard](https://voyager.so/dashboard/games) shows games made this way. Building happens in the desktop app. > [!NOTE] > > **Before you start** > > * **The Voyager desktop app**, set up with an agent. See [Choose your setup](/get-started/choose-your-setup). > * **Cost:** games work on Voyager Free. Making a game needs no paid generation, though images, music or sounds you ask Voyager to generate for it use credits as usual. Free keeps a small number of games published at a time; paid plans keep more. See [Voyager pricing](https://voyager.so/pricing). ## Browse the Games tab The Games tab doesn't make anything itself. Everything on it plays a published game or opens the desktop app: * **One-shot games**: simple games, each made from a single request. Choose **Play** to play it, or **Remix in app** to start a game like it in the desktop app. * **Beyond one-shots**: longer, directed work in game engines such as Unreal Engine and Godot, with **Read how** links. * **Start from a game technique**: step-by-step techniques you can read or open in the app. ## Make and publish your own **1. Describe the game** In a new chat in the desktop app, describe the game, its controls and how a round ends. You can also attach a drawing or a sprite to start from. **Open in app** on the Games tab starts this chat for you. **2. Let the agent build and playtest it** Voyager builds the game and plays full rounds with real input to check it works. Try it in the preview and ask for changes. **3. Ask Voyager to publish it** Say "publish this game". Voyager shows what will be uploaded and asks you to confirm, because **every file in the game becomes public**. Ask for a thumbnail too if you plan to post the link on X. ## Check it worked Voyager gives you a link like `https://moon-hop-a2b3c4.voyager.site`. Open it in any browser, or send it to someone. The link stays the same when you publish updates. To change a published game, ask Voyager to update it. To take it down, ask Voyager to unpublish it. ## If something went wrong > [accordion] Publishing asks me to sign in > > Publishing uses your Voyager account. Sign in in the browser window that opens, then ask Voyager to publish again. > [accordion] I can't publish another game > > Your plan has reached the number of games it keeps published. Unpublish one you no longer need, or see [Voyager pricing](https://voyager.so/pricing) for plans that keep more. > [accordion] A link posted on X shows a plain card, not the game > > The game has no thumbnail. Ask Voyager to add a square poster and publish an update; X then shows a playable card. ## Related pages > [card] [Use your dashboard](/web/dashboard) > > Everything else on voyager.so/dashboard. > [card] [Write a good request](/guides/write-a-request) > > Describe what you want so Voyager gets it right the first time. # Generate in your browser Source: https://docs.voyager.so/web/generate Make videos, images, voiceover, music and sound effects at voyager.so/dashboard with Voyager credits, and find everything you've made under Your generations. You can make a video clip, an image or a piece of audio on [voyager.so/dashboard](https://voyager.so/dashboard) without installing anything. Pick a model, describe what you want and Voyager renders it with your workspace's Voyager credits. > [!NOTE] > > **Before you start** > > * **A Voyager account.** Anyone signed in can use Generate. > * **Cost:** each generation uses Voyager credits from your workspace. The cost shows before you start. Voyager Free includes some image and voice models; video needs a paid plan. See [Plans and credits](/account/plans-and-credits) and [Voyager pricing](https://voyager.so/pricing). > * **One result at a time.** Generate makes single clips, images and sounds. To plan, edit and finish a whole video, use the desktop app. See [Generate images and video](/guides/generate-images-and-video). ## Make something **1. Choose Video, Image or Audio** In the top bar, choose **Video**, **Image** or **Audio**. Under **Audio** you pick **Voice**, **Music** or **Sound effect**. **2. Pick a model** Open the model button above the prompt and choose a model. A model your plan doesn't include shows the plan it needs. **3. Describe it** Write your prompt in **Describe what you want to create**. For a voice, write the **Script** the way it should be read. Many video and image models also take images: a **Start frame**, an **End frame**, **Reference images**, or an image to edit. Some take a reference video. Add them in the slots under the prompt, or leave them empty to work from the prompt alone. **4. Check the cost and generate** Adjust the settings, such as length or aspect ratio. The estimated credits show under the button. Choose **Generate**, or press ⌘ Enter (Ctrl Enter). Not sure where to start? The **Examples** tab shows what each model can do. Choose **Use this example** to load its prompt and settings. > [!WARNING] > > Generating spends Voyager credits as soon as the job starts. Check the estimate first, especially for long or high-resolution video. ## Check it worked When the result is ready it appears under **Latest**. Play it, open it larger, or choose **Download** to save it. **Run again** makes another take with the same settings. ## Your generations Everything you've made in this workspace is under **Your generations**, next to **Examples** on each Generate page. You can also open it from your account menu. Each page shows its own kind: videos on **Video**, images on **Image**, sounds on **Audio**. Choose a result to open it, or the download button to save it. ## If something went wrong > [accordion] The button says Upgrade plan > > The model you picked isn't in your workspace's plan, and the message says which plan it starts on. Your prompt and settings stay while you upgrade. Only workspace owners and admins can upgrade; if you're a member, ask one of them. Or pick another model. > [accordion] More credits needed, or Free generation allowance used > > Your workspace doesn't have enough Voyager credits for this generation. Owners and admins can add credits in **Settings → Plan & billing**. On Free, wait for your allowance to renew or upgrade. See [Plans and credits](/account/plans-and-credits). > [accordion] The button says Request access > > Some models must be turned on for a workspace before anyone can use them. Choose **Request access**, read and confirm the rules, and send the request. The button shows **Requested** until it's answered. > [accordion] A Voyager seat is required > > Your workspace has a plan, but you don't have a seat on it yet. Ask a workspace owner or admin to give you one. ## Related pages > [card] [Use your dashboard](/web/dashboard) > > Everything else on voyager.so/dashboard. > [card] [Connect your AI](/connect/overview) > > Generate from ChatGPT, Claude or Codex instead.