# 인증

모델을 실행하거나 요청을 읽는 모든 호출에는 API 키가 필요합니다. 카탈로그(`GET /models`, `GET /categories`), `POST /quote` 및 OpenAPI
문서는 공개되어 있습니다.

## API 키

[https://doitong.com/developers/dashboard#keys](https://doitong.com/developers/dashboard#keys)에서 키를 만들고 폐기하세요. 키는 `doitong_` 뒤에 64개의 16진수 문자가 이어지는
형식이며, 만들 때 한 번만 표시됩니다. `Authorization` 헤더로 전송하세요.

```bash
curl https://api.doitong.com/v1/account -H "Authorization: Bearer $DOITONG_API_KEY"
```

`X-API-Key: <key>`도 사용할 수 있습니다.

> [!WARNING]
> 키는 서버에 보관하세요. 키를 가진 사람은 해당 키로 허용된 API 크레딧을 사용할 수 있습니다. 키가 유출되면 폐기하고 새 키를 만드세요.

키가 없는 요청은 `missing_api_key` 코드와 함께 `401`을 반환합니다. 알 수 없거나 폐기되었거나 만료된 키도 `401`을 반환합니다.

## 범위

각 키에는 범위가 포함됩니다. 모델 API는 다음 범위를 확인합니다.

| 작업 | 필요한 범위 |
|---|---|
| 모델 실행, 요청 취소, 요청의 파일 삭제, 스토리지 설정 변경 | `models:run` (이전 버전의 `images:create` 또는 `videos:create`가 있는 키도 작동) |
| 업로드 URL 만들기 | `models:run` 또는 `media:upload` |
| 요청 및 계정 읽기 | `models:read` (모델을 실행할 수 있는 키도 읽기 가능) |

새 키에는 기본값으로 `models:read` 및 `models:run`이 부여됩니다. 올바른 범위가 없는 호출은 `insufficient_scope` 코드와 함께 `403`을 반환합니다.

## 크레딧 한도

키에는 계정 소유자가 설정한 자체 API 크레딧 한도를 지정할 수 있습니다(1,000 API 크레딧 = $1). 총 한도, 일일 한도(최근 24시간) 또는 둘 다 설정할 수
있습니다. 실행 비용이 청구되기 전에 이 API를 통해 키가 이미 사용한 금액(환불을 제외한 순액)과 비교해 비용을 확인합니다. 한도를 초과하게 되는 실행은
`402 budget_exceeded`와 함께 거부되며 비용이 청구되지 않습니다.

> [!IMPORTANT]
> 한도 초과로 거부된 요청은 최종 처리됩니다. 소유자가 한도를 높일 때까지 재시도해도 소용없습니다.

 한도가 없는 키는 API 잔액까지 사용할 수 있습니다. 이와 별개로 API 잔액으로 감당할 수 없는 실행은 `402 insufficient_credits`와
`top_up_url`을 반환합니다.

`GET https://api.doitong.com/v1/account`는 API 잔액과 키에 남은 한도를 모두 API 크레딧으로 표시합니다.

```json 200 OK · 계정
{
  "object": "account",
  "credits": 125000,
  "balance": { "credits": 125000, "usd": "125.00" },
  "top_up_url": "https://doitong.com/developers/dashboard#balance",
  "key": {
    "name": "Production server",
    "prefix": "doitong_3fa9c1e...",
    "scopes": ["models:read", "models:run"],
    "budget_remaining": 50000,
    "rate_limit": 3600,
    "rate_limit_remaining": 3571
  },
  "webhook_signing_secret": "whsec_..."
}
```

`budget_remaining`은 키에 자체 한도가 없을 때 `null`입니다.

## 요청 제한

각 키는 별도로 제한이 설정되지 않은 경우 시간당 3600개의 요청을 보낼 수 있습니다. 인증된 모든 응답에는 현재 상태가 포함됩니다.

| 헤더 | 의미 |
|---|---|
| `X-RateLimit-Limit` | 현재 기간에 허용된 요청 수 |
| `X-RateLimit-Remaining` | 현재 기간에 남은 요청 수 |
| `X-RateLimit-Reset` | 기간이 재설정되는 Unix 시간 |

제한을 초과하면 `Retry-After` 헤더와 함께 `429`가 반환됩니다(초). `?wait=`를 사용한 장시간 폴링은 호출당 요청 1개로 계산되므로 빠르게 폴링하는
것보다 기다리는 편이 효율적입니다.

계정당 진행 중인 요청(`queued` 또는 `running`)은 10개로 제한됩니다. 하나를 더 시작하면 `429 too_many_inflight`가 반환됩니다. 하나가 완료된 후
다시 시작하세요.