생성 내역

동영상 및 이미지 모델은 몇 초에서 몇 분이 걸리므로 모든 요청은 비동기 방식입니다. 제출하면 생성 내역이 즉시 반환됩니다. 이후 상태를 조회하거나 최종 상태에 도달했을 때 웹훅을 받을 수 있습니다. 생성 객체 하나에 입력, 상태, 결과, 오류, 비용이 모두 담깁니다.

수명 주기#

succeeded, failed, canceled는 최종 상태입니다. 이 중 하나에 도달하면 생성 상태가 바뀌지 않습니다. 중간 상태가 추가되더라도 코드가 작동하도록 다른 값은 모두 “진행 중”으로 처리하세요.

1. 제출#

모델 입력값을 JSON 본문으로 POST /api/v1/run/{endpoint}하세요. 엔드포인트 ID는 모델과 작업을 조합한 값입니다 (예: bytedance/seedance-2.0-fast/text-to-video). 모든 엔드포인트와 입력 필드는 모델 페이지에서 확인할 수 있습니다.

입력값을 검증하고 가격을 계산해 잔액에서 금액을 보류한 뒤 작업을 대기열에 넣습니다. 응답은 생성 객체가 포함된 202 Accepted이며, 편의를 위해 urls.get과 urls.cancel도 반환합니다:

{
  "id": "gen_8c2QmX1nq0k4Lw7Z",
  "object": "generation",
  "model": "bytedance/seedance-2.0-fast",
  "endpoint": "bytedance/seedance-2.0-fast/text-to-video",
  "mode": "text-to-video",
  "status": "queued",
  "input": {
    "prompt": "골든아워에 꽃병을 빚는 도예가에게 천천히 다가가는 카메라, 빛 속 먼지 입자, 얕은 심도",
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "duration": 5,
    "generate_audio": true
  },
  "output": null,
  "error": null,
  "cost": {
    "amount_usd": 0.4494,
    "currency": "usd",
    "estimated": true
  },
  "source": "api",
  "created_at": "2026-10-15T09:21:04.512Z",
  "started_at": null,
  "completed_at": null,
  "retention": "1d",
  "expires_at": null,
  "purged_at": null,
  "urls": {
    "get": "https://cheapergen.com/api/v1/generations/gen_8c2QmX1nq0k4Lw7Z",
    "cancel": "https://cheapergen.com/api/v1/generations/gen_8c2QmX1nq0k4Lw7Z/cancel"
  }
}

참조 이미지, 동영상 및 오디오#

reference-to-video 모드에는 최대 세 종류의 참조 자료를 각각 HTTPS URL 목록으로 전달할 수 있습니다 (공개 링크 또는 uploads의 URL): 캐릭터, 제품, 장면용 reference_image_urls, 움직임, 카메라 이동, 효과용 reference_video_urls, 음성, 음악, 사운드용 reference_audio_urls.

프롬프트에서 참조 위치를 지정하세요. @Image1은 reference_image_urls의 첫 번째 URL, @Video1는 reference_video_urls의 첫 번째 URL, @Audio2는 두 번째 오디오 클립을 가리킵니다. 멘션은 대소문자를 구분하지 않으며 @Image1 형식으로 정규화됩니다. 일치하는 참조가 없는 멘션(예: 동영상 하나만 첨부했는데 @Video2라고 지정한 경우)은 요금 청구 전에 400 invalid_request(param: "prompt") 오류로 거부됩니다.

{
  "prompt": "@Image1 dances on a rooftop, copying the choreography and camera move of @Video1, in sync with @Audio1",
  "reference_image_urls": [
    "https://example.com/dancer.jpg"
  ],
  "reference_video_urls": [
    "https://example.com/choreo.mp4"
  ],
  "reference_audio_urls": [
    "https://example.com/beat.mp3"
  ],
  "resolution": "720p",
  "duration": 8
}

요청 제출 시 각 참조 동영상과 오디오 파일의 시작 부분을 다운로드해 실제 길이, 크기, 해상도, 프레임 레이트가 모델 제한에 맞는지 확인합니다. 범위를 벗어난 항목 (20초 클립, 720p만 지원하는 모델에 1080p, MP3/WAV가 필요한 곳의 M4A, 응답하지 않는 URL 등)은 청구 전에 400 invalid_request 오류를 반환합니다. param에 문제가 된 필드를 표시하고 (예: reference_video_urls) 메시지에 클립 이름을 포함합니다. 참조 동영상은 추가 과금 초로 계산됩니다. 자세한 내용: 결제 및 청구.

