CheaperGen

API 레퍼런스

API 레퍼런스

REST API 레퍼런스: 생성 제출, 조회, 취소, 모델 및 가격 목록, 견적 확인, 잔액 조회, 이미지·동영상·오디오 업로드 방법과 예제

API는 다음 리소스를 중심으로 구성됩니다: generations(실행하는 작업), 모델(실행 가능한 모델과 요금), quotes, account(계정), uploads(업로드). 모든 요청과 응답은 HTTPS를 통한 JSON 형식입니다.

기본 URLhttps://cheapergen.com/api/v1

Authorization: Bearer cg_live_…로 인증하세요(인증 참조). 오류 응답은 오류 처리에 설명된 형식을 따릅니다. 모든 엔드포인트는 CORS 헤더를 보냅니다. 브라우저에서 키를 노출하지 마세요. 클라이언트 측 호출은 공개 엔드포인트만 지원합니다.

API 엔드포인트
엔드포인트
POST/run/{endpoint}
GET/generations/{id}
GET/generations
POST/generations/{id}/cancel
DELETE/generations/{id}
GET/models
GET/models/{vendor}/{model}
POST/quote/{endpoint}
GET/account
GET/account/pricing
POST/uploads
GET/webhooks/secret

생성 요청 제출#

POST/api/v1/run/{endpoint}API 키 필요

비동기 생성 작업을 시작하면 202 Accepted 응답이 반환됩니다. 응답에는 대기열에 등록된 상태(queued)의 생성 객체가 포함됩니다. 이 시점에 요금이 잔액에서 보류됩니다(자세한 내용: 결제 및 청구).

경로 매개변수
endpointstring필수
모델 엔드포인트 ID {vendor}/{model}/{task} — 예: bytedance/seedance-2.0-fast/text-to-video. 모든 ID는 모델 페이지에 있습니다.
본문
…model inputsobject필수
엔드포인트 입력 필드로 prompt, resolution, image_url 등을 사용합니다. 각 모델 API 페이지에 필드, 자료형, 기본값, 허용값이 설명되어 있으며 모델 정보 가져오기에서 JSON Schema로도 확인할 수 있습니다. 알 수 없는 필드는 거부됩니다.
webhook_urlstring (https URL)
선택 사항. 생성이 완료되면 이 URL로 POST합니다. 자세한 내용: 웹훅.
retentionstring
선택 사항. 이 생성의 프롬프트, 입력 및 출력물을 보관하는 기간입니다: immediate, 1h, 1d, 7d 또는 30d. 기본값은 계정 설정(1d)입니다. 모든 계정에서 기간을 단축할 수 있지만, 7d 및 30d에는 엔터프라이즈 보관 설정이 필요합니다. 자세한 내용은 데이터 보관을 참조하세요.
allow_fallback_priceboolean
선택 항목이며 기본값은 true입니다. 요청에 사용할 일반 용량을 이용할 수 없으면 긴급 요금 가격으로 더 비싼 용량에서 실행합니다. 이 가격은 모델의 공식 가격을 넘지 않으며 max_cost_usd보다 높지 않습니다. 제출할 때 적용되며(가격은 응답과 /quote에 표시됨), 작업을 접수한 뒤 용량에 문제가 생기면 다른 용량으로 전환될 때도 적용됩니다(이때 추가 금액을 보류하며 pricing.fallback와 웹훅에 표시됨). 견적받은 가격보다 더 지불하지 않으려면 false를 설정하세요. Pro 또는 Max 요금제에서는 별도로 설정하지 않은 접수 작업이 일반 가격까지 올라갈 수 있습니다. 설정하면 더 높은 가격 대신 503 fallback_price_declined를 받거나, 작업이 실패해 전액 환불됩니다.
max_cost_usdnumber
선택 사항입니다. 긴급 요금을 포함해 이 생성에 지불할 최대 금액을 설정합니다. 한도를 초과하면 400 max_cost_exceeded 오류가 반환되고 요금은 청구되지 않습니다. 접수된 작업도 이 한도를 초과하는 용량으로 전환되지 않습니다.
const resp = await fetch("https://cheapergen.com/api/v1/run/bytedance/seedance-2.0-fast/text-to-video", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CHEAPERGEN_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "prompt": "골든아워에 꽃병을 빚는 도예가에게 천천히 다가가는 카메라, 빛 속 먼지 입자, 얕은 심도",
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "duration": 5
  }),
});
const generation = await resp.json();
응답 · 202 Accepted
{
  "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"
  }
}

