AI 이미지 API를 에이전시 파이프라인에 연결하기: 키, 장부, 아카이브

API 레퍼런스는 이미지 한 장을 만드는 법을 알려 줍니다. 에이전시의 문제는 다릅니다. 수천 장의 이미지, 십여 개의 클라이언트, 버튼을 누르는 세 사람, 그리고 월말에 누가 무엇을 썼는지 묻는 재무 담당자 한 명이 있습니다. 어느 것도 어렵지는 않지만, 첫 주에 실수하기 쉬운 부분이 곳곳에 있습니다. 아래는 여섯 가지 규칙이며, 모두 저희가 바라는 모습이 아니라 API가 실제로 동작하는 방식에서 나왔습니다. 아직 첫 요청을 보내 보지 않았다면 API 소개부터 시작하세요.

규칙 1: 클라이언트마다 키 하나, 그 뒤에는 지갑 하나

키는 API Console에서 각각 이름을 붙여 만들고, 전체 키는 딱 한 번만 표시됩니다. 키 이름은 클라이언트 이름으로 지으세요. 유출된 키나 계약이 끝난 키는 따로 폐기할 수 있고, 나머지 키는 계속 작동합니다. 다만 키가 돈을 나눠 주지는 않습니다. 계정의 모든 키는 같은 코인 잔액을 사용합니다. 두 클라이언트가 절대 잔액을 공유하면 안 된다면 계정이 두 개여야 하며, 나중에 계정 간에 코인을 옮길 수는 없습니다.

규칙 2: 작업 ID로 묶은 자체 장부

목록 엔드포인트는 키 하나의 작업이 아니라 스튜디오 이미지까지 포함한 계정 전체를 반환합니다. 그러니 클라이언트, 작업, 생성 ID, 청구된 코인을 담은 자체 장부를 두세요. 이것들을 가장 깔끔하게 연결하는 방법은 Idempotency-Key 헤더입니다. 자체 작업 ID로 만들어 두면, 연결이 끊긴 뒤 재시도한 요청은 두 번째 청구 대신 이미 존재하는 생성을 반환합니다. 키는 계정 안에서만이 아니라 서비스 전체에서 확인되므로, 에이전시 고유의 접두사를 붙이세요. 무작위 문자열이면 충분합니다.

POST /v1/api/images
Authorization: Bearer fk_live_key_for_client_a
Idempotency-Key: 7f1c2b90-client-a-deck-0042

{
  "prompt": "a linen shirt on a wooden hanger, soft window light",
  "quality": "standard",
  "aspectRatio": "4:5"
}

응답은 생성 ID와 coinsCharged가 담긴 202입니다. 다른 일을 하기 전에 두 값을 먼저 장부에 기록하세요.

규칙 3: 기다리지 말고 폴링하기

생성은 대기열에 들어간 뒤 백그라운드에서 실행됩니다. 적당한 간격으로 상태를 폴링하고(대기 중에는 응답의 etaMs에 예상 시간이 담깁니다), 작업을 하나씩 차례로 보내기보다 여러 개를 한꺼번에 보내세요. API는 그것이 기본 사용 방식이기 때문에 스튜디오보다 계정당 더 많은 병렬 작업을 허용합니다.

GET /v1/api/images/{id}          -> "queued", "generating", then "succeeded",
                                    or "failed" / "refunded" with refunded: true
GET /v1/api/images/{id}/content  -> the bytes, until the retention window ends
                                    (after that: 410 BYTES_EXPIRED)

규칙 4: 실패도 데이터로 다루기

실패한 생성은 코인을 자동으로 환불하고 refunded로 그 사실을 알려 줍니다. failureCode는 짧은 고정 목록 중 하나입니다. TIMEOUT과 VENDOR_ERROR는 나중에 한 번 재시도할 가치가 있고, MODERATION_REJECTED는 프롬프트를 반복하지 말고 다시 써야 한다는 뜻이며, UNKNOWN은 나머지를 포괄합니다. 코드를 장부에 기록하세요. 브리프가 계속 모더레이션 실패를 내는 클라이언트에게는 재시도 루프가 아니라 대화가 필요합니다. 재시도의 비용 구조는 가격과 실패에 관한 글에 있습니다.

규칙 5: 성공하는 순간 아카이브하기

API는 에셋 라이브러리가 아닙니다. 완성된 파일은 제품 페이지에 나온 보관 기간이 끝나면 삭제되고, 그 이후에는 콘텐츠 요청이 410 BYTES_EXPIRED로 응답합니다. 성공한 이미지는 모두 즉시 장부의 클라이언트와 작업 아래 자체 저장소로 내려받으세요. 클라이언트의 이미지를 저희가 전혀 보관하면 안 되는 경우라면, 아카이브한 뒤 API로 삭제하세요.

규칙 6: 한도는 코드로 확인하고, 납품 전에는 사람이 보기

키마다 요청 속도 한도가 있고, 계정에는 하루 이미지 허용량이 있습니다. 둘 다 한 번의 호출로 알 수 있으므로, 배치 작업은 중간에 실패하는 대신 시작 전에 확인할 수 있습니다.

GET /v1/api/me
-> { "keyName": "client-a", "coins": ..., "rateLimitPerMin": ..., "dailyImagesRemaining": ... }

구체적인 숫자는 제품 페이지에 있습니다. 그리고 무엇이든 클라이언트에게 가기 전에 누군가가 직접 봐야 합니다. 모델은 손에 손가락 여섯 개를 그리거나 간판에 틀린 단어를 넣을 수 있고, 자동화된 파이프라인은 좋은 이미지만큼이나 빠르게 그것을 납품해 버립니다.

API가 에이전시를 위해 해 주지 않는 것

하위 계정도, 클라이언트별 잔액도, 키별 사용량 보고서도 없습니다. 그 정산은 여러분의 몫입니다. 서비스 수준 계약도, 보장된 납품 시간도 없으니 직접 측정하지 않은 시간을 클라이언트에게 약속하지 마세요. 상업적 사용이 허용되고 저희가 어떤 몫도 가져가지 않더라도, AI 이미지는 누구의 것인가에서 설명하듯 생성된 이미지가 저작권 의미에서 여러분의 것이 되지는 않습니다. 그리고 실제 인물의 얼굴은 요청이 어떤 경로로 오든 여전히 그 사람의 허락이 필요합니다.

이 모든 것을 뒷받침하는 코인 예산은 팀이 실제로 쓰는 비용에서 다루며, 직접 만드는 이미지를 위한 스튜디오는 Fellowi Images입니다.