Creative Fabrica Voices API

openapi: 3.2.0
info:
  title: Creativefabrica Voices API
  version: 1.0.0
  contact:
    name: Idea AI
    url: https://www.idea.ai/
  description: 'Operations tagged voices across 2 of this provider''s published API definitions: idea-ai-genai-openapi.json, creativefabrica-idea-ai-genai-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.idea.ai/genai
  description: Production
- url: https://api.cf.land/genai
  description: Staging
security:
- bearerAuth: []
tags:
- name: Voices
  description: Selectable voices for speech models
paths:
  /v1/voices/{voiceCatalog}:
    get:
      operationId: listVoices
      tags:
      - Voices
      summary: List the voices in a speaker catalog
      description: 'Lists the selectable voices in one catalog. Pass a voice''s `id` as the

        `speaker` option when creating a generation.


        Find the catalog for a model in `voiceCatalog` on `GET /v1/models` or

        `GET /v1/models/{model}`. A voice id is only valid on the catalog it came

        from, so a model backed by a different catalog will reject it.


        Catalogs are small and fully enumerable — there is no server-side filter.

        Narrow the results client-side using the `labels` and `languages` on each

        voice, and raise `limit` to fetch a whole catalog in fewer round-trips.'
      parameters:
      - name: voiceCatalog
        in: path
        required: true
        description: 'Catalog to list, taken from a model''s `voiceCatalog`

          (`GET /v1/models/{model}`).

          '
        schema:
          type: string
        example: byteplus_seed_tts_2
      - $ref: '#/components/parameters/Cursor'
      - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: One page of voices.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoiceList'
              example:
                data:
                - id: it_male_enzo_uranus_bigtts
                  name: Enzo
                  description: A composed young man with a calm, unflappable approach.
                  voiceCatalog: byteplus_seed_tts_2
                  provider: byteplus
                  previewUrl: https://cdn.example.com/voices/enzo.wav
                  avatarUrl: https://cdn.example.com/voices/enzo.png
                  labels:
                    gender: male
                    age: middle_aged
                  languages:
                  - language: it
                hasMore: false
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
    servers:
    - url: https://api.idea.ai/genai
      description: Production
    - url: https://api.cf.land/genai
      description: Staging
components:
  responses:
    InternalError:
      description: Unexpected server error.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    BadRequest:
      description: The request is invalid (malformed body, unknown option, constraint violation).
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Unauthorized:
      description: Missing or invalid bearer token.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
  schemas:
    Voice:
      type: object
      description: One selectable speaker voice.
      required:
      - id
      - name
      - voiceCatalog
      - provider
      properties:
        id:
          type: string
          description: 'Pass as the `speaker` option. Unique within its catalog only — ids are

            not interchangeable between catalogs.

            '
          example: it_male_enzo_uranus_bigtts
        name:
          type: string
          example: Enzo
        description:
          type: string
        voiceCatalog:
          type: string
          description: Catalog this voice belongs to.
          example: byteplus_seed_tts_2
        provider:
          type: string
          description: Vendor backing the catalog.
          example: byteplus
        previewUrl:
          type: string
          format: uri
          description: Audition sample. Absent when the vendor publishes none.
        avatarUrl:
          type: string
          format: uri
          description: Thumbnail image. Absent when the vendor publishes none.
        labels:
          $ref: '#/components/schemas/VoiceLabels'
        languages:
          type: array
          description: 'Every language the voice speaks. May be empty when the vendor

            publishes no language metadata.

            '
          items:
            $ref: '#/components/schemas/VoiceLanguage'
    VoiceList:
      type: object
      description: A cursor-paginated page of voices.
      required:
      - data
      - hasMore
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Voice'
        hasMore:
          type: boolean
        nextCursor:
          type:
          - string
          - 'null'
          description: Pass as `cursor` to fetch the next page. Null when `hasMore` is false.
    VoiceLanguage:
      type: object
      required:
      - language
      properties:
        language:
          type: string
          description: ISO 639-1 code, optionally region-qualified.
          example: pt-br
        previewUrl:
          type: string
          format: uri
          description: Per-language audition sample, when published.
        sampleText:
          type: string
          description: The text spoken in the per-language sample.
    VoiceLabels:
      type: object
      description: 'Filterable descriptive labels. Values are normalized to canonical

        lowercase ids (e.g. `female`, `middle_aged`) so they are stable across

        vendors, which differ in case and spelling. Fields are absent when the

        vendor publishes no value.

        '
      properties:
        gender:
          type: string
          example: male
        age:
          type: string
          example: middle_aged
        accent:
          type: string
        useCase:
          type: string
    FieldViolation:
      type: object
      required:
      - field
      - reason
      - description
      properties:
        field:
          type: string
          description: 'Dotted path of the offending input, e.g. `options.duration_seconds`

            or `inputMedia.sourceVideo[0].durationSeconds`.

            '
          example: options.duration_seconds
        reason:
          type: string
          description: 'Stable machine-readable code. Current values: `missing_option`,

            `invalid_option`, `unknown_option`, `missing_media`,

            `missing_media_metadata`, `invalid_media_metadata`. New codes may be

            added — treat unknown values as a generic validation failure.

            '
          example: missing_option
        description:
          type: string
          description: Human-readable explanation.
          example: option "duration_seconds" is required to price model "seedance_v2"
    Problem:
      type: object
      description: 'RFC 9457 problem details. Returned with Content-Type: application/problem+json.'
      required:
      - title
      - status
      - code
      properties:
        type:
          type: string
          format: uri
          description: URI identifying the problem type.
          default: about:blank
        title:
          type: string
          description: Short human-readable summary.
          example: Invalid request
        status:
          type: integer
          description: HTTP status code.
          example: 400
        detail:
          type: string
          description: Human-readable explanation specific to this occurrence.
          example: option "duration_seconds" value is above maximum
        code:
          type: string
          description: 'Stable machine-readable error code. Branch on this, not on prose.

            Examples: `validation_error`, `model_not_found`, `unsupported_modality`,

            `alias_mismatch`, `prompt_blocked`, `insufficient_balance`,

            `missing_subscription`, `missing_unlimited_subscription`,

            `payment_required`, `team_coins_unavailable`, `not_found`,

            `unauthenticated`, `forbidden`, `rate_limited`, `internal_error`.

            '
          example: validation_error
        violations:
          type: array
          description: 'Per-input violations, set on `validation_error` problems that can

            attribute failures to specific request inputs (e.g.

            `POST /v1/models/{model}/cost`). Lists every violation at once so

            all inputs can be fixed in one round-trip.

            '
          items:
            $ref: '#/components/schemas/FieldViolation'
  parameters:
    Limit:
      name: limit
      in: query
      required: false
      description: Page size.
      schema:
        type: integer
        default: 20
        minimum: 1
        maximum: 100
    Cursor:
      name: cursor
      in: query
      required: false
      description: Opaque pagination cursor from a previous page's `nextCursor`.
      schema:
        type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: idea.ai GenAI API key (`sk-...`).
x-refined-from:
- idea-ai-genai-openapi.json
- creativefabrica-idea-ai-genai-openapi.yml
x-tagGroups:
- name: Endpoints
  tags:
  - generations
  - presets
  - models
  - voices
- name: Guides
  tags:
  - guide_uploads
- name: Object reference
  tags:
  - schema_generation
  - schema_input_media
  - schema_output
  - schema_image_output
  - schema_video_output
  - schema_audio_output
  - schema_text_output
  - schema_preset
  - schema_voice
  - schema_upload_target