작업 및 결과

멱등 키로 비동기 작업을 안전하게 제출하고, 미디어를 업로드하고, 상태를 확인해 결과를 내려받으세요.

작업 제출(비동기)

동기 호출은 없습니다. POST /api/v1/jobs는 입력을 검증하고 크레딧에서 가격을 예약한 뒤 즉시 응답합니다. 새 작업은 202, 멱등 재시도가 이전 요청과 일치하면 200입니다.

헤더	값	참고
`Authorization`	`Bearer <API key>`	또는 x-api-key로 키를 보냅니다.
`Content-Type`	`application/json`
`Idempotency-Key`	`<unique string ≤128>`	필수입니다. 동일한 요청을 재시도할 때만 재사용하세요.

필드	유형	필수	참고
`model`	`string`	필수	카탈로그의 모델 slug입니다.
`input`	`object`	필수	모델 입력 스키마의 필드입니다.
`expectedPriceMicros`	`integer`	선택	사용자에게 보여 준 가격입니다. 일치하지 않으면 청구 전에 409 PRICE_CHANGED를 반환합니다.

안전하게 재시도

네트워크 장애 후 재시도할 때는 같은 Idempotency-Key와 본문을 유지하세요. 입력을 바꿀 때는 새 키를 사용하세요. 입력을 바꾼 채 같은 키를 재사용하면 409 IDEMPOTENCY_CONFLICT가 반환됩니다.

미디어 업로드

이미지 및 동영상 필드는 공개 HTTPS URL 또는 media:<uuid> 참조를 받습니다. 로컬 파일은 먼저 업로드하세요:

POST /api/v1/media

curl -X POST https://api.hermes-ai.net/api/v1/media \
  -H "Authorization: Bearer $HERMES_API_KEY" \
  -H "Content-Type: image/png" \
  --data-binary @input.png
# → { "reference": "media:<uuid>", ... }  Use the reference in an image or video field.

작업 결과 가져오기

폴링 GET /api/v1/jobs/{id} 몇 초마다 폴링하고 최종 상태에서 멈추세요. reconciliation_required 작업은 자동으로 다시 제출하지 마세요.

상태	최종 상태	의미
`queued`	아니요	접수되어 워커를 기다리는 중입니다.
`submitting`	아니요	모델 제공업체로 전송 중입니다.
`running`	아니요	모델이 생성 중입니다.
`succeeded`	예	완료되었습니다. 결과는 assets에 있습니다.
`failed`	예	결과 없이 종료되었습니다. 예약이 해제됩니다.
`reconciliation_required`	예	The result is being verified. Keep the task ID and do not resubmit automatically.

필드	유형	참고
`id`	`string`	Hermes AI 작업 ID입니다. 폴링에 사용하세요.
`model`	`string`	모델 slug입니다.
`status`	`string`	작업 상태를 참조하세요.
`errorCode`	`string \| null`	작업이 실패하거나 검토가 필요할 때 설정됩니다.
`priceMicros`	`integer`	접수 시 확정된 견적(USD 마이크로 단위)입니다.
`currency`	`"USD"`
`createdAt / updatedAt`	`string`	ISO 8601 타임스탬프입니다.
`assets[]`	`array`	{ id, type, url?, text? }. url은 동일 출처의 /api/v1/results/<uuid> 링크입니다.
`replayed`	`boolean`	제출 시에만 해당합니다. 멱등 재시도가 일치하면 true입니다.

결과 에셋에는 텍스트 또는 동일 출처의 /api/v1/results/<uuid> URL이 포함됩니다. 같은 자격 증명(media:read 권한)으로 파일을 다운로드하세요. GET /api/v1/jobs는 최근 100개 작업을 나열합니다.