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

# 실행과 비용 관리하기

> 비동기 실행, 멱등 재시도, 비용 예약, 정산, 결과물 조회 방법을 설명합니다.

## 개요

이 페이지에서는 견적, 비용 예약, 비동기 실행, 정산, 결과물 조회를 설명합니다. 긴 작업은 HTTP 연결을 유지하지 않고 실행 ID로 추적합니다.

## 실행과 결제 흐름 이해하기

`POST /tools/quote`는 입력에 대한 요금 버전, 최소 비용, 최대 예약 금액을 반환합니다. 견적은 무료이며 외부 서비스를 호출하거나 잔액을 예약하지 않습니다.

견적과 같은 `tool`, `arguments`에 다음 두 항목을 추가합니다.

* `priceVersion` — 견적에서 반환한 요금 버전
* `maximumChargeMicros` — 견적에서 반환한 최대 예약 금액

요금이 바뀌었거나 한도가 부족하면 처리 시작 전에 거절됩니다. 새 견적을 받고 다시 검토하세요.

## 비용 예약과 정산

유료 작업 접수 시 선불 USD 잔액에서 최대 금액을 임시 확보합니다. 완료 후 실제 비용을 정산하고 사용하지 않은 예약분을 돌려줍니다.

| 필드 | 의미 |
| - | - |
| `reservedMicros` | 접수 시 확보한 최대 금액으로, 완료 후에도 처음 값을 유지합니다. |
| `chargedMicros` | 완료 또는 실패 후 확정 비용입니다. 처리 중 `0`은 미정산을 뜻합니다. |
| `currency` | `usd`. 1 USD는 1,000,000 micros입니다. |

실패나 취소라도 외부 처리 비용이 이미 발생했다면 실제 비용이 정산됩니다. 최대 예약 금액을 넘어 자동 청구되지는 않습니다.

## 실행 상태 조회하기

접수 시 HTTP 202와 실행 ID를 받습니다. `Retry-After: 5`에 따라 최소 5초 간격으로 같은 ID를 조회합니다.

| 상태 | 의미 | 다음 조치 |
| - | - | - |
| `queued` | 실행 대기 | 최소 5초 후 다시 조회 |
| `running` | 처리 중 | 같은 실행 ID 조회 |
| `waiting` | 외부 처리 대기 | 같은 실행 ID 조회 |
| `succeeded` | 성공 및 정산 완료 | `output`, `chargedMicros` 조회 |
| `failed` | 실패 및 발생 비용 정산 | `errorCode`와 확정 비용 조회 |
| `cancelled` | 취소 완료 | 확정 비용 조회 |
| `needs_review` | 결과나 비용 검토 필요 | 재실행하지 말고 ID와 함께 지원팀에 문의 |

## 멱등 키로 중복 방지하기

멱등 키는 실수로 같은 요청을 여러 번 보내도 별도 실행이 생성되지 않게 하는 식별자입니다. 유료 `POST /tools/{tool}`에는 `Idempotency-Key`가 필수입니다.

키는 8\~128자로 영문, 숫자, `.`, `_`, `:`, `-`를 사용합니다. 논리 요청마다 하나씩 만들어 실행 ID와 함께 저장하세요.

* 같은 API 키, 본문, 멱등 키를 보내면 같은 실행이 반환됩니다.
* 같은 멱등 키로 본문이나 API 키를 바꾸면 HTTP 409가 반환됩니다.
* 연결이 끊기면 본문과 멱등 키를 바꾸지 않고 다시 보냅니다.
* `needs_review` 작업을 새 키로 보내면 별도 유료 실행이 생성됩니다.

> [!WARNING]
>
> 응답을 받지 못했다고 실행이 접수되지 않은 것은 아닙니다. 결과를 모르면 새 멱등 키를 만들지 마세요.

## 실행 취소하기

`POST /tools/executions/{id}/cancel`은 시작 전 작업의 중단을 요청합니다. 실행을 만든 키나 프로젝트 `ADMIN`이 요청할 수 있습니다.

외부 처리가 시작됐다면 취소만으로 작업이나 비용을 되돌리지 못할 수 있습니다. `cancelRequested`, 최종 `status`, `chargedMicros`를 확인하세요.

## 결과물 가져오기

생성된 이미지, 오디오, 영상은 `output.artifacts`에 파일 ID, 형식, 크기, 해시, 만료일로 표시됩니다. 결과에 파일 본문이나 영구 URL은 포함되지 않습니다.

`GET /tools/executions/{id}/artifacts/{artifactId}/download`는 최대 5분 유효한 URL을 반환합니다. 저장 파일은 30일 후 만료됩니다.

임시 URL도 비공개 데이터 접근 정보입니다. 로그나 공개 페이지에 기록하지 말고 Developer Platform 키를 URL에 붙이지 마세요.

## 관련 페이지

첫 실행과 엔드포인트는 다음 페이지에서 설명합니다.

* [시작하기](https://docs.noimosai.com/ko/developers/api/getting-started.md)
* [API 참조](https://docs.noimosai.com/ko/developers/api/reference.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.