Generor API 문서

GET /generators

사용 가능한 모든 생성기를 표시합니다.

curl https://generor.com/api/v1/generators

쿼리 매개변수: status (active, development, all)

응답: 슬러그, 제목, 설명, 아이콘 및 유사 생성기를 포함한 생성기 배열.

GET /generators/{slug}

특정 생성기에 대한 자세한 정보를 가져옵니다.

curl https://generor.com/api/v1/generators/image

POST /generators/{slug}/estimate

/generate를 호출하기 이전에 크레딧 비용과 예상 생성 시간을 미리 확인하세요. /generate와 동일한 본문 형식이지만 읽기 전용입니다: 크레딧이 청구되지 않고 작품이 작성되지 않습니다. 이는 UI에서 생성 버튼 옆에 표시되는 것과 정확히 같은 숫자입니다.

curl -X POST https://generor.com/api/v1/generators/horoscope/estimate \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": 37,
    "count": 5,
    "parameters": {
      "zodiac-sign": "aries",
      "horoscope-length": "long"
    }
  }'

응답:

{
  "success": true,
  "data": {
    "generator": "horoscope",
    "model_id": 37,
    "model_type": "text",
    "model_name": "Gemini 3.5 Flash",
    "credit_cost": {
      "total": 15,             // after bulk discount
      "per_item": 3,           // model base × length/quality multipliers
      "count": 5,
      "discount": 0,           // credits saved
      "discount_percent": 5    // % off applied (count% off, capped at 10%)
    },
    "time_estimate": {
      "seconds": 50,           // total wall-clock estimate
      "per_item": 10,
      "min_seconds": 8,
      "max_seconds": 14,
      "sample_count": 10,      // recent generations averaged
      "has_historical": true,
      "source": "historical"   // or "fallback" when sample_count < 3
    },
    "applied_parameters": {    // what the API actually used (schema-filtered)
      "zodiac-sign": "aries",
      "horoscope-length": "long",
      "model-text": "3",
      "horoscope-count": "5"
    }
  }
}

인증되지 않은 호출자에게 공개됩니다 — 가격/시간 정보는 공개 정보이며 공개 생성기 페이지에 표시되는 내용과 일치합니다.

스냅된 영상 길이

모델의 supported_durations에 없는 seconds 값을 전달하면, API는 가장 가까운 지원 값으로 맞추고(동일한 경우 더 낮은 값으로) 변경 사항을 adjustments 블록에 표시합니다. 동일한 응답의 크레딧 비용과 시간 추정치는 원래 요청이 아니라 맞춰진 값 — /generate가 실제로 수행할 값 — 을 반영합니다.

{
  "success": true,
  "data": {
    "credit_cost": { "total": 30, ... },
    "time_estimate": { "seconds": 60, ... },
    "adjustments": {
      "seconds": {
        "requested": 3,
        "used": 5,
        "supported": [5, 6, 7, 8, 10, 12, 15],
        "reason": "snapped to nearest provider-supported duration"
      }
    }
  }
}

사용 시점

• 사전 비용 확인 — 요금을 청구하기 전에 사용자가 생성 비용을 감당할 수 있는지 확인하세요.
• 진행 상황 UI — time_estimate.seconds를 로딩 바에 입력하여 사용자가 얼마나 기다려야 하는지 알 수 있도록 하세요.
• 매개변수 조정 — 사용자가 드롭다운을 변경할 때마다 호출하세요. 생성을 확정하지 않고도 비용이 업데이트됩니다.

/generate와의 관계 — /estimate는 별도, 선택 사항 호출입니다. /generate는 이미 청구된 실제 credit_cost와 사후 credits_remaining을 반환하므로, 실시간 가격을 그대로 지불해도 괜찮다면 /estimate를 완전히 건너뛸 수 있습니다.

Use the Generor API at https://generor.com/api/v1.

Before calling POST /generators/{slug}/generate, call
POST /generators/{slug}/estimate with the same body to get back:
  - credit_cost.total (credits the next generate call will charge)
  - time_estimate.seconds (expected wall-clock duration)

Show both to the user, then call /generate when they confirm.
The /generate response includes the real credit_cost charged and
credits_remaining — use those to update the user's balance.