오류: 400 invalid_request(검증), 401 unauthorized, 402 insufficient_balance, 404 not_found(알 수 없는 엔드포인트), 429 rate_limited(요청 빈도, 또는 대기 중인 생성 대기열이 가득 참), 503 model_unavailable, 503 pricing_unavailable(잠시 후 재시도하세요. 요금이 청구되지 않았습니다), 503 fallback_price_declined(비상 가격만 이용할 수 있는데 allow_fallback_price: false을(를) 전송함), 400 max_cost_exceeded.

생성 결과 가져오기#

GET/api/v1/generations/{id}API 키 필요

ID로 생성 작업을 조회합니다. 상태 확인 시점이 되면 응답 전에 확인을 수행하므로 이 엔드포인트를 폴링하는 것만으로 작업을 완료 상태까지 진행할 수 있습니다. 알 수 없는 ID나 다른 계정의 생성 요청에는 404 not_found 응답을 반환합니다.

요청
curl https://cheapergen.com/api/v1/generations/gen_8c2QmX1nq0k4Lw7Z \
  -H "Authorization: Bearer $CHEAPERGEN_API_KEY"
응답 · 200 OK
{
  "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": "succeeded",
  "input": {
    "prompt": "골든아워에 꽃병을 빚는 도예가에게 천천히 다가가는 카메라, 빛 속 먼지 입자, 얕은 심도",
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "duration": 5,
    "generate_audio": true
  },
  "output": {
    "video": {
      "url": "https://cdn.cheapergen.com/outputs/gen_8c2QmX1nq0k4Lw7Z.mp4",
      "content_type": "video/mp4"
    }
  },
  "error": null,
  "cost": {
    "amount_usd": 0.4494,
    "currency": "usd",
    "estimated": false
  },
  "source": "api",
  "created_at": "2026-10-15T09:21:04.512Z",
  "started_at": "2026-10-15T09:21:09.031Z",
  "completed_at": "2026-10-15T09:22:31.870Z",
  "retention": "1d",
  "expires_at": "2026-10-16T09:22:31.870Z",
  "purged_at": null
}

생성 내역 목록#

GET/api/v1/generationsAPI 키 필요

내 생성 내역을 최신순으로 나열합니다. Studio 및 플레이그라운드에서 제출한 작업도 포함됩니다.

쿼리 매개변수
limitinteger
페이지 크기, 1–100. 기본값 20.
cursorstring
이전 페이지의 next_cursor.
statusstring
다음 상태만 조회합니다: queued, running, succeeded, failed 또는 canceled.
modelstring
모델 ID, 예: bytedance/seedance-2.0-fast.
sourcestring
playground (Studio 및 모델 페이지), api 또는 mcp (AI 에이전트)에서 생성한 항목만 조회합니다.
요청
curl "https://cheapergen.com/api/v1/generations?limit=2&status=succeeded" \
  -H "Authorization: Bearer $CHEAPERGEN_API_KEY"
