tomorrowlives-com Jobs API

openapi: 3.2.0
info:
  title: Tomorrow Lives Engines Jobs API
  version: 2026-10-12.5
  description: 'Reproducible, IP-clean assets for software agents: the same request returns the same bytes, and no image, video or voice model made any of it. Seven production engines (tagged Production engines) make print designs, materials, forms, characters, terrain, voice, and short videos and shots rendered in a queue. The Lab (tagged Lab, https://tomorrowlives.com/lab) holds research instruments, which answer a question instead of making an asset; today that is the pull engine, which measures whether one agent follows another beyond chance. Both share one account, one key and one endpoint. A Pull run is paid for by the same engine account as the seven production engines, from the same units, and there is no separate Pull plan: a run costs units, drawn first from the included units of the account''s pass or card plan, then from its unit packs (500 for $10.00), or on the free plan from the free allowance. An agent buys a 30-day pass with a shared payment token: $1.00 the first time (a one-time offer for a new owner), then $20.00, with 1,500 units each. A pass never renews. More units: 500 for $10.00 a pack, spent after the included units and kept until used. A person can subscribe by card: $1.00 the first month, then $20.00 a month, with the same units. It renews automatically until cancelled; cancel any time. Available in the United States. Free plan: 50 units a month, no card needed; it starts when the owner confirms their email. Queued renders need a pass or the card plan. We limit free plans and first-pass offers to prevent abuse. Docs: https://tomorrowlives.com/engines. Terms: https://tomorrowlives.com/engines/terms.'
  termsOfService: https://tomorrowlives.com/engines/terms
servers:
- url: https://tomorrowlives.com
tags:
- name: Jobs
  description: Queued jobs, their files and cancelling them.
paths:
  /api/agents/jobs:
    get:
      operationId: jobs
      summary: This account's newest queued jobs, at most 50, ids and states only, newest first
      description: The queued jobs are video_still, video_render, raster_render, and a large pull_analyse, pull_twin or pull_lab. GET /api/agents/jobs/{job} reads one in full.
      security:
      - apiKey: []
      responses:
        '200':
          description: The jobs
          content:
            application/json:
              schema:
                type: object
                properties:
                  jobs:
                    type: array
                    items:
                      type: object
                      properties:
                        job:
                          type: string
                        status:
                          $ref: '#/components/schemas/JobState'
                  limit:
                    type: integer
        '401':
          description: No valid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: unauthorized
                message: send the engine API key as a bearer token
      tags:
      - Jobs
  /api/agents/jobs/{job}/cancel:
    post:
      operationId: cancelJob
      summary: 'Cancel a queued job. Waiting: cancelled at no charge.'
      description: A job still waiting is cancelled at once and costs nothing. A running one is stopped and charged for the CPU it had used, one unit for each 10 CPU-seconds rounded up, never more than its price; the answer waits for it to stop and carries the units charged. 202 if it was told to stop but is not yet written as stopped (poll it); 409 not_cancellable if it had already ended or was never queued.
      security:
      - apiKey: []
      parameters:
      - name: job
        in: path
        required: true
        schema:
          type: string
          pattern: ^job_[0-9a-f]{24}$
      responses:
        '200':
          description: Cancelled; units is what it was charged
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobStatus'
        '202':
          description: Told to stop; poll the job until it reads cancelled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobStatus'
        '401':
          description: No valid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: unauthorized
                message: send the engine API key as a bearer token
        '404':
          description: No such verb or job
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: not_found
                message: there is no such job
        '409':
          description: The request conflicts with the account's state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Jobs
  /api/agents/jobs/{job}:
    get:
      operationId: job
      summary: A job's record and fresh signed URLs for its files, within 24 hours.
      description: A queued job (video_still, video_render, raster_render, and a large pull_analyse, pull_twin or pull_lab) reads queued, running, ok, refused, failed, cancelled or expired. A queued pull job's result is its verdict, and its whole report is the file report.json. Once ok, its files come as signed URLs that work for 15 minutes; ask again for fresh ones until the files are deleted, 24 hours after the job finished (then expired). wait holds the answer until the job ends or that many seconds pass, at most 25.
      security:
      - apiKey: []
      parameters:
      - name: job
        in: path
        required: true
        schema:
          type: string
          pattern: ^job_[0-9a-f]{24}$
      - name: wait
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          maximum: 25
        description: Seconds to hold the answer while a queued job runs
      responses:
        '200':
          description: The job
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobStatus'
        '401':
          description: No valid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: unauthorized
                message: send the engine API key as a bearer token
        '404':
          description: No such verb or job
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: not_found
                message: there is no such job
      tags:
      - Jobs
  /api/agents/outputs/{job}/{file}:
    get:
      operationId: output
      summary: Download one output file.
      security: []
      parameters:
      - name: job
        in: path
        required: true
        schema:
          type: string
      - name: file
        in: path
        required: true
        schema:
          type: string
      - name: expires
        in: query
        required: true
        schema:
          type: integer
      - name: sig
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The file
        '403':
          description: The signature is wrong or has expired
        '410':
          description: The 24-hour hold has passed
      tags:
      - Jobs
      description: The signed URL comes in a job's answer. The file is held for 24 hours after the job finished; ask the job again for a fresh URL while it is held. No API key is needed.
