Hermoso AI Jobs API

openapi: 3.2.0
info:
  title: Hermoso Ai Jobs API
  version: '2026-08-26'
  description: 'Operations tagged jobs across 2 of this provider''s published API definitions: app_hermoso_ai.json, app_hermoso_ai_rest.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://app.hermoso.ai
security:
- bearerAuth: []
tags:
- name: Jobs
paths:
  /v1/jobs:
    get:
      operationId: listJobs
      summary: List jobs
      description: 'Renders and other long-running work for this profile, newest first. Cursor-paginated. A job belongs to the profile that started it (`brand_id`); send `X-Hermoso-User` to list another profile’s. Jobs are kept while they are useful to poll, not forever: a finished job ages out of this list, and its output lives on in the Library.'
      tags:
      - Jobs
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
        description: 1-100, default 25.
      - name: starting_after
        in: query
        required: false
        schema:
          type: string
        description: A job id from a previous page; returns the page after it. An unknown cursor is an error, never a silent restart.
      - name: status
        in: query
        required: false
        schema:
          type: string
        description: 'Filter: queued, running, done, error.'
      - name: type
        in: query
        required: false
        schema:
          type: string
        description: Filter to one job type, e.g. video, stitch, avatar, templatead.
      - name: X-Hermoso-User
        in: header
        required: false
        schema:
          type: string
        description: 'Which profile to act on, when the account holds more than one: an `id` from `GET /v1/brands`. Defaults to the workspace the key is pinned to. Membership is re-authorised on every request, and an id this key cannot act on is a 404 `brand_not_found`, never an empty result.'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobList'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing, invalid or revoked key — or a channel that is not connected, in which case `error.connector` names it and `error.type` is `connector_error`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: '`error.code: brand_not_found`: `X-Hermoso-User` (or the profile this key is pinned to) names a profile this key cannot act on. `GET /v1/brands` lists the valid ids.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited. `Retry-After` says how long to wait.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - bearerAuth: []
    servers:
    - url: https://app.hermoso.ai
  /v1/jobs/{id}:
    get:
      operationId: getJob
      summary: Retrieve a job
      description: 'One job. Poll this until `status` is `done` or `error`; a few seconds between reads is plenty, and reads spend the read budget, not the write one. `url` is the finished file once there is one. An id that is not on your account is a 404, whether or not it exists somewhere else, and that answer is final: stop polling it and do not re-run the render on the strength of it.'
      tags:
      - Jobs
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: X-Hermoso-User
        in: header
        required: false
        schema:
          type: string
        description: 'Which profile to act on, when the account holds more than one: an `id` from `GET /v1/brands`. Defaults to the workspace the key is pinned to. Membership is re-authorised on every request, and an id this key cannot act on is a 404 `brand_not_found`, never an empty result.'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing, invalid or revoked key — or a channel that is not connected, in which case `error.connector` names it and `error.type` is `connector_error`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: '`error.code: job_not_found`: no job with that id on this account. Also `error.code: brand_not_found` when `X-Hermoso-User` names a profile this key cannot act on; `GET /v1/brands` lists the valid ids.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited. `Retry-After` says how long to wait.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - bearerAuth: []
    servers:
    - url: https://app.hermoso.ai
  /v1/jobs/{id}/cancel:
    post:
      operationId: cancelJob
      summary: Cancel an image or video job
      description: 'Stop an image or video generation. A job that has not started is stopped and charged nothing. A job that is starting stops before it reaches a model when it still can, and is charged nothing if it does. Once a model is rendering it, the render cannot be called back: it finishes, its credits are used and it lands in the Library, and `outcome` says so. Keep polling `GET /v1/jobs/{id}` for the final state; a stopped job ends `error` with `cancelled: true`. Safe to repeat.'
      tags:
      - Jobs
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: X-Hermoso-User
        in: header
        required: false
        schema:
          type: string
        description: 'Which profile to act on, when the account holds more than one: an `id` from `GET /v1/brands`. Defaults to the workspace the key is pinned to. Membership is re-authorised on every request, and an id this key cannot act on is a 404 `brand_not_found`, never an empty result.'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobCancel'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing, invalid or revoked key — or a channel that is not connected, in which case `error.connector` names it and `error.type` is `connector_error`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: '`error.code: job_not_found`: no job with that id on this account. Also `error.code: brand_not_found` when `X-Hermoso-User` names a profile this key cannot act on; `GET /v1/brands` lists the valid ids.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: '`error.code: not_cancellable`: only image and video generations are cancelled here.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited. `Retry-After` says how long to wait.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - bearerAuth: []
    servers:
    - url: https://app.hermoso.ai