Discover each generator's tweakable fields with GET /generators/{slug}
and pass them under the `parameters` object on both /estimate and
/generate (keys match the dropdown IDs you see on the public page).

POST /generators/{slug}/generate AUTH

AI로 콘텐츠를 생성하세요. 이것은 동기식 호출입니다 — 생성이 완료되면 응답이 반환됩니다. 선택한 모델에 따라 크레딧이 소모됩니다. 텍스트 생성은 일반적으로 5~30초, 이미지 생성은 10~60초가 걸리며, 동영상 생성은 몇 분이 걸릴 수 있습니다.

# Text generation (joke with GPT 5 Nano)
curl -X POST https://generor.com/api/v1/generators/joke/generate \
  -H "Authorization: Bearer gnr_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Tell me a joke about programming",
    "model_id": 37
  }'

# Image generation (Flux Schnell, square)
curl -X POST https://generor.com/api/v1/generators/image/generate \
  -H "Authorization: Bearer gnr_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A sunset over mountains",
    "model_id": 10003,
    "aspect_ratio": 1
  }'

# Image description (vision — Qwen VL Max, image-only input, prompt is optional)
curl -X POST https://generor.com/api/v1/generators/vision/generate \
  -H "Authorization: Bearer gnr_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": 34,
    "image_url": "https://example.com/photo.jpg",
    "preference": "detailed"
  }'

# Video generation (Happy Horse 1.0 R2V — multi-reference, 6s, wide)
curl -X POST https://generor.com/api/v1/generators/video/generate \
  -H "Authorization: Bearer gnr_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "The character from [Image1] walks through the forest from [Image2]",
    "model_id": 20050,
    "aspect_ratio": "16:9",
    "seconds": 6,
    "reference_images": [
      "https://example.com/character.jpg",
      "https://example.com/forest.jpg"
    ]
  }'

# Video generation (Happy Horse Video Edit — natural-language edit of an existing clip)
curl -X POST https://generor.com/api/v1/generators/video/generate \
  -H "Authorization: Bearer gnr_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Replace the sky with a stormy sunset",
    "model_id": 20051,
    "video_url": "https://example.com/source.mp4",
    "seconds": 5
  }'

요청 본문:

생성기 매개변수

각 생성기의 조정 가능한 전체 필드 모음은 생성기별 스키마에 들어 있습니다(사이트 드롭다운 및 URL 사전 입력이 사용하는 동일한 소스). 생성 요청의 parameters 객체에 이러한 필드 중 아무거나 전달하여 프로그래밍 방식으로 제어할 수 있습니다.

GET /generators/{slug}에서 모든 생성기의 스키마를 가져옵니다 — 응답의 parameters 배열은 각 필드를 id, type(enum, number 또는 model), options(또는 min/max), default, cost_multipliers와 함께 나열합니다.

# 1) Discover the parameters for the horoscope generator
curl https://generor.com/api/v1/generators/horoscope

# 2) Pass them on the generate call
curl -X POST https://generor.com/api/v1/generators/horoscope/generate \
  -H "Authorization: Bearer gnr_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Aries weekly reading",
    "model_id": 37,
    "parameters": {
      "zodiac-sign": "aries",
      "horoscope-timeframe": "weekly",
      "horoscope-tone": "mystical",
      "horoscope-length": "long",
      "horoscope-focus": "career"
    }
  }'

# Image example — every dropdown in the UI is a key here
curl -X POST https://generor.com/api/v1/generators/wallart/generate \
  -H "Authorization: Bearer gnr_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Calm mountain lake at dawn",
    "model_id": 10003,
    "parameters": {
      "wallart-type": "framed-print",
      "wallart-orientation": "landscape",
      "image-aspect-ratio": "4"
    }
  }'

추가 텍스트 생성 필드

텍스트 생성기(model_id 1-9999)의 경우, 관련이 있을 때 다음 최상위 본문 필드가 LLM 엔드포인트로 전달됩니다:

응답 (201 Created) — 텍스트 제너레이터 예시:

{
  "success": true,
  "data": {
    "generator": "joke",
    "model_id": 37,
    "model_type": "text",
    "model_name": "Gemini 3.5 Flash",
    "creations": [
      {
        "creation_id": 6144,
        "text": "Why do programmers prefer dark mode? Because light attracts bugs!",
        "illustration_desc": "a minimalist bug icon on a dark background"
      }
    ],
    "credit_cost": 1,
    "credit_cost_estimated": 1,
    "credits_remaining": 36024,
    "time_taken_seconds": 4.18
  }
}

응답 (201 Created) — 이미지 제너레이터 예시:

{
  "success": true,
  "data": {
    "generator": "image",
    "model_id": 10003,
    "model_type": "image",
    "model_name": "black-forest-labs/flux-schnell",
    "creations": [
      {
        "creation_id": 6147,
        "image_url": "https://generor.com/users/2/img/image-6147.webp"
      }
    ],
    "credit_cost": 24,
    "credit_cost_estimated": 6,
    "credits_remaining": 35998,
    "time_taken_seconds": 23.7
  }
}

스냅된 영상 길이 — 호출자의 seconds가 모델의 supported_durations에 없는 경우, API는 제공자를 호출하기 전에 가장 가까운 지원 값으로 맞추고 /estimate의 것과 동일한 형태의 adjustments.seconds 블록을 응답에 추가합니다. 이는 제공자가 지원되지 않는 값을 조용히 기본값으로 처리하는 것을 방지합니다.

비용 필드 작동 방식

• credit_cost — balance_before − balance_after로 계산된 실제 차감 금액. 이것이 신뢰할 수 있는 기준입니다. 로깅, 청구, 사용자 잔액 업데이트에 사용하세요.
• credit_cost_estimated — 사전 카탈로그 추정치(/estimate가 예측했을 동일한 수치). 투명성과 편차 모니터링을 위해 포함됩니다. 실제 요금이 제공자 호출 내부에서 계산되는 동영상 / 초당 / 문자당 가격 책정의 경우 credit_cost와 다른 경우가 많습니다.
• time_taken_seconds — 실제 경과 시간입니다. /estimate의 time_estimate.seconds과 비교하여 과거 시간 예측을 검증하세요.

GET /creations AUTH

내 창작물 목록을 표시합니다.

curl https://generor.com/api/v1/creations \
  -H "Authorization: Bearer gnr_live_..."

쿼리 매개변수: generator (슬러그로 필터링), page, per_page, sort

GET /creations/{id}

전체 세부 정보, 이미지, 생성기별 데이터를 포함한 단일 창작물을 가져옵니다.

curl https://generor.com/api/v1/creations/12345

창작물 소유자로 인증하거나, 해당 창작물이 공유된 팀의 멤버여야 합니다.

응답에 포함되는 항목:

{
  "success": true,
  "data": {
    "creation_id": 12345,
    "generator": "image",
    "user_id": 42,
    "username": "johndoe",
    "prompt": "A sunset over mountains",
    "created_at": "2026-02-20 12:00:00",
    "privacy_mode": 1,
    "type": "img",
    "license": 1,
    "images": [
      {
        "url": "/users/42/img/image-12345.png",
        "width": 1024,
        "height": 1024
      }
    ],
    "generator_data": { ... }
  }
}

GET /creations/{id}/status AUTH

창작물의 생성 상태를 확인합니다(생성 기록을 추적할 때 유용합니다).

curl https://generor.com/api/v1/creations/12345/status \
  -H "Authorization: Bearer gnr_live_..."

상태 값: pending, generating, completed, failed, cancelled

PATCH /creations/{id} AUTH

본인이 소유한 창작물을 업데이트합니다.

curl -X PATCH https://generor.com/api/v1/creations/12345 \
  -H "Authorization: Bearer gnr_live_..." \
  -H "Content-Type: application/json" \
  -d '{"privacy_mode": 1, "license": 2}'

DELETE /creations/{id} AUTH

소유한 창작물을 삭제합니다(소프트 삭제).

curl -X DELETE https://generor.com/api/v1/creations/12345 \
  -H "Authorization: Bearer gnr_live_..."

GET /models

사용 가능한 모든 AI 모델을 유형별로 그룹화하여 표시합니다.

curl https://generor.com/api/v1/models

GET /models/{type}

특정 유형의 모델을 표시합니다.

curl https://generor.com/api/v1/models/image

유효한 유형: text, image, video, speech, music, soundeffect, upscale, vector, backgroundremoval