components:
  schemas:
    JobState:
      type: string
      enum:
      - queued
      - running
      - ok
      - refused
      - failed
      - cancelled
      - expired
    File:
      type: object
      properties:
        name:
          type: string
        bytes:
          type: integer
        content_type:
          type: string
        url:
          type: string
        url_expires_at:
          type: string
          format: date-time
    JobStatus:
      type: object
      properties:
        job:
          type: string
        verb:
          type: string
        units:
          type: integer
          description: The price while it waits or runs; once it ends, what it was charged
        status:
          $ref: '#/components/schemas/JobState'
        queued:
          type: boolean
        created_at:
          type: string
          format: date-time
        started_at:
          type:
          - string
          - 'null'
          format: date-time
        finished_at:
          type:
          - string
          - 'null'
          format: date-time
        retry_after_s:
          type: integer
          description: 'While queued or running: when to ask again'
        result:
          description: 'Once ok: what the engine printed, as JSON'
        error:
          type: string
        message:
          type: string
        http_status:
          type: integer
          description: 'For refused or failed: the status an immediate call would have had'
        files_expire_at:
          type: string
          format: date-time
        files:
          type: array
          items:
            $ref: '#/components/schemas/File'
    Error:
      type: object
      required:
      - error
      - message
      properties:
        error:
          type: string
        message:
          type: string
        limit:
          type: string
          enum:
          - monthly_units
          - free_plan_units
          - not_eligible
          - rate
        reset_at:
          type: string
          format: date-time
        retry_after_s:
          type: integer
        policy:
          type: object
          description: 'With error content_policy: the rule the input broke and the acceptable use policy''s address'
          properties:
            rule:
              type: string
              enum:
              - trademark
              - hate
              - minors
              - impersonation
            acceptable_use_policy:
              type: string
              format: uri
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: An engine API key (tleng_...) from POST /api/agents/signup
x-limits:
  units_per_period: 1500
  pass:
    days: 30
    first_cents: 100
    cents: 2000
    renews: false
    buy: /api/agents/subscribe
  unit_pack:
    units: 500
    cents: 1000
    spent_after: units_per_period
    expire: false
    buy: /api/agents/units
  card_plan:
    first_month_cents: 100
    monthly_cents: 2000
    renews: monthly, until cancelled
    subscribe: /engines/subscribe
  free_plan:
    units_per_month: 50
    queued_renders: need a pass or the card plan
    starts_when: the owner confirms their email
  max_input_bytes: 1048576
  max_output_bytes: 52428800
  output_hold_hours: 24
  unit_costs:
    art_schema: none
    art_presets: none
    art_materials: none
    art_starter: none
    art_check: none
    art_render: 1 at 1200 pixels wide or less, 5 above
    art_swatch: 1 at 512 or less, 2 above
    material_bake: 1 at 512 or less, 2 at 1024
    material_check: none
    material_cost: none
    material_apply: '1'
    form_starter: none
    form_check: none
    form_apply: '1'
    form_build: '1'
    character_list: none
    character_generate: 3 for a person at near detail; 1 at mid or far, for the lofted figure and for an animal
    terrain_heightmap: '1'
    city_plan: '1'
    world_schema: none
    world_starter: none
    world_check: none
    world_apply: '1'
    world_heightmap: '1'
    voice_speak: '1'
    sound_list: none
    sound_effect: '1'
    video_schema: none
    video_presets: none
    video_examples: none
    video_check: none
    video_cost: none
    video_still: 1, or with shots in the scene 1 plus 3 plus 1 for each 1.6 megapixels
    video_render: 'from the engine''s cost report: design renders x megapixels / 45, plus frames x megapixels / 200, plus shot frames x megapixels / 1.6, plus 3 a shot clip (video_cost says it first); at most 600'
    raster_schema: none
    raster_check: none
    raster_render: '3 plus 1 for each 1.6 megapixels: 4 at 1280x720, 5 at 1920x1080'
    pull_schema: none
    pull_prereg: none
    pull_analyse: 1 for each 40,000 session-draws over a thousand events, at least 1 (300 default twin sessions cost 9); over 2, queued; at most 300
    pull_twin: 1 for each 40,000 session-draws over a thousand events, at least 1 (300 default twin sessions cost 9); over 2, queued; at most 300
    pull_cost: none
    pull_schedule: '1'
    pull_seal: '1'
    pull_open: '1'
    pull_close: '1'
    pull_replay: '1'
    pull_align: '1'
    pull_lab: 1 for a one-dimensional reference; a theory document (one-dimensional or with a model) and reference skyrme or hopfion are queued and cost 1 for each 5 CPU-seconds of one thread the engine estimates from its lattice and steps (pull_cost says it first); at most 300
    pull_practice: '1'
    pull_call: '1'
  queued:
    verbs:
    - video_still
    - video_render
    - raster_render
    - pull_analyse
    - pull_twin
    - pull_lab
    max_video_seconds: 60
    max_long_side: 1920
    max_short_side: 1080
    max_fps: 30
    max_units_per_job: 600
    job_minutes: 40
    max_output_bytes: 52428800
    poll_wait_max_s: 25
  pull:
    units: ceil(sum over sessions of (draws + 200) x max(1, events / 1000) / 40000), at least 1
    max_surrogates: 9999
    max_twin_sessions: 1000
    max_sessions: 200
    max_events_per_session: 50000
    max_twin_beats: 5000
    immediate_units: 2
    immediate_twin_sessions: 20
    max_units_per_job: 300
    cpu_seconds_per_unit: 15
    quick_seconds: 30