Distribea Models API

openapi: 3.2.0
info:
  title: Distribea Models API
  version: 1.0.0
  summary: Royalty-free media catalog and AI image, video, music and voice generation for agents.
  description: 'Royalty-free media catalog (music, sound effects, stock footage, images) and AI generation (images, video, music, voice) for AI agents and scripts.


    ## Quick start (steps 1 and 2 need no key)


    1. Search the catalog:

    `GET https://distribea.com/api/v1/catalog/search?q=epic+cinematic+drums&type=music`

    2. Get the exact price of a generation. Nothing is generated or charged:

    `POST https://distribea.com/api/v1/generate/image` with `{"prompt":"a red fox in fresh snow","dry_run":true}`

    3. Get a key at https://distribea.com/account/mcp. Every new account includes 250 test credits, even without a plan.

    4. Send the same body without `dry_run`, with the key, to generate. The response holds the file URL.


    ## Authentication


    Send the key in `Authorization: Bearer ` (or `X-Api-Key: `). Catalog search, item details, the model list and every `dry_run` price quote are public. The account and real generation need a key. The same key works with the Distribea MCP server at https://distribea.com/api/mcp/remote.


    ## Responses


    Success bodies are plain JSON objects, snake_case, with no envelope. One name per idea, in requests and responses alike: `duration_seconds` for any length, `aspect_ratio` for the picture shape (`16:9`), `file_type` for the file format (`png`, `mp4`, `mp3`). Lists are JSON arrays (`genre`, `mood`, `tags`). A setting left to the model''s default is `null`.


    Every generation answer is a `GenerationResult`: read `status` first. `quoted` (`QuotedResult`: dry run, price and settings, `charged: false`), `succeeded` (`SucceededResult`: the file, `charged: true`) or `pending` (`PendingResult`: send again later).


    ## Retries


    For video, music and voice, a job is identified by the request itself: the same key and the same JSON body within 3 minutes is the same job (the body is compared after parsing, so key order and spacing do not matter), so sending it again collects the result and never charges twice. No idempotency header is needed. An image request sent twice makes two images. Only errors with `retryable: true` are worth sending again unchanged.


    Every error, on every endpoint, has one shape:


    `{"error":{"code":"missing_parameter","message":"...","param":"q","fix":"...","retryable":false,"docs_url":"https://distribea.com/openapi.json"}}`


    `code` is stable and machine-readable, `param` names the field to change, `fix` says what to send instead, `valid_values` lists the accepted values when there is a fixed list, `retryable` says whether the same request can simply be sent again, and `retry_after_seconds` (also in the `Retry-After` header) says when.


    ## Credits and limits


    Generation is paid in credits at the same price as the website. `GET /api/v1/models` shows each model''s starting price, and `dry_run: true` returns the exact price of a request. A failed generation is refunded automatically. Each account can run 12 generations per minute and 200 per day (UTC). Public endpoints are cached for 10 minutes.


    ## Long jobs


    Video can take a few minutes. If it is not ready within the request, the API answers `202` with `status: "pending"` and a `Retry-After` header: send the exact same request again to collect the result. Video, music and voice retries within 3 minutes are never charged twice.'
  contact:
    name: Distribea
    email: hello@distribea.com
    url: https://distribea.com
  termsOfService: https://distribea.com/legal/licence-terms
servers:
- url: https://distribea.com
  description: Production
security: []
tags:
- name: Models
  description: Generation models, settings and prices. Public.
