Distribea Account API

openapi: 3.2.0
info:
  title: Distribea Account 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: Account
  description: The account behind an API key.
paths:
  /api/v1/account:
    get:
      operationId: getAccount
      tags:
      - Account
      summary: Get the key's account
      description: Plan, credit balance, downloads today and protected channels of the account behind the key.
      security:
      - bearerAuth: []
      - apiKeyHeader: []
      responses:
        '200':
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            Cache-Control:
              $ref: '#/components/headers/CacheControl'
          description: The account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
              example:
                plan: free
                tier: free
                credits: 250
                downloads_today: 0
                protected_channels: 0
                upgrade_url: https://distribea.com/pricing?src=api
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  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
  schemas:
    Account:
      type: object
      required:
      - plan
      - tier
      - credits
      - downloads_today
      - protected_channels
      properties:
        plan:
          type: string
        tier:
          type: string
          enum:
          - free
          - trial
          - paid
        credits:
          type:
          - integer
          - 'null'
          description: Credit balance.
        downloads_today:
          type: integer
        protected_channels:
          type: integer
        upgrade_url:
          type: string
          format: uri
          description: Present when the account has no paid plan.
    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
  responses:
    Unauthorized:
      description: 'The key is missing, invalid or was replaced by a newer one. A price quote (`dry_run: true`) never needs one.'
      headers:
        WWW-Authenticate:
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            missing:
              value:
                error:
                  code: missing_api_key
                  message: This endpoint needs an API key.
                  fix: 'Send your key as "Authorization: Bearer <key>". Get it at https://distribea.com/account/mcp (every new account includes 250 test credits). To see the price without a key, add "dry_run": true.'
                  retryable: false
                  docs_url: https://distribea.com/openapi.json
            invalid:
              value:
                error:
                  code: invalid_api_key
                  message: This API key is invalid or was replaced by a newer one.
                  fix: 'Send your key as "Authorization: Bearer <key>". Get it at https://distribea.com/account/mcp (every new account includes 250 test credits).'
                  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