Hermoso AI Billing API

openapi: 3.2.0
info:
  title: Hermoso Ai Billing API
  version: '2026-08-26'
  description: 'Operations tagged billing 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: Billing
paths:
  /api/billing/machine-payment:
    post:
      operationId: buyCreditsWithMachinePayment
      summary: Buy a credit pack with a machine payment
      description: 'Top up credits with no human and no card entry, for an agent that holds its own payment credential. Name a credit pack and this answers `402` with an MPP challenge; authorise it and retry, and the pack is granted against the same account and the same credit meter a Stripe Checkout purchase would have credited.


        The amount is taken from the pack catalog and never from the request. `GET /api/billing/config` carries a `machinePayments` block with the pack ids, prices, per-credit rates and whether this lane is enabled on this server.


        If you do NOT hold a payment credential — which is still the common case — use `POST /api/billing/checkout-link` instead. It mints a Stripe Checkout URL for a person to pay on.'
      tags:
      - Billing
      x-payment-info:
        offers:
        - amount: null
          currency: usd
          description: A Hermoso credit pack. The charge is the catalog price of the pack named in the request body.
          intent: charge
          method: stripe
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - packId
              properties:
                packId:
                  type: string
                  description: A pack id from GET /api/billing/config, e.g. pack-1k.
      responses:
        '200':
          description: Paid and credited. The response carries a `Payment-Receipt` header.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
        '400':
          description: Unknown pack, or a pack below the payment floor.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing, invalid or revoked key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: Payment required. The `WWW-Authenticate` header carries the MPP challenge; authorise it and retry the same request with the credential.
        '501':
          description: Machine payments are not enabled on this server. The body names the reason and points at the Checkout path.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - bearerAuth: []
    servers:
    - url: https://app.hermoso.ai
components:
  schemas:
    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