Cheaper Gen. API

공식 비디오 및 이미지 모델을 위한 하나의 비동기 REST API입니다. 요금은 선불 USD 잔액에서 차감되며, 비디오 초당 또는 이미지당 비용을 지불하고 실패한 생성은 자동 환불됩니다.

기본 URL: https://cheapergen.com/api/v1
인증: Authorization: Bearer $CHEAPERGEN_API_KEY (키는 cg_live_로 시작하며 https://cheapergen.com/dashboard/keys에서 생성 가능). 환경 변수에서 키를 읽어오세요. 절대 출력, 로깅, 커밋하지 마세요.
MCP 서버가 연결되어 있으면 MCP 서버를 우선 사용하세요. 도구는 list_models, get_model, quote, generate (wait_seconds 및 max_cost_usd 예산 제한 포함), get_generation, get_account, add_credits(잔액이 부족할 때 사용자가 열 결제 링크)입니다. HTTP 호출 대신 이 도구들을 사용하세요. 아래 워크플로우는 동일합니다. 연결하려면 원격 서버 https://cheapergen.com/api/mcp를 추가하세요. 사용자가 브라우저에서 로그인 및 승인(OAuth)하며 키가 필요 없습니다. Claude Code: claude mcp add --transport http cheapergen https://cheapergen.com/api/mcp, 그런 다음 /mcp → 인증. 전체 설정: https://cheapergen.com/docs/mcp

워크플로우

모델 선택: GET /models (공개). 각 모델의 endpoints[].id와 가격 등급을 반환합니다. 항상 실시간 목록을 사용하세요. 모델은 변경됩니다.
- 비디오: Seedance 2.0 (최고 품질, 4K, 동기화된 오디오), Seedance 2.0 Fast / Mini (저렴하고 빠름), Seedance 2.5 (최신, 가장 긴 참조), Wan 3.0 / Prime (Alibaba), MiniMax H3 / H3 Max.
- 이미지: Seedream 5.0 Pro / Lite / Flash (텍스트-이미지 및 edit).
- 엔드포인트 ID 형식은 {vendor}/{model}/{mode}입니다. 예: bytedance/seedance-2.0-fast/text-to-video, bytedance/seedream-5.0-lite/text-to-image.
입력 스키마 읽기: GET /models/{vendor}/{model} (공개)는 endpoints[].input_schema (열거형, 기본값, 제한이 있는 JSON 스키마)와 pricing.tiers를 반환합니다. 스키마의 필드만 전송하세요. 알 수 없는 필드는 400 오류와 함께 거부됩니다.
견적: POST /quote/{endpoint}에 입력값을 보내면 (공개, 무료) { amount_usd, list_usd, discount_pct, available }을 반환합니다. 비용이 많이 드는 작업(1080p/4K 비디오, 긴 지속 시간, 배치) 전에 사용자에게 가격을 알려주세요.
제출: POST /run/{endpoint}에 입력값을 JSON 본문으로 보내면 202와 status: "queued"인 생성 항목을 반환합니다. 이 시점에서 잔액에서 가격이 보류됩니다.
대기: GET /generations/{id}를 status가 succeeded, failed 또는 canceled가 될 때까지 폴링합니다. 이미지는 1~~2초마다, 비디오는 3~~5초마다 폴링하고 10초로 백오프합니다. 5초 클립은 일반적으로 1~3분이 소요되기 때문입니다. 또는 webhook_url을 전달하세요 (아래 참조).
출력 사용: output.video.url (비디오) 또는 output.images[].url (이미지). URL은 공개되지만 계정의 보존 기간(기본값 1일, expires_at 참조)에 따라 만료되므로 보관할 가치가 있는 것은 다운로드하세요.

curl -s https://cheapergen.com/api/v1/run/bytedance/seedance-2.0-fast/text-to-video \
  -H "Authorization: Bearer $CHEAPERGEN_API_KEY" -H "Content-Type: application/json" \
  -d '{"prompt":"A paper boat drifting down a rainy neon street, slow dolly-in","resolution":"720p","duration":5,"aspect_ratio":"16:9"}'
# → 202 {"id":"gen_…","status":"queued","cost":{"amount_usd":…,"estimated":true},…}
curl -s https://cheapergen.com/api/v1/generations/gen_… -H "Authorization: Bearer $CHEAPERGEN_API_KEY"

import os, time, requests
API = "https://cheapergen.com/api/v1"
H = {"Authorization": f"Bearer {os.environ['CHEAPERGEN_API_KEY']}"}

def generate(endpoint: str, inp: dict, timeout_s: int = 900) -> dict:
    r = requests.post(f"{API}/run/{endpoint}", json=inp, headers=H, timeout=60)
    r.raise_for_status()  # 4xx 본문: {"error": {"code", "message", "param"}}
    gen, delay, start = r.json(), 2.0, time.time()
    while gen["status"] in ("queued", "running"):
        if time.time() - start > timeout_s:
            raise TimeoutError(gen["id"])
        time.sleep(delay)
        delay = min(delay * 1.5, 10)
        r = requests.get(f"{API}/generations/{gen['id']}", headers=H, timeout=30)
        if r.status_code == 429 or r.status_code >= 500:
            continue  # 일시적 오류: 계속 폴링
        r.raise_for_status()
        gen = r.json()
    if gen["status"] != "succeeded":
        raise RuntimeError(gen["error"])  # 보류 금액이 환불되었습니다
    return gen  # gen["output"]["video"]["url"] 또는 gen["output"]["images"][0]["url"]

모드 및 입력

text-to-video 및 text-to-image: prompt와 옵션(resolution, duration, aspect_ratio, size, seed, generate_audio…)을 사용합니다. 각 모델의 스키마에서 열거형을 확인하세요.
image-to-video: image_url(첫 번째 프레임)과 일부 모델의 경우 end_image_url(마지막 프레임)을 사용합니다.
edit (Seedream): image_urls (편집하거나 결합할 이미지, 프롬프트에서 "image 1", "image 2"로 참조)와 prompt의 지시사항을 사용합니다.
reference-to-video: reference_image_urls, reference_video_urls, reference_audio_urls를 사용합니다. 프롬프트에서 1부터 시작하는 위치로 참조합니다: @Image1, @Image2, @Video1, @Audio1 (대소문자 구분 없음). 일치하는 참조가 없는 멘션은 param: "prompt"와 함께 400 오류를 반환합니다. 예: "@Image1 walks through the market from @Image2, camera moves like @Video1".
- 스키마의 reference_rules는 최대 파일 수와 하나 이상의 이미지 또는 비디오가 필요한지 여부를 설정합니다 (Seedance 및 H3의 경우 오디오만으로는 충분하지 않음).
- 참조 비디오 및 오디오는 서버에서 media_limits / x-media-limits에 대해 (지속 시간, 크기, 해상도, fps) 측정됩니다. Seedance 2.0은 각 2~15초, 총 15초의 MP4/MOV 비디오를 허용합니다. 오디오는 MP3/WAV여야 합니다. 위반 시 파일 이름을 명시하는 400 오류가 발생합니다. 예: @Video2 is 16 s long….
- 참조 비디오 초는 출력 초와 함께 청구됩니다. 참조 이미지 및 오디오는 무료입니다. 견적을 받으려면 reference_video_durations: [6.5](클립당 초)를 전달하세요.
미디어 입력은 공개 https URL이어야 합니다. 로컬 파일의 경우 POST /uploads를 JSON { "filename", "content_type", "size" }로 호출하세요. { upload_url, headers, url }을 반환합니다. upload_url에 정확히 해당 headers와 함께 바이트를 PUT한 다음 url을 입력으로 사용하세요. 제한: 이미지(PNG/JPEG/WebP/GIF) ≤ 20 MB, 비디오(MP4/MOV) ≤ 50 MB, 오디오(MP3/WAV/M4A) ≤ 15 MB.
모든 실행에 선택 사항: webhook_url (HTTPS) 및 retention (immediate | 1h | 1d; 7d / 30d는 계정 설정 필요).

웹훅

작업이 완료되면(성공 또는 실패), webhook_url에 { "type": "generation.succeeded" | "generation.failed", "data": <generation> }을 CheaperGen-Signature: t=<unix>,v1=<hex> 헤더와 함께 POST합니다. 확인하려면 계정의 웹훅 서명 비밀(whsec_…, 대시보드 → API 키)으로 hex(HMAC_SHA256(secret, "<t>.<raw body>"))를 계산하고, 일정 시간 내에 비교하며 t가 5분 이상 지난 요청은 거부합니다. 다시 직렬화된 JSON이 아닌 원시 요청 본문을 사용하세요. 빠르게 2xx를 반환하세요. 실패한 전달은 재시도됩니다(총 3회).

가격 및 청구

가격은 출력 비디오 초당 또는 이미지당입니다. GET /models는 각 등급의 price_usd와 list_price_usd(공식 가격)를 보여줍니다.
제출 시 견적 가격이 보류됩니다(cost.estimated: true). 성공 시 최종 가격이 되고, 실패 또는 취소 시 전액 환불됩니다(cost.amount_usd: 0). cost.official_usd 및 cost.saved_usd는 절감액을 보여줍니다.
잔액: GET /account는 balance_usd와 reserved_usd(진행 중인 작업에 대해 보류된 금액)를 반환합니다. 402 오류는 잔액이 너무 낮다는 의미입니다. MCP를 통해 add_credits를 호출하고 사용자에게 결제 링크를 보여주세요. 그렇지 않으면 사용자가 https://cheapergen.com/dashboard/billing에서 크레딧을 추가합니다.
대기 중인 작업은 POST /generations/{id}/cancel로 취소합니다(실행 중이면 409). 완료된 작업은 DELETE /generations/{id}로 삭제합니다.

오류

모든 오류는 { "error": { "code", "message", "param"? } } 형태입니다.

HTTP	code	조치 방법
400	`invalid_request`	`param`에 지정된 필드를 수정하세요 (스키마, 열거형, 제한 및 멘션 확인). 변경 없이 재시도하지 마세요.
401	`unauthorized`	키가 없거나, 유효하지 않거나, 해지되었습니다.
402	`insufficient_balance`	`add_credits` (MCP)로 결제 링크를 받고 사용자에게 지불을 요청하거나 더 저렴한 등급을 선택하세요.
404	`not_found`	잘못된 엔드포인트 또는 생성 ID입니다.
409	`conflict`	예: 이미 시작된 작업을 취소하는 경우.
429	`rate_limited`	백오프 후 재시도하세요. 제한은 약 버스트 20개의 요청이며, 키당 초당 10개로 보충되고 계정당 동시 생성 수 제한(기본값 20)이 있습니다.
502	`upstream_error`	한 번 재시도한 다음 다른 모델을 시도하세요.
503	`model_unavailable`	나중에 재시도하거나 모델을 전환하세요.

failed로 끝난 생성은 error.code(예: generation_failed, timeout)가 있으며 환불되었습니다. 동일한 입력으로 최대 한 번 재시도하세요.

추가 정보

문서: https://cheapergen.com/docs, MCP 설정: https://cheapergen.com/docs/mcp
이 스킬 및 Claude Code 플러그인의 소스: https://github.com/CheaperGen/skills
모델별 API 페이지: https://cheapergen.com/models/{vendor}/{model}/api
기계 판독 가능 요약: https://cheapergen.com/llms.txt

CheaperGen/skills

skills란 무엇인가요?

즐겨 사용하는 AI에게 물어보기

문서

Cheaper Gen. API

워크플로우

모드 및 입력

웹훅

가격 및 청구

오류

추가 정보

관련 스킬

steipete/video-frames

steipete/summarize

openclaw/openclaw

obra/superpowers

affaan-m/ECC

affaan-m/everything-claude-code