응답 · 200 OK
{
  "object": "list",
  "data": [
    {
      "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": "succeeded",
      "input": {
        "prompt": "골든아워에 꽃병을 빚는 도예가에게 천천히 다가가는 카메라, 빛 속 먼지 입자, 얕은 심도",
        "aspect_ratio": "16:9",
        "resolution": "720p",
        "duration": 5,
        "generate_audio": true
      },
      "output": {
        "video": {
          "url": "https://cdn.cheapergen.com/outputs/gen_8c2QmX1nq0k4Lw7Z.mp4",
          "content_type": "video/mp4"
        }
      },
      "error": null,
      "cost": {
        "amount_usd": 0.4494,
        "currency": "usd",
        "estimated": false
      },
      "source": "api",
      "created_at": "2026-10-15T09:21:04.512Z",
      "started_at": "2026-10-15T09:21:09.031Z",
      "completed_at": "2026-10-15T09:22:31.870Z",
      "retention": "1d",
      "expires_at": "2026-10-16T09:22:31.870Z",
      "purged_at": null
    },
    {
      "id": "gen_3vYk2PqL9sTn0bWd",
      "object": "generation",
      "model": "bytedance/seedream-5.0-pro",
      "endpoint": "bytedance/seedream-5.0-pro/text-to-image",
      "mode": "text-to-image",
      "status": "succeeded",
      "input": {
        "prompt": "트라버틴 위 무광 검정 에스프레소 머신 제품 사진, 부드러운 창가 빛, 85mm 렌즈",
        "aspect_ratio": "1:1",
        "size": "2K"
      },
      "output": {
        "images": [
          {
            "url": "https://cdn.cheapergen.com/outputs/gen_8c2QmX1nq0k4Lw7Z.png",
            "content_type": "image/png"
          }
        ]
      },
      "error": null,
      "cost": {
        "amount_usd": 0.0665,
        "currency": "usd",
        "estimated": false
      },
      "source": "api",
      "created_at": "2026-10-15T09:21:04.512Z",
      "started_at": "2026-10-15T09:21:09.031Z",
      "completed_at": "2026-10-15T09:22:31.870Z",
      "retention": "1d",
      "expires_at": "2026-10-16T09:22:31.870Z",
      "purged_at": null
    }
  ],
  "next_cursor": "gen_3vYk2PqL9sTn0bWd"
}

마지막 페이지에서는 next_cursor 값이 null입니다.

생성 취소#

POST/api/v1/generations/{id}/cancelAPI 키 필요

아직 queued 상태인 생성을 취소하고 보류 금액을 전액 환불합니다. 업데이트된 생성 객체와 status: "canceled"을 반환합니다. 이미 실행 중이거나 완료된 생성, 또는 대기 작업 취소를 지원하지 않는 모델에는 409 conflict를 반환합니다.

요청
curl -X POST https://cheapergen.com/api/v1/generations/gen_8c2QmX1nq0k4Lw7Z/cancel \
  -H "Authorization: Bearer $CHEAPERGEN_API_KEY"
응답 · 200 OK
{
  "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": "canceled",
  "input": {
    "prompt": "골든아워에 꽃병을 빚는 도예가에게 천천히 다가가는 카메라, 빛 속 먼지 입자, 얕은 심도",
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "duration": 5,
    "generate_audio": true
  },
  "output": null,
  "error": null,
  "cost": {
    "amount_usd": 0,
    "currency": "usd",
    "estimated": false
  },
  "source": "api",
  "created_at": "2026-10-15T09:21:04.512Z",
  "started_at": null,
  "completed_at": "2026-10-15T09:21:06.200Z",
  "retention": "1d",
  "expires_at": "2026-10-16T09:21:06.200Z",
  "purged_at": null
}

생성 삭제#

DELETE/api/v1/generations/{id}API 키 필요

생성을 삭제합니다. 결과 파일, 다른 생성에서 사용하지 않는 업로드 입력 파일, 프롬프트와 입력값을 즉시 삭제하고 목록에서도 제거하며 GET이 404을 반환합니다. 결제 기록(원장 청구 내역과 사용량)은 보존됩니다. 아직 queued 상태인 생성은 먼저 취소되고 보류된 금액이 전액 환불됩니다. 더 이상 취소할 수 없으면(실행 중이거나 모델이 대기 중인 작업의 취소를 지원하지 않는 경우) 409 conflict를 반환하니 완료될 때까지 기다리세요.

요청
curl -X DELETE https://cheapergen.com/api/v1/generations/gen_8c2QmX1nq0k4Lw7Z \
  -H "Authorization: Bearer $CHEAPERGEN_API_KEY"
응답 · 200 OK
{
  "id": "gen_8c2QmX1nq0k4Lw7Z",
  "object": "generation",
  "deleted": true
}

생성 객체#