모델별 응답:

{
  "id": 10001,
  "name": "Flux 1.1 Pro",
  "type": "image",
  "provider": "replicate",
  "description": "High-quality image generation...",
  "credit_cost": 80,
  "supports_img2img": true,
  "supports_aspect_ratio": true
}

동영상 모델 추가로 전체 제공업체 기능 구조체를 포함합니다:

{
  "id": 20061,
  "name": "Dreamina Seedance 2.0 (720p)",
  "type": "video",
  "provider": "byteplus",
  "credit_cost": 6,

  // Duration constraints
  "supported_durations": [5, 6, 7, 8, 10, 12, 15],
  "default_duration": 8,

  // Audio toggle
  "supports_audio": true,
  "audio_cost_multiplier": 1,

  // End-frame anchoring (pass `ending_frame_url` on /generate)
  "supports_end_frame": true,

  // Resolution variants — same model at different qualities lives at
  // different model_ids. Switch quality by picking the matching id.
  "quality": "720p",
  "default_quality": "720p",
  "qualities": { "480p": 20060, "720p": 20061, "1080p": 20062 },
  "group_slug": "dreamina-seedance-2-direct",
  "group_name": "Dreamina Seedance 2.0",

  // Aspect ratios accepted on /generate
  "supports_aspect_ratio": true,
  "aspect_ratios": [
    { "id": 1, "ratio": "16:9", "label": "Wide" },
    { "id": 2, "ratio": "9:16", "label": "Tall" }
  ]
}

이미지 모델 화면 비율이 다양한 경우 동등한 aspect_ratios 배열이 포함됩니다 (이미지 측에는 정사각형, 세로, 가로, 와이드, 톨에 더해 img2img 모드용 match_input_image까지 6개의 항목이 있습니다).

이 필드 사용 방법

• supported_durations — seconds를 통해 여기에 아무 값이나 전달하세요. 지원되지 않는 값은 서버 측에서 맞춰지며 adjustments.seconds 아래에 보고됩니다.
• qualities — 해상도를 변경하려면 원하는 해상도의 model_id를 찾아서 model_id로 전달하세요. (해상도는 런타임 매개변수가 아니라 동급 모델입니다.)
• supports_audio — true일 때 /generate에 "generate_audio": true를 전달할 수 있습니다. false일 때는 해당 플래그가 무시됩니다.
• supports_end_frame — true일 때 image_url(시작 프레임)과 ending_frame_url를 함께 사용하여 매끄러운 전환이나 루프를 만들 수 있습니다.
• aspect_ratios — /generate의 aspect_ratio 필드 아래에 id(정수) 또는 ratio(문자열)를 전달하세요. 두 형식 모두 작동합니다.

GET /models/{type}/{id}

특정 모델의 세부 정보와 가격을 가져옵니다.

curl https://generor.com/api/v1/models/image/10001

GET /users/me AUTH

프로필, 크레딧 잔액, 통계를 가져옵니다.

curl https://generor.com/api/v1/users/me \
  -H "Authorization: Bearer gnr_live_..."

응답:

{
  "success": true,
  "data": {
    "user_id": 42,
    "username": "johndoe",
    "email": "[email protected]",
    "avatar": null,
    "bio": "I make things with AI",
    "website": "https://example.com",
    "joined": "2025-01-15 10:30:00",
    "credits": {
      "total": 1250,
      "paid": 1000,
      "free": 200,
      "earned": 50,
      "max": 250
    },
    "creation_count": 347,
    "follower_count": 12,
    "following_count": 5,
    "teams": [...]
  }
}

PATCH /users/me AUTH

프로필을 업데이트합니다.

curl -X PATCH https://generor.com/api/v1/users/me \
  -H "Authorization: Bearer gnr_live_..." \
  -H "Content-Type: application/json" \
  -d '{"bio": "Updated bio", "website": "https://example.com"}'

GET /users/{username}

사용자의 공개 프로필을 가져옵니다.

curl https://generor.com/api/v1/users/johndoe

GET /users/{username}/followers

사용자의 팔로워 목록을 표시합니다. 페이지네이션을 지원합니다.

GET /users/{username}/following

사용자가 팔로우하는 대상 목록을 표시합니다. 페이지네이션을 지원합니다.

