文生图 · Generate Image

根据一段文本提示词（prompt）直接生成图片，无需依附于某条对话消息。与 对话生图 不同，本接口是独立的「文生图」通道：你自由描述画面、选择引擎与画风。

本接口为异步接口：提交后立即返回一个 logId，图片不会在本次响应里直接返回，需用该 logId 调用 查询生成任务 轮询获取最终结果。

接口地址

POST https://xiangcao.ai/api/generate-image

提交成功后响应的 status 通常为 pending，表示任务已受理、正在生成。请保存返回的 logId，随后轮询 查询生成任务 直到 status 变为 completed（或 failed）。

鉴权

需要在请求头携带 API Key：

Authorization: Bearer <YOUR_API_KEY>

缺少或无效的 Token 会返回 401。接口对每个用户有调用频率限制（rate limit）。

请求体（JSON）

只有 prompt 必填，其余字段均可选，不传时由后端按引擎默认值填充。提示词支持中文，后端会按引擎自动翻译/优化（除非引擎原生支持中文）。

常用字段

引擎

engine 为品牌化引擎 ID，不同引擎的画风与出图质量不同。默认 xiangcao-nova。当前仅支持以下两个引擎：

宽高比与分辨率

• aspectRatio 可选值：1:1、9:16、16:9、2:3、3:2、4:5、5:4。
• resolution 可选值：1M（标清）、1.5M（高清）、2M（超清）；分辨率越高越贵，且仅对部分引擎生效，其余引擎忽略此字段沿用原生尺寸。

类型定义（TypeScript）

type AspectRatio = "1:1" | "9:16" | "16:9" | "2:3" | "3:2" | "4:5" | "5:4";
type Resolution = "1M" | "1.5M" | "2M";

interface GenerateImageRequest {
  /** 画面描述提示词（必填） */
  prompt: string;
  /** 引擎 ID；不传使用默认 xiangcao-nova */
  engine?: string;
  /** 负向提示词 */
  negativePrompt?: string;
  /** 宽高比；不传默认 2:3 */
  aspectRatio?: AspectRatio;
  /** 分辨率档位；不传默认 1M（仅部分引擎生效） */
  resolution?: Resolution;
  /** 生成数量 1-4；不传默认 1 */
  nSamples?: number;
  /** 随机种子；不传则随机 */
  seed?: number;
  /** 基础 seed 的偏移量，复现批量生成中的第几张；不传按 0 处理 */
  seedIndex?: number;
  /** 画风预设 ID；不传或 "none" 不注入风格 */
  stylePreset?: string;
}

响应（JSON）

interface GenerateImageResponse {
  /** 生成记录 ID，用于查询任务状态 */
  logId: string;
  /** 任务状态 */
  status: "pending" | "completed" | "failed";
  /** 底层任务 ID，可能为空 */
  taskId?: string | null;
  /** 生成的图片地址 */
  urls: string[];
}

拿到 logId 后，请轮询 查询生成任务 获取图片；当其 status 变为 completed 时，返回的 urls 即为最终图片。

计费

• 按「引擎基价 × 张数倍率 ×（1 + 分辨率加成）」预估积分（钻石），并在生成前扣费。
• 张数越多单价越低（倍率 1 / 1.8 / 2.4 / 3 对应 1–4 张）；分辨率 1.5M、2M 会带来额外加成。
• 需要精确预估时，可先调用 calculate-generation-price 接口预览本次扣费。

示例

请求：

curl -X POST "https://xiangcao.ai/api/generate-image" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "夕阳下的少女，海边，长发飘动",
    "engine": "xiangcao-nova",
    "aspectRatio": "2:3",
    "nSamples": 1
  }'

响应（异步受理，urls 待轮询获取）：

{
  "logId": "log_abc123",
  "status": "pending",
  "taskId": "task_789",
  "urls": []
}

随后用 logId 轮询 查询生成任务 获取最终图片。

错误处理

出错时返回相应 HTTP 状态码及 JSON：{ "error": "..." }。