{
  "openapi": "3.1.0",
  "info": {
    "title": "Seedream 图片生成 API",
    "version": "1.0.0",
    "description": "Seedream 图片生成 API - 提交任务并查询结果。"
  },
  "servers": [{ "url": "https://api.ttapi.io" }],
  "components": {
    "securitySchemes": {
      "CustomApiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "TT-API-KEY",
        "description": "请前往 <a href='https://dashboard.ttapi.io' target='_blank'>TTAPI 控制台</a> 获取 API 密钥。"
      }
    },
    "responses": {
      "SuccessResponse": {
        "description": "任务提交成功",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "status": { "type": "string", "example": "SUCCESS" },
                "message": { "type": "string", "example": "success" },
                "data": { "type": "object", "example": { "id": "id" } }
              },
              "required": ["status", "message", "data"]
            }
          }
        }
      },
      "400Response": {
        "description": "参数错误",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "status": { "type": "string", "example": "FAILED" },
                "message": { "type": "string", "example": "\"prompt\" cannot be empty." },
                "data": { "type": "object" }
              },
              "required": ["status", "message"]
            }
          }
        }
      },
      "401Response": {
        "description": "授权失败",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "status": { "type": "string", "example": "FAILED" },
                "message": { "type": "string", "example": "Wrong TT-API-KEY or email is not activated." }
              },
              "required": ["status", "message"]
            }
          }
        }
      }
    },
    "schemas": {
      "AsyncGenerateRequest": {
        "type": "object",
        "description": "Seedream 图片生成请求参数",
        "properties": {
          "model": {
            "type": "string",
            "description": "模型名称。\n- `doubao-seedream-5-0-pro-260628`：专业版\n- `doubao-seedream-5-0-flash-260915`：快速版",
            "enum": ["doubao-seedream-5-0-pro-260628", "doubao-seedream-5-0-flash-260915"],
            "example": "doubao-seedream-5-0-pro-260628"
          },
          "prompt": { "type": "string", "description": "提示词，用于描述生成图像的内容。" },
          "image": {
            "type": "array",
            "description": "参考图片 URL 列表。支持 1-10 张参考图。",
            "items": { "type": "string" }
          },
          "size": {
            "type": "string",
            "description": "图像尺寸。5.0 pro/flash 可选：1K、1.5K、2K（默认 2K），或指定像素值如 `2048x1024`。",
            "default": "2K",
            "enum": ["1K", "1.5K", "2K"],
            "example": "2K"
          },
          "output_format": { "type": "string", "description": "输出图像格式。", "default": "jpeg", "enum": ["png", "jpeg"] },
          "response_format": { "type": "string", "description": "返回格式。`url` 返回图片下载链接（24h 有效），`b64_json` 返回 Base64 编码。", "default": "url", "enum": ["url", "b64_json"] },
          "background": { "type": "string", "description": "图片透明通道设置。`transparent`=透明背景（仅图生图场景，需输入带透明通道的图片，输出默认 png），`opaque`=不透明背景。仅 5.0 pro/flash 支持。", "default": "opaque", "enum": ["transparent", "opaque"] },
          "watermark": { "type": "boolean", "description": "是否添加水印。true=右下角显示「AI 生成」，false=不添加。", "default": true, "enum": [true, false], "example": false },
          "optimize_prompt_options": {
            "type": "object",
            "description": "提示词优化配置",
            "properties": {
              "mode": { "type": "string", "enum": ["standard", "fast"], "default": "standard", "description": "优化模式。standard=标准模式（质量更高，耗时较长），fast=快速模式（耗时更短，效果略低，5.0 flash 不支持）" }
            }
          },
          "layer_decomposition": {
            "type": "boolean",
            "description": "是否开启图层拆分模式。true=图层拆分（最多 16 个图层），false=图片生成模式。仅 5.0 pro/flash 支持。",
            "default": false,
            "enum": [true, false]
          },
          "execution_expires_after": { "type": "integer", "default": 172800, "description": "任务超时阈值（秒）。范围 [3600, 259200]（1~72 小时），默认 172800（48 小时）" },
          "priority": { "type": "integer", "default": 0, "description": "执行优先级。范围 [0, 9]，数值越大优先级越高，默认 0（FIFO）" },
          "safety_identifier": { "type": "string", "description": "终端用户唯一标识符，不超过 64 字符。建议传入哈希处理后的字符串" }
        },
        "required": ["model", "prompt"]
      }
    }
  },
  "paths": {
    "/sd/api/v3/images/generations/tasks": {
      "post": {
        "description": "生成图片 - 提交图片生成任务",
        "security": [{ "CustomApiKey": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/AsyncGenerateRequest" },
              "example": {
                "model": "doubao-seedream-5-0-pro-260628",
                "prompt": "充满活力的特写编辑肖像，模特眼神犀利，背景为抽象的彩色光影",
                "size": "2K",
                "output_format": "jpeg",
                "watermark": false
              }
            }
          }
        },
        "responses": {
          "200": { "$ref": "#/components/responses/SuccessResponse" },
          "400": { "$ref": "#/components/responses/400Response" },
          "401": { "$ref": "#/components/responses/401Response" }
        }
      }
    },
    "/sd/api/v3/images/generations/tasks/{id}": {
      "get": {
        "description": "查询图片生成任务结果",
        "security": [{ "CustomApiKey": [] }],
        "parameters": [{ "name": "id", "in": "path", "required": true, "description": "任务 ID", "schema": { "type": "string" } }],
        "responses": {
          "200": {
            "description": "请求成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": { "type": "string", "enum": ["PENDING_QUEUE", "ON_QUEUE", "SUCCESS", "FAILED"], "description": "任务状态" },
                    "message": { "type": "string", "description": "响应信息" },
                    "id": { "type": "string", "description": "任务 ID" },
                    "data": {
                      "type": "object",
                      "description": "任务结果",
                      "properties": {
                        "images": { "type": "array", "description": "生成的图片 URL 列表", "items": { "type": "string" } },
                        "size": { "type": "string", "description": "图像宽高像素值" },
                        "output_format": { "type": "string", "description": "输出格式" },
                        "quota": { "type": "string", "description": "消耗配额" }
                      }
                    }
                  },
                  "example": {
                    "status": "SUCCESS",
                    "message": "success",
                    "id": "30d9b07d-7349-4cbc-8e11-9ba302c6d165",
                    "data": {
                      "images": ["https://cdn.ttapi.io/seedream/2026-10-21/xxxx.png"],
                      "size": "2048x2048",
                      "output_format": "jpeg",
                      "quota": "0"
                    }
                  },
                  "required": ["status", "message"]
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/400Response" },
          "401": { "$ref": "#/components/responses/401Response" }
        }
      }
    }
  }
}