idstring
gen_ 접두사가 붙는 고유 ID입니다.
objectstring
항상 "generation"입니다.
modelstring
모델 ID, 예: bytedance/seedance-2.0-fast.
endpointstring
작업을 제출한 엔드포인트 ID, 예: bytedance/seedance-2.0-fast/text-to-video.
modestring
작업: text-to-video, image-to-video, reference-to-video, text-to-image 또는 image-edit.
statusstring
queued → running → succeeded | failed 또는 canceled. 자세한 내용: 생성 내역.
inputobject
The validated input, with defaults filled in.
outputobject | null
성공한 경우 설정됩니다. 동영상: { "video": { "url", "content_type" } }. 이미지: { "images": [{ "url", "content_type" }] }. 안전 검사기가 대체해 빈 이미지가 반환된 경우에도 "safety_filtered": true가 설정되며, 다른 결과와 동일한 요금이 청구됩니다.
errorobject | null
실패 시 { "code", "message", "reason", "hint", "retryable", "refunded" } 값이 설정됩니다. 확인된 경우 param에는 변경할 필드, detail에는 제공자가 반환한 문구가 포함됩니다. 실패 이유는 reason에 기록됩니다. 예: content_blocked, invalid_input, upstream_unavailable. 자세한 내용: 실패 이유.
costobject
amount_usd, currency ("usd") 및 estimated — 보류 중에는 true, 확정 후에는 false. 실패하거나 취소된 생성의 비용은 0입니다.
pricingobject
custom_price(나만의 가격: 계약 가격 또는 Pro 또는 Max 요금제), volume_level(요금제가 가격을 정한 경우 Pro는 1, Max는 2, 그 외에는 null), standard_usd(이 요청의 일반 가격), 그리고 fallback: null. 긴급 가격으로 처리된 경우에는 { "active", "reason", "message", "standard_usd", "amount_usd" }을 반환합니다. 긴급 가격은 allow_fallback_price에 따라 정해지고 max_cost_usd를 넘을 수 없으며 공식 가격 이하입니다.
sourcestring
"api" 또는 "playground" (Studio 및 모델 페이지).
created_atstring
ISO 8601 timestamp of submission.
started_atstring | null
When the model started generating.
completed_atstring | null
When the generation reached a final state.
retentionstring | null
API 생성 작업의 보관 기간 옵션은 immediate, 1h, 1d, 7d 또는 30d입니다. Studio 생성 작업은 null로 표시되며, 사용자가 삭제할 때까지 보관됩니다.
expires_atstring | null
프롬프트, 입력, 출력, 미디어가 삭제되는 시점입니다. 생성이 완료되면 설정됩니다. 보관 기간에 immediate 옵션을 지정하면 결과가 처음 전달된 뒤 10분 후에 삭제됩니다.
purged_atstring | null
삭제된 시점에 설정됩니다. 이후 output은 null이 되고, input에는 가격에 영향을 주는 매개변수만 남으며 content_expired에 삭제 이유가 기록됩니다. 비용과 타임스탬프는 유지됩니다.
urlsobject
제출 응답에만 포함됩니다. 이 생성에 사용할 get 및 cancel URL입니다.

모델 목록#

GET/api/v1/models공개 · 인증 불필요

사용 가능한 모든 모델과 엔드포인트, 실시간 가격을 반환합니다. 가격은 unit당(second 동영상 출력 또는 image)입니다. list_price_usd은(는) 비교 기준 정가이고 discount_pct는 절감률입니다.list_price_source에서 가격 기준을 확인할 수 있습니다. official은(는) 개발사의 자체 정가, reference은(는) list_price_label이(가) 명시한 다른 가격입니다. 예를 들어 개발사가 국제 API를 판매하지 않는 모델의 fal API 가격이 이에 해당합니다.

요청
curl https://cheapergen.com/api/v1/models
응답 · 200 OK
{
  "object": "list",
  "data": [
    {
      "id": "bytedance/seedance-2.0-fast",
      "object": "model",
      "name": "Seedance 2.0 Fast",
      "vendor": "ByteDance",
      "category": "video",
      "available": true,
      "url": "https://cheapergen.com/models/bytedance/seedance-2.0-fast",
      "endpoints": [
        {
          "id": "bytedance/seedance-2.0-fast/text-to-video",
          "mode": "text-to-video",
          "output": "video"
        },
        {
          "id": "bytedance/seedance-2.0-fast/image-to-video",
          "mode": "image-to-video",
          "output": "video"
        },
        {
          "id": "bytedance/seedance-2.0-fast/reference-to-video",
          "mode": "reference-to-video",
          "output": "video"
        }
      ],
      "pricing": {
        "unit": "second",
        "list_price_source": "official",
        "list_price_label": "Official",
        "tiers": [
          {
            "tier": "480p",
            "price_usd": 0.050086,
            "list_price_usd": 0.056246,
            "discount_pct": 11
          },
          {
            "tier": "720p",
            "price_usd": 0.08988,
            "list_price_usd": 0.12096,
            "discount_pct": 26
          }
        ]
      },
      "deprecation": null,
      "upcoming_price_changes": []
    }
  ]
}

