> ## Documentation Index
> Fetch the complete documentation index at: https://docs.toapis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 創建 API 令牌

> 通過 API 創建新的 API 令牌

> [!NOTE]
>
> **中國大陸用戶請注意：** 中國大陸用戶請使用 `https://toapis.cn` 作為接口地址（Base URL）。文檔示例中的 `https://toapis.com` 請替換為 `https://toapis.cn`。

* 通過 API 創建新的 API 令牌
* 支持設置令牌名稱和過期時間
* 支持配置額度限制和模型限制
* 新令牌密鑰僅在創建時返回一次

> [!WARNING]
>
> **安全提示**
>
> 請妥善保管返回的令牌密鑰（`key` 字段），它僅在創建時顯示一次，之後無法再次獲取。

## Authorizations

**Authorization** `string` *required*

所有接口均需要使用 Bearer Token 進行認證

獲取 API Key：

訪問 [API Key 管理頁面](https://toapis.com/console/token) 獲取您的 API Key

使用時在請求頭中添加：

```
Authorization: Bearer YOUR_API_KEY
```

## Body

**name** `string` *required*

令牌名稱，最大 50 個字符

示例：`"我的新令牌"`

**expired\_time** `integer` (default: -1)

令牌過期時間（Unix 時間戳，秒級）

* 設置爲 `-1` 表示永不過期
* 設置爲具體時間戳表示在該時間點後過期

示例：`1738483200`（2025-02-02 00:00:00 UTC）

**remain\_quota** `integer` (default: 0)

令牌剩餘額度（內部單位）

換算關係：`500000` = \$1 USD

示例：`500000`（相當於 \$1）

**remain\_credits** `float` (default: 0)

令牌剩餘積分。如果傳入該字段，會覆蓋 `remain_quota`

換算關係：`200` 積分 = \$1 USD = `500000` 內部額度

示例：`200`（相當於 \$1）

**daily\_credits** `float` (default: 0)

令牌每日限額積分。如果傳入該字段，會自動換算爲 `daily_quota`

示例：`100`（相當於每日 \$0.5 限額）

**monthly\_credits** `float` (default: 0)

令牌每月限額積分。如果傳入該字段，會自動換算爲 `monthly_quota`

示例：`1000`（相當於每月 \$5 限額）

**unlimited\_quota** `boolean` (default: false)

是否爲無限額度

* `true`：無限額度，不受額度限制
* `false`：有限額度，使用 `remain_quota` 的值

示例：`false`

**model\_limits\_enabled** `boolean` (default: false)

是否啓用模型限制

* `true`：啓用模型限制，僅允許使用 `model_limits` 中指定的模型
* `false`：不限制可用模型

示例：`false`

**model\_limits** `string`

允許使用的模型列表（逗號分隔）

僅當 `model_limits_enabled` 爲 `true` 時有效

示例：`"gpt-4o,gpt-4o-mini,claude-3-5-sonnet"`

**group** `string`

令牌分組名稱

用於指定令牌使用的渠道分組

示例：`"default"`

## Response

**success** `boolean`

請求是否成功

**message** `string`

錯誤信息（僅失敗時返回）

**data** `object`

創建的令牌信息（成功時返回）

**data 字段詳情**

**id** `integer`

令牌 ID

**key** `string`

令牌密鑰（僅在創建時返回一次，請妥善保管）

格式爲 48 位隨機字符串，使用時需加上 `sk-` 前綴

**name** `string`

令牌名稱

**status** `integer`

令牌狀態

* `1`：啓用
* `2`：禁用
* `3`：已過期
* `4`：額度耗盡

**user\_id** `integer`

所屬用戶 ID

**created\_time** `integer`

創建時間（Unix 時間戳）

**expired\_time** `integer`

過期時間（Unix 時間戳），-1 表示永不過期

**remain\_quota** `integer`

剩餘額度

**remain\_credits** `float`

剩餘積分，固定按 `1 USD = 200 積分` 換算

**unlimited\_quota** `boolean`

是否爲無限額度

**used\_quota** `integer`

已使用額度

**used\_credits** `float`

已使用積分

**daily\_credits** `float`

每日限額積分

**monthly\_credits** `float`

每月限額積分

**model\_limits\_enabled** `boolean`

是否啓用模型限制

**model\_limits** `string`

模型限制列表

**group** `string`

分組名稱

```bash cURL theme={null}
curl --request POST \
  --url 'https://toapis.com/v1/tokens' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "我的新令牌",
    "expired_time": -1,
    "remain_credits": 200,
    "unlimited_quota": false
  }'
```

```python Python theme={null}
import requests

API_BASE = 'https://toapis.com'
API_KEY = 'sk-xxxxxxxxxxxxxxxxxxxxxx'

headers = {
    'Authorization': f'Bearer {API_KEY}',
    'Content-Type': 'application/json'
}

def create_token():
    payload = {
        'name': '我的新令牌',
        'expired_time': -1,  # 永不過期
        'remain_credits': 200,
        'unlimited_quota': False
    }

    response = requests.post(
        f'{API_BASE}/v1/tokens',
        headers=headers,
        json=payload
    )
    data = response.json()

    if data.get('success'):
        token_data = data['data']
        print(f"令牌創建成功！")
        print(f"令牌名稱: {token_data['name']}")
        print(f"令牌密鑰: sk-{token_data['key']}")
        print("請妥善保管此密鑰，它僅顯示一次！")
    else:
        print(f"創建失敗: {data.get('message')}")

    return data

create_token()
```

```javascript JavaScript theme={null}
const API_BASE = 'https://toapis.com';
const API_KEY = 'sk-xxxxxxxxxxxxxxxxxxxxxx';

async function createToken() {
  const payload = {
    name: '我的新令牌',
    expired_time: -1, // 永不過期
    remain_credits: 200,
    unlimited_quota: false
  };

  const response = await fetch(`${API_BASE}/v1/tokens`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(payload)
  });

  const data = await response.json();

  if (data.success) {
    const tokenData = data.data;
    console.log('令牌創建成功！');
    console.log(`令牌名稱: ${tokenData.name}`);
    console.log(`令牌密鑰: sk-${tokenData.key}`);
    console.log('請妥善保管此密鑰，它僅顯示一次！');
  } else {
    console.error('創建失敗:', data.message);
  }

  return data;
}

createToken();
```

```go Go theme={null}
package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io/ioutil"
    "net/http"
)

type CreateTokenRequest struct {
    Name           string  `json:"name"`
    ExpiredTime    int64   `json:"expired_time"`
    RemainCredits  float64 `json:"remain_credits"`
    UnlimitedQuota bool    `json:"unlimited_quota"`
}

type TokenResponse struct {
    Success bool   `json:"success"`
    Message string `json:"message,omitempty"`
    Data    struct {
        Id             int    `json:"id"`
        Key            string `json:"key"`
        Name           string `json:"name"`
        Status         int    `json:"status"`
        CreatedTime    int64  `json:"created_time"`
        ExpiredTime    int64  `json:"expired_time"`
        RemainQuota    int    `json:"remain_quota"`
        UnlimitedQuota bool   `json:"unlimited_quota"`
    } `json:"data"`
}

func main() {
    url := "https://toapis.com/v1/tokens"
    apiKey := "sk-xxxxxxxxxxxxxxxxxxxxxx"

    payload := CreateTokenRequest{
        Name:           "我的新令牌",
        ExpiredTime:    -1,
        RemainCredits:  200,
        UnlimitedQuota: false,
    }

    jsonData, _ := json.Marshal(payload)

    req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
    req.Header.Set("Authorization", "Bearer "+apiKey)
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, _ := ioutil.ReadAll(resp.Body)

    var result TokenResponse
    json.Unmarshal(body, &result)

    if result.Success {
        fmt.Println("令牌創建成功！")
        fmt.Printf("令牌名稱: %s\n", result.Data.Name)
        fmt.Printf("令牌密鑰: sk-%s\n", result.Data.Key)
        fmt.Println("請妥善保管此密鑰，它僅顯示一次！")
    } else {
        fmt.Printf("創建失敗: %s\n", result.Message)
    }
}
```

```php PHP theme={null}
<?php

$api_key = 'sk-xxxxxxxxxxxxxxxxxxxxxx';

$payload = [
    'name' => '我的新令牌',
    'expired_time' => -1,
    'remain_credits' => 200,
    'unlimited_quota' => false
];

$ch = curl_init('https://toapis.com/v1/tokens');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer $api_key",
    "Content-Type: application/json"
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);

if ($data['success']) {
    echo "令牌創建成功！\n";
    echo "令牌名稱: " . $data['data']['name'] . "\n";
    echo "令牌密鑰: sk-" . $data['data']['key'] . "\n";
    echo "請妥善保管此密鑰，它僅顯示一次！\n";
} else {
    echo "創建失敗: " . $data['message'] . "\n";
}
?>
```

```json 200 - 創建成功 theme={null}
{
  "success": true,
  "message": "",
  "credits_per_usd": 200,
  "data": {
    "id": 123,
    "user_id": 456,
    "key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "status": 1,
    "name": "我的新令牌",
    "created_time": 1738483200,
    "accessed_time": 1738483200,
    "expired_time": -1,
    "remain_quota": 500000,
    "remain_credits": 200,
    "unlimited_quota": false,
    "used_quota": 0,
    "used_credits": 0,
    "daily_credits": 0,
    "monthly_credits": 0,
    "model_limits_enabled": false,
    "model_limits": "",
    "group": "",
    "cross_group_retry": false
  }
}
```

```json 200 - 名稱過長 theme={null}
{
  "success": false,
  "message": "令牌名稱過長"
}
```

```json 401 - 認證失敗 theme={null}
{
  "error": {
    "code": 401,
    "message": "身份驗證失敗，請檢查您的API密鑰",
    "type": "authentication_error"
  }
}
```

```json 429 - 請求過於頻繁 theme={null}
{
  "error": {
    "code": 429,
    "message": "請求過於頻繁，請稍後再試",
    "type": "rate_limit_error"
  }
}
```

## 使用場景

* 自動化創建多個 API 令牌
* 爲不同應用或服務創建獨立的令牌
* 通過腳本批量管理令牌生命週期

> [!NOTE]
>
> **令牌密鑰格式**
>
> 創建成功後返回的 `key` 字段是 48 位隨機字符串。使用時需要加上 `sk-` 前綴，完整格式爲 `sk-xxxxxxxx...`。

> [!TIP]
>
> **最佳實踐**
>
> * 爲不同用途創建不同的令牌，便於追蹤和管理
> * 設置合理的過期時間，定期輪換令牌
> * 如果只需要訪問特定模型，啓用模型限制可以提高安全性

## 常見錯誤

| 錯誤信息 | 原因 | 解決方案 |
| - | - | - |
| 令牌名稱過長 | 名稱超過 50 個字符 | 使用較短的令牌名稱 |
| 生成令牌失敗 | 系統內部錯誤 | 稍後重試或聯繫支持 |
| 身份驗證失敗 | API Key 無效或已過期 | 檢查 API Key 是否正確 |

> [!WARNING]
>
> **安全提示**
>
> * 創建的令牌密鑰僅在響應中返回一次，請立即保存
> * 不要在客戶端代碼中硬編碼 API Key
> * 生產環境請務必使用 HTTPS
> * 建議爲每個應用創建獨立的令牌，便於管理和撤銷


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.