components:
  schemas:
    Job:
      type: object
      properties:
        object:
          type: string
          enum:
          - job
        id:
          type: string
        type:
          type: string
          description: 'What kind of work it is: video, stitch, avatar, templatead, upscale, and so on. This set MAY GROW.'
        status:
          type: string
          description: 'queued, running, done or error. `done` and `error` are final. This enum MAY GROW: keep polling on a value you have not seen.'
        progress:
          type: number
          description: 0 to 1, when the worker reports it.
        label:
          type: string
          nullable: true
        brand_id:
          type: string
          description: The profile that started the job.
        created_at:
          type: string
          nullable: true
          description: ISO-8601.
        updated_at:
          type: string
          nullable: true
          description: ISO-8601. For a finished job, when it finished.
        run_at:
          type: string
          nullable: true
          description: ISO-8601, for work scheduled to start later; null for work that starts immediately.
        url:
          type: string
          nullable: true
          description: The finished file, once `status` is `done` and the job produced one. Always an absolute, publicly reachable URL.
        poster_url:
          type: string
          nullable: true
          description: A still for a finished video, when there is one.
        model:
          type: string
          nullable: true
          description: The model that rendered it.
        credits_used:
          type: number
          nullable: true
        error_message:
          type: string
          nullable: true
          description: Why it failed, when `status` is `error`. Named `error_message` so it can never be mistaken for this API’s error envelope.
        cancelled:
          type: boolean
          description: True when the job was stopped by `POST /v1/jobs/{id}/cancel` before it reached a model. Its `status` is `error` and nothing was charged.
        result:
          type: object
          nullable: true
          description: 'The worker’s full result. PASSTHROUGH TIER: its shape is the job type’s own and improves with it, like a tool’s `data`. Build on the fields above; read this for detail.'
        poll:
          type: string
          description: This job’s own path.
    JobList:
      type: object
      properties:
        object:
          type: string
          enum:
          - list
        data:
          type: array
          items:
            $ref: '#/components/schemas/Job'
        running:
          type: integer
          description: How many of the jobs matching this filter are running right now.
        has_more:
          type: boolean
        next_cursor:
          type: string
          nullable: true
          description: Pass it back as `starting_after`.
    JobCancel:
      type: object
      properties:
        object:
          type: string
          enum:
          - job_cancel
        outcome:
          type: string
          description: '`cancelled`: it had not started, it is stopped and nothing was charged. `requested`: it is starting; it stops before it reaches a model if it can, and is charged nothing if it does. `too_late`: it has already reached the model, so it finishes, is charged as usual and lands in the Library. `finished`: it had already ended. This enum MAY GROW.'
        message:
          type: string
          description: A plain sentence for the person who asked to cancel.
        job:
          $ref: '#/components/schemas/Job'
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - type
          - code
          - message
          properties:
            type:
              type: string
              enum:
              - authentication_error
              - permission_error
              - invalid_request_error
              - connector_error
              - rate_limit_error
              - insufficient_credits
              - api_error
              description: The coarse family — branch on this. New CODES land inside an existing type wherever possible so that branch keeps working; the enum is published for code generation, and a client should still fall through gracefully on a member it does not recognise.
            code:
              type: string
              description: The specific reason. Log this. New values may appear at any time.
            message:
              type: string
            param:
              type: string
              description: The offending field, when there is one.
            connector:
              type: string
              description: Present when the reason is a channel that is not connected. Reconnect in the app — an OAuth consent screen cannot be completed headlessly.
            credits_needed:
              type: number
              description: 'On `insufficient_credits` from a recast or an edit: what the request needs.'
            balance:
              type: number
              description: 'On `insufficient_credits` from a recast or an edit: what this workspace has.'
            unknown_arguments:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                    description: The key that was sent.
                  did_you_mean:
                    type: string
                    nullable: true
                    description: An argument THIS tool declares that the key most likely meant, or null.
              description: 'On `invalid_arguments` from POST /v1/tools/{name}: each key the tool does not take, with the argument it most likely meant. Nothing was run.'
            upgrade_url:
              type: string
              description: 'On `real_face_needs_paid`: where to choose a paid plan.'
            alternative:
              type: string
              description: 'On `real_face_needs_paid`: the field that works on every plan instead (`person.describe`).'
            person_url:
              type: string
              description: 'On a recast with `person.describe` whose recast step was refused after the person was made: the AI person, in your Library. Send it as `person.image_url` to retry without making a new one.'
        request_id:
          type: string
          nullable: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: hmk_...
      description: A Hermoso API key, or an access token from the OAuth authorization-code flow (which is the same thing).
x-refined-from:
- app_hermoso_ai.json
- app_hermoso_ai_rest.json