ImageDescriptionGenerator API Docs

Base URL: https://api.imagedescriptiongenerator.online · 前台统一使用 /api/v1，后台使用 /api/admin。

System

服务状态和在线文档。

GET /

接口列表页面。

Auth: No

Response Example

{
  "contentType": "text/html",
  "status": 200
}
GET /openapi.json

OpenAPI JSON。

Auth: No

Response Example

{
  "openapi": "3.0.3",
  "info": {
    "title": "ImageDescriptionGenerator API",
    "version": "0.1.0"
  },
  "paths": {}
}
GET /health

健康检查。

Auth: No

Response Example

{
  "success": true,
  "data": {
    "service": "api-imagedescriptiongenerator",
    "status": "ok"
  },
  "message": ""
}

Website API - /api/v1

给主站 imagedescriptiongenerator.online 调用。

POST /api/v1/users/anonymous

打开网站时创建或恢复匿名用户；登录用户调用时返回登录用户资料和 credits。

Auth: Optional Bearer Supabase access token

Request Example

{
  "anonymousToken": "localStorage 中保存的 anonymousToken，可选",
  "deviceFingerprint": "前端设备指纹 hash，建议传",
  "client": {
    "timezone": "Asia/Shanghai",
    "screenWidth": 1440,
    "screenHeight": 900,
    "deviceMemory": 8,
    "hardwareConcurrency": 12,
    "platform": "Win32"
  }
}

Response Example

{
  "success": true,
  "data": {
    "anonymousId": "anonymous-session-uuid",
    "anonymousToken": "server-signed-token",
    "isNewUser": true,
    "freeQuota": {
      "limit": 3,
      "used": 0,
      "remaining": 3
    },
    "confidenceScore": 100,
    "riskScore": 8,
    "restoredBy": "new"
  },
  "message": ""
}

Alternate Response

{
  "success": true,
  "data": {
    "authenticated": true,
    "userType": "registered",
    "userId": "auth-user-uuid",
    "email": "[email protected]",
    "profile": {
      "id": "auth-user-uuid",
      "email": "[email protected]",
      "displayName": "User Name",
      "avatarUrl": "https://...",
      "authProvider": "google"
    },
    "signupBonus": {
      "granted": false,
      "amount": 0
    },
    "credits": {
      "balance": 5
    }
  },
  "message": ""
}
POST /api/v1/users/merge-anonymous

登录后合并匿名用户数据；已合并或没有匿名身份时会跳过。

Auth: Bearer Supabase access token

Request Example

{
  "anonymousToken": "localStorage 中保存的 anonymousToken",
  "anonymousId": "anonymous-session-uuid",
  "reason": "login"
}

Response Example

{
  "success": true,
  "data": {
    "anonymousId": "anonymous-session-uuid",
    "userId": "auth-user-uuid",
    "merged": true,
    "signupBonus": {
      "granted": true,
      "amount": 5
    },
    "credits": {
      "balance": 5
    }
  },
  "message": ""
}
POST /api/v1/events

网站行为事件上报，用于后台查看用户访问路径。

Auth: Optional Bearer Supabase access token

Request Example

{
  "anonymousId": "anonymous-session-uuid",
  "sessionId": "browser-session-id",
  "eventName": "page_view",
  "step": "进入首页",
  "pagePath": "/en/image-description-generator",
  "pageTitle": "Image Description Generator",
  "locale": "en",
  "tool": "image-description",
  "metadata": {}
}

Response Example

{
  "success": true,
  "data": {
    "accepted": true,
    "stored": true,
    "sessionId": "browser-session-id"
  },
  "message": ""
}
POST /api/v1/generations

创建图片生成任务。匿名用户消耗 lifetime 免费 3 次；登录用户按 credits 规则扣费。

Auth: Optional Bearer Supabase access token

Request Example

{
  "anonymousId": "anonymous-session-uuid",
  "tool": "alt-text",
  "locale": "en",
  "quality": "standard",
  "imageUrl": "https://example.com/photo.jpg",
  "imageStoragePath": "uploads/xxx.webp",
  "imageHash": "sha256...",
  "mimeType": "image/webp",
  "fileSize": 123456,
  "originalFileName": "loud-kids-club-poster.webp",
  "toolOptions": {
    "purpose": "seo",
    "tokenLength": "concise",
    "keywords": [
      "streetwear hoodie",
      "kids fashion",
      "poster"
    ],
    "outputFormats": [
      "plain_text",
      "html_img",
      "markdown"
    ],
    "strictVisibleOnly": true
  }
}

Response Example

{
  "success": true,
  "data": {
    "jobId": "generation-job-uuid",
    "status": "queued",
    "billing": {
      "mode": "anonymous_free",
      "creditsCharged": 0,
      "freeQuota": {
        "limit": 3,
        "used": 1,
        "remaining": 2
      }
    }
  },
  "message": ""
}

