Generor API Documentation

GET /generators

List all available generators.

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

Query params: status (active, development, all)

Response: Array of generators with slug, title, description, icon, and similar generators.

GET /generators/{slug}

Get detailed info about a specific generator.

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

GET /generators/{slug}/creations

Browse public creations for a generator. Supports pagination.

curl "https://generor.com/api/v1/generators/joke/creations?page=1&per_page=10"

POST /generators/{slug}/estimate

Preview the credit cost and expected generation time before calling /generate. Same body shape as /generate — but read-only: no credits charged, no creation written. This is the exact same number the UI shows next to the Generate button.

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"
    }
  }'

Response:

{
  "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"
    }
  }
}

Open to unauthenticated callers — pricing/timing is public information and matches what the public generator page displays.

Snapped video durations

If you pass a seconds value that isn't in the model's supported_durations, the API snaps to the nearest supported value (ties break to the lower) and surfaces the change in an adjustments block. The credit cost and time estimate in the same response reflect the snapped value — what /generate will actually do — not the original request.

{
  "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"
      }
    }
  }
}

When to use it

• Pre-flight cost check — confirm a user can afford the generation before charging.
• Progress UI — feed time_estimate.seconds into your loading bar so users know how long to wait.
• Parameter tuning — call it whenever a user changes a dropdown; cost updates without committing to generate.

Relationship to /generate — /estimate is a separate, optional call. /generate already returns the actual credit_cost it charged + credits_remaining after the fact, so if you're happy paying whatever the live price is, you can skip /estimate entirely.

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

Generate content using AI. This is a synchronous call — the response returns when generation is complete. Costs credits based on the model selected. Text generation typically takes 5-30 seconds, image generation 10-60 seconds, and video generation can take several minutes.

# 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
  }'

Request body:

Generator Parameters

Every generator's full set of tweakable fields lives in a per-generator schema (the same source the on-site dropdowns and URL-prefill use). Pass any of those fields in the parameters object on a generate request to drive them programmatically.

Get the schema for any generator at GET /generators/{slug} — the parameters array on the response lists each field with its id, type (enum, number, or model), options (or min/max), default, and 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"
    }
  }'

Additional text-generation fields

For text generators (model_id 1-9999), these top-level body fields are forwarded to the LLM endpoint when relevant:

Response (201 Created) — Text generator example:

{
  "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
  }
}

Response (201 Created) — Image generator example:

{
  "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
  }
}

Snapped video durations — if the caller's seconds isn't in the model's supported_durations, the API snaps to the nearest supported value before invoking the provider and adds an adjustments.seconds block to the response identical in shape to the one on /estimate. This prevents providers from silently defaulting unsupported values.

How the cost fields work

• credit_cost — the actual amount deducted, computed as balance_before − balance_after. This is the source of truth: use it for logging, billing, and updating user balances.
• credit_cost_estimated — the upfront catalog estimate (the same number /estimate would have predicted). Included for transparency and drift monitoring. Often differs from credit_cost for video / per-second / per-character pricing where the real charge is computed inside the provider call.
• time_taken_seconds — actual wall-clock duration. Compare against time_estimate.seconds from /estimate to validate the historical-time prediction.

GET /creations AUTH

List your own creations.

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

Query params: generator (filter by slug), page, per_page, sort

GET /creations/public

Browse all public creations across all generators.

curl "https://generor.com/api/v1/creations/public?generator=image&page=1"

GET /creations/search

Search public creations by prompt text.

curl "https://generor.com/api/v1/creations/search?q=sunset+mountain"

GET /creations/{id}

Get a single creation with full details, images, and generator-specific data.

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

Public creations are accessible to anyone. Private creations require authentication as the owner.

Response includes:

{
  "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": 0,
    "type": "img",
    "license": 1,
    "images": [
      {
        "url": "/users/42/img/image-12345.png",
        "width": 1024,
        "height": 1024
      }
    ],
    "generator_data": { ... }
  }
}

