> ## Documentation Index > Fetch the complete documentation index at: https://docs.zelto.ai/llms.txt > Use this file to discover all available pages before exploring further. # Añadir una clave de proveedor de IA > Valida la clave con una llamada sin costo al proveedor y la guarda cifrada. El proveedor factura directamente el uso de la clave, que no cuenta para la asignación de evaluaciones del plan y lleva la tarifa de plataforma de Zelto por clave propia. Se rechaza para organizaciones en modo PHI. Queda en el registro de auditoría como `ai_key.created`. ## OpenAPI ````yaml /es/docs-openapi.json post /v1/ai-keys openapi: 3.1.0 info: title: API REST de Zelto version: v1 description: >- Acceso programático a tu organización de Zelto. Cada endpoint está limitado a la organización a la que pertenece la clave de API. Crea una clave en Configuración → Integraciones → Integración por API. servers: - url: https://api.zelto.ai description: Producción security: - bearerAuth: [] tags: - name: Monitors description: Exportaciones filtradas y asíncronas de resultados guardados de monitores. - name: Agentes description: >- Agentes de IA de voz y texto normalizados mediante el flujo de ingestión de Zelto. - name: Conversaciones description: >- Conversaciones de voz y texto (llamadas, chats y mensajes de voz), junto con sus transcripciones y grabaciones. - name: Métricas del cliente description: >- Evaluaciones proporcionadas por el cliente y asociadas a una conversación. Requiere que las métricas estén habilitadas. - name: Revisiones description: Estado de revisión humana de las conversaciones. - name: Colas de revisión description: Agrupa y dirige conversaciones para revisarlas por lotes. - name: Empresas description: Clientes o marcas para los que trabajan tus agentes, y sus logos. - name: Hallazgos description: >- Problemas estructurados descubiertos durante el análisis, con conversaciones y comentarios opcionales. - name: Experimentos description: >- Medición prospectiva de dos versiones de prompt enrutadas externamente mediante resultados de monitores independientes. - name: Organizaciones description: >- Aprovisionamiento de organizaciones sin interfaz. Requiere una clave de API de administrador o servicio. - name: Proveedores de IA description: >- Las claves propias de tu organización para proveedores de IA (trae tu propia clave). Los monitores pueden ejecutarse con ellas en lugar de los modelos integrados de Zelto. Solo propietarios o administradores; el secreto es de solo escritura. paths: /v1/ai-keys: post: tags: - Proveedores de IA summary: Añadir una clave de proveedor de IA description: >- Valida la clave con una llamada sin costo al proveedor y la guarda cifrada. El proveedor factura directamente el uso de la clave, que no cuenta para la asignación de evaluaciones del plan y lleva la tarifa de plataforma de Zelto por clave propia. Se rechaza para organizaciones en modo PHI. Queda en el registro de auditoría como `ai_key.created`. operationId: createAiKey requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AiKeyCreate' responses: '201': description: Clave validada y guardada. content: application/json: schema: $ref: '#/components/schemas/AiKey' '400': description: >- `invalid_input` (ver `details`) o `invalid_key` (el proveedor rechazó la clave). Un cuerpo JSON mal formado es `invalid_json`. content: application/json: schema: $ref: '#/components/schemas/AiKeyError' '401': $ref: '#/components/responses/Unauthorized' '403': description: >- No eres propietario ni administrador de la organización (`{ "error": "Owner or admin access required" }`), o `phi_mode_blocked`: la organización está en modo PHI. content: application/json: schema: $ref: '#/components/schemas/AiKeyError' '409': description: >- `duplicate_label`: ya existe una clave con ese nombre para el proveedor. content: application/json: schema: $ref: '#/components/schemas/AiKeyError' '502': description: >- `provider_unreachable`: no se pudo contactar al proveedor para comprobar la clave. No se guardó nada; vuelve a intentarlo. content: application/json: schema: $ref: '#/components/schemas/AiKeyError' components: schemas: AiKeyCreate: type: object additionalProperties: false required: - provider - apiKey properties: provider: type: string enum: - openai - anthropic - openrouter - vercel_gateway - typesafe - deepgram description: >- `openai`, `anthropic`, `openrouter`, `vercel_gateway` y `typesafe` son claves de LLM / evaluación con las que puede ejecutarse un monitor. `deepgram` es una clave de voz a texto, guardada para los próximos Benchmarks. label: type: string minLength: 1 maxLength: 100 description: Por defecto, el nombre del proveedor. apiKey: type: string minLength: 8 maxLength: 512 writeOnly: true description: >- La clave de API del proveedor, sin espacios. Se valida con una llamada sin costo al proveedor antes de guardarla cifrada; nunca se devuelve. AiKey: type: object description: >- Una clave de proveedor de IA de la organización. Nunca incluye el secreto: solo sus últimos cuatro caracteres. required: - id - provider - label - lastFour - createdAt - createdBy - rotatedAt - rotatedBy - lastTestedAt - lastTestStatus - lastTestError - monitorCount properties: id: type: string format: uuid provider: type: string enum: - openai - anthropic - openrouter - vercel_gateway - typesafe - deepgram description: >- `openai`, `anthropic`, `openrouter`, `vercel_gateway` y `typesafe` son claves de LLM / evaluación con las que puede ejecutarse un monitor. `deepgram` es una clave de voz a texto, guardada para los próximos Benchmarks. label: type: string maxLength: 100 description: Distingue varias claves del mismo proveedor. Única por proveedor. lastFour: type: string description: Los últimos cuatro caracteres de la clave guardada. createdAt: type: string format: date-time createdBy: type: - object - 'null' required: - id - name - email properties: id: type: string name: type: - string - 'null' email: type: - string - 'null' format: email description: Quién añadió la clave. rotatedAt: type: - string - 'null' format: date-time description: Cuándo se reemplazó el secreto por última vez. rotatedBy: type: - object - 'null' required: - id - name - email properties: id: type: string name: type: - string - 'null' email: type: - string - 'null' format: email description: Quién reemplazó el secreto por última vez. lastTestedAt: type: - string - 'null' format: date-time lastTestStatus: type: - string - 'null' enum: - ok - failed - null description: >- Resultado de la última comprobación con el proveedor (al guardar, rotar o probar). lastTestError: type: - string - 'null' description: >- Por qué falló la última comprobación, por ejemplo `invalid_key` o `provider_unreachable:`. monitorCount: type: integer minimum: 0 description: Monitores que se ejecutan actualmente con esta clave. AiKeyError: type: object required: - error - message properties: error: type: string enum: - invalid_input - phi_mode_blocked - invalid_key - provider_unreachable - duplicate_label - not_found - in_use description: >- Código estable: `invalid_input` (400), `invalid_key` (400, el proveedor rechazó la clave), `phi_mode_blocked` (403), `not_found` (404), `duplicate_label` (409), `in_use` (409), `provider_unreachable` (502). message: type: string details: type: array items: type: object additionalProperties: true description: 'Con `invalid_input`: los problemas de validación.' monitors: type: array description: 'Con `in_use`: los monitores que aún se ejecutan con la clave.' items: type: object required: - id - name properties: id: type: string format: uuid name: type: string Error: type: object required: - error properties: error: type: string description: >- Nombre corto del error: `Unauthorized`, `Validation failed`, `Not found` o un código estable en snake_case que puedes comparar en tu código, como `unknown_query_parameter`, `invalid_parameter`, `payload_too_large` o `not_found`. message: type: string description: Una frase en lenguaje claro que explica qué falla y cómo corregirlo. code: type: string description: >- Causa estable y legible por máquina; compara con este valor y no con `error` ni `message`. En un 401: `missing_credentials`, `malformed_credentials`, `ingest_key_not_allowed` (se usó una clave de ingesta de observabilidad, solo de escritura, en un endpoint que requiere una clave API), `key_expired` o `invalid_credentials`. En otros casos, por ejemplo: `not_found`, `invalid_parameter`, `unknown_query_parameter`, `missing_parameter`, `validation_failed`, `invalid_json`, `payload_too_large`, `conversation_not_found`, `plan_required`. hint: type: string description: >- El siguiente paso a probar: dónde encontrar el id correcto, qué parámetros acepta el endpoint, cómo mejorar el plan o cómo autenticarte. parameter: type: string description: 'Con `invalid_parameter`: el parámetro de consulta rechazado.' unknown: type: array items: type: string description: >- Con `unknown_query_parameter`: los parámetros enviados que este endpoint no acepta. valid: type: array items: type: string description: >- Con `unknown_query_parameter`: los parámetros que acepta este endpoint. details: type: object additionalProperties: true responses: Unauthorized: description: >- Clave API faltante o no válida. El cuerpo indica la causa en `code` (por ejemplo `ingest_key_not_allowed` cuando se usa aquí una clave de ingesta, solo de escritura), con un `message` y un `hint`. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearerAuth: type: http scheme: bearer description: >- Envía `Authorization: Bearer YOUR_API_KEY`. La clave corresponde a una sola organización. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.