생성 API 문서

API로 생성 작업을 만들려면 유료 크레딧 팩이나 활성 유료 구독이 필요하며, 유료 크레딧만 사용합니다. 조회, 목록, 다운로드는 계정의 어떤 키로도 할 수 있습니다.

빠른 시작

API 키 페이지에서 키를 만들고, 서버에만 두고, API_KEY로 설정하세요. 아래 예시는 seed-audio-1.0(으)로 생성 작업을 만들고, 끝날 때까지 조회한 뒤, 첫 파일을 내려받습니다.

새 요청마다 새 Idempotency-Key를 보내세요. 응답을 받지 못한 요청은 같은 키와 같은 본문으로 다시 보내면 됩니다. 첫 요청이 만든 작업을 받으며 청구는 한 번뿐입니다.

export API_ORIGIN='https://demo.freshapp.ai'
export API_KEY='sk_YOUR_API_KEY'

curl --fail-with-body "$API_ORIGIN/api/v1/generations" \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-1001' \
  -d '{"model":"seed-audio-1.0","input":{"prompt":"새벽녘 절벽 위의 등대, 잔잔한 바다, 부드러운 빛."}}'

# Read it every 5 to 10 seconds until its status ends.
curl --fail-with-body "$API_ORIGIN/api/v1/generations/GENERATION_ID" \
  -H "Authorization: Bearer $API_KEY"

# A delivered output's url is a signed link: no key needed.
curl --fail-with-body -o result "OUTPUT_URL"

import { createClient } from './open-api-client';

const client = createClient({
  baseUrl: "https://demo.freshapp.ai",
  apiKey: process.env.API_KEY, // on your server only
});
const generation = await client.create(
  {
    "model": "seed-audio-1.0",
    "input": {
      "prompt": "새벽녘 절벽 위의 등대, 잔잔한 바다, 부드러운 빛."
    }
  },
  { idempotencyKey: "order-1001" }
);
const done = await client.wait(generation.id);
for (const output of done.outputs)
  if (output.status === 'delivered') {
    const file = await client.download(output);
    // file.body is the output, as output.content_type says
  }

import { createClient } from './open-api-client';
import { useGeneration } from './open-api-react';

// In a browser on this site: no key, the visitor's own session.
const client = createClient();

export function Progress({ id }: { id: string }) {
  const { generation, error, done } = useGeneration(client, id);
  if (error) return <p>{String(error)}</p>;
  return <p>{generation?.status ?? '…'}{done ? ' ✓' : ''}</p>;
}

키와 권한

모든 요청은 API 키 페이지에서 만든 키를 Authorization: Bearer에 담아 보냅니다. 키는 sk_ 뒤에 영문자, 숫자, 하이픈, 밑줄 43자가 붙은 형태이며, 만들거나 교체할 때 한 번만 보입니다. Authorization이 있는 요청은 키로만 판단하며, 함께 있는 로그인 세션은 쓰지 않습니다.

키는 읽기만 하거나(목록, 조회, 다운로드) 생성까지 할 수 있습니다(생성과 취소). 읽기 전용 키로 생성이나 취소를 시도하면 403 insufficient_scope가 되고 아무것도 기록되지 않습니다.

키에는 주소와 네트워크로 된 IP 허용 목록을 붙일 수 있으며, 다른 주소에서 오면 403 ip_not_allowed가 됩니다. 키 권한을 넓히거나 한도를 올리거나 허용 목록을 넓히려면 최근 로그인이 필요하지만, 좁힐 때는 필요 없습니다.

키를 교체하면 즉시 새 값이 생기고 이전 값은 멈춥니다. 키를 폐기하면 영구히 멈춥니다. 아직 모델에 보내지 않은 작업은 취소되어 크레딧이 돌아오고, 이미 진행 중인 작업은 그대로 끝납니다.

유료 이용 자격이 있는 계정만 API로 생성 작업을 만들 수 있으며(아니면 403 not_eligible), API는 유료 크레딧만 씁니다(부족하면 402 insufficient_credits). 선물·출석 크레딧은 웹사이트용으로 남습니다.

생성 API 엔드포인트

모든 경로는 이 사이트에 있습니다. 요청과 응답 본문은 결과 파일을 빼고 모두 JSON입니다.

https://demo.freshapp.ai

모델과 가격

이 사이트에서 활성화된 모델을 API에서 쓰는 형태로 보여 줍니다. ID는 model에, 필드는 input에 넣으세요. 요청은 만들 때 가장 비싼 결과의 금액을 잡아 두고, 끝나면 전달된 만큼만 냅니다.

멱등성

생성 작업을 만들려면 영문자, 숫자, 점, 콜론, 밑줄, 하이픈 1~128자로 된 Idempotency-Key 헤더가 필요합니다. 주문 번호처럼 내 시스템의 ID를 쓰면 같은 일에는 늘 같은 키가 붙습니다.

같은 키와 같은 요청은 몇 번을 보내도 같은 작업을 돌려주며 청구는 한 번뿐입니다. 같은 키로 다른 요청을 보내면 409 idempotency_conflict가 되고 아무것도 만들어지지 않습니다.