GET /creations/{id}/status AUTH

Check the generation status of a creation (useful if you're tracking generation records).

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

Status values: pending, generating, completed, failed, cancelled

PATCH /creations/{id} AUTH

Update a creation you own.

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

Delete a creation you own (soft delete).

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

GET /models

List all available AI models grouped by type.

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

GET /models/{type}

List models for a specific type.

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

Valid types: text, image, video, speech, music, soundeffect, upscale, vector, backgroundremoval

Response per model:

{
  "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
}

Video models additionally include the full provider-capability struct:

{
  "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" }
  ]
}

Image models that vary aspect ratio include an equivalent aspect_ratios array (image-side has 6 entries: square, vertical, horizontal, wide, tall, plus match_input_image for img2img modes).

How to use these fields

• supported_durations — pass any value here via seconds. Unsupported values snap server-side and are reported under adjustments.seconds.
• qualities — to switch resolution, look up the model_id for the resolution you want and pass that as your model_id. (Resolutions are sibling models, not a runtime parameter.)
• supports_audio — when true, you can pass "generate_audio": true on /generate. When false, the flag is ignored.
• supports_end_frame — when true, you can pair image_url (start frame) with ending_frame_url for seamless transitions or loops.
• aspect_ratios — pass the id (integer) or ratio (string) under the aspect_ratio field on /generate. Both forms work.

GET /models/{type}/{id}

Get a specific model's details and pricing.

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

GET /users/me AUTH

Get your profile, credit balance, and stats.

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

Response:

{
  "success": true,
  "data": {
    "user_id": 42,
    "username": "johndoe",
    "email": "john@example.com",
    "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

Update your profile.

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}

Get a user's public profile.

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

GET /users/{username}/creations

List a user's public creations. Supports pagination.

GET /users/{username}/followers

List a user's followers. Supports pagination.

GET /users/{username}/following

List who a user follows. Supports pagination.

POST /users/{username}/follow AUTH

Follow a user.

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

DELETE /users/{username}/follow AUTH

Unfollow a user.

GET /users/{username}/follow AUTH

Check if you follow a user. Returns {"following": true/false}.

GET /teams AUTH

List your teams.

POST /teams AUTH

Create a new team.

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

Get team details with member list.

DELETE /teams/{id} AUTH

Leave a team.

POST /teams/{id}/members AUTH

Add a member by username: {"username": "janedoe"}

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

Remove a team member (owner only).

POST /teams/join/{invite_code} AUTH

Join a team via invite code.

POST /teams/{id}/invite AUTH

Regenerate invite code (owner only).

GET /teams/{id}/creations AUTH

List team creations. Supports pagination.

GET /creations/{id}/comments

List comments on a creation. Supports pagination.

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

POST /creations/{id}/comments AUTH

Add a comment.

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

Delete your own comment.

POST /comments/{id}/vote AUTH

Vote on a comment: {"vote": "up"} or {"vote": "down"}

GET /creations/{id}/rating

Get average rating for a creation.

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

POST /creations/{id}/rating AUTH

Rate a creation (1-5). Updates existing rating if already rated.

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

Get your current credit balance.

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

Get credit transaction history.

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

Query params: type (spend, purchase, daily_bonus, weekly_bonus, signup_bonus, refund, gift_sent, gift_received), page, per_page

GET /feed AUTH

Get public creations from users you follow.

curl "https://generor.com/api/v1/feed?generator=image&page=1" \
  -H "Authorization: Bearer gnr_live_..."

Query params: generator (filter by slug), page, per_page

GET /api-keys AUTH

List your API keys (shows prefix, not full key).

POST /api-keys AUTH

Create a new API key. The full key is shown only once in the response.

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."
  }
}

Maximum 10 active keys per account.

DELETE /api-keys/{id} AUTH

Revoke an API key (deactivates it immediately).