간결한 설명을 위해 모델 하나만 표시합니다.

모델 정보 가져오기#

GET/api/v1/models/{vendor}/{model}공개 · 인증 불필요

모델 정보와 각 엔드포인트 입력에 사용할 JSON Schema를 반환합니다. 폼을 만들거나 요청 전 유효성을 검사할 때 유용합니다. 알 수 없는 모델 요청에는 404 not_found 오류를 반환합니다.

요청
curl https://cheapergen.com/api/v1/models/bytedance/seedream-5.0-pro
응답 · 200 OK
{
  "id": "bytedance/seedream-5.0-pro",
  "object": "model",
  "name": "Seedream 5.0 Pro",
  "vendor": "ByteDance",
  "category": "image",
  "available": true,
  "description": "ByteDance Seedream 5.0 Pro는 정교한 다중 이미지 편집과 정확한 텍스트 렌더링으로 브랜드에 어울리는 사실적 이미지를 최대 2K로 생성하고 편집합니다.",
  "url": "https://cheapergen.com/models/bytedance/seedream-5.0-pro",
  "endpoints": [
    {
      "id": "bytedance/seedream-5.0-pro/text-to-image",
      "mode": "text-to-image",
      "label": "텍스트 → 이미지",
      "output": "image",
      "input_schema": {
        "type": "object",
        "required": [
          "prompt"
        ],
        "properties": {
          "prompt": {
            "title": "프롬프트",
            "description": "피사체, 동작, 카메라 움직임, 조명, 스타일을 설명하세요.",
            "type": "string",
            "maxLength": 5000
          },
          "aspect_ratio": {
            "title": "화면 비율",
            "description": "출력 이미지 비율입니다.",
            "type": "string",
            "enum": [
              "1:1",
              "4:3",
              "3:4",
              "16:9",
              "9:16",
              "3:2",
              "2:3",
              "21:9"
            ],
            "default": "1:1"
          },
          "size": {
            "title": "크기",
            "description": "1K ≈ 1메가픽셀, 2K ≈ 4메가픽셀",
            "type": "string",
            "enum": [
              "1K",
              "2K"
            ],
            "default": "2K"
          },
          "seed": {
            "title": "시드",
            "description": "같은 시드와 설정을 사용하면 결과를 재현할 수 있습니다. 비워 두면 무작위로 설정됩니다.",
            "type": "integer",
            "minimum": 0,
            "maximum": 2147483647
          },
          "webhook_url": {
            "type": "string",
            "format": "uri",
            "title": "Webhook URL",
            "description": "Optional. We POST the finished generation here (signed)."
          }
        },
        "additionalProperties": false
      }
    }
  ],
  "pricing": {
    "unit": "image",
    "notes": [],
    "list_price_source": "official",
    "list_price_label": "Official",
    "tiers": [
      {
        "tier": "1K",
        "detail": "≈1 MP",
        "price_usd": 0.03325,
        "list_price_usd": 0.045,
        "discount_pct": 26
      },
      {
        "tier": "2K",
        "detail": "≈4 MP",
        "price_usd": 0.0665,
        "list_price_usd": 0.09,
        "discount_pct": 26
      }
    ]
  },
  "deprecation": null,
  "upcoming_price_changes": []
}

간결한 설명을 위해 엔드포인트 하나만 표시합니다.

서비스 종료 및 가격 변경#

가격 인상과 모델 종료는 사전에 안내합니다. 가격 인상은 최소 14일 전에 (계약에 따라 더 일찍) 이메일로 알리고, 모델 종료는 최근 90일 동안 해당 모델을 사용한 모든 고객에게 14–30일 전에 이메일과 변경 내역 (RSS)로 안내합니다. API에서도 같은 정보를 제공하므로 코드와 에이전트가 대응할 수 있습니다:

deprecationobject | null
모델 목록 및 모델 정보 가져오기에서 확인할 수 있습니다. 모델 종료가 예정되면 다음 값을 설정합니다: sunset_at(ISO 8601; 해당 시점 이후 요청에는 410 model_delisted 응답이 반환되고 요금은 청구되지 않음), replacement(추천 모델 ID, 우선순위 순), reason, announced_at, info_url. 그 외에는 null입니다.
upcoming_price_changesarray
적용 전인 단계별 가격 변경 일정: tier, effective_at, current_price_usd, 새 가격 price_usd/unit. effective_at 이전에 요청하면 현재 가격이 적용되며, 제출 후 생성 요금은 다시 계산되지 않습니다. 예약된 변경이 없으면 비어 있습니다.
warningsarray
생성 요청 제출 및 견적 조회 응답에는 확인할 정보가 있을 때만 다음 내용이 포함됩니다: model_deprecated(sunset_at 및 replacement 포함) 또는 요청 단계의 price_change_scheduled(effective_at 및 새 가격 price_usd 포함). 각 항목에는 사람이 읽을 수 있는 message와 info_url가 포함됩니다.
요청
curl https://cheapergen.com/api/v1/models/bytedance/seedance-2.0-fast
응답 · 200 OK
{
  "id": "bytedance/seedance-2.0-fast",
  "object": "model",
  "…": "…",
  "deprecation": {
    "sunset_at": "2026-11-20T00:00:00.000Z",
    "replacement": [
      "bytedance/seedance-2.0-fast"
    ],
    "reason": "개발자가 이 모델을 서비스 종료할 예정입니다.",
    "announced_at": "2026-10-21T09:30:00.000Z",
    "info_url": "https://cheapergen.com/changelog#cm2x7k9"
  },
  "upcoming_price_changes": [
    {
      "tier": "720p",
      "effective_at": "2026-11-04T00:00:00.000Z",
      "unit": "second",
      "current_price_usd": 0.08,
      "price_usd": 0.092,
      "change_pct": 15,
      "info_url": "https://cheapergen.com/changelog#cm2x8a1"
    }
  ]
}

서비스 종료 및 Sunset 헤더#

모델 종료가 예정되어 있으면 해당 모델에 대한 응답에 POST /run, POST /quote, GET /models/{vendor}/{model}가 포함됩니다. 표준 헤더를 사용하므로 HTTP 클라이언트와 API 게이트웨이에서 기록하거나 알림을 설정할 수 있습니다:

응답 헤더
Deprecation: @1792575000
Sunset: Fri, 20 Nov 2026 00:00:00 GMT
Link: <https://cheapergen.com/changelog#cm2x7k9>; rel="deprecation"; type="text/html", <https://cheapergen.com/changelog#cm2x7k9>; rel="sunset"; type="text/html"

Deprecation (RFC 9745)은 종료가 공지된 시점의 Unix 타임스탬프이고, Sunset (RFC 8594)는 요청 처리가 중단되는 시점입니다. 모델 전환은 한 줄만 바꾸면 됩니다. 동일한 요청을 대체 모델의 엔드포인트로 보내세요 (옵션 차이는 입력 스키마에서 확인).

MCP에서는 list_models 및 get_model에 동일한 deprecation, upcoming_price_changes 필드와 한 줄 notice 설명이 포함되어 모델이 종료될 예정일 때 에이전트가 사용자에게 미리 알릴 수 있습니다.

견적 조회#

POST/api/v1/quote/{endpoint}공개 · 인증 불필요

실행하지 않고 입력 가격을 계산합니다. 가격에 영향을 주는 필드(해상도, 길이, 크기, 이미지 수 등)만 읽고 콘텐츠 필드인 prompt 및 참조 URL은 무시합니다. 생략한 필드에는 기본값이 적용됩니다. 모델이 일시적으로 새 생성 요청을 받지 않을 때 available 값은 false입니다.

참조 동영상은 과금 대상 초에 포함됩니다. 사용하려면 reference_video_durations (초 단위, 클립당 숫자 하나)을 입력하세요. 이는 추정값이며 /run이 실제 파일을 측정하고 해당 가격을 보류합니다. 자세한 내용: 결제 및 청구.

