# 빠른 시작

몇 분 안에 첫 번째 생성을 실행해 보세요. 1,496개의 모든 모델은 동일한 유형의 요청을 받고 이미지, 동영상, 오디오에 대해
동일한 요청 객체를 반환합니다. 여기서 한 번만 익히면 됩니다.

> [!NOTE]
> 기본 URL은 `https://api.doitong.ru/v1`입니다. 모든 호출은 `Authorization: Bearer <your key>`를 전송하며, 동일한 키를 HTTP
> API와 MCP 서버 모두에 사용할 수 있습니다.

## 1. API 키 받기

[https://doitong.com/developers/dashboard#keys](https://doitong.com/developers/dashboard#keys)에서 키를 만들고 환경 변수에 저장하세요. 키는 한 번만
표시됩니다. 각 키에는 자체 한도를 설정할 수 있으므로 전체 계정에 위험을 주지 않고 에이전트에 키를 전달할 수 있습니다. `GET /account`는 API 잔액을
반환합니다.

```bash
export DOITONG_API_KEY="doitong_..."

curl "https://api.doitong.ru/v1/account" \
  -H "Authorization: Bearer $DOITONG_API_KEY"
```
```javascript
const res = await fetch("https://api.doitong.ru/v1/account", {
  headers: { Authorization: `Bearer ${process.env.DOITONG_API_KEY}` },
});

console.log(await res.json());
```
```python
import os
import requests

r = requests.get(
    "https://api.doitong.ru/v1/account",
    headers={"Authorization": f"Bearer {os.environ['DOITONG_API_KEY']}"},
)
print(r.json())
```

실행 비용은 계정의 **API 잔액**에서 API 크레딧으로 차감됩니다. 1,000 API 크레딧 = $1이며, 모든 모델의 비용은 제작자가 정한 가격과
정확히 같습니다. [https://doitong.ru/developers/dashboard#balance](https://doitong.ru/developers/dashboard#balance)에서 충전하세요.

## 2. 견적을 받은 후 실행하기

`POST /quote/{model_id}`는 입력 JSON을 받아 정확한 가격을 반환합니다. 키가 필요하지 않으며 비용도 없습니다. 동일한 입력을 실행하면 정확히 그
금액이 청구됩니다. 견적이 곧 청구 금액입니다. (사용량에 따라 청구되는 모델은 예외입니다. 이 경우 견적은 실행에 청구될 수 있는 최대 금액이며,
사용하지 않은 부분은 실행 후 환불됩니다.)

```bash
curl -X POST "https://api.doitong.ru/v1/quote/kling-video/v3/pro/image-to-video" \
  -H "Content-Type: application/json" \
  -d '{"image": "https://example.com/fox.jpg", "duration": 5, "generate_audio": true}'
```
```javascript
const res = await fetch("https://api.doitong.ru/v1/quote/kling-video/v3/pro/image-to-video", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ image: "https://example.com/fox.jpg", duration: 5, generate_audio: true }),
});

const quote = await res.json();
console.log(quote.credits, quote.usd); // 840 "0.84"
```
```python
import requests

r = requests.post(
    "https://api.doitong.ru/v1/quote/kling-video/v3/pro/image-to-video",
    json={"image": "https://example.com/fox.jpg", "duration": 5, "generate_audio": True},
)
print(r.json()["credits"], r.json()["usd"])  # 840 0.84
```

```json 200 OK · 견적
{
  "object": "quote",
  "model": "kling-video/v3/pro/image-to-video",
  "credits": 840,
  "usd": "0.84",
  "unit": "second",
  "quantity": 5,
  "unit_credits": 168,
  "mode": "exact",
  "breakdown": "5 s × 168 API credits"
}
```

그런 다음 동일한 본문을 `POST /run/{model_id}`로 전송하세요. `?wait=20`을 추가하면 연결을 최대 20초 동안 유지할 수 있습니다. 빠른
모델은 한 번의 왕복으로 완료된 결과를 반환합니다. `Idempotency-Key` 헤더를 전송하면 재시도해도 실행 또는 비용 청구가 두 번 발생하지 않습니다.

```bash
curl -X POST "https://api.doitong.ru/v1/run/flux/schnell?wait=20" \
  -H "Authorization: Bearer $DOITONG_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: lighthouse-001" \
  -d '{"prompt": "A lighthouse on a rocky coast at dusk, warm light in the window"}'
```
```javascript
const res = await fetch("https://api.doitong.ru/v1/run/flux/schnell?wait=20", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.DOITONG_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "lighthouse-001",
  },
  body: JSON.stringify({ prompt: "A lighthouse on a rocky coast at dusk, warm light in the window" }),
});

const request = await res.json();
console.log(request.status, request.outputs[0]?.url);
```
```python
import os
import requests

r = requests.post(
    "https://api.doitong.ru/v1/run/flux/schnell",
    params={"wait": 20},
    headers={
        "Authorization": f"Bearer {os.environ['DOITONG_API_KEY']}",
        "Idempotency-Key": "lighthouse-001",
    },
    json={"prompt": "A lighthouse on a rocky coast at dusk, warm light in the window"},
)
request = r.json()
print(request["status"], request["outputs"][0]["url"] if request["outputs"] else None)
```

응답은 요청 객체입니다.

```json 200 OK · 요청
{
  "id": "req_8k2m4q7x1z9c3v5b6n0p2r4t",
  "object": "request",
  "model": "flux/schnell",
  "status": "succeeded",
  "cost": { "credits": 3, "usd": "0.003", "charged": 3, "refunded": 0 },
  "outputs": [
    { "type": "image", "url": "https://content.doitong.com/dev-api/2026/10/20/req_8k2m4q7x1z9c3v5b6n0p2r4t/0-output.jpeg",
      "content_type": "image/jpeg", "width": 1024, "height": 768, "stored": true }
  ],
  "error": null
}
```

## 3. 상태 확인하기

대기 시간이 끝났을 때 모델이 아직 작업 중이면 요청의 `id`와 현재 `status`가 포함된 `202 Accepted`를 받습니다. 모든 요청은 동일한 수명 주기를
거칩니다.

요청 수명 주기: `queued` → `running` → `succeeded` | `failed` | `canceled` (최종 상태이며, 실패 및 취소된 요청은 환불됩니다).

id를 사용해 요청을 다시 읽으세요. 여기서도 `?wait=20`이 작동하므로 간단한 루프면 충분합니다.

```bash
curl "https://api.doitong.ru/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t?wait=20" \
  -H "Authorization: Bearer $DOITONG_API_KEY"
```
```javascript
const headers = { Authorization: `Bearer ${process.env.DOITONG_API_KEY}` };
let request = await (await fetch("https://api.doitong.ru/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t?wait=20", { headers })).json();

while (request.status === "queued" || request.status === "running") {
  const res = await fetch(`https://api.doitong.ru/v1/requests/${request.id}?wait=20`, { headers });
  request = await res.json();
}

console.log(request.status, request.outputs[0]?.url);
```
```python
import os
import requests

headers = {"Authorization": f"Bearer {os.environ['DOITONG_API_KEY']}"}
request = {"id": "req_8k2m4q7x1z9c3v5b6n0p2r4t", "status": "queued"}

while request["status"] in ("queued", "running"):
    request = requests.get(
        f"https://api.doitong.ru/v1/requests/{request['id']}",
        params={"wait": 20},
        headers=headers,
    ).json()

print(request["status"], request["outputs"][0]["url"] if request["outputs"] else None)
```

`status`가 `succeeded`이면 `outputs[].url`에 스토리지에 있는 파일의 링크가 들어 있습니다. 요청이 `failed` 또는 `canceled`이면 API 크레딧이
자동으로 환불되고 `error`에 이유가 표시됩니다. 아직 `queued` 또는 `running` 상태인 항목은 취소할 수 있습니다.

```bash
curl -X POST "https://api.doitong.ru/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t/cancel" \
  -H "Authorization: Bearer $DOITONG_API_KEY"
```

긴 동영상 작업에서는 폴링을 건너뛰고 대신 `webhook_url`을 전달할 수 있습니다([웹훅](https://doitong.com/developers/docs/webhooks) 참조).

## 4. 파일

공개 URL을 입력으로 전달하거나 `POST /files`에 업로드 URL을 요청한 다음, 해당 URL로 파일을 `PUT`하고 반환된 `file_url`을 사용하세요([파일](https://doitong.com/developers/docs/files) 참조). 성공한 요청은 결과를 `outputs[]`에 나열하며, 유형, 콘텐츠 유형, 알려진 경우 크기와 재생 시간을 포함합니다.

```bash
curl -X POST "https://api.doitong.ru/v1/files" \
  -H "Authorization: Bearer $DOITONG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename": "fox.jpg", "content_type": "image/jpeg", "size": 482113}'
