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

# 빠른 시작

> 첫 번째 생성 작업을 제출하고, 완료될 때까지 상태를 폴링한 후 결과를 다운로드합니다.

WideRouter 작업은 이미지를 생성하든 동영상을 생성하든, 어떤 모델을 선택하든 관계없이 항상 동일한 세 단계를 따릅니다.

## API 키 가져오기

콘솔에서 키를 만든 다음, 아래 예시에서 읽을 수 있도록 내보냅니다.
커밋하는 파일에 키를 하드코딩하지 마십시오.

```bash theme={null}
export WIDEROUTER_API_KEY="sk-your-api-key"
```

## 작업 생성

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.widerouter.com/v1/task/submit \
    -H "Authorization: Bearer $WIDEROUTER_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gemini-3.1-flash-image",
      "input": { "prompt": "a lighthouse at dusk" }
    }'
  ```

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

  resp = requests.post(
      "https://api.widerouter.com/v1/task/submit",
      headers={"Authorization": f"Bearer {os.environ['WIDEROUTER_API_KEY']}"},
      json={"model": "gemini-3.1-flash-image",
            "input": {"prompt": "a lighthouse at dusk"}},
      timeout=30,
  )
  task_id = resp.json()["id"]
  ```
</CodeGroup>

호출은 약 1초 후 task id와 함께 반환되며, 생성 작업은
백그라운드에서 계속 진행됩니다.

```json theme={null}
{ "id": "task_koYlX7Gm6lEn5jfPS54TcDZcN7OvZA8M", "status": "queued", "created_at": 1788104112 }
```

## 완료될 때까지 폴링

`status`이 터미널 상태인 `completed` 또는 `failed`에 도달할 때까지 작업을 읽습니다.

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.widerouter.com/v1/task/task_koYlX7Gm6lEn5jfPS54TcDZcN7OvZA8M \
    -H "Authorization: Bearer $WIDEROUTER_API_KEY"
  ```

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

  while True:
      task = requests.get(
          f"https://api.widerouter.com/v1/task/{task_id}",
          headers={"Authorization": f"Bearer {os.environ['WIDEROUTER_API_KEY']}"},
          timeout=30,
      ).json()
      if task["status"] in ("completed", "failed"):
          break
      time.sleep(3)

  print(task["outputs"])
  ```
</CodeGroup>

1K 이미지의 종단 간 처리에는 15\~40초가 소요될 것으로 예상되며, 동영상은 클립 길이에 따라 더 오래 걸립니다. 완료된 작업에는 아티팩트 URL의 `outputs` 배열이 포함됩니다. 이미지는 JPEG이고 동영상은 MP4입니다.

<Warning>
  긴밀한 루프가 아니라 백오프를 사용해 폴링하십시오. 처음에는 2\~3초 정도로 시작하십시오. 100밀리초마다 폴링하는 클라이언트는 더 빠르게 완료되지도 않으면서 요청 제한에 걸립니다.
</Warning>

## 결과 다운로드

출력 URL은 인증이 필요 없으며 작업이 **완료된** 후 24시간이 지나면 만료됩니다.
보관하려는 항목은 자체 저장소에 복사하십시오.

```bash theme={null}
URL=$(curl -s "https://api.widerouter.com/v1/task/$TASK_ID" \
  -H "Authorization: Bearer $WIDEROUTER_API_KEY" | jq -r '.outputs[0]')

curl -L -O "$URL"
```

<Tip>
  `-O`은 서버가 제공하는 파일명을 유지하므로 추측 없이 올바른 확장자를 얻을 수 있습니다.
  `.jpg`을 하드코딩하지 마십시오 — 동일한 엔드포인트는 동영상 모델에 대해 MP4를 반환합니다.
</Tip>

## 다음 단계

<CardGroup cols={2}>
  <Card title="비동기 작업 API" icon="clock" href="/ko/api/async-tasks">
    전체 요청 및 응답 스키마, 콜백 및 오류 표입니다.
  </Card>

  <Card title="Nano Banana 시리즈" icon="layers" href="/ko/models/nano-banana/overview">
    각 모델이 허용하는 매개변수와 기본값입니다.
  </Card>

  <Card title="Grok Imagine 이미지" icon="image" href="/ko/models/grok-imagine/image/overview">
    세 가지 xAI 이미지 변형과 해상도 및 품질 표입니다.
  </Card>

  <Card title="Grok Imagine 동영상" icon="film" href="/ko/models/grok-imagine/video/overview">
    텍스트를 동영상으로 변환, 이미지를 동영상으로 변환, 클립 편집 및 확장입니다.
  </Card>
</CardGroup>