> ## 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.

# 플레이그라운드

> 이 페이지에서 실제 생성 작업을 제출한 다음, 반환된 작업 ID로 상태를 조회합니다.

API 키와 프롬프트를 입력한 다음 전송합니다. 그러면 실제 API가 호출됩니다. 코드에서 호출하는 것과 동일한
엔드포인트입니다.

<Warning>
  **이 페이지에서 전송하는 요청은 실제 요청이며 사용자의 키에 과금됩니다.**
  1K 이미지 1개는 모델에 따라 약 \$0.02–0.09입니다. 이곳의 어떤 것도
  샌드박스나 모의 환경이 아닙니다.
</Warning>

## 매개변수

<ParamField body="model" type="string" required>
  실행할 모델입니다. `gemini-3-pro-image` 또는 `gemini-3.1-flash-image`을 허용하며,
  정확히 일치해야 합니다. 별칭과 `-preview` 접미사는 허용되지 않습니다.
</ParamField>

<ParamField body="input" type="object" required>
  생성 매개변수입니다. 아래에 나열되지 않은 키는
  `invalid_params`와 함께 거부됩니다.

  <Expandable title="입력">
    <ParamField body="input.prompt" type="string" required>
      생성할 내용입니다. 1\~32000바이트입니다.
    </ParamField>

    <ParamField body="input.n" type="integer" default="1">
      생성할 이미지 수로, 1\~4개입니다. 각 이미지는
      `outputs`의 별도 항목입니다.
    </ParamField>

    <ParamField body="input.aspect_ratio" type="string">
      `1:1` `2:3` `3:2` `3:4` `4:3` `4:5` `5:4` `9:16` `16:9` `21:9` 중 하나입니다.
      생략하면 정사각형 이미지가 생성되거나, 참조 이미지를 전달할 경우
      원본 이미지의 비율을 따릅니다.
    </ParamField>

    <ParamField body="input.image_size" type="string" default="1K">
      `1K`, `2K` 또는 `4K`입니다. 대소문자를 구분합니다. 전체 프레임의 크기를 조정하므로,
      `21:9` 이미지가 `4K`인 경우 결과는 6336 × 2688이 됩니다.
    </ParamField>

    <ParamField body="input.images" type="string[]">
      편집하거나 합성할 참조 이미지로, 최대 14개입니다. 각 항목은
      `https` URL 또는 base64 데이터 URI입니다.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="callback_url" type="string">
  완료된 작업을 POST할 `https` URL이므로 폴링을 생략할 수 있습니다. 반드시
  `https`이어야 하며, 그 외의 값은 제출 시 거부됩니다.
</ParamField>

## 반환되는 내용

제출 요청은 1초도 걸리지 않아 즉시 반환됩니다. 이미지가 이 응답에 포함되는
것은 아닙니다 — 생성은 백그라운드에서 진행됩니다.

| 필드           | 유형  | 설명                              |
| ------------ | --- | ------------------------------- |
| `id`         | 문자열 | 작업 ID입니다. 다른 모든 작업에 이 값이 필요합니다. |
| `status`     | 문자열 | 새 작업에서의 `queued`입니다.            |
| `created_at` | 정수  | Unix 초 단위이며, UTC 기준입니다.         |

<ResponseExample>
  ```json 응답 theme={null}
  {
    "id": "task_dksUgWLYX4jIVueCACD8KwJzjR5JhRsI",
    "status": "queued",
    "created_at": 1788104112
  }
  ```
</ResponseExample>

## 그런 다음 이미지 상태를 폴링합니다

이 플레이그라운드는 생성 호출만 다룹니다. 위 응답에서 `id`를 가져온 다음
`status`가 `completed` 또는 `failed`에 도달할 때까지 작업을 조회합니다. 1K 이미지의 경우
15\~40초가 걸릴 것으로 예상됩니다.

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

완료된 작업에는 이미지 URL의 `outputs` 배열이 포함됩니다.

```json theme={null}
{
  "id": "task_dksUgWLYX4jIVueCACD8KwJzjR5JhRsI",
  "status": "completed",
  "outputs": ["https://…/task_dksUgWLYX4jIVueCACD8KwJzjR5JhRsI_0.jpg"],
  "counts": { "requested": 1, "succeeded": 1, "failed": 0 }
}
```

<Warning>
  출력 URL은 인증되지 않으며 작업 생성 후 24시간이 지나면 만료됩니다.
  이미지를 다운로드할 때는 `User-Agent` 헤더를 전송해야 합니다. 전송 CDN은 헤더가 없는
  요청에 대해 본문이 없는 `403`을 반환합니다.
</Warning>

## 다음 단계

<CardGroup cols={2}>
  <Card title="개요" icon="layers" href="/ko/models/nano-banana/overview">
    해당 시리즈의 모든 매개변수, 해상도 등급 및 측정된 지연 시간입니다.
  </Card>

  <Card title="비동기 작업 API" icon="clock" href="/ko/api/async-tasks">
    폴링 루프, 콜백 및 전체 오류 표입니다.
  </Card>
</CardGroup>