Seedream 分解圖層

01

概覽

使用分解圖層端點配合支援的模型。使用回傳的 Task ID 擷取其狀態，或提供 callback_url 以接收以下記錄的交付內容。

快速入門

建立 API 金鑰並將其設定為 RUNAPI_API_KEY。
選擇支援的模型，並發送主體符合該模型結構的 POST 請求。
儲存返回的任務 ID，然後輪詢直至達到終止狀態，或處理下方說明的回呼。

POST /api/v1/seedream/decompose_layers

基礎 URL: https://runapi.ai
API 版本: v1
身份驗證: Authorization: Bearer YOUR_API_TOKEN

02

支援的模型

開啟模型頁面以查看當前定價、速率限制及商業用途詳情。

seedream-5-pro-layer-decomposition

03

請求結構

JSON 內容

欄位及允許的值取決於所選模型。提供後，callback_url 將接收以下記錄的 Task 交付內容。

seedream-5-pro-layer-decomposition6 個欄位

callback_urlstring

選填

image_urlstring

必填

恰好一個公開的 PNG、JPEG、WebP、BMP、TIFF 或 GIF 圖像 URL；不支援 HEIC 和 HEIF。最大 30 MB，總像素 262,144-36,000,000，長寬比 1:16-16:1。

modelstring

選填

output_formatstring

選填

基礎圖像格式。分離圖層為 PNG。

允許值: png, jpeg 預設值: jpeg

promptstring

選填

描述要分離哪些元素的可選指示。

邊界值: 5000

sizestring

選填 允許值: auto, 1K, 1.5K, 2K 預設值: auto

04

建立接受

HTTP 202

POST /api/v1/seedream/decompose_layers

回應結構

JSON

