Generor API 文档

GET /generators

列出所有可用的生成器。

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

查询参数： status (active, development, all)

响应： 包含 slug、标题、描述、图标及相似生成器的生成器数组。

GET /generators/{slug}

获取特定生成器的详细信息。

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

GET /generators/{slug}/creations

浏览某个生成器的公开创作。支持分页。

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

POST /generators/{slug}/estimate

在调用 /generate 之前 预览积分成本和预计生成时间。与 /generate 的请求体结构相同——但为只读：不扣除积分，不写入作品。这与界面中 Generate 按钮旁显示的数字完全一致。

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

对未经身份验证的调用方开放——定价/时长为公开信息，与公开生成器页面所显示的内容一致。

对齐的视频时长

如果你传入的 seconds 值不在模型的 supported_durations 范围内，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"
      }
    }
  }
}

何时使用

• 预检成本核查 — 在扣费前确认用户能够负担此次生成。
• 进度界面 — 将 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
  }'

请求体：

生成器参数

每个生成器可调整的完整字段集都存放在各自的 schema 中（与站内下拉菜单和 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 (按 slug 筛选), page, per_page, sort

GET /creations/public

浏览所有生成器的全部公开创作。

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

GET /creations/search

按提示词文本搜索公开作品。

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

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": 0,
    "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 数组（图像侧有 6 个条目：方形、竖向、横向、宽屏、高屏，外加用于 img2img 模式的 match_input_image）。

如何使用这些字段

• 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": "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

更新你的个人资料。

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}/creations

列出用户的公开作品。支持分页。

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 /feed AUTH

获取你关注的用户的公开创作。

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

查询参数： generator (按 slug 筛选), 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 密钥（立即停用）。