동영상은 H.264 또는 H.265 코덱을 사용하는 MP4/MOV 형식이어야 합니다. 모델별 실행 용량 중 가장 엄격한 제한이 적용되므로 여기서 통과한 요청은 업스트림에서도 승인됩니다. 참조 이미지와 오디오는 가격에 영향을 주지 않습니다.

2. 결과 폴링#

GET /api/v1/generations/{id}은 현재 상태를 반환합니다. 생성 정보를 조회하면 진행도 한 단계 앞으로 나아갑니다. 상태 점검 시점이 되면 응답 전에 확인하므로 폴링 결과는 몇 초 이상 오래되지 않습니다.

const API = "https://cheapergen.com/api/v1";
const headers = { Authorization: `Bearer ${process.env.CHEAPERGEN_API_KEY}` };
const FINAL = new Set(["succeeded", "failed", "canceled"]);

export async function wait(id, timeoutMs = 15 * 60_000) {
  let delay = 2000;
  const deadline = Date.now() + timeoutMs;
  while (Date.now() < deadline) {
    const gen = await fetch(`${API}/generations/${id}`, { headers }).then((r) => r.json());
    if (FINAL.has(gen.status)) return gen;
    await new Promise((r) => setTimeout(r, delay));
    delay = Math.min(delay * 1.5, 10_000); // back off to every 10 s
  }
  // Giving up: cancel it first, or it still runs and is charged when it finishes (once running it can't be: 409).
  await fetch(`${API}/generations/${id}/cancel`, { method: "POST", headers }).catch(() => {});
  throw new Error(`Timed out waiting for ${id}`);
}

import os, time, requests

API = "https://cheapergen.com/api/v1"
headers = {"Authorization": f"Bearer {os.environ['CHEAPERGEN_API_KEY']}"}

def wait(gen_id, timeout=900):
    delay, waited = 2, 0
    while waited < timeout:
        gen = requests.get(f"{API}/generations/{gen_id}", headers=headers).json()
        if gen["status"] in ("succeeded", "failed", "canceled"):
            return gen
        time.sleep(delay)
        waited += delay
        delay = min(delay * 1.5, 10)  # back off to every 10 s
    # Giving up: cancel it first, or it still runs and is charged when it finishes (once running it can't be: 409).
    requests.post(f"{API}/generations/{gen_id}/cancel", headers=headers)
    raise TimeoutError(gen_id)

권장 폴링 간격#

• 이미지: 1~2초 간격으로 폴링하세요. 대부분 30초 이내에 완료됩니다.
• 동영상: 처음에는 3~5초 간격으로 폴링하고 이후 10초까지 간격을 늘리세요. 5초 클립은 보통 1~3분, 고해상도에서는 더 오래 걸립니다.
• 폴링도 요청 제한에 포함됩니다. 여러 작업을 동시에 실행할 때는 웹훅을 사용하는 것이 좋습니다.

3. 결과 사용#

성공하면 output에 생성된 미디어의 HTTPS URL이 담깁니다. 동영상 모델은 파일 하나를 반환합니다:

{
  "output": {
    "video": {
      "url": "https://cdn.cheapergen.com/outputs/gen_8c2QmX1nq0k4Lw7Z.mp4",
      "content_type": "video/mp4"
    }
  }
}

이미지 모델은 생성된 이미지마다 항목 하나씩 목록으로 반환합니다:

{
  "output": {
    "images": [
      {
        "url": "https://cdn.cheapergen.com/outputs/gen_8c2QmX1nq0k4Lw7Z.png",
        "content_type": "image/png"
      }
    ]
  }
}

실패 및 환불#

생성이 실패하면 status 은 failed, error 에 원인과 해결 방법이 표시되고, cost.amount_usd 은 0 — 보류 금액 전액을 잔액으로 돌려드립니다. 작업을 실패로 표시하기 전, 외부 서비스 장애와 오류는 사용 가능한 다른 경로에서 자동으로 재시도합니다. 안전 필터에 걸렸거나 모델이 처리할 수 없는 입력은 같은 이유로 다시 거부되므로 재시도하지 않습니다. 모델 서비스에서 입력 파일을 다운로드하지 못하면 보통 저희가 직접 다운로드해 같은 가격으로 재시도합니다. input_unreachable는 대개 파일을 전혀 다운로드하지 못했다는 뜻입니다.

{
  "status": "failed",
  "error": {
    "code": "generation_failed",
    "message": "ByteDance's safety review for Seedance 2.0 Fast rejected this request (the prompt or an input file).",
    "reason": "content_blocked",
    "hint": "Describe the character's look instead of naming a copyrighted character or real person, keep it non-explicit, or try another model.",
    "retryable": false,
    "refunded": true,
    "detail": "요청이 콘텐츠 안전성 검토를 통과하지 못했습니다. 프롬프트를 수정한 뒤 다시 시도하세요."
  },
  "cost": {
    "amount_usd": 0,
    "currency": "usd",
    "estimated": false
  }
}

