Vai al contenuto
Riferimento API
Riferimento API

Creare una Chiave API

Crea una Chiave API Standard. Salva la chiave in chiaro restituita da questa operazione perché viene mostrata una sola volta.

Visualizza Markdown

Crea una Chiave API Standard. Salva la chiave in chiaro restituita da questa operazione perché viene mostrata una sola volta.

Endpoint

POST /api/v1/keys
URL di base
https://runapi.ai
Versione API
v1
Autenticazione
Authorization: Bearer YOUR_MANAGEMENT_API_KEY
Autorizzazione
Richiede una Chiave API di gestione con ruolo account-admin. La nuova Chiave API Standard è di proprietà del chiamante.
02

Richiesta

Corpo JSON

Invia i valori solo nella posizione di richiesta elencata.

Corpo JSON8 campi
allowed_modelsarray | null
Opzionale

Allowlist opzionale degli identificatori di modello.

credit_limit_centsinteger | null
Opzionale

Limite di spesa opzionale in centesimi di USD.

credit_limit_reset_intervalstring | null
Opzionale

Cadenza opzionale di ripristino del limite di spesa della chiave.

Valori consentiti: daily, weekly, monthly
credit_limit_windowsobject
Opzionale

Limiti di spesa progressivi con chiave 1h, 1d o 7d; ogni valore contiene un limit_cents intero positivo.

enabledboolean
Opzionale

Se le richieste che utilizzano questa chiave vengono accettate.

Predefinito: true
guardrail_idstring
Opzionale

ID prefisso guardrail opzionale da allegare alla creazione.

namestring
Opzionale

Nome descrittivo per la Chiave API.

tagsarray
Opzionale

Stringhe key:value complete (chiave di 1–32 caratteri, valore di 1–64, senza spazi bianchi; massimo 20 tag). Un usage:developer o usage:service; predefinito usage:service alla creazione. Un solo ambiente facoltativo: env:production, env:staging o env:dev.

03

Risposta di successo

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",
  "tags": [
    "usage:service",
    "env:production",
    "dept:ml"
  ]
}
04

Risposta di errore (401)

HTTP 401
Schema della risposta
JSON 
{
  "properties": {
    "error": {
      "description": "Messaggio di errore leggibile.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Esempio di risposta

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

Risposta di errore (403)

HTTP 403
Schema della risposta
JSON 
{
  "properties": {
    "error": {
      "description": "Messaggio di errore leggibile.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Esempio di risposta

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

Risposta di errore (403)

HTTP 403
Schema della risposta
JSON 
{
  "properties": {
    "error": {
      "description": "Messaggio di errore leggibile.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Esempio di risposta

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

Risposta di errore (400)

HTTP 400
Schema della risposta
JSON 
{
  "oneOf": [
    {
      "properties": {
        "error": {
          "description": "Messaggio di errore leggibile.",
          "type": "string"
        }
      },
      "required": [
        "error"
      ],
      "type": "object",
      "unevaluatedProperties": false
    },
    {
      "properties": {
        "error": {
          "description": "Riepilogo di convalida leggibile dall'utente.",
          "type": "string"
        },
        "errors": {
          "additionalProperties": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "description": "Messaggi di convalida con chiave per campo della richiesta pubblica, con un array di stringhe leggibili dall'utente per ogni campo.",
          "type": "object"
        }
      },
      "required": [
        "error",
        "errors"
      ],
      "type": "object",
      "unevaluatedProperties": false
    }
  ]
}

Esempio di risposta

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

Risposta di errore (422)

HTTP 422
Schema della risposta
JSON 
{
  "properties": {
    "error": {
      "description": "Riepilogo di convalida leggibile dall'utente.",
      "type": "string"
    },
    "errors": {
      "additionalProperties": {
        "items": {
          "type": "string"
        },
        "type": "array"
      },
      "description": "Messaggi di convalida con chiave per campo della richiesta pubblica, con un array di stringhe leggibili dall'utente per ogni campo.",
      "type": "object"
    }
  },
  "required": [
    "error",
    "errors"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Esempio di risposta

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

Esempio 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","tags":["env:production","dept:ml"],"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"}'