Error Response

{
  "success": false,
  "code": "ANONYMOUS_FREE_LIMIT_REACHED",
  "message": "You've used your 3 free generations. Sign up to get 5 credits.",
  "details": {
    "nextAction": "signup",
    "freeQuota": {
      "limit": 3,
      "used": 3,
      "remaining": 0
    }
  }
}
GET /api/v1/generations/:id

查询生成任务结果。

Auth: Optional Bearer Supabase access token

Response Example

{
  "success": true,
  "data": {
    "jobId": "generation-job-uuid",
    "status": "completed",
    "tool": "alt-text",
    "result": {
      "recommendedAltText": "Loud Kids Club street style poster with a model in a blue smiley hoodie holding a lollipop",
      "htmlImgTag": "<img src=\"loud-kids-club-poster.webp\" alt=\"Loud Kids Club street style poster with a model in a blue smiley hoodie holding a lollipop\" />",
      "markdown": "![Loud Kids Club street style poster with a model in a blue smiley hoodie holding a lollipop](loud-kids-club-poster.webp)"
    },
    "error": null
  },
  "message": ""
}
GET /api/v1/me/credits

获取当前登录用户积分余额。

Auth: Bearer Supabase access token

Response Example

{
  "success": true,
  "data": {
    "userId": "auth-user-uuid",
    "balance": 5,
    "signupBonus": {
      "granted": false,
      "amount": 0
    }
  },
  "message": ""
}
GET /api/v1/pricing?site=imagedescriptiongenerator&type=subscription&locale=en

获取公开价格配置；subscription 和 credits 按后台启用状态返回。

Auth: No

Response Example

{
  "success": true,
  "data": {
    "site": "imagedescriptiongenerator",
    "currency": "USD",
    "locale": "en",
    "sections": [
      {
        "type": "subscription",
        "enabled": true,
        "plans": []
      }
    ],
    "plans": [
      {
        "id": "pricing-plan-uuid",
        "planType": "subscription",
        "slug": "basic-monthly",
        "name": "Basic",
        "price": 5.94,
        "priceLabel": "$5.94/mo",
        "billingInterval": "month",
        "credits": 180,
        "status": "enabled",
        "purchasable": true,
        "discount": {
          "showDiscount": true,
          "percentage": 40,
          "discountedPrice": 3.56,
          "daysRemaining": 7
        },
        "availableLocales": [
          "en",
          "zh",
          "ja"
        ]
      }
    ]
  },
  "message": ""
}
GET /api/v1/color-page/categories?locale=en

获取 Color Page 首页分类；name/description 按 locale 本地化。

Auth: No

Request Fields

字段类型/位置必填说明
localequery否返回文案语言：en、zh、ja、ko、es、fr、de、ru、pt、it、zh-TW、hi、id、th、vi。

Response Fields

字段类型/位置必填说明
data.localestring是本次请求使用的目标语言。
data.items[].slugstring是分类 slug。
data.items[].namestring是本地化后的分类名称。
data.items[].descriptionstring是本地化后的分类描述。
data.items[].availableLocalesstring[]是已配置语言列表。

Response Example

{
  "success": true,
  "data": {
    "locale": "en",
    "items": [
      {
        "id": "category-uuid",
        "slug": "trending",
        "name": "Trending",
        "description": "Popular coloring page creations",
        "sortOrder": 20,
        "locale": "en",
        "availableLocales": [
          "en",
          "zh",
          "ja"
        ],
        "createdAt": "2026-06-11T08:00:00.000Z"
      }
    ]
  },
  "message": ""
}
GET /api/v1/color-page/images?category=trending&locale=en&page=1&pageSize=20&sort=popular

获取 Color Page 图片；图片标题、描述和分类信息按 locale 本地化。

Auth: No

Request Fields

字段类型/位置必填说明
categoryquery否分类 slug。
categoryIdquery否分类 UUID；与 category 二选一。
localequery否返回文案语言。
page/pageSizequery否分页参数。
sortquery否newest、popular、order。

Response Fields

字段类型/位置必填说明
data.localestring是本次请求使用的目标语言。
data.items[].titlestring是本地化后的图片标题。
data.items[].descriptionstring是本地化后的图片描述。
data.items[].category.namestring是本地化后的分类名称。
data.items[].availableLocalesstring[]是该图片已配置语言列表。

Response Example

{
  "success": true,
  "data": {
    "locale": "en",
    "page": 1,
    "pageSize": 20,
    "total": 42,
    "items": [
      {
        "id": "image-uuid",
        "categoryId": "category-uuid",
        "title": "Sunset Coloring Page",
        "name": "Sunset Coloring Page",
        "description": "A printable sunset coloring page for kids.",
        "imageUrl": "https://storage.example.com/color-page/sunset.png",
        "thumbnailUrl": "https://storage.example.com/color-page/sunset.png",
        "downloadCount": 128,
        "sortOrder": 10,
        "locale": "en",
        "availableLocales": [
          "en",
          "zh"
        ],
        "createdAt": "2026-06-11T08:00:00.000Z",
        "category": {
          "id": "category-uuid",
          "slug": "trending",
          "name": "Trending",
          "description": "Popular coloring page creations"
        }
      }
    ]
  },
  "message": ""
}
POST /api/v1/checkout/creem

