Saltar al contenido
Referencia de API
Referencia de API

Crear una Clave de API

Cree una Clave de API estándar. Guarde la clave en texto plano que devuelve esta operación, ya que se muestra una sola vez.

Ver Markdown

Cree una Clave de API estándar. Guarde la clave en texto plano que devuelve esta operación, ya que se muestra una sola vez.

Endpoint

POST /api/v1/keys
URL base
https://runapi.ai
Versión de la API
v1
Autenticación
Authorization: Bearer YOUR_MANAGEMENT_API_KEY
Autorización
Requiere una Clave de API de administración con rol de administrador de cuenta. La nueva Clave de API estándar es propiedad del solicitante.
02

Solicitud

Cuerpo JSON

Envíe valores únicamente en la ubicación de solicitud indicada.

Cuerpo JSON7 campos
allowed_modelsarray | null
Opcional

Lista de permitidos opcional de identificadores de modelo.

credit_limit_centsinteger | null
Opcional

Límite de gasto opcional en centavos de USD.

credit_limit_reset_intervalstring | null
Opcional

Cadencia de restablecimiento opcional para el límite de gasto de la clave.

Valores permitidos: daily, weekly, monthly
credit_limit_windowsobject
Opcional

Límites de gasto rotativo con clave 1h, 1d o 7d; cada valor contiene un limit_cents entero positivo.

enabledboolean
Opcional

Si se aceptan las solicitudes que usan esta clave.

Valor predeterminado: true
guardrail_idstring
Opcional

ID de prefijo de barrera de seguridad opcional para adjuntar en la creación.

namestring
Opcional

Nombre descriptivo de la clave de API.

03

Respuesta de éxito

HTTP 201

POST /api/v1/keys

JSON 
{
  "allowed_models": [
    "gpt-5.4"
  ],
  "created_at": "2026-07-27T10:00:00.000Z",
  "credit_limit_cents": 1000,
  "credit_limit_reset_interval": "daily",
  "credit_limit_windows": {
    "1d": {
      "limit_cents": 500
    },
    "1h": {
      "limit_cents": 100
    },
    "7d": {
      "limit_cents": 2000
    }
  },
  "enabled": true,
  "guardrail_id": "guardrail_123",
  "id": "token_123",
  "key": "runapi_plaintext_example",
  "last_used_at": null,
  "masked_token": "runapi_abc...wxyz",
  "name": "Production"
}
04

Respuesta de error (401)

HTTP 401
Esquema de respuesta
JSON 
{
  "properties": {
    "error": {
      "description": "Mensaje de error legible por personas.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Ejemplo de respuesta

JSON 
{
  "error": "Authentication required"
}
05

Respuesta de error (403)

HTTP 403
Esquema de respuesta
JSON 
{
  "properties": {
    "error": {
      "description": "Mensaje de error legible por personas.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Ejemplo de respuesta

JSON 
{
  "error": "Management API key required"
}
06

Respuesta de error (403)

HTTP 403
Esquema de respuesta
JSON 
{
  "properties": {
    "error": {
      "description": "Mensaje de error legible por personas.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Ejemplo de respuesta

JSON 
{
  "error": "Account admin required"
}
07

Respuesta de error (400)

HTTP 400
Esquema de respuesta
JSON 
{
  "oneOf": [
    {
      "properties": {
        "error": {
          "description": "Mensaje de error legible por personas.",
          "type": "string"
        }
      },
      "required": [
        "error"
      ],
      "type": "object",
      "unevaluatedProperties": false
    },
    {
      "properties": {
        "error": {
          "description": "Resumen de validación legible por personas.",
          "type": "string"
        },
        "errors": {
          "additionalProperties": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "description": "Mensajes de validación con clave por campo de solicitud público, con un array de cadenas legibles por personas para cada campo.",
          "type": "object"
        }
      },
      "required": [
        "error",
        "errors"
      ],
      "type": "object",
      "unevaluatedProperties": false
    }
  ]
}

Ejemplo de respuesta

JSON 
{
  "error": "page must be an integer"
}
08

Respuesta de error (422)

HTTP 422
Esquema de respuesta
JSON 
{
  "properties": {
    "error": {
      "description": "Resumen de validación legible por personas.",
      "type": "string"
    },
    "errors": {
      "additionalProperties": {
        "items": {
          "type": "string"
        },
        "type": "array"
      },
      "description": "Mensajes de validación con clave por campo de solicitud público, con un array de cadenas legibles por personas para cada campo.",
      "type": "object"
    }
  },
  "required": [
    "error",
    "errors"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Ejemplo de respuesta

JSON 
{
  "error": "Validation failed",
  "errors": {
    "base": [
      "Validation failed"
    ]
  }
}
09

Ejemplo de cURL

CURL 
curl -X POST https://runapi.ai/api/v1/keys \
  -H 'Authorization: Bearer YOUR_MANAGEMENT_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Production","credit_limit_cents":1000,"credit_limit_reset_interval":"daily","credit_limit_windows":{"1h":{"limit_cents":100},"1d":{"limit_cents":500},"7d":{"limit_cents":2000}},"allowed_models":["gpt-5.4"],"guardrail_id":"guardrail_123"}'