{
  "properties": {
    "billing": {
      "properties": {
        "refund": {
          "oneOf": [
            {
              "properties": {
                "refunded_at": {
                  "type": "string"
                }
              },
              "required": [
                "refunded_at"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        },
        "reservation": {
          "oneOf": [
            {
              "properties": {
                "amount_cents": {
                  "type": "integer"
                }
              },
              "required": [
                "amount_cents"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        },
        "settlement": {
          "oneOf": [
            {
              "properties": {
                "amount_micro_cents": {
                  "type": "integer"
                },
                "charged_amount_cents": {
                  "type": "integer"
                }
              },
              "required": [
                "charged_amount_cents",
                "amount_micro_cents"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        }
      },
      "required": [
        "reservation",
        "settlement",
        "refund"
      ],
      "type": "object",
      "unevaluatedProperties": false
    },
    "id": {
      "type": "string"
    },
    "status": {
      "enum": [
        "processing"
      ],
      "type": "string"
    },
    "task_replayed": {
      "type": "boolean"
    }
  },
  "required": [
    "id",
    "status",
    "billing"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

回應範例

JSON

{
  "billing": {
    "refund": null,
    "reservation": null,
    "settlement": null
  },
  "id": "tsk_reference_demo",
  "status": "processing"
}

05

輪詢處理中

HTTP 200

GET /api/v1/seedream/decompose_layers/:id

回應結構

JSON

{
  "properties": {
    "billing": {
      "properties": {
        "refund": {
          "oneOf": [
            {
              "properties": {
                "refunded_at": {
                  "type": "string"
                }
              },
              "required": [
                "refunded_at"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        },
        "reservation": {
          "oneOf": [
            {
              "properties": {
                "amount_cents": {
                  "type": "integer"
                }
              },
              "required": [
                "amount_cents"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        },
        "settlement": {
          "oneOf": [
            {
              "properties": {
                "amount_micro_cents": {
                  "type": "integer"
                },
                "charged_amount_cents": {
                  "type": "integer"
                }
              },
              "required": [
                "charged_amount_cents",
                "amount_micro_cents"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        }
      },
      "required": [
        "reservation",
        "settlement",
        "refund"
      ],
      "type": "object",
      "unevaluatedProperties": false
    },
    "id": {
      "type": "string"
    },
    "status": {
      "enum": [
        "processing"
      ],
      "type": "string"
    }
  },
  "required": [
    "id",
    "status",
    "billing"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

回應範例

JSON

{
  "billing": {
    "refund": null,
    "reservation": null,
    "settlement": null
  },
  "id": "tsk_reference_demo",
  "status": "processing"
}

06

輪詢已完成

HTTP 200

GET /api/v1/seedream/decompose_layers/:id

回應結構

JSON

{
  "properties": {
    "base_image": {
      "properties": {
        "url": {
          "type": "string",
          "x-runapi-generated-media": true
        }
      },
      "required": [
        "url"
      ],
      "type": "object",
      "unevaluatedProperties": false
    },
    "billing": {
      "properties": {
        "refund": {
          "oneOf": [
            {
              "properties": {
                "refunded_at": {
                  "type": "string"
                }
              },
              "required": [
                "refunded_at"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        },
        "reservation": {
          "oneOf": [
            {
              "properties": {
                "amount_cents": {
                  "type": "integer"
                }
              },
              "required": [
                "amount_cents"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        },
        "settlement": {
          "oneOf": [
            {
              "properties": {
                "amount_micro_cents": {
                  "type": "integer"
                },
                "charged_amount_cents": {
                  "type": "integer"
                }
              },
              "required": [
                "charged_amount_cents",
                "amount_micro_cents"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        }
      },
      "required": [
        "reservation",
        "settlement",
        "refund"
      ],
      "type": "object",
      "unevaluatedProperties": false
    },
    "id": {
      "type": "string"
    },
    "layers": {
      "items": {
        "properties": {
          "bounding_box": {
            "properties": {
              "absolute": {
                "items": {
                  "type": "integer"
                },
                "type": "array"
              },
              "normalized": {
                "items": {
                  "type": "integer"
                },
                "type": "array"
              }
            },
            "type": "object"
          },
          "description": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "x-runapi-generated-media": true
          },
          "z_index": {
            "type": "integer"
          }
        },
        "required": [
          "url",
          "z_index"
        ],
        "type": "object",
        "unevaluatedProperties": false
      },
      "type": "array"
    },
    "status": {
      "enum": [
        "completed"
      ],
      "type": "string"
    }
  },
  "required": [
    "id",
    "status",
    "base_image",
    "layers",
    "billing"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

回應範例

JSON

{
  "base_image": {
    "url": "https://cdn.runapi.ai/public/samples/image.jpg"
  },
  "billing": {
    "refund": null,
    "reservation": null,
    "settlement": null
  },
  "id": "tsk_reference_demo",
  "layers": [
    {
      "bounding_box": {
        "absolute": [
          120,
          80,
          920,
          300
        ],
        "normalized": [
          117,
          78,
          898,
          293
        ]
      },
      "name": "Title text",
      "url": "https://cdn.runapi.ai/public/samples/image.png",
      "z_index": 1
    }
  ],
  "status": "completed"
}

07

輪詢失敗

HTTP 200

GET /api/v1/seedream/decompose_layers/:id

回應結構

JSON

{
  "properties": {
    "billing": {
      "properties": {
        "refund": {
          "oneOf": [
            {
              "properties": {
                "refunded_at": {
                  "type": "string"
                }
              },
              "required": [
                "refunded_at"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        },
        "reservation": {
          "oneOf": [
            {
              "properties": {
                "amount_cents": {
                  "type": "integer"
                }
              },
              "required": [
                "amount_cents"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        },
        "settlement": {
          "oneOf": [
            {
              "properties": {
                "amount_micro_cents": {
                  "type": "integer"
                },
                "charged_amount_cents": {
                  "type": "integer"
                }
              },
              "required": [
                "charged_amount_cents",
                "amount_micro_cents"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        }
      },
      "required": [
        "reservation",
        "settlement",
        "refund"
      ],
      "type": "object",
      "unevaluatedProperties": false
    },
    "error": {
      "type": "string"
    },
    "id": {
      "type": "string"
    },
    "status": {
      "enum": [
        "failed"
      ],
      "type": "string"
    }
  },
  "required": [
    "id",
    "status",
    "error",
    "billing"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

回應範例

JSON

{
  "billing": {
    "refund": null,
    "reservation": null,
    "settlement": null
  },
  "error": "Task processing failed.",
  "id": "tsk_reference_demo",
  "status": "failed"
}

08

客戶回呼：已完成

HTTP 200

POST callback_url

回應結構

JSON

{
  "properties": {
    "base_image": {
      "properties": {
        "url": {
          "type": "string",
          "x-runapi-generated-media": true
        }
      },
      "required": [
        "url"
      ],
      "type": "object",
      "unevaluatedProperties": false
    },
    "id": {
      "type": "string"
    },
    "layers": {
      "items": {
        "properties": {
          "bounding_box": {
            "properties": {
              "absolute": {
                "items": {
                  "type": "integer"
                },
                "type": "array"
              },
              "normalized": {
                "items": {
                  "type": "integer"
                },
                "type": "array"
              }
            },
            "type": "object"
          },
          "description": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "x-runapi-generated-media": true
          },
          "z_index": {
            "type": "integer"
          }
        },
        "required": [
          "url",
          "z_index"
        ],
        "type": "object",
        "unevaluatedProperties": false
      },
      "type": "array"
    },
    "status": {
      "enum": [
        "completed"
      ],
      "type": "string"
    }
  },
  "required": [
    "id",
    "status",
    "base_image",
    "layers"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

回應範例

JSON

{
  "base_image": {
    "url": "https://cdn.runapi.ai/public/samples/image.jpg"
  },
  "id": "tsk_reference_demo",
  "layers": [
    {
      "bounding_box": {
        "absolute": [
          120,
          80,
          920,
          300
        ],
        "normalized": [
          117,
          78,
          898,
          293
        ]
      },
      "name": "Title text",
      "url": "https://cdn.runapi.ai/public/samples/image.png",
      "z_index": 1
    }
  ],
  "status": "completed"
}

09

客戶回呼：已失敗

HTTP 200

POST callback_url

回應結構

JSON

{
  "properties": {
    "error": {
      "oneOf": [
        {
          "type": "string"
        },
        {
          "properties": {
            "code": {
              "type": "string"
            },
            "limit_cents": {
              "type": "integer"
            },
            "message": {
              "type": "string"
            },
            "reset_at": {
              "format": "date-time",
              "type": [
                "string",
                "null"
              ]
            },
            "used_cents": {
              "type": "integer"
            },
            "window": {
              "enum": [
                "1h",
                "1d",
                "7d",
                "daily",
                "weekly",
                "monthly",
                "lifetime"
              ],
              "type": "string"
            }
          },
          "required": [
            "code",
            "message"
          ],
          "type": "object",
          "unevaluatedProperties": false
        }
      ]
    },
    "id": {
      "type": "string"
    },
    "status": {
      "enum": [
        "failed"
      ],
      "type": "string"
    }
  },
  "required": [
    "id",
    "status",
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

回應範例

JSON

{
  "error": {
    "code": "generation_failed",
    "message": "Task processing failed."
  },
  "id": "tsk_reference_demo",
  "status": "failed"
}

10

錯誤

HTTP 401

POST /api/v1/seedream/decompose_layers

回應結構

JSON

{
  "properties": {
    "error": {
      "description": "人類可讀的錯誤訊息。",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

回應範例

JSON

{
  "error": "Authentication required"
}

11

錯誤

HTTP 401

GET /api/v1/seedream/decompose_layers/:id

回應結構

JSON

{
  "properties": {
    "error": {
      "description": "人類可讀的錯誤訊息。",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

回應範例

JSON

{
  "error": "Authentication required"
}

12

錯誤

HTTP 400

POST /api/v1/seedream/decompose_layers

回應結構

JSON

{
  "oneOf": [
    {
      "properties": {
        "error": {
          "description": "人類可讀的錯誤訊息。",
          "type": "string"
        }
      },
      "required": [
        "error"
      ],
      "type": "object",
      "unevaluatedProperties": false
    },
    {
      "properties": {
        "error": {
          "description": "人類可讀的驗證摘要。",
          "type": "string"
        },
        "errors": {
          "additionalProperties": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "description": "以公開請求欄位為鍵的驗證訊息，每個欄位對應一組人類可讀的字串陣列。",
          "type": "object"
        }
      },
      "required": [
        "error",
        "errors"
      ],
      "type": "object",
      "unevaluatedProperties": false
    }
  ]
}

回應範例

JSON

{
  "error": "model must be one of: seedream-5-pro-layer-decomposition"
}

13

錯誤

HTTP 402

POST /api/v1/seedream/decompose_layers

回應結構

JSON

{
  "properties": {
    "error": {
      "description": "人類可讀的錯誤訊息。",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

回應範例

JSON

{
  "error": "Insufficient balance"
}

14

錯誤

HTTP 429

POST /api/v1/seedream/decompose_layers

回應結構

JSON

{
  "properties": {
    "error": {
      "description": "人類可讀的錯誤訊息。",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

回應範例

JSON

{
  "error": "API key credit limit exceeded"
}

15

錯誤

HTTP 409

POST /api/v1/seedream/decompose_layers

回應結構

JSON

{
  "properties": {
    "error": {
      "description": "人類可讀的錯誤訊息。",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

回應範例

JSON

{
  "error": "The request uses features that are not supported for the selected model"
}

16

錯誤

HTTP 429

POST /api/v1/seedream/decompose_layers

回應結構

JSON

{
  "properties": {
    "error": {
      "description": "人類可讀的錯誤訊息。",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

回應範例

JSON

{
  "error": "Rate limit reached. Please retry later."
}

17

錯誤

HTTP 503

POST /api/v1/seedream/decompose_layers

回應結構

JSON

{
  "properties": {
    "error": {
      "description": "人類可讀的錯誤訊息。",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

回應範例

JSON

{
  "error": "Service under maintenance, please try again later"
}

18

錯誤

HTTP 504

POST /api/v1/seedream/decompose_layers

回應結構

JSON

{
  "properties": {
    "error": {
      "description": "人類可讀的錯誤訊息。",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

回應範例

JSON

{
  "error": "The request timed out"
}

19

錯誤

HTTP 404

GET /api/v1/seedream/decompose_layers/:id

回應結構

JSON

{
  "properties": {
    "error": {
      "description": "人類可讀的錯誤訊息。",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

回應範例

JSON

{
  "error": "Task with id 'tsk_reference_demo' not found"
}

20

已生成的程式碼範例

直接使用 cURL，或為您的語言安裝 SDK。每個範例均提交本參考中所示的已驗證請求。

安裝

Shell

pip install runapi-seedream

PYTHON

import os
from runapi.seedream import SeedreamClient

client = SeedreamClient(api_key=os.environ["RUNAPI_API_KEY"])
task = client.decompose_layers.create(
  model="seedream-5-pro-layer-decomposition",
  image_url="https://cdn.runapi.ai/public/samples/image.jpg",
  size="1K",
  output_format="jpeg"
)

安裝

Shell

npm install @runapi.ai/seedream

JAVASCRIPT

import { SeedreamClient } from "@runapi.ai/seedream";

const client = new SeedreamClient({ apiKey: process.env.RUNAPI_API_KEY });
const task = await client.decomposeLayers.create({
  "model": "seedream-5-pro-layer-decomposition",
  "image_url": "https://cdn.runapi.ai/public/samples/image.jpg",
  "size": "1K",
  "output_format": "jpeg"
});

CURL

curl -X POST https://runapi.ai/api/v1/seedream/decompose_layers \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"model":"seedream-5-pro-layer-decomposition","image_url":"https://cdn.runapi.ai/public/samples/image.jpg","size":"1K","output_format":"jpeg"}'

安裝

Shell

go get github.com/runapi-ai/seedream-sdk/go@latest

GO

package main

import (
  "context"
  "log"
  "os"

  "github.com/runapi-ai/core-sdk/go/option"
  seedream "github.com/runapi-ai/seedream-sdk/go/seedream"
)

func main() {
  client, err := seedream.NewClient(option.WithAPIKey(os.Getenv("RUNAPI_API_KEY")))
  if err != nil {
    log.Fatal(err)
  }

  task, err := client.DecomposeLayers.Create(context.Background(), seedream.DecomposeLayersParams{
    Model: seedream.SeedreamModel("seedream-5-pro-layer-decomposition"),
    ImageURL: "https://cdn.runapi.ai/public/samples/image.jpg",
    Size: seedream.LayerDecompositionSize("1K"),
    OutputFormat: seedream.OutputFormat("jpeg"),
  })
  if err != nil {
    log.Fatal(err)
  }
  _ = task
}

21

Seedream 分解圖層

概覽

快速入門

端點

支援的模型

請求結構

建立接受

回應範例

輪詢處理中

回應範例

輪詢已完成

回應範例

輪詢失敗

回應範例

客戶回呼：已完成

回應範例

客戶回呼：已失敗

回應範例

錯誤

回應範例

錯誤

回應範例

錯誤

回應範例

錯誤

回應範例

錯誤

回應範例

錯誤

回應範例

錯誤

回應範例

錯誤

回應範例

錯誤

回應範例

錯誤

回應範例

已生成的程式碼範例

安裝

相關指南