Suzanne Jobs API

openapi: 3.2.0
info:
  title: Suzanne Jobs API
  version: '2026-10-07'
  description: 'Turn a text prompt or 1-4 photos into a textured 3D mesh. The API returns standard GLB (and optionally OBJ / STL / FBX). Submit a job, poll GET /v1/jobs/{job_id} until it is terminal, then download. Base URL: https://api.suzanne3d.com. GENERATED FROM DOCUMENTATION by API Evangelist; Suzanne publishes no machine-readable contract.'
  x-evidence-tiers:
    code-example: 2
    documentation: 5
    pages-with-code: 4
    pages-read: 17
  x-generated-from: documentation
  x-provenance: generated
  x-authored-by: API Evangelist
  x-generated: '2026-10-07'
  x-generator: generate-contract-from-docs.py
  x-engine: anthropic
  x-sources:
  - https://console.suzanne3d.com/documentation
  - https://console.suzanne3d.com/documentation/errors
  - https://console.suzanne3d.com/documentation/quickstart
  - https://console.suzanne3d.com/documentation/authentication
  - https://console.suzanne3d.com/documentation/models
  - https://console.suzanne3d.com/documentation/atelier2
  - https://console.suzanne3d.com/documentation/parameters
  - https://console.suzanne3d.com/documentation/idempotency
  - https://console.suzanne3d.com/documentation/text-to-3d
  - https://console.suzanne3d.com/documentation/photo-to-3d
  - https://console.suzanne3d.com/documentation/uploads
  - https://console.suzanne3d.com/documentation/jobs
  - https://console.suzanne3d.com/documentation/cancel-job
  - https://console.suzanne3d.com/documentation/download-model
  - https://console.suzanne3d.com/documentation/limits
  - https://console.suzanne3d.com/documentation/recipes
  - https://console.suzanne3d.com/documentation/claude-code-integration
  x-repair:
    date: '2026-10-07'
    by: enrichment pass (script-gated)
    reason: generate-contract-from-docs.py kept 0 operations from the six endpoint pages and its collapse step merged the sibling literal paths /v1/generations/text-to-3d + /v1/generations/photo-to-3d into /v1/generations/{generationid} and /v1/uploads into /v1/{v1id}; those paths exist on no page. The operations below were re-derived one per endpoint page, each METHOD + path gated verbatim against that page; schemas carry only the fields the page example responses show.
servers:
- url: https://api.suzanne3d.com
security:
- bearer: []
tags:
- name: Jobs
  description: Poll and cancel jobs
paths:
  /v1/jobs/{job_id}:
    get:
      operationId: getJob
      tags:
      - Jobs
      summary: Poll job status
      description: Poll job status. Returns the current state plus download URLs once the mesh is ready. Typical job latency is 30 s - 2 min for single-image, 1 - 4 min for multi-view. Poll every 5-10 s; give up after 20 min.
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
        description: job_<uuid>
      responses:
        '200':
          description: 200 OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
        '401':
          description: unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: 'not_found: no such job, or it belongs to a different account'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-source: https://console.suzanne3d.com/documentation/jobs
      x-evidence:
        kind: documentation
        response_status_on_page: 'Response: 200 OK'
  /v1/jobs/{job_id}/cancel:
    post:
      operationId: cancelJob
      tags:
      - Jobs
      summary: Cancel a queued or running job
      description: 'Cancel a queued or running job. Best-effort; if the job is already running, the worker checks for cancellation between vendor calls and refunds the bill if it stops. already_terminal: true means the job was already done / failed / cancelled (no-op).'
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: 200 OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancelResult'
        '401':
          description: unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-source: https://console.suzanne3d.com/documentation/cancel-job
      x-evidence:
        kind: documentation
        response_status_on_page: 'Response: 200 OK'
components:
  schemas:
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              enum:
              - invalid_request
              - auth
              - rate_limit
              - internal
              - vendor
            code:
              type: string
              description: machine-readable string
            message:
              type: string
            request_id:
              type: string
              description: Always include request_id in support requests.
    JobError:
      type: object
      properties:
        code:
          type: string
          enum:
          - vendor_model_error
          - vendor_http_error
          - vendor_timeout
          - vendor_not_configured
          - missing_image
          - insufficient_views
          - job_cancelled
          - sqs_enqueue_failed
        message:
          type: string
    Job:
      type: object
      properties:
        job_id:
          type: string
        status:
          type: string
          enum:
          - queued
          - running
          - done
          - failed
          - cancelled
        model:
          type: string
          enum:
          - sculptor
          - atelier
          - capture
          description: Stable named model; all three run on the Atelier2 engine.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        completed_at:
          type:
          - string
          - 'null'
          format: date-time
        outputs:
          type: array
          items:
            type: object
            properties:
              format:
                type: string
                enum:
                - glb
                - obj
                - stl
                - fbx
              download_url:
                type: string
                format: uri
                description: Stable download URL; call it to get a fresh 15-minute presigned S3 URL.
        error:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/JobError'
          description: Set when status == "failed".
    CancelResult:
      type: object
      properties:
        job_id:
          type: string
        status:
          type: string
          enum:
          - cancelled
          - queued
          - running
          - done
          - failed
        already_terminal:
          type: boolean
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      description: 'Authorization: Bearer <key>. Keys start with sznn_test_ (sandbox) or sznn_live_ (production). Server-side only.'