요청
curl -X POST https://cheapergen.com/api/v1/quote/bytedance/seedance-2.0-fast/text-to-video \
  -H "Content-Type: application/json" \
  -d '{"aspect_ratio":"16:9","resolution":"720p","duration":5}'
응답 · 200 OK
{
  "amount_usd": 0.4494,
  "list_usd": 0.6048,
  "list_price_source": "official",
  "list_price_label": "Official",
  "discount_pct": 26,
  "available": true,
  "currency": "usd"
}

자신에게 적용되는 가격을 확인하려면 API 키를 보내세요. 계정에 계약 가격이나 Pro 또는 Max 요금제이 적용되는 경우, 견적에는 일반 가격인 custom_price: true 및 standard_amount_usd도 포함됩니다. volume_level(1 또는 2)는 Pro 요금제가 가격을 정하면 1, Max 요금제가 정하면 2로 표시됩니다.

계정 정보 가져오기#

GET/api/v1/accountAPI 키 필요

잔액과 자동 충전 설정을 반환합니다. balance_usd은 지금 사용할 수 있는 잔액이고, image_credit_usd은 이미지 모델에 먼저 적용되는 이미지 전용 크레딧(예: 가입 환영 크레딧)으로 동영상에는 사용할 수 없습니다. reserved_usd는 진행 중인 생성 작업 때문에 잔액에서 보류된 금액입니다. 자세한 내용은 결제 및 크레딧을 참조하세요.

요청
curl https://cheapergen.com/api/v1/account \
  -H "Authorization: Bearer $CHEAPERGEN_API_KEY"
응답 · 200 OK
{
  "object": "account",
  "email": "you@company.com",
  "balance_usd": 42.5,
  "image_credit_usd": 0,
  "reserved_usd": 1.2,
  "auto_topup": {
    "enabled": true,
    "threshold_usd": 10,
    "amount_usd": 50
  },
  "limits": {
    "unlimited": false,
    "concurrent_generations": 20,
    "in_flight": 3,
    "requests_per_second": 10,
    "burst": 20,
    "tier": null
  }
}

limits은(는) 계정의 API 한도와 진행 중인 생성 수입니다. 한도가 없는 계정은 각 한도가 null이며 unlimited: true이(가) 함께 표시됩니다. 요청 제한을(를) 참고하세요.

내 가격 확인하기#

GET/api/v1/account/pricingAPI 키 필요

월간 요금제와 요금제가 제공하는 이용량 구간, 각 단계에서 적용되는 나만의 가격과 일반 가격을 반환합니다. 모델 하나에 대한 요금제는 ?model={vendor}/{model}을 추가하세요. 종량제 이용에는 요금제가 필요하지 않습니다. 이 경우 plan은 null, custom은 false입니다. 자세한 내용은 월간 요금제을 참조하세요.

customboolean
Pro 또는 Max 요금제나 계약 가격으로 가격이 낮아지는 경우 true
planobject | null
현재 월간 요금제: { "id", "status" }. 예: pro 및 active(starter, pro 또는 max). 요금제가 없으면 null입니다.
volumeobject
level: Pro가 활성 상태이면 1, Max가 활성 상태이면 2, 그 외에는 null입니다.
rulesarray
현재 적용 중이거나 예정된 계약 가격: scope, status, discount_pct 또는 unit_price_usd, starts_at, ends_at; 알아보기 쉬운 형식은 description입니다.
modelsarray
요금제 또는 규칙이 적용되는 모든 모델: id, name, unit 및 tiers — 각각에 대해 price_usd(회원님 가격), standard_price_usd, custom, volume_level(요금제가 가격을 정한 경우) 및 available이 표시됩니다.
요청
curl "https://cheapergen.com/api/v1/account/pricing?model=bytedance/seedance-2.0-fast" \
  -H "Authorization: Bearer $CHEAPERGEN_API_KEY"
응답 · 200 OK
{
  "object": "customer_pricing",
  "custom": true,
  "plan": {
    "id": "pro",
    "status": "active"
  },
  "volume": {
    "level": 1
  },
  "rules": [],
  "models": [
    {
      "id": "bytedance/seedance-2.0-fast",
      "name": "Seedance 2.0 Fast",
      "unit": "second",
      "tiers": [
        "…"
      ]
    }
  ]
}

파일 업로드#

POST/api/v1/uploadsAPI 키 필요