```

> [!TIP]
> **파일을 영구 보관하거나 7일 동안 무료로 보관할 수 있습니다.** 원하는 방식을 선택하세요. 출력 파일은 요청이 성공하기 전에
> 스토리지에 복사됩니다. 기본값으로 파일은 삭제할 때까지 유지됩니다(월별 GB당 100 API 크레딧). 대시보드에서
> "파일 영구 보관"을 끄거나 `?storage=temporary`를 전달하면 7일 동안 무료로 보관됩니다([파일](https://doitong.com/developers/docs/files#storage) 참조).

## 오류

모든 모델은 동일한 방식으로 실패합니다. `type`, 정확한 `code`, 문제가 발생한 `param`, 모든 문제를 담은 `details`가 하나의 봉투에 포함되므로
에이전트가 문장을 읽지 않고도 요청을 수정할 수 있습니다. 유효하지 않은 요청에는 비용이 청구되지 않습니다.

```json 422 처리할 수 없는 엔터티
{
  "error": {
    "type": "invalid_request",
    "code": "invalid_input",
    "message": "duration must be one of 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15.",
    "param": "duration",
    "details": [ { "param": "duration", "message": "duration must be one of 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15." } ],
    "request_id": null,
    "doc_url": "https://doitong.com/developers/docs/errors#invalid_input"
  }
}
```

모든 유형과 코드는 [오류](https://doitong.com/developers/docs/errors)에 나열되어 있습니다.

## 가격

가격은 USD와 API 크레딧으로 표시되며 실행 전에 모든 모델 페이지에서 확인할 수 있습니다. 각 요청에는 `cost`와 함께 `credits`, `usd`,
`charged`, `refunded`가 포함됩니다. 실행이 수락되면 비용이 청구되고, `failed` 및 `canceled` 요청은 자동으로 환불됩니다. 일부 모델은 입력에 따라
정확히 가격이 책정되고, 일부는 전송한 파일의 길이나 크기에 따라 책정되며, 다른 모델은 *실행당 예상 가격*을 청구합니다. 어느 경우든 견적이
실제 지불 금액입니다. 일부 모델(언어 및 비전 모델, 음성, 처리 시간 도구)은 *사용량에 따라 청구*됩니다. 견적은 실행에 청구될 수 있는 최대 금액이며,
실행에서 사용하지 않은 부분은 자동으로 환불됩니다. [가격](https://doitong.com/developers/docs/pricing)을 참조하세요.

## MCP 및 AI 에이전트

동일한 Bearer 키를 사용해 모든 MCP 클라이언트를 `https://api.doitong.ru/v1/mcp`에 연결하세요. 에이전트는 카탈로그를 검색하고, 모델의 견적을 확인하고 실행하며,
모든 문서 페이지를 Markdown으로 읽을 수 있습니다.

```bash Claude Code
claude mcp add --transport http doitong-models https://api.doitong.ru/v1/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"
```

## 다음 단계

- [모든 모델](https://doitong.com/developers/models)을 살펴보세요. 각 페이지에는 코드를 대신 작성해 주는 요청 빌더가 있습니다.
- 요청 수명 주기를 알아보세요: [요청](https://doitong.com/developers/docs/requests).
- 모든 모델에서 동일한 매개변수 이름을 사용하세요: [매개변수](https://doitong.com/developers/docs/parameters).
- AI 코딩 에이전트와 작업 중인가요? [https://doitong.com/developers/llms.txt](https://doitong.com/developers/llms.txt)를 제공하거나 [MCP 서버](https://doitong.com/developers/docs/mcp)에 연결하세요.