Authentication

The Perso API uses API Key based authentication. Every API request must include a valid API Key.

API Key

You need an API Key to access the Perso API. You can generate one from the API Keys page.

Include your API Key in the XP-API-KEY HTTP header with every request to authenticate.

Header Name	`XP-API-KEY`
Value	Your issued API Key (e.g. `pk_live_xxxxxxxxxxxxxxxxxxxx`)
Required	Required

Examples

cURL

curl -X GET https://api.perso.ai/video-translator/api/v1/languages \
  -H "XP-API-KEY: pk_live_xxxxxxxxxxxxxxxxxxxx"

bash

Node.js

const response = await fetch(
  "https://api.perso.ai/video-translator/api/v1/languages",
  {
    method: "GET",
    headers: {
      "XP-API-KEY": process.env.XP_API_KEY,
    },
  }
);

const data = await response.json();
console.log(data);

javascript

Python

import os
import requests

response = requests.get(
    "https://api.perso.ai/video-translator/api/v1/languages",
    headers={
        "XP-API-KEY": os.environ["XP_API_KEY"],
    },
)

data = response.json()
print(data)

python

Security Best Practices

Your API Key is a secret.

Do not share it with others or expose it in any client-side code (browsers, mobile apps, etc.).

Always use your API Key on the server side only and manage it through environment variables.
Never commit your API Key to a Git repository. Add your .env file to .gitignore.
If your API Key is compromised, immediately revoke it on the API Keys page and generate a new one.
Use separate API Keys for different purposes to make security management easier.

# .env
XP_API_KEY=pk_live_xxxxxxxxxxxxxxxxxxxx

# .gitignore
.env
.env.local

bash

Rate Limiting

API 요청은 API Key 단위로 Rate Limit이 적용됩니다. Fixed Window Counter 방식으로 동작하며, Read와 Write 요청에 대해 별도의 한도가 적용됩니다.

Type	HTTP Methods	Limit
Read	`GET`	6,000 req / min
Write	`POST` `PUT` `DELETE` `PATCH`	1,800 req / min

Rate Limit Response Headers

모든 API 응답에는 현재 Rate Limit 상태를 나타내는 헤더가 포함됩니다.

Header	Description
`X-RateLimit-Limit`	현재 윈도우의 최대 허용 요청 수
`X-RateLimit-Remaining`	현재 윈도우에서 남은 요청 수
`X-RateLimit-Reset`	Rate Limit 윈도우가 초기화되는 시각 (Unix timestamp, 초 단위)

Rate Limit 초과 시

한도를 초과하면 429 응답과 함께 에러 코드 G0005가 반환됩니다. X-RateLimit-Reset 헤더의 시각까지 대기 후 재시도하세요.

// 429 Too Many Requests
{
  "code": "G0005",
  "message": "요청 한도를 초과했습니다. 잠시 후 다시 시도해 주세요.",
  "status": "TOO_MANY_REQUESTS"
}

json

Authentication Error Responses

인증 실패 시 아래의 에러 코드와 함께 JSON 응답이 반환됩니다.

Status Code	Error Code	Description
404	`A0009`	API 키를 찾을 수 없습니다
401	`A0010`	유효하지 않은 API 키입니다
401	`A0011`	만료되거나 비활성화된 API 키입니다
403	API Key does not have access to the requested resource
429	`G0005`	Rate limit exceeded

Error Response Format

{
  "code": "A0011",
  "message": "만료되거나 비활성화된 API 키입니다.",
  "status": "UNAUTHORIZED"
}

json