첫 프레임, 참조 이미지, 참조 동영상 또는 참조 오디오 클립처럼 입력 URL로 사용할 파일을 업로드합니다. 파일을 업로드하는 대신 공개 HTTPS URL을 직접 전달해도 됩니다.

종류형식최대 크기
이미지PNG, JPEG, WebP, GIF20 MB
동영상MP4, MOV50 MB
오디오MP3, WAV, M4A(현재 모델은 MP3 또는 WAV 지원)15 MB

직접 업로드(권장)#

파일의 filename, content_type, size를 JSON으로 보내세요(크기는 바이트 단위). 만료 시간이 짧은 upload_url을 받으면 응답에 포함된 headers 값을 그대로 사용해 원본 바이트를 PUT하세요. 그다음 입력값으로 url을 사용합니다. 파일은 스토리지에 직접 업로드되므로 위 제한 외에 요청 크기 제한은 없습니다. 업로드 URL은 15분 후 만료됩니다. size는 파일의 정확한 바이트 크기여야 합니다. PUT할 때 정확히 그만큼의 바이트를 Content-Length와 함께 보내세요(chunked나 스트리밍 본문은 사용할 수 없음). 그 밖의 요청은 스토리지가 403으로 거부합니다.

요청
curl -X POST https://cheapergen.com/api/v1/uploads \
  -H "Authorization: Bearer $CHEAPERGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename":"choreo.mp4","content_type":"video/mp4","size":8421903}'
응답 · 201 Created
{
  "object": "upload",
  "method": "PUT",
  "upload_url": "https://storage.example.com/media/uploads/7f3k2m9q/0b8d2c5e1a7f4h6j9k3m.mp4?X-Amz-Algorithm=AWS4-HMAC-SHA256&…",
  "headers": {
    "Content-Type": "video/mp4"
  },
  "url": "https://cdn.cheapergen.com/uploads/7f3k2m9q/0b8d2c5e1a7f4h6j9k3m.mp4",
  "kind": "video",
  "content_type": "video/mp4",
  "bytes": 8421903,
  "expires_at": "2026-10-15T09:36:04.000Z"
}
그런 다음 파일 데이터를 업로드하세요.
curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: video/mp4" \
  --data-binary @choreo.mp4

Multipart 업로드#

대신 multipart/form-data 형식의 요청에 file 필드를 넣어 보내면 파일을 저장해 드립니다(201 Created 응답과 url 반환). 이 방식은 파일 바이트를 API를 통해 전달하므로 요청 본문 크기가 약 4.5 MB로 제한됩니다. 더 큰 파일은 직접 업로드하세요. 배포 환경에서 직접 업로드를 지원하지 않으면 JSON 요청에 501 direct_upload_unavailable가 반환되므로 multipart 형식으로 업로드하세요.

요청
curl -X POST https://cheapergen.com/api/v1/uploads \
  -H "Authorization: Bearer $CHEAPERGEN_API_KEY" \
  -F "file=@first-frame.png"
응답 · 201 Created
{
  "object": "upload",
  "url": "https://cdn.cheapergen.com/uploads/7f3k2m9q/0b8d2c5e1a7f4h6j9k3m.png",
  "kind": "image",
  "content_type": "image/png",
  "bytes": 1834221
}

업로드한 이미지 사용#

이미지에서 동영상 만들기 또는 편집 엔드포인트의 image 필드에 반환된 URL을 전달하세요:

curl -X POST https://cheapergen.com/api/v1/run/bytedance/seedance-2.0-fast/image-to-video \
  -H "Authorization: Bearer $CHEAPERGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "prompt": "그녀가 돌아서 미소 짓고 바람에 머리카락이 흩날리는 동안 카메라가 다가갑니다.",
  "image_url": "https://cdn.cheapergen.com/uploads/7f3k2m9q/0b8d2c5e1a7f4h6j9k3m.png",
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "duration": 5
}'

모델별 참조 정보

모든 모델의 API 페이지에는 필드별 자료형, 기본값, 허용값과 복사해 사용할 수 있는 예제가 있습니다. 모델 목록에서 시작하세요.

궁금한 점이나 빠진 내용이 있나요? support@cheapergen.com로 이메일을 보내 주세요. 모든 의견을 읽고 있습니다.