• code — 출시 이후 변경되지 않은 상위 분류: generation_failed (입력이 거부되었거나 완료할 수 없음), upstream_error, timeout 또는 model_unavailable.
• reason — 아래 표에서 설명하는 정확한 원인입니다. 신규 연동에서는 이 값을 기준으로 분기하세요. 새로운 사유가 추가될 수 있습니다.
• message — 사용자에게 보여 줄 수 있는 설명입니다. 안전 필터가 거부한 경우 어느 모델의 필터인지 표시합니다.
• hint — 다음에 변경하거나 수행할 작업입니다.
• retryable 값이 true이면 같은 요청을 다시 보냈을 때 성공할 수 있고, false이면 같은 방식으로 재시도해도 실패합니다.
• refunded 값이 true이면 보류 금액이 반환된 것입니다. 실패한 생성에는 요금이 부과되지 않습니다.
• param — 알 수 있는 경우 변경할 입력 필드입니다 (예: image_url, duration).
• detail — 추가 정보를 제공하는 경우 모델 측의 원문입니다.

reason 필드가 도입되기 전에 실패한 생성은 기존 code 값을 유지합니다. 해당 생성에도 reason와 hint 값을 채웁니다.

긴급 가격#

요청에 필요한 일반 용량을 사용할 수 없는 경우 최대 긴급 요금이 적용됩니다. 모델의 공식 가격을 넘지 않습니다. allow_fallback_price 이 설정이 적용 여부를 결정하며 기본값은 true REST API와 MCP에서 새 요청은 견적을 받은 뒤 긴급 가격으로 청구됩니다. 일반 가격으로 승인된 작업도 용량이 중간에 부족해지면 긴급 가격으로 전환될 수 있으며, 추가 금액은 그때 보류됩니다. max_cost_usd 두 경우 모두 가격 상한을 제한합니다. allow_fallback_price: false 견적받은 가격보다 더 많이 지불하지 않으려면 설정하세요(Pro 또는 Max 요금제에서는 Pro 또는 Max 요금제, 이미 접수된 작업의 가격도 최대 일반 가격까지 올라갈 수 있습니다): 새 요청에는 503 fallback_price_declined. 이미 승인된 작업은 실패 처리 후 환불됩니다. Studio 작업은 사용자가 생성을 클릭한 뒤 더 높은 가격으로 변경되지 않습니다. 긴급 가격이 적용되면 생성 내역의 pricing.fallback (웹훅에도 포함)에 두 가격이 모두 표시됩니다.가 적용됩니다.

안전성 검사기#

enable_safety_checker의 기본값은 true입니다. API 요청에서는 false를 사용할 수 있습니다. Studio와 모델 페이지에서는 항상 켜져 있으며, 기능은 모델에 따라 다릅니다:

• 비공개 모델 (Seedance, Kling, Veo, MiniMax H3, Wan 3.0 등)은 각 연구소의 자체 콘텐츠 필터를 사용하며, 이를 끌 수 없습니다. true 및 false에서는 해당 옵션을 바꿔도 동작이 달라지지 않아 요청 스키마에 표시되지 않습니다. MiniMax H3 Max는 예외입니다. 안전 검사기를 끌 수 있어 요청 스키마에 해당 옵션을 표시합니다. 안전 검사를 끈 요청에는 별도의 안전 설정이 적용됩니다 — 비상 가격이 적용될 수도 있지만, 공식 정가를 넘지 않습니다.
• Seedream 4.5 and Seedream 5.0 Lite도 옵션을 표시합니다. 끄면 요청은 ByteDance의 해외용 모델 설정에서 실행되어 추가 필터가 적용되지 않습니다. 켜면 일반 필터가 적용됩니다. 저희 검사기는 미성년자가 관련된 성적 콘텐츠를 계속 차단합니다. 필터를 끈 요청에는 별도의 높은 가격인 Seedream 4.5 $0.04 per image · Seedream 5.0 Lite $0.035 per image가 적용됩니다. /quote는 요청값 enable_safety_checker: false (포함: fallback.reason "safety_checker_off"을 보내면 해당 가격을 반환합니다). 이는 긴급 요금로 집계됩니다. allow_fallback_price: false가 적용된 경우 이런 요청은 거부됩니다. 현재 실행할 수 없을 때는 요청이 503 model_unavailable (param: "enable_safety_checker") 오류와 함께 거부됩니다. 표준 필터로 실행하려면 true를 전송하세요.
• 오픈 웨이트 모델은 해당 옵션을 표시합니다. 생성 작업이 자체 필터가 없는 용량에서 실행되는 경우, 먼저 프롬프트와 입력 이미지를 검사합니다. 필터를 켜면 성적 콘텐츠, 노골적인 폭력 및 자해 콘텐츠를 차단하고, 끄더라도 미성년자가 관련된 성적 콘텐츠는 계속 차단합니다. 용량 자체에 전환 가능한 필터가 있으면 요청에 전달된 옵션을 그대로 적용합니다. 필터를 끄더라도 미성년자가 관련된 성적 콘텐츠는 계속 차단합니다.

