开发者文档
新时尚.ai API
通过程序生成产品摄影、视频及广告大片。与平台使用的API完全相同 — 从第一天起即可用于您的系统集成。
基础 URL
所有端点均以 /api/v1 进行版本管理，并通过 HTTPS 提供服务。网页应用使用相同端点——不存在仅供 UI 使用的私有路由。
Base URL
https://app.neofashion.ai/api/v1身份验证
每个请求均通过 Bearer token 验证。支持两种 token 类型，均会解析至同一工作区上下文。
API 密钥
适用于服务器到服务器的集成。在工作区设置中创建密钥；每把密钥均限定于您的工作区。Enterprise 方案可用。
Authorization: Bearer ne_live_xxxxxxxxxxxx会话 JWT
在网页应用登录时签发。供平台 UI 使用，适用于短时效、用户范围内的调用。
Authorization: Bearer eyJhbGci...所有请求均包含 source 字段（ui 或 api），并可选包含 api_key_id，用于审计和计费。
端点
核心生成与读取端点。视频和批量生成等长时任务会异步运行——轮询生成任务，或在应用中查看状态更新。
| 方法 | 端点 | 说明 |
|---|---|---|
| POST | /api/v1/generate/image | 生成单个产品照片 |
| POST | /api/v1/generate/video | 生成时尚短视频 |
| POST | /api/v1/generate/bulk | 异步批量生成作业 |
| POST | /api/v1/sketch-to-photo | 素描 → 活动品质照片 |
| GET | /api/v1/generations | 列出世代（分页） |
| GET | /api/v1/generations/:id | 生成详细信息+状态 |
| GET | /api/v1/credits/balance | 当前贷方余额 |
| GET | /api/v1/personas | 工作空间角色 |
| GET | /api/v1/models | 品牌DNA / 专属人物 API |
响应格式
每个端点均返回相同的封装：data、meta（已用积分、剩余积分、请求 ID）和 error。data 与 error 仅会设置其中一个。
成功
{
"data": {
"id": "gen_01hwz...",
"status": "completed",
"output_url": "https://...",
"credits_used": 50
},
"meta": {
"credits_used": 50,
"credits_remaining": 7950,
"request_id": "req_01hwz..."
},
"error": null
}错误
{
"data": null,
"meta": { "request_id": "req_01hwz..." },
"error": {
"code": "INSUFFICIENT_CREDITS",
"message": "Credit balance too low for this operation.",
"details": { "required": 50, "available": 20 }
}
}速率限制
限制按工作区适用。超过限制时，API 将返回 429 RATE_LIMITED，并附带 retry-after header。
| 方案 | 速率限制 |
|---|---|
| Enterprise | 定制 — 根据合同约定，并包含 SLA |
错误代码
错误通过 error 字段返回，包含稳定的 code、可读消息和结构化详情。
| 代码 | HTTP | 含义 |
|---|---|---|
INSUFFICIENT_CREDITS | 402 | 工作区余额不足以执行所请求的操作。充值或升级后继续。 |
UNAUTHORIZED | 401 | Token 缺失、已过期或无效。 |
FORBIDDEN | 403 | Token 有效，但当前方案或角色不允许执行此操作。 |
NOT_FOUND | 404 | 该资源不存在，或属于其他工作区。 |
RATE_LIMITED | 429 | 请求过于频繁——请在指定间隔后重试。 |
PROVIDER_ERROR | 502 | 上游 AI 提供商失败。积分将被退还，您可重试请求。 |