> ## 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.

# Cancel a job

> 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.



## OpenAPI

````yaml /openapi/voyager-api.yaml post /jobs/{job_id}/cancel
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": "<id>", "operation": "<op>", "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/<job id>?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:
  /jobs/{job_id}/cancel:
    post:
      tags:
        - Jobs
      summary: Cancel a job
      description: >-
        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.
      operationId: cancelJob
      parameters:
        - name: job_id
          in: path
          required: true
          schema:
            type: string
            title: Job Id
        - name: Idempotency-Key
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Accepted and validated; a cancel is idempotent itself.
            title: Idempotency-Key
          description: Accepted and validated; a cancel is idempotent itself.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
          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, invalid or revoked API key.
          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: Not found in this workspace.
          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: Conflict with the resource's current state.
          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: Temporarily unavailable. Retry with backoff.
          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:
        - bearerAuth: []
components:
  schemas:
    Job:
      properties:
        id:
          type: string
          title: Id
          description: job_…
        object:
          type: string
          const: job
          title: Object
          default: job
          description: Always "job".
        type:
          type: string
          title: Type
          description: image, video, speech, music, sound_effect or 3d.
        model:
          anyOf:
            - type: string
            - type: 'null'
          title: Model
          description: The model that ran (or will run) the job.
        operation:
          anyOf:
            - type: string
            - type: 'null'
          title: Operation
          description: e.g. text-to-image, edit, image-to-video, tts.
        status:
          type: string
          enum:
            - queued
            - running
            - succeeded
            - failed
            - canceled
          title: Status
          description: queued, running, succeeded, failed or canceled.
        input:
          additionalProperties: true
          type: object
          title: Input
          description: The job's input, as sent.
        outputs:
          items:
            $ref: '#/components/schemas/JobOutput'
          type: array
          title: Outputs
          description: The files the job made, once it succeeded.
        credits:
          $ref: '#/components/schemas/JobCredits'
          description: What the job is expected to cost and what it was charged.
        error:
          anyOf:
            - $ref: '#/components/schemas/JobError'
            - type: 'null'
          description: Why the job failed or was canceled.
        metadata:
          additionalProperties:
            type: string
          type: object
          title: Metadata
          description: The metadata sent with the job, echoed as is.
        created_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Created At
          description: When it was created (ISO 8601).
        started_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Started At
          description: When the job started running (ISO 8601); null while queued.
        completed_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Completed At
          description: When the job reached a terminal status (ISO 8601); null until then.
        poll_after_ms:
          anyOf:
            - type: integer
            - type: 'null'
          title: Poll After Ms
          description: 'While active: when to poll again.'
        links:
          $ref: '#/components/schemas/JobLinks'
          description: Links to read and cancel the job.
        cast_usage:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Cast Usage
          description: >-
            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.
      type: object
      required:
        - id
        - type
        - model
        - operation
        - status
        - input
        - outputs
        - credits
        - error
        - metadata
        - created_at
        - started_at
        - completed_at
        - poll_after_ms
        - links
      title: Job
    ErrorResponse:
      properties:
        error:
          $ref: '#/components/schemas/ErrorBody'
          description: What went wrong.
      type: object
      required:
        - error
      title: ErrorResponse
      description: Every non-2xx answer.
    JobOutput:
      properties:
        id:
          type: string
          title: Id
          description: file_… id; GET /v1/files/{id} for a fresh link.
        object:
          type: string
          const: file
          title: Object
          default: file
          description: Always "file".
        type:
          type: string
          title: Type
          description: image, video, audio, model3d or other.
        mime_type:
          type: string
          title: Mime Type
          description: The file's media type, e.g. image/png or video/mp4.
        file_name:
          type: string
          title: File Name
          description: The file's name.
        size_bytes:
          type: integer
          title: Size Bytes
          description: Size in bytes.
        url:
          type: string
          title: Url
          description: Signed download link, valid one hour.
        url_expires_at:
          type: string
          format: date-time
          title: Url Expires At
          description: >-
            When `url` stops working (ISO 8601); read the object again for a
            fresh link.
        expires_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Expires At
          description: When the file itself is deleted (outputs are kept 30 days).
        width:
          anyOf:
            - type: integer
            - type: 'null'
          title: Width
          description: Width in pixels, when known.
        height:
          anyOf:
            - type: integer
            - type: 'null'
          title: Height
          description: Height in pixels, when known.
        duration_seconds:
          anyOf:
            - type: number
            - type: 'null'
          title: Duration Seconds
          description: Length in seconds, when known.
        formats:
          anyOf:
            - items:
                $ref: '#/components/schemas/JobOutputFormat'
              type: array
            - type: 'null'
          title: Formats
          description: '3D jobs: every downloadable format.'
        preview_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Preview Url
          description: '3D jobs: a still preview.'
        role:
          anyOf:
            - type: string
            - type: 'null'
          title: Role
          description: >-
            What the file is beside the main output: mask, cutout, mask_video,
            data or preview (segmentation).
        metadata:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Metadata
          description: >-
            Per-file facts: a mask's object_id, score and box (source pixels), a
            mask video's frames.
      type: object
      required:
        - id
        - type
        - mime_type
        - file_name
        - size_bytes
        - url
        - url_expires_at
        - expires_at
      title: JobOutput
    JobCredits:
      properties:
        estimated:
          anyOf:
            - type: number
            - type: 'null'
          title: Estimated
          description: Estimated charge when the job is accepted. Not a cap.
        held:
          anyOf:
            - type: number
            - type: 'null'
          title: Held
          description: Credits held for this job now, where proven; null when unknown.
        charged:
          anyOf:
            - type: number
            - type: 'null'
          title: Charged
          description: Final charge once settled; null until then (never a stand-in zero).
        released:
          anyOf:
            - type: number
            - type: 'null'
          title: Released
          description: Held credits returned, where proven; null when unknown.
        state:
          type: string
          enum:
            - pending
            - settled
            - unresolved
          title: State
          description: >-
            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.
        charge_ref:
          anyOf:
            - type: string
            - type: 'null'
          title: Charge Ref
          description: The charge reference in your usage records; quote it to support.
      type: object
      required:
        - estimated
        - held
        - charged
        - released
        - state
        - charge_ref
      title: JobCredits
    JobError:
      properties:
        code:
          type: string
          title: Code
          description: A stable machine code (see x-voyager-errors).
        message:
          type: string
          title: Message
          description: For developers. Not localized.
        details:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Details
          description: Code-specific detail.
      type: object
      required:
        - code
        - message
      title: JobError
    JobLinks:
      properties:
        self:
          type: string
          title: Self
          description: GET this job.
        cancel:
          type: string
          title: Cancel
          description: POST here to cancel the job.
      type: object
      required:
        - self
        - cancel
      title: JobLinks
    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#<code>
        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
    JobOutputFormat:
      properties:
        format:
          type: string
          title: Format
          description: glb, fbx, usdz, obj or ply.
        id:
          type: string
          title: Id
          description: The format's id.
        url:
          type: string
          title: Url
          description: A link to the file in this format.
        url_expires_at:
          type: string
          format: date-time
          title: Url Expires At
          description: >-
            When `url` stops working (ISO 8601); read the object again for a
            fresh link.
      type: object
      required:
        - format
        - id
        - url
        - url_expires_at
      title: JobOutputFormat
    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:
    bearerAuth:
      type: http
      description: A Voyager API key from https://voyager.so/dashboard/api.
      scheme: bearer
      bearerFormat: vy_live_…

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.