POST /users/{username}/follow AUTH

사용자를 팔로우합니다.

curl -X POST https://generor.com/api/v1/users/johndoe/follow \
  -H "Authorization: Bearer gnr_live_..."

DELETE /users/{username}/follow AUTH

사용자 팔로우를 취소합니다.

GET /users/{username}/follow AUTH

사용자를 팔로우하고 있는지 확인합니다. {"following": true/false}를 반환합니다.

GET /teams AUTH

내 팀 목록을 표시합니다.

POST /teams AUTH

새 팀을 만듭니다.

curl -X POST https://generor.com/api/v1/teams \
  -H "Authorization: Bearer gnr_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "My Creative Team"}'

GET /teams/{id} AUTH

구성원 목록과 함께 팀 세부 정보를 가져옵니다.

DELETE /teams/{id} AUTH

팀에서 나갑니다.

POST /teams/{id}/members AUTH

사용자 이름으로 멤버 추가: {"username": "janedoe"}

DELETE /teams/{id}/members/{user_id} AUTH

팀원 제거 (소유자 전용).

POST /teams/join/{invite_code} AUTH

초대 코드로 팀에 가입하세요.

POST /teams/{id}/invite AUTH

초대 코드 다시 생성 (소유자 전용).

GET /teams/{id}/creations AUTH

팀 창작물 목록을 표시합니다. 페이지네이션을 지원합니다.

GET /creations/{id}/comments

창작물의 댓글 목록을 표시합니다. 페이지네이션을 지원합니다.

curl https://generor.com/api/v1/creations/12345/comments

POST /creations/{id}/comments AUTH

댓글 추가.

curl -X POST https://generor.com/api/v1/creations/12345/comments \
  -H "Authorization: Bearer gnr_live_..." \
  -H "Content-Type: application/json" \
  -d '{"text": "Great creation!", "parent_id": null}'

DELETE /comments/{id} AUTH

본인의 댓글을 삭제합니다.

POST /comments/{id}/vote AUTH

댓글에 투표: {"vote": "up"} 또는 {"vote": "down"}

GET /creations/{id}/rating

창작물의 평균 평점을 가져옵니다.

// Response:
{"success": true, "data": {"creation_id": 12345, "average": 4.2, "count": 15}}

POST /creations/{id}/rating AUTH

창작물 평가 (1-5). 이미 평가한 경우 기존 평가를 업데이트합니다.

curl -X POST https://generor.com/api/v1/creations/12345/rating \
  -H "Authorization: Bearer gnr_live_..." \
  -H "Content-Type: application/json" \
  -d '{"score": 5}'

GET /credits/balance AUTH

현재 크레딧 잔액을 가져옵니다.

curl https://generor.com/api/v1/credits/balance \
  -H "Authorization: Bearer gnr_live_..."

// Response:
{
  "success": true,
  "data": {
    "total": 1250,
    "paid": 1000,
    "free": 200,
    "earned": 50,
    "max": 250
  }
}

GET /credits/transactions AUTH

크레딧 거래 내역을 가져옵니다.

curl "https://generor.com/api/v1/credits/transactions?type=spend&page=1" \
  -H "Authorization: Bearer gnr_live_..."

쿼리 매개변수: type (spend, purchase, daily_bonus, weekly_bonus, signup_bonus, refund, gift_sent, gift_received), page, per_page

GET /api-keys AUTH

API 키 목록을 표시합니다(전체 키가 아닌 접두사 표시).

POST /api-keys AUTH

새 API 키를 만듭니다. 전체 키는 응답에 한 번만 표시됩니다.

curl -X POST https://generor.com/api/v1/api-keys \
  -H "Authorization: Bearer gnr_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "My App", "scopes": ["read", "generate"]}'

// Response (201):
{
  "success": true,
  "data": {
    "key_id": 1,
    "api_key": "gnr_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0",
    "prefix": "gnr_live_a1b2c3d4",
    "name": "My App",
    "scopes": ["read", "generate"],
    "message": "Save this API key now. It will not be shown again."
  }
}

계정당 최대 10개의 활성 키.

DELETE /api-keys/{id} AUTH

API 키를 취소합니다 (즉시 비활성화됩니다).