创建 Creem checkout。

Auth: Bearer Supabase access token

Request Example

{
  "packSlug": "starter"
}

Response Example

{
  "success": true,
  "data": {
    "orderId": "order-uuid",
    "checkoutUrl": "https://checkout.creem.io/..."
  },
  "message": ""
}
POST /api/v1/webhooks/creem

Creem webhook 回调。

Auth: Creem signature

Response Example

{
  "success": true,
  "data": {
    "received": true,
    "eventId": "evt_xxx",
    "eventType": "payment.completed"
  },
  "message": ""
}

Admin API - /api/admin

给后台 admin.imagedescriptiongenerator.online 调用。

POST /api/admin/login

管理员登录。

Auth: No

Request Example

{
  "username": "admin",
  "password": "admin888"
}

Response Example

{
  "success": true,
  "data": {
    "username": "admin",
    "role": "super_admin"
  },
  "message": ""
}
POST /api/admin/logout

管理员退出。

Auth: Admin cookie

Response Example

{
  "success": true,
  "data": {
    "loggedOut": true
  },
  "message": ""
}
GET /api/admin/dashboard/stats

首页核心指标和用户/收入趋势。

Auth: Admin cookie

Response Example

{
  "success": true,
  "data": {
    "totals": {
      "users": 100,
      "revenue": 6900
    },
    "today": {
      "users": 3,
      "revenue": 69
    },
    "charts": {
      "revenue": [],
      "users": []
    }
  },
  "message": ""
}
GET /api/admin/users

用户列表。

Auth: Admin cookie

Response Example

{
  "success": true,
  "data": {
    "items": []
  },
  "message": ""
}
GET /api/admin/users/:id/events

用户网站事件曲线和访问路径。

Auth: Admin cookie

Response Example

{
  "success": true,
  "data": {
    "items": []
  },
  "message": ""
}
GET /api/admin/pricing-plans

价格方案列表。

Auth: Admin cookie

Response Example

{
  "success": true,
  "data": {
    "items": []
  },
  "message": ""
}
GET /api/admin/pricing-plans/:id/translations

价格方案多语言。

Auth: Admin cookie

Response Example

{
  "success": true,
  "data": {
    "items": []
  },
  "message": ""
}
GET /api/admin/color-page-categories

Color Page 分类列表。

Auth: Admin cookie

Response Example

{
  "success": true,
  "data": {
    "items": []
  },
  "message": ""
}
GET /api/admin/color-page-categories/:id/translations

Color Page 分类多语言。

Auth: Admin cookie

Response Example

{
  "success": true,
  "data": {
    "items": [
      {
        "locale": "en",
        "name": "Trending",
        "description": "Popular coloring page creations"
      }
    ]
  },
  "message": ""
}
PUT /api/admin/color-page-categories/:id/translations/:locale

保存 Color Page 分类某个语言。

Auth: Admin cookie

Request Example

{
  "name": "Trending",
  "description": "Popular coloring page creations"
}

Response Example

{
  "success": true,
  "data": {
    "locale": "en",
    "name": "Trending"
  },
  "message": ""
}
DELETE /api/admin/color-page-categories/:id/translations/:locale

删除 Color Page 分类某个语言。

Auth: Admin cookie

Response Example

{
  "success": true,
  "data": {
    "deleted": true
  },
  "message": ""
}
GET /api/admin/color-page-images

Color Page 图片列表。

Auth: Admin cookie

Response Example

{
  "success": true,
  "data": {
    "items": []
  },
  "message": ""
}
GET /api/admin/color-page-images/:id/translations

Color Page 图片多语言。

Auth: Admin cookie

Response Example

{
  "success": true,
  "data": {
    "items": [
      {
        "locale": "en",
        "title": "Sunset Coloring Page",
        "description": "A printable sunset coloring page for kids."
      }
    ]
  },
  "message": ""
}
PUT /api/admin/color-page-images/:id/translations/:locale

保存 Color Page 图片某个语言。

Auth: Admin cookie

Request Example

{
  "title": "Sunset Coloring Page",
  "description": "A printable sunset coloring page for kids."
}

Response Example

{
  "success": true,
  "data": {
    "locale": "en",
    "title": "Sunset Coloring Page"
  },
  "message": ""
}
DELETE /api/admin/color-page-images/:id/translations/:locale

删除 Color Page 图片某个语言。

Auth: Admin cookie

Response Example

{
  "success": true,
  "data": {
    "deleted": true
  },
  "message": ""
}