SFXMint Generation API

openapi: 3.2.0
info:
  title: SFXMint Sound Effects Generation API
  version: 1.0.0
  summary: Free CC0 sound effects for apps and games, no API key.
  description: 'JSON API for 9,700+ AI-generated CC0 sound effects: search by description, look up a sound by the event it is for, fetch a set for a whole app or game, and download WAV or MP3 files. The library needs no key or signup. Generating a sound the library lacks needs an API key from https://sfxmint.com/dashboard/keys. The same tools are an MCP server at https://sfxmint.com/mcp.'
  termsOfService: https://sfxmint.com/terms
  contact:
    name: SFXMint
    url: https://sfxmint.com/contact
    email: hello@sfxmint.com
  license:
    name: CC0-1.0 (the sounds)
    identifier: CC0-1.0
  x-logo:
    url: https://sfxmint.com/icon.png
servers:
- url: https://sfxmint.com
tags:
- name: generation
  description: Generating with an API key.
paths:
  /api/v1/orders:
    post:
      tags:
      - generation
      operationId: generateSound
      summary: Generate a sound the library lacks
      description: 'Uses the account''s free tries, then its credits (one per generation, given back when nothing is made) or its plan. Each take is a CC0 WAV. An agent never pays: on 402 pass the message and buy_url to the user.'
      security:
      - apiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderRequest'
      responses:
        '201':
          description: The generation has started; poll GET /api/v1/orders/{id}.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderCreated'
        '400':
          description: Invalid request (invalid_body, invalid_duration, invalid_variations, …).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: No key (sign_in_required, with website_url) or a wrong key (invalid_api_key).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: No credits or plan (payment_required, with message, buy_url, website_url and plans).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Today's plan generations are used (plan_day_used) or too many active orders.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/orders/{id}:
    get:
      tags:
      - generation
      operationId: getGeneration
      summary: Get a generation and its takes
      security:
      - apiKey: []
      parameters:
      - name: id
        in: path
        required: true
        description: Order id.
        schema:
          type: string
        example: ord_0123456789abcdef01234567
      responses:
        '200':
          description: The order and its files.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderDetail'
        '401':
          description: No key or a wrong key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No such order for this key (not_found).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    OrderCreated:
      type: object
      properties:
        order_id:
          type: string
        free:
          type: boolean
        held:
          type: boolean
    OrderDetail:
      type: object
      properties:
        order:
          type: object
        files:
          type: array
          items:
            type: object
        license:
          type:
          - string
          - 'null'
        license_id:
          type:
          - string
          - 'null'
    OrderRequest:
      type: object
      required:
      - prompt
      properties:
        prompt:
          type: string
          description: 'The sound in plain words, in any language: what it is for and what should be heard. Leave lengths to duration_s.'
        variations:
          type: integer
          enum:
          - 1
          - 2
          - 4
          default: 4
          description: Takes to make.
        duration_s:
          description: Longest a take may be, in seconds; left out or "auto", SFXMint chooses.
          oneOf:
          - type: number
            enum:
            - 0.2
            - 0.5
            - 1
            - 1.5
            - 2
            - 2.5
            - 3
            - 4
            - 5
            - 6
            - 7
            - 8
            - 9
            - 10
          - const: auto
        enhance:
          type: boolean
          default: false
          description: Write the prompt into a full sound description first.
        refine:
          type: object
          description: 'Change a take instead of making a new one (free): {from: <order_id>, take, change}.'
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string
        message:
          type: string
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: An SFXMint API key (sfx_live_…). X-API-Key is accepted too.
externalDocs:
  description: API documentation
  url: https://sfxmint.com/api/docs