> ## Documentation Index > Fetch the complete documentation index at: https://docs.voyager.so/llms.txt > Use this file to discover all available pages before exploring further. # Run Command > 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`). ## OpenAPI ````yaml /openapi/voyager-api.yaml post /machines/{machine}/run openapi: 3.1.0 info: title: Voyager API description: >- Generate images, video, speech, music, sound effects and 3D with your Voyager workspace's credits. Authenticate with `Authorization: Bearer vy_live_…`. Every response carries `X-Request-ID` and the `X-RateLimit-Limit` / `X-RateLimit-Remaining` / `X-RateLimit-Reset` (seconds until the window resets) headers; a 429 adds `Retry-After`. Errors share one envelope (`ErrorResponse`). version: 1.0.0 x-voyager-agent-prompt: > 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). servers: - url: https://api.voyager.so/v1 description: Production security: [] paths: /machines/{machine}/run: post: tags: - machines summary: Run Command description: >- 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`). operationId: runCloudMachineCommand parameters: - name: machine in: path required: true schema: type: string title: Machine - name: Idempotency-Key in: header required: false schema: anyOf: - type: string maxLength: 120 - type: 'null' description: >- Repeat a request safely: the same key and body return the original result. title: Idempotency-Key description: >- Repeat a request safely: the same key and body return the original result. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/MachineRun' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/MachineRunResult' headers: X-Request-ID: $ref: '#/components/headers/X-Request-ID' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' '202': description: The job, still running. content: application/json: schema: $ref: '#/components/schemas/MachineJob' headers: X-Request-ID: $ref: '#/components/headers/X-Request-ID' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' '400': description: The request is invalid (`INVALID_REQUEST`). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: X-Request-ID: $ref: '#/components/headers/X-Request-ID' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' '401': description: Missing or invalid credential. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: X-Request-ID: $ref: '#/components/headers/X-Request-ID' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' '402': description: >- Not enough credits (`INSUFFICIENT_CREDITS`); `details.upgrade_url` links to billing. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: X-Request-ID: $ref: '#/components/headers/X-Request-ID' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' '403': description: >- This workspace needs a paid Voyager plan with a completed payment (`PLAN_REQUIRED`, `VERIFICATION_REQUIRED`; `details.upgrade_url`), or the key lacks a scope. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: X-Request-ID: $ref: '#/components/headers/X-Request-ID' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' '404': description: No such machine, job or path. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: X-Request-ID: $ref: '#/components/headers/X-Request-ID' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' '409': description: >- The machine is in the wrong state for this (e.g. `MACHINE_NOT_READY`, `MACHINE_RELEASED`), or the Idempotency-Key was used for a different request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: X-Request-ID: $ref: '#/components/headers/X-Request-ID' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' '429': description: Rate limited; retry after `Retry-After` seconds. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: X-Request-ID: $ref: '#/components/headers/X-Request-ID' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' Retry-After: $ref: '#/components/headers/Retry-After' '503': description: >- No capacity or a temporary outage; retry after `Retry-After` seconds. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: X-Request-ID: $ref: '#/components/headers/X-Request-ID' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' security: - API Key: [] components: schemas: MachineRun: properties: command: anyOf: - type: string maxLength: 65536 minLength: 1 - type: 'null' title: Command description: A shell command (run with `sh -c`). argv: anyOf: - items: type: string type: array maxItems: 4096 minItems: 1 - type: 'null' title: Argv description: Or an argv, no shell. cwd: type: string maxLength: 1024 minLength: 1 title: Cwd default: /project description: The working directory (default `/project`). env: additionalProperties: type: string type: object title: Env description: Extra environment variables. timeout: anyOf: - type: integer maximum: 604800 minimum: 1 - type: 'null' title: Timeout description: Kill the command after N s. wait: type: boolean title: Wait description: >- Wait up to about 60 s for it to finish and return its output; after that the running job. default: false additionalProperties: false type: object title: MachineRun MachineRunResult: properties: job_id: type: string title: Job Id description: The job id (`mjb_…`). status: type: string enum: - succeeded - failed - canceled title: Status description: The state (see the enum). exit_code: anyOf: - type: integer - type: 'null' title: Exit Code description: The command's exit code, once it has ended. stdout: type: string title: Stdout description: The command's output (stderr is merged into it, in order). stderr: type: string title: Stderr description: 'Always empty: stderr is merged into stdout.' truncated: type: boolean title: Truncated description: True when only the last 256 KB of output is returned. resumed: type: boolean title: Resumed description: True when the machine was paused and resumed for this call. next: type: string title: Next description: What to do next, for agents. type: object required: - job_id - status - exit_code - stdout - stderr - truncated - resumed - next title: MachineRunResult MachineJob: properties: id: type: string title: Id description: The job id (`mjb_…`). machine_id: type: string title: Machine Id description: The machine id (`mch_…`). status: type: string enum: - running - succeeded - failed - canceled title: Status description: The state (see the enum). exit_code: anyOf: - type: integer - type: 'null' title: Exit Code description: The command's exit code, once it has ended. output_tail: anyOf: - type: string - type: 'null' title: Output Tail description: The last few KB of output (stdout and stderr together). started_at: anyOf: - type: string - type: 'null' title: Started At description: When the job started running (ISO 8601); null while queued. ended_at: anyOf: - type: string - type: 'null' title: Ended At description: When it ended. resumed: type: boolean title: Resumed description: True when the machine was paused and resumed for this run. default: false next: type: string title: Next description: What to do next, for agents. type: object required: - id - machine_id - status - exit_code - output_tail - started_at - ended_at - next title: MachineJob ErrorResponse: properties: error: $ref: '#/components/schemas/ErrorBody' description: What went wrong. type: object required: - error title: ErrorResponse description: Every non-2xx answer. ErrorBody: properties: type: $ref: '#/components/schemas/ErrorType' description: Stable category to branch on. code: type: string enum: - invalid_request - invalid_input - content_policy - upstream_unavailable - rate_limited - queue_full - model_unavailable - model_not_found - insufficient_credits - paid_plan_required - model_not_in_plan - model_access_required - outcome_unknown - expired - not_found - conflict - forbidden - internal_error - catalog_unavailable - billing_unavailable - no_voyager_seat - credits_reloading - cast_not_supported - voice_cloning_unavailable - too_many_references - payload_too_large - upload_too_large - intake_full - invalid_url - fetch_failed - unsupported_file - invalid_api_key - idempotency_conflict - idempotency_in_flight - invalid_idempotency_key - invalid_cursor - invalid_webhook_url - method_not_allowed - account_unavailable - plan_required_for_faces - version_conflict - slug_taken - already_referenced - asset_in_use - upload_incomplete - cancel_unsupported - unsupported_model - invalid_job_id - voice_required - observation_timeout - reference_unavailable - queue_timeout - reference_missing title: Code description: >- Stable machine code; never renamed once published (x-voyager-errors lists each). message: type: string title: Message description: For developers. Not localized. doc_url: type: string title: Doc Url description: https://docs.voyager.so/api/errors# request_id: anyOf: - type: string - type: 'null' title: Request Id description: Also in the X-Request-ID header; quote it to support. retryable: anyOf: - type: boolean - type: 'null' title: Retryable description: Whether the same request can succeed later. retry_after_ms: anyOf: - type: integer - type: 'null' title: Retry After Ms description: How long to wait before retrying. param: anyOf: - type: string - type: 'null' title: Param description: >- The request field at fault, as a path (e.g. input.resolution); set on invalid_input. details: anyOf: - additionalProperties: true type: object - type: 'null' title: Details description: Code-specific detail, e.g. upgrade_url on a billing wall. type: object required: - type - code - message - doc_url title: ErrorBody ErrorType: type: string enum: - invalid_request - authentication - permission - not_found - conflict - rate_limited - idempotency_conflict - unprocessable - upstream_error - internal_error title: ErrorType description: Closed set of high-level categories SDKs branch on. headers: X-Request-ID: description: This request's id (also error.request_id). schema: type: string X-RateLimit-Limit: description: >- Requests allowed per 60 seconds in this bucket (120 writes or 600 reads per minute per key). schema: type: integer X-RateLimit-Remaining: description: Requests left in this window. schema: type: integer X-RateLimit-Reset: description: Seconds until the window resets. schema: type: integer Retry-After: description: Seconds to wait before retrying. schema: type: integer securitySchemes: API Key: type: http description: API key from Settings > Developer > REST API scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.