옵션을 표시하지 않는 모드(자체 검사 기능을 끌 수 없는 모드)에서 false을 요청하면 400 invalid_request을 반환합니다. 옵션을 꺼도 허용 사용 정책에서 금지하는 콘텐츠를 생성할 수 있는 것은 아닙니다.

데이터 보관#

API로 생성한 작업은 기본적으로 완료 시점부터 1일 동안 보관됩니다. 이후 프롬프트, 입력 미디어, 결과물과 파일을 자동으로 삭제합니다. 모델, 가격에 영향을 주는 매개변수, 비용, 타임스탬프는 생성 객체에 남겨 사용 내역과 청구서를 정확하게 유지합니다. 이때 output는 null이 되고, purged_at가 설정되며, content_expired에 삭제 이유가 기록됩니다. 보관할 결과물은 expires_at 전에 다운로드하세요.

요청 본문에 retention을 전달하면 생성별 보관 기간을 지정할 수 있습니다. 모든 계정에서 기간을 단축하거나 최대 1d까지 요청할 수 있습니다. 7d와 30d은 계정 수준의 보관 설정이 필요합니다(영업팀에 문의). 계정에서 허용하는 기간보다 길게 요청하면 400 invalid_request 오류와 함께 param: "retention" 필드가 표시됩니다.

{
  "prompt": "A paper boat drifting down a rain-soaked street",
  "resolution": "720p",
  "duration": 5,
  "retention": "immediate",
  "webhook_url": "https://example.com/hooks/cheapergen"
}

Studio 및 플레이그라운드 생성 내역은 사용자가 삭제할 때까지 보관됩니다. 업로드 파일은 보관 중인 생성에서 사용하는 동안 유지되며, 어느 생성에서도 사용하지 않는 파일은 1일 후 삭제됩니다. 계정을 삭제하면 모든 생성과 파일도 삭제됩니다. 모델 제공자가 허용하는 경우 제공자 측에도 가능한 한 짧게 보관하도록 요청합니다.

생성 내역 삭제#

완료된 생성은 DELETE /api/v1/generations/{id}, 대시보드의 생성 목록 또는 Studio 뷰어에서 삭제할 수 있습니다. API로는 아직 취소할 수 있는 대기 중인 생성도 삭제할 수 있습니다(먼저 취소되고 보류된 금액이 전액 환불됩니다). 파일, 프롬프트, 입력은 바로 삭제되고 목록에서도 사라지며, 청구 금액은 결제 내역에 남습니다. API 레퍼런스를 참고하세요.

취소#

POST /api/v1/generations/{id}/cancel 요청은 아직 queued 상태인 생성을 취소하고 보류 금액을 환불합니다. 작업이 running 상태라면 모델이 이미 처리 중이므로 취소 요청은 409 conflict 응답을 반환하고, 작업은 계속되어 정상적으로 완료·청구됩니다. 대기 중 취소를 지원하지 않는 일부 모델도 409 응답을 반환합니다.

curl -X POST https://cheapergen.com/api/v1/generations/gen_8c2QmX1nq0k4Lw7Z/cancel \
  -H "Authorization: Bearer $CHEAPERGEN_API_KEY"

생성 목록#

GET /api/v1/generations 요청은 생성 작업을 최신순으로 나열하고 커서 페이지네이션을 지원합니다. status, model 또는 source(playground, api, mcp)로 필터링할 수 있습니다. 다음 페이지를 조회할 때는 반환된 next_cursor 값을 cursor에 전달하세요. 자세한 내용은 API 레퍼런스에서 확인하세요.

curl "https://cheapergen.com/api/v1/generations?status=succeeded&limit=50" \
  -H "Authorization: Bearer $CHEAPERGEN_API_KEY"

Studio 및 모델 페이지에서 만든 생성도 표시되며 출처는 source: "playground", API 요청은 source: "api"입니다.