Claix Audio a JSON API

openapi: 3.2.0
info:
  title: Claix Audio a JSON API
  description: 'Claix es una API de conversión de datos tabulares, JSON y documentos (PDF, Word, texto plano, imágenes, audio) pensada para integraciones server-to-server (backends, scripts, herramientas de automatización como n8n, Zapier o Make). Source Tracing opcional: citas por campo `{ value, source }` o `requires_human_revision` si falta evidencia. Expone seis endpoints principales de conversión:

    - **Excel/CSV → JSON**: recibe un archivo Excel o CSV y lo transforma en

    JSON según la estructura definida en un "schema" previamente creado. - **JSON → Excel**: recibe uno o varios documentos JSON y devuelve un

    archivo Excel (.xlsx) binario, según la estructura definida en un

    "schema" previamente creado. - **PDF → JSON**: recibe un archivo PDF (de texto o escaneado) y devuelve

    un objeto JSON con los datos extraídos del documento, según la

    estructura definida en un "schema" previamente creado. - **Documento → JSON**: recibe un archivo de documento (.docx, .txt, .md

    o .rtf) y devuelve un objeto JSON con los datos extraídos, según la

    estructura definida en un "schema" previamente creado. - **Imagen → JSON**: recibe una imagen (.jpeg, .jpg, .png, .webp, .heic

    o .heif) y devuelve un objeto JSON con los datos extraídos del

    contenido visible, según la estructura definida en un "schema"

    previamente creado. - **Txt / HTML / XML → JSON**: recibe el campo `content` (texto plano,

    HTML o XML ya procesado, sin archivo) y devuelve un objeto JSON con los

    datos extraídos, según un schema de tipo txt-json. Máximo 300.000

    caracteres. Tarifa fija €0,10 por llamada exitosa tras el free tier. - **Excel/CSV → Markdown**, **PDF → Markdown**, **Documento → Markdown**,

    **Imagen → Markdown**, **Txt/HTML/XML → Markdown** y **Audio → Markdown**:

    misma autenticación, mismos formatos y mismos límites que el endpoint JSON

    equivalente. No piden schema_id. save=true inserta el Markdown en la base

    conectada y la respuesta incluye row_id. PDF con texto, Excel, documentos y

    texto se convierten en local. PDF escaneado, imagen y audio llaman al

    mismo modelo con BYOK. - **Audio → JSON**: recibe un archivo de audio (.mp3, .wav, .m4a o .ogg)

    y un schema_id, y devuelve un único objeto JSON con los datos extraídos

    de lo hablado. Tamaño máximo 12 MB y duración máxima 10 minutos. Si el

    audio no es inteligible, responde 422. Además, expone endpoints para consultar y gestionar los schemas de la cuenta:

    - **Listar schemas**: dado un API key, devuelve todos los schemas de esa

    cuenta con su información completa (id, nombre, tipo y definición). - **Obtener schema**: dado un `schema_id` en la URL, devuelve ese schema

    con su definición completa. - **Crear schema**: crea un schema con `name`, `type`, `schema_definition`

    y, opcionalmente, Modo Agente (`is_agent_mode`, `agent_definition`,

    `resumen_agent`) y verificación de fuente. - **Actualizar schema**: sustituye la configuración completa de un schema

    existente (`schema_id` en la URL; mismo body que crear). - **Borrar schema**: elimina un schema de la cuenta por `schema_id`. **Ventana de Contexto** — Tras una extracción con `window_context` activo, el `document_id` devuelto permite consultar el contenido bruto, preguntar al markdown persistido o eliminar el documento:

    - **GET https://claix.dev/get-document/{document_id}**: devuelve el

    contenido bruto y metadatos del documento (`content`, `file_name`,

    `schema_id`, `processed_at`). Llamada gratuita. - **POST https://claix.dev/document-context/{document_id}**: body

    `{ "questions": [{ "question": "...", "format": "string"|"int"|"boolean"|"timestamp"|"array" }] }`

    (máximo 5 preguntas, 400 caracteres cada una). Respuesta

    `{ user_ask, ia_response, log_id }`. Cada respuesta respeta el `format`

    pedido (o `null`). Si la verificación de fuente está activada en consulta

    a documentos, cada ítem de `ia_response` es `{ value, source }`. - **DELETE https://claix.dev/delete-document/{document_id}**: elimina el

    documento persistido por `document_id`. Sin body ni query params. Respuesta `{ document_id }`.'
  version: 1.12.0
servers:
- url: https://claix.dev/api
  description: Producción (dominio público Claix)
security:
- ApiKeyAuth: []
- BearerAuth: []
tags:
- name: Audio a JSON
  description: Extracción de datos estructurados a partir de audio hablado (.mp3, .wav, .m4a, .ogg)