paths:
  /api/v1/models:
    get:
      operationId: listModels
      tags:
      - Models
      summary: List generation models
      description: Every model you can pass as `model` to POST /api/v1/generate/{kind}, with its settings and its starting price in credits. No key needed.
      parameters:
      - name: type
        in: query
        required: false
        description: Which kind of model.
        schema:
          type: string
          enum:
          - image
          - video
          - music
          - voice
          default: image
      responses:
        '200':
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            Cache-Control:
              $ref: '#/components/headers/CacheControl'
          description: Models, cheapest first. Image models list `qualities`, `aspect_ratios` and `max_images`; video models list `durations_seconds`, `resolutions` and `aspect_ratios`; music models list `durations_seconds`; voice models list `languages` and `sample_voices`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelsResponse'
              example:
                type: image
                count: 2
                models:
                - id: flux-2.0-flash
                  label: Flux 2 Flash
                  tagline: Fast drafts
                  tier: fast
                  qualities:
                  - 0.5K
                  - 1K
                  - 2K
                  aspect_ratios:
                  - '21:9'
                  - '16:9'
                  - '4:3'
                  - '3:2'
                  - '1:1'
                  - '2:3'
                  - '3:4'
                  - '9:16'
                  - '9:21'
                  max_images: 4
                  price_credits: 1
                - id: nano-banana-pro
                  label: Nano Banana Pro
                  tagline: Most advanced
                  tier: premium
                  qualities:
                  - 2K
                  - 4K
                  aspect_ratios:
                  - '1:1'
                  - '16:9'
                  - '9:16'
                  - '4:3'
                  - '3:4'
                  - '21:9'
                  - '3:2'
                  - '5:4'
                  - '4:5'
                  - '2:3'
                  max_images: 4
                  price_credits: 23
                generate_with: POST /api/v1/generate/image
        '400':
          $ref: '#/components/responses/BadRequest'
