개요
이 페이지에서는 견적, 비용 예약, 비동기 실행, 정산, 결과물 조회를 설명합니다. 긴 작업은 HTTP 연결을 유지하지 않고 실행 ID로 추적합니다.실행과 결제 흐름 이해하기
POST /tools/quote는 입력에 대한 요금 버전, 최소 비용, 최대 예약 금액을 반환합니다. 견적은 무료이며 외부 서비스를 호출하거나 잔액을 예약하지 않습니다.
견적과 같은 tool, arguments에 다음 두 항목을 추가합니다.
priceVersion— 견적에서 반환한 요금 버전maximumChargeMicros— 견적에서 반환한 최대 예약 금액
비용 예약과 정산
유료 작업 접수 시 선불 USD 잔액에서 최대 금액을 임시 확보합니다. 완료 후 실제 비용을 정산하고 사용하지 않은 예약분을 돌려줍니다.
실패나 취소라도 외부 처리 비용이 이미 발생했다면 실제 비용이 정산됩니다. 최대 예약 금액을 넘어 자동 청구되지는 않습니다.
실행 상태 조회하기
접수 시 HTTP 202와 실행 ID를 받습니다.Retry-After: 5에 따라 최소 5초 간격으로 같은 ID를 조회합니다.
멱등 키로 중복 방지하기
멱등 키는 실수로 같은 요청을 여러 번 보내도 별도 실행이 생성되지 않게 하는 식별자입니다. 유료POST /tools/{tool}에는 Idempotency-Key가 필수입니다.
키는 8~128자로 영문, 숫자, ., _, :, -를 사용합니다. 논리 요청마다 하나씩 만들어 실행 ID와 함께 저장하세요.
- 같은 API 키, 본문, 멱등 키를 보내면 같은 실행이 반환됩니다.
- 같은 멱등 키로 본문이나 API 키를 바꾸면 HTTP 409가 반환됩니다.
- 연결이 끊기면 본문과 멱등 키를 바꾸지 않고 다시 보냅니다.
needs_review작업을 새 키로 보내면 별도 유료 실행이 생성됩니다.
실행 취소하기
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에 붙이지 마세요.