Suzanne Uploads API

openapi: 3.2.0
info:
  title: Suzanne Uploads 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: Uploads
  description: Presigned image uploads
paths:
  /v1/uploads:
    post:
      operationId: createUpload
      tags:
      - Uploads
      summary: Create a presigned upload URL
      description: Get a 5-minute presigned PUT URL so the client uploads a JPEG/PNG directly to S3 (bypasses the API Gateway 10 MB body limit). Empty body, just the auth header. Then PUT the image to upload_url WITHOUT a Content-Type header. The object auto-expires after 7 days.
      responses:
        '201':
          description: 201 Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadCreated'
        '401':
          description: unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: 'internal: could not generate a presigned URL; retry'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-source: https://console.suzanne3d.com/documentation/uploads
      x-evidence:
        kind: documentation
        response_status_on_page: 'Response: 201 Created'
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.
    UploadCreated:
      type: object
      properties:
        upload_id:
          type: string
          description: upl_<uuid>
        upload_url:
          type: string
          format: uri
          description: Presigned S3 PUT URL, valid 5 minutes. Do NOT send a Content-Type header on the PUT.
        expires_at:
          type: string
          format: date-time
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      description: 'Authorization: Bearer <key>. Keys start with sznn_test_ (sandbox) or sznn_live_ (production). Server-side only.'