시간 초과나 연결 끊김은 요청이 실패했다는 뜻이 아닙니다. 같은 키와 같은 본문으로 다시 보내고, 응답을 받을 때까지 둘 다 보관하세요. 5xx, 429, 408도 마찬가지로 Retry-After만큼 기다린 뒤 요청을 그대로 다시 보냅니다.

상태와 폴링

GET /api/v1/generations/{id}로 작업을 조회합니다. 처음에는 5초마다, 이후에는 최대 10초마다, 상태가 끝날 때까지 조회하세요. 429가 오면 Retry-After에 다시 조회할 때가 적혀 있습니다.

billing.reserved_credits는 작업을 만들 때 잡아 둔 금액입니다. 정산 후 charged_credits는 낸 금액, refunded_credits는 돌아온 금액이며, 그전에는 둘 다 null이고 held_credits에 잡아 둔 금액이 나옵니다.

수동 확인을 기다리는 작업은 review에 확인이 시작된 시각이 나오고, 확인이 끝날 때까지 크레딧을 잡아 둡니다. 그 뒤 작업이 이어지거나 크레딧이 돌아옵니다.

결과 파일

전달된 출력마다 이 사이트의 url이 있습니다. 키로 조회하면 서명된 링크가 되어 1시간 동안 키 없이 어느 주소에서든 열리므로 다운로드 도구에 그대로 넘길 수 있습니다. 1시간이 지나면 작업을 다시 조회해 새 링크를 받으세요.

키를 직접 써서 GET /api/media/{id}로도 파일을 받을 수 있으며, 이때는 키의 허용 목록이 적용됩니다. 두 방법 모두 HEAD와 바이트 범위 하나(Range: bytes=0-1023)를 지원하고 다른 사이트로 리디렉션하지 않습니다.

입력에서 참조하는 파일(오디오 샘플이나 이미지 등)은 이 계정이 웹사이트에 올린 파일, 사이트가 제공하는 샘플, 또는 사이트가 허용하는 출처의 링크여야 합니다. 그 밖의 참조는 크레딧을 잡기 전에 거절됩니다.

한도

아래 한도는 모두 이 사이트가 지금 적용하는 값이며, 거절될 때는 어느 한도에 걸렸는지 알려 줍니다.

• 요청 한 번에 잡아 두는 크레딧은 최대 150이며, 활성 모델 중 가장 비싼 요청의 가격입니다. 키에 더 낮은 값을 정할 수 있고 요청의 max_credits로 그 요청만 더 낮출 수 있습니다. 넘으면 400 request_limit_exceeded가 됩니다.
• 키 하나는 UTC 기준 하루에 최대 5,000 크레딧을 쓰며, 키별 한도를 최대 1,000,000까지 정할 수 있습니다. 넘은 키는 다음 UTC 날까지 429 key_daily_limit_exceeded가 됩니다.
• 계정의 모든 키와 AI 클라이언트를 합쳐 UTC 기준 하루 최대 10,000 크레딧을 쓰며, 계정 한도를 따로 정할 수 있습니다. 넘으면 429 account_daily_limit_exceeded가 됩니다.
• 키마다, 계정마다 1분에 생성·취소 20번, 조회·다운로드 240번까지이며, 넘으면 Retry-After와 함께 429 rate_limited가 됩니다.
• 계정에서 동시에 실행되는 생성 작업은 최대 2개이며, 더 만들면 429 too_many_active로 기다려야 합니다.
• 요청 본문은 최대 32 KiB의 JSON이며, 더 크면 413 request_too_large가 됩니다.

오류 코드

오류는 {"error": {"code": …, "message": …}} 형태로 옵니다. code는 언제나 아래 표 중 하나이고, message는 개발자를 위한 영어 설명입니다. 429와 503은 기다릴 초를 Retry-After에 담습니다. 실패하거나 취소된 작업은 작업용으로 표시된 코드 중 하나를 error 필드에 담습니다.

TypeScript 클라이언트와 React 훅

TypeScript 클라이언트 open-api-client.ts는 다른 패키지가 필요 없고 서버, 워커, 브라우저에서 실행됩니다. 서버에서는 baseUrl과 apiKey를 주고, 이 사이트의 브라우저 페이지에서는 둘 다 주지 않으면 방문자 자신의 로그인 세션으로 요청합니다.

create는 Idempotency-Key(지정한 값 또는 새 무작위 값)를 보내고, 연결 끊김, 5xx, 429, 408이 오면 Retry-After만큼 기다린 뒤 같은 요청을 다시 보냅니다. 포기할 때는 오류에 키가 담겨 있어 나중에 그 키로 다시 보낼 수 있습니다. localStorage 같은 store를 주면 페이지를 새로 고쳐도 처음 키를 유지합니다.

wait는 작업이 끝날 때까지 조회합니다. 처음에는 5초, 이후 최대 10초 간격이며 중단하면 바로 멈춥니다. download는 출력의 파일을 받아 오며, 키는 이 사이트의 서명되지 않은 링크에만 붙입니다.

React 훅 open-api-react.ts는 클라이언트의 wait로 작업 하나를 따라가고, 컴포넌트가 언마운트되면 멈춥니다. 두 파일을 내려받아 같은 곳에 두고 확장자를 .ts로 바꾸세요.

다운로드