paths:
  /audio-json:
    post:
      operationId: audioToJson
      tags:
      - Audio a JSON
      summary: Extrae datos estructurados de un audio según un schema
      description: 'Recibe un archivo de audio (.mp3, .wav, .m4a o .ogg) y un schema_id, y devuelve un único objeto JSON con los datos extraídos de lo hablado, con las claves exactamente iguales a las propiedades definidas en el schema. El análisis lo realiza un modelo multimodal de IA. Antes de extraer datos, el modelo evalúa si el habla es inteligible; si no lo es, responde con 422. El audio se trata como una única fuente de datos: la respuesta siempre contiene exactamente un registro en "data". Tamaño máximo 12 MB. Duración máxima 10 minutos. La respuesta incluye `log_id`. Si la verificación de fuente está activada en el schema, cada propiedad extraída es `{ value, source }`. Con window_context, la transcripción se persiste en markdown.'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/AudioJsonRequest'
      responses:
        '200':
          description: Audio analizado y datos extraídos correctamente
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AudioJsonSuccessResponse'
        '400':
          description: 'Petición inválida (archivo faltante, formato no soportado, audio vacío, corrupto, firma binaria incoherente, o schema_id incorrecto/faltante/de tipo equivocado)

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: No autorizado (API key inválida, inactiva o cuenta suspendida)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: El schema_id no existe o no pertenece a la cuenta
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '405':
          description: Método HTTP no permitido (solo se admite POST)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: El audio supera el tamaño máximo (12 MB) o la duración máxima (10 minutos)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: 'Audio ininteligible (silencio, ruido, música sin habla) o sin datos extraíbles según el schema indicado

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Error interno del servidor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: Fallo del servicio de IA encargado de analizar el audio
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    LogId:
      type:
      - string
      - 'null'
      format: uuid
      description: 'Identificador del registro en usage_logs de esta llamada. Presente en respuestas de éxito de extracción, modo agente, document-context y space-context, y en la mayoría de errores una vez autenticada la petición. Puede omitirse si el insert del log falla.

        '
      example: 7c2e1a90-4b3d-4f8a-9e21-6d5c8b0a1f34
    AudioJsonSuccessResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        schema_utilizado:
          type: string
          description: Nombre del schema aplicado.
          example: Notas de llamada
        total_registros:
          type: integer
          description: 'Siempre 1 en este endpoint: el audio completo se trata como una única fuente de datos.

            '
          example: 1
        data:
          type: array
          description: 'Contiene exactamente un objeto con los datos extraídos del audio, según las propiedades definidas en el schema. Los datos no encontrados se devuelven como null. Si la verificación de fuente está activada en el schema, cada propiedad es { value, source } (fragmento hablado o momento).

            '
          items:
            type: object
            additionalProperties: true
          example:
          - cliente: Suministros Industriales del Ebro S.L.
            numero_factura: F-2026-00456
            fecha_emision: '2026-03-14'
            importe_total: 1284.5
        log_id:
          $ref: '#/components/schemas/LogId'
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Descripción legible del problema.
          example: No se envió el campo schema_id.
        detalle:
          type: string
          description: Información técnica adicional (solo presente en algunos casos).
          example: Missing required field 'schema_id' in multipart/form-data body.
        log_id:
          $ref: '#/components/schemas/LogId'
    AudioJsonRequest:
      type: object
      required:
      - file
      - schema_id
      properties:
        file:
          type: string
          format: binary
          description: 'Audio a analizar. Formatos admitidos: .mp3, .wav, .m4a y .ogg. Tamaño máximo admitido: 12 MB. Duración máxima: 10 minutos.

            '
        schema_id:
          type: string
          format: uuid
          description: 'Identificador del schema (previamente creado) de tipo "Audio a JSON".

            '
          example: 3c7a9f21-4b8e-4d1a-9c6f-2e0d8a5b7c4f
        space_id:
          type: string
          format: uuid
          description: 'Opcional. Espacio de conocimiento al que se asocia el documento guardado. Debe pertenecer al mismo usuario dueño de la API key. Solo tiene efecto cuando el schema tiene la ventana de contexto activada, que es cuando el documento se guarda.

            '
          example: 5b9e2c14-7d3a-4f8b-9e1c-6a0d4b8f2e7c
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: 'API key secreta de servidor. Tiene prioridad sobre Authorization si se envían ambos headers.

        '
    BearerAuth:
      type: http
      scheme: bearer
      description: Forma alternativa de enviar la API key como Bearer token.
x-provenance:
  method: harvested
  publisher: Claix
  source: https://www.claix.dev/openapi.yaml
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)