Aller au contenu
Référence API
Référence API

Créer une clé API

Créez une clé API standard. Sauvegardez la clé en clair retournée par cette opération car elle n'est affichée qu'une seule fois.

Voir en Markdown

Créez une clé API standard. Sauvegardez la clé en clair retournée par cette opération car elle n’est affichée qu’une seule fois.

Point de terminaison

POST /api/v1/keys
URL de base
https://runapi.ai
Version de l'API
v1
Authentification
Authorization: Bearer YOUR_MANAGEMENT_API_KEY
Autorisation
Nécessite une clé API de gestion d'administrateur de compte. La nouvelle clé API standard appartient à l'appelant.
02

Requête

Corps JSON

Envoyez les valeurs uniquement à l'emplacement de requête indiqué.

Corps JSON7 champs
allowed_modelsarray | null
Optionnel

Liste blanche optionnelle d'identifiants de modèles.

credit_limit_centsinteger | null
Optionnel

Plafond de dépenses optionnel en centimes USD.

credit_limit_reset_intervalstring | null
Optionnel

Cadence optionnelle de réinitialisation du plafond de dépenses de la clé.

Valeurs autorisées: daily, weekly, monthly
credit_limit_windowsobject
Optionnel

Plafonds de dépenses glissants indexés par 1h, 1d ou 7d ; chaque valeur contient un entier positif limit_cents.

enabledboolean
Optionnel

Indique si les requêtes utilisant cette clé sont acceptées.

Par défaut: true
guardrail_idstring
Optionnel

ID de préfixe optionnel du garde-fou à associer à la création.

namestring
Optionnel

Nom convivial de la clé API.

03

Réponse de succès

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

Réponse d'erreur (401)

HTTP 401
Schéma de réponse
JSON 
{
  "properties": {
    "error": {
      "description": "Message d'erreur lisible par l'humain.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Exemple de réponse

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

Réponse d'erreur (403)

HTTP 403
Schéma de réponse
JSON 
{
  "properties": {
    "error": {
      "description": "Message d'erreur lisible par l'humain.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Exemple de réponse

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

Réponse d'erreur (403)

HTTP 403
Schéma de réponse
JSON 
{
  "properties": {
    "error": {
      "description": "Message d'erreur lisible par l'humain.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Exemple de réponse

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

Réponse d'erreur (400)

HTTP 400
Schéma de réponse
JSON 
{
  "oneOf": [
    {
      "properties": {
        "error": {
          "description": "Message d'erreur lisible par l'humain.",
          "type": "string"
        }
      },
      "required": [
        "error"
      ],
      "type": "object",
      "unevaluatedProperties": false
    },
    {
      "properties": {
        "error": {
          "description": "Résumé de validation lisible par l'humain.",
          "type": "string"
        },
        "errors": {
          "additionalProperties": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "description": "Messages de validation indexés par champ de requête public, avec un tableau de chaînes lisibles par l'humain pour chaque champ.",
          "type": "object"
        }
      },
      "required": [
        "error",
        "errors"
      ],
      "type": "object",
      "unevaluatedProperties": false
    }
  ]
}

Exemple de réponse

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

Réponse d'erreur (422)

HTTP 422
Schéma de réponse
JSON 
{
  "properties": {
    "error": {
      "description": "Résumé de validation lisible par l'humain.",
      "type": "string"
    },
    "errors": {
      "additionalProperties": {
        "items": {
          "type": "string"
        },
        "type": "array"
      },
      "description": "Messages de validation indexés par champ de requête public, avec un tableau de chaînes lisibles par l'humain pour chaque champ.",
      "type": "object"
    }
  },
  "required": [
    "error",
    "errors"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Exemple de réponse

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

Exemple 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"}'