components:
  schemas:
    ImageModel:
      type: object
      required:
      - id
      - label
      - tier
      - qualities
      - aspect_ratios
      - max_images
      - price_credits
      properties:
        id:
          type: string
          description: Pass it as `model`.
        label:
          type: string
        tagline:
          type: string
        tier:
          type: string
          enum:
          - fast
          - premium
        price_credits:
          type:
          - integer
          - 'null'
          description: Starting price for one default output. `dry_run` gives the exact price.
        qualities:
          type: array
          items:
            type: string
          description: Pass one as `quality`.
        aspect_ratios:
          type: array
          items:
            type: string
          description: Pass one as `aspect_ratio`.
        max_images:
          type: integer
          description: Upper bound for `count`.
    VideoModel:
      type: object
      required:
      - id
      - label
      - tier
      - durations_seconds
      - resolutions
      - aspect_ratios
      - price_credits
      properties:
        id:
          type: string
          description: Pass it as `model`.
        label:
          type: string
        tagline:
          type: string
        tier:
          type: string
          enum:
          - fast
          - premium
        price_credits:
          type:
          - integer
          - 'null'
          description: Starting price for one default output. `dry_run` gives the exact price.
        durations_seconds:
          type: array
          items:
            type: integer
          description: 'Pass one as `duration_seconds`. Empty: the model picks the length.'
        default_duration_seconds:
          type:
          - integer
          - 'null'
        resolutions:
          type: array
          items:
            type: string
          description: Pass one as `resolution`.
        aspect_ratios:
          type: array
          items:
            type: string
          description: Pass one as `aspect_ratio`.
    ModelsResponse:
      description: 'Read `type` first: it says which model schema the `models` items follow.'
      oneOf:
      - type: object
        required:
        - type
        - count
        - models
        properties:
          type:
            type: string
            const: image
          count:
            type: integer
          models:
            type: array
            items:
              $ref: '#/components/schemas/ImageModel'
          generate_with:
            type: string
            const: POST /api/v1/generate/image
      - type: object
        required:
        - type
        - count
        - models
        properties:
          type:
            type: string
            const: video
          count:
            type: integer
          models:
            type: array
            items:
              $ref: '#/components/schemas/VideoModel'
          generate_with:
            type: string
            const: POST /api/v1/generate/video
      - type: object
        required:
        - type
        - count
        - models
        properties:
          type:
            type: string
            const: music
          count:
            type: integer
          models:
            type: array
            items:
              $ref: '#/components/schemas/MusicModel'
          generate_with:
            type: string
            const: POST /api/v1/generate/music
      - type: object
        required:
        - type
        - count
        - models
        properties:
          type:
            type: string
            const: voice
          count:
            type: integer
          models:
            type: array
            items:
              $ref: '#/components/schemas/VoiceModel'
          generate_with:
            type: string
            const: POST /api/v1/generate/voice
      discriminator:
        propertyName: type
    VoiceModel:
      type: object
      required:
      - id
      - label
      - tier
      - languages
      - sample_voices
      - price_credits
      properties:
        id:
          type: string
          description: Pass it as `model`.
        label:
          type: string
        tagline:
          type: string
        tier:
          type: string
          enum:
          - fast
          - premium
        price_credits:
          type:
          - integer
          - 'null'
          description: Starting price for one default output. `dry_run` gives the exact price.
        languages:
          type: array
          items:
            type: string
          description: Pass one as `language`.
        voice_count:
          type: integer
        sample_voices:
          type: array
          description: Pass an `id` as `voice`.
          items:
            type: object
            required:
            - id
            - name
            properties:
              id:
                type: string
              name:
                type: string
              gender:
                type: string
    MusicModel:
      type: object
      required:
      - id
      - label
      - tier
      - durations_seconds
      - price_credits
      properties:
        id:
          type: string
          description: Pass it as `model`.
        label:
          type: string
        tagline:
          type: string
        tier:
          type: string
          enum:
          - fast
          - premium
        price_credits:
          type:
          - integer
          - 'null'
          description: Starting price for one default output. `dry_run` gives the exact price.
        durations_seconds:
          type: array
          items:
            type: integer
          description: 'Pass one as `duration_seconds`. Empty: the model picks the length.'
        default_duration_seconds:
          type:
          - integer
          - 'null'
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          - retryable
          - docs_url
          properties:
            code:
              type: string
              description: Stable, machine-readable error code.
              enum:
              - missing_parameter
              - invalid_parameter
              - invalid_json
              - not_found
              - method_not_allowed
              - missing_api_key
              - invalid_api_key
              - insufficient_credits
              - test_credits_used_up
              - rate_limited
              - daily_limit_reached
              - request_in_progress
              - generation_failed
              - internal_error
            message:
              type: string
              description: What went wrong, in one sentence.
            param:
              type: string
              description: The parameter or field to change.
            fix:
              type: string
              description: What to send instead.
            valid_values:
              type: array
              items:
                type:
                - string
                - integer
              description: Accepted values, when there is a fixed list.
            credits_required:
              type: integer
              description: Price of the refused request, in credits.
            valid_endpoints:
              type: array
              items:
                type: string
              description: 'Unknown address only: every endpoint of the API.'
            daily_limit:
              type: integer
              description: Generations allowed per day (UTC).
            retryable:
              type: boolean
              description: 'true: send the same request again (after `retry_after_seconds` when present). false: change the request first.'
            retry_after_seconds:
              type: integer
              description: Seconds to wait, same as the Retry-After header.
            docs_url:
              type: string
              format: uri
  headers:
    XRequestId:
      description: Unique id of this response. Quote it when reporting a problem.
      schema:
        type: string
        format: uuid
    CacheControl:
      description: public, s-maxage=600 on catalog and model lists (CDN cached 10 minutes); no-store on the account and on generation.
      schema:
        type: string
  responses:
    BadRequest:
      description: A query parameter is missing or not accepted. `param` names it, `fix` says what to send and `valid_values` lists the accepted values.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            missing_q:
              value:
                error:
                  code: missing_parameter
                  message: The "q" parameter is required.
                  param: q
                  fix: Add what to search for, e.g. /api/v1/catalog/search?q=epic+cinematic+drums&type=music
                  retryable: false
                  docs_url: https://distribea.com/openapi.json
            bad_type:
              value:
                error:
                  code: invalid_parameter
                  message: '"type" must be one of: music, sfx, footage, images.'
                  param: type
                  fix: Use type=music, type=sfx, type=footage or type=images.
                  valid_values:
                  - music
                  - sfx
                  - footage
                  - images
                  retryable: false
                  docs_url: https://distribea.com/openapi.json
            bad_limit:
              value:
                error:
                  code: invalid_parameter
                  message: '"limit" must be an integer from 1 to 20.'
                  param: limit
                  fix: Use limit=10, or remove it.
                  retryable: false
                  docs_url: https://distribea.com/openapi.json
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Your Distribea key, from https://distribea.com/account/mcp.
    apiKeyHeader:
      type: apiKey
      in: header
      name: X-Api-Key
      description: The same key, for clients that cannot set Authorization.
externalDocs:
  description: llms.txt
  url: https://distribea.com/llms.txt