API 文档

Kewen AI 提供标准 REST API，支持 AI 图像生成。按积分计费，生成成功后扣费，失败自动退款。

认证

所有 API 请求（除注册/登录外）均需在 Header 中携带认证信息：

Authorization: Bearer <your-api-key>

API Key 以 sk- 开头，在控制台 → API Keys 中创建。也可使用登录后返回的 JWT Token。

定价

POST /auth/register

注册新用户，返回 JWT Token。

请求 Body

{
  "email": "user@example.com",
  "username": "张三",
  "password": "your_password"
}

响应

{
  "access_token": "eyJ...",
  "token_type": "bearer",
  "user_id": 1,
  "email": "user@example.com",
  "balance": 0.0
}

POST /auth/login

用户登录，返回 JWT Token。

curl -X POST https://your-domain/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"your_password"}'

GET /auth/me

获取当前登录用户信息和余额。

curl https://your-domain/auth/me \
  -H "Authorization: Bearer sk-xxxx"

{
  "id": 1,
  "email": "user@example.com",
  "username": "张三",
  "balance": 9.95,
  "total_tasks": 1
}

POST /v1/generate

提交图片生成任务。任务异步处理，提交后轮询状态。

请求参数

curl -X POST https://your-domain/v1/generate \
  -H "Authorization: Bearer sk-xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "product_image_url": "https://example.com/product.jpg",
    "model": "nano-banana-2"
  }'

响应

{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "model": "nano-banana-2",
  "cost": 0.05,
  "result_image_url": null,
  "error_msg": null,
  "created_at": "2025-05-02T10:00:00",
  "updated_at": "2025-05-02T10:00:00"
}

GET /v1/tasks/{task_id}

查询任务状态。建议每 5 秒轮询一次，最长等待 10 分钟。

curl https://your-domain/v1/tasks/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer sk-xxxx"

成功响应示例

{
  "task_id": "550e8400-...",
  "status": "success",
  "model": "nano-banana-2",
  "cost": 0.05,
  "result_image_url": "https://cdn.example.com/results/550e8400.png",
  "error_msg": null,
  "created_at": "2025-05-02T10:00:00",
  "updated_at": "2025-05-02T10:02:30"
}

GET /v1/tasks

获取当前用户的任务列表。

curl "https://your-domain/v1/tasks?limit=10" \
  -H "Authorization: Bearer sk-xxxx"

GET /v1/balance

curl https://your-domain/v1/balance \
  -H "Authorization: Bearer sk-xxxx"

# 响应
{"balance": 99.79, "points": 9979}

GET /v1/api-keys

列出当前用户的所有 API Key。

POST /v1/api-keys

curl -X POST https://your-domain/v1/api-keys \
  -H "Authorization: Bearer <jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{"key_name": "production"}'

# 响应（只显示一次完整 key）
{"id":1,"key_name":"production","key_value":"sk-abcd...","total_calls":0,...}

DELETE /v1/api-keys/{key_id}

curl -X DELETE https://your-domain/v1/api-keys/1 \
  -H "Authorization: Bearer <jwt-token>"

Python 示例代码

import time
import requests

API_KEY = "sk-your-api-key"
BASE_URL = "https://your-domain.com"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

def generate_image(product_url: str, model: str = "nano-banana-2") -> str:
    # 1. 提交任务
    resp = requests.post(
        f"{BASE_URL}/v1/generate",
        json={"product_image_url": product_url, "model": model},
        headers=HEADERS,
    )
    resp.raise_for_status()
    task = resp.json()
    task_id = task["task_id"]
    print(f"Task submitted: {task_id}")

    # 2. 轮询结果
    for _ in range(120):  # 最多等 10 分钟
        time.sleep(5)
        r = requests.get(f"{BASE_URL}/v1/tasks/{task_id}", headers=HEADERS)
        t = r.json()
        if t["status"] == "success":
            return t["result_image_url"]
        elif t["status"] == "failed":
            raise RuntimeError(f"生成失败: {t['error_msg']}")

    raise TimeoutError("等待超时")


# 使用示例
url = generate_image("https://example.com/product.jpg", "nano-banana-pro")
print(f"结果图: {url}")

错误码