{
  "openapi": "3.1.0",
  "info": {
    "title": "Seedream Image Generation API",
    "version": "1.0.0",
    "description": "Seedream Image Generation API - Submit tasks and query results."
  },
  "servers": [
    {
      "url": "https://api.ttapi.io"
    }
  ],
  "components": {
    "securitySchemes": {
      "CustomApiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "TT-API-KEY",
        "description": "Get your API key from the <a href='https://dashboard.ttapi.io' target='_blank'>TTAPI Dashboard</a>."
      }
    },
    "responses": {
      "SuccessResponse": {
        "description": "Task submitted successfully",
        "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": "Parameter error",
        "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": "Authorization failed",
        "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 image generation request parameters",
        "properties": {
          "model": {
            "type": "string",
            "description": "Model name.\n- `doubao-seedream-5-0-pro-260628`: Pro version\n- `doubao-seedream-5-0-flash-260915`: Flash version",
            "enum": [
              "doubao-seedream-5-0-pro-260628",
              "doubao-seedream-5-0-flash-260915"
            ],
            "example": "doubao-seedream-5-0-pro-260628"
          },
          "prompt": {
            "type": "string",
            "description": "Prompt, used to describe the content of the generated image."
          },
          "image": {
            "type": "array",
            "description": "List of reference image URLs. Supports 1-10 reference images.",
            "items": {
              "type": "string"
            }
          },
          "size": {
            "type": "string",
            "description": "Image size. 5.0 pro/flash options: 1K, 1.5K, 2K (default 2K), or pixel values like `2048x1024`.",
            "default": "2K",
            "enum": [
              "1K",
              "1.5K",
              "2K"
            ],
            "example": "2K"
          },
          "output_format": {
            "type": "string",
            "description": "Output image format.",
            "default": "jpeg",
            "enum": [
              "png",
              "jpeg"
            ]
          },
          "response_format": {
            "type": "string",
            "description": "Return format. `url` returns image download link (24h valid), `b64_json` returns Base64 encoded data.",
            "default": "url",
            "enum": [
              "url",
              "b64_json"
            ]
          },
          "background": {
            "type": "string",
            "description": "Image alpha channel setting. `transparent`=transparent background (image-to-image only, requires input with alpha channel, output defaults to png), `opaque`=opaque background. Only 5.0 pro/flash supports.",
            "default": "opaque",
            "enum": [
              "transparent",
              "opaque"
            ]
          },
          "watermark": {
            "type": "boolean",
            "description": "Whether to add watermark. true=Display \"AI Generated\" in bottom-right, false=Do not add.",
            "default": true,
            "enum": [
              true,
              false
            ],
            "example": false
          },
          "optimize_prompt_options": {
            "type": "object",
            "description": "Prompt optimization config",
            "properties": {
              "mode": {
                "type": "string",
                "enum": [
                  "standard",
                  "fast"
                ],
                "default": "standard",
                "description": "Optimization mode. standard=standard mode (higher quality, longer time), fast=fast mode (shorter time, slightly lower quality, 5.0 flash not supported)"
              }
            }
          },
          "layer_decomposition": {
            "type": "boolean",
            "description": "Enable layer decomposition mode. true=layer decomposition (max 16 layers), false=image generation mode. Only 5.0 pro/flash supports.",
            "default": false,
            "enum": [
              true,
              false
            ]
          },
          "execution_expires_after": {
            "type": "integer",
            "default": 172800,
            "description": "Task timeout threshold (seconds). Range [3600, 259200] (1-72 hours), default 172800 (48 hours)"
          },
          "priority": {
            "type": "integer",
            "default": 0,
            "description": "Execution priority. Range [0, 9], higher value = higher priority, default 0 (FIFO)"
          },
          "safety_identifier": {
            "type": "string",
            "description": "End user unique identifier, max 64 characters. Recommend passing a hashed string"
          }
        },
        "required": [
          "model",
          "prompt"
        ]
      }
    }
  },
  "paths": {
    "/sd/api/v3/images/generations/tasks": {
      "post": {
        "description": "Generate image - Submit image generation task",
        "security": [
          {
            "CustomApiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AsyncGenerateRequest"
              },
              "example": {
                "model": "doubao-seedream-5-0-pro-260628",
                "prompt": "Vibrant close-up editorial portrait, model with sharp gaze, abstract colorful light and shadow background",
                "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": "Query image generation task results",
        "security": [
          {
            "CustomApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Task ID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Request successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "enum": [
                        "PENDING_QUEUE",
                        "ON_QUEUE",
                        "SUCCESS",
                        "FAILED"
                      ],
                      "description": "Task status"
                    },
                    "message": {
                      "type": "string",
                      "description": "Response message"
                    },
                    "id": {
                      "type": "string",
                      "description": "Task ID"
                    },
                    "data": {
                      "type": "object",
                      "description": "Task result",
                      "properties": {
                        "images": {
                          "type": "array",
                          "description": "List of generated image URLs",
                          "items": {
                            "type": "string"
                          }
                        },
                        "size": {
                          "type": "string",
                          "description": "Image width/height pixel values"
                        },
                        "output_format": {
                          "type": "string",
                          "description": "Output format"
                        },
                        "quota": {
                          "type": "string",
                          "description": "Quota consumed"
                        }
                      }
                    }
                  },
                  "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"
          }
        }
      }
    }
  }
}