API 参考Seedream

Seedream v4.5 图生图

Seedream v4.5 图生图 API 文档,基于源图片和文本描述进行图像编辑和风格转换。

Seedream v4.5 图生图 API 允许您基于文本描述和参考图片对现有图像进行转换和编辑。

  • 支持 1-14 张源图片作为参考
  • 支持中英文 Prompt 描述
  • 多种宽高比选择:1:1, 2:3, 3:2, 3:4, 4:3, 16:9, 9:16, 21:9
  • 高分辨率输出:支持 2K 和 4K 分辨率
  • 异步任务模式:提交请求后轮询获取结果

接口定义

POST
https://api.apipod.ai/v1/images/generations

异步任务模式

此 API 为异步操作,提交请求后会返回任务 ID,需要轮询状态接口获取结果。

步骤:1. 提交任务并附带源图片获取 task_id → 2. 轮询状态接口直到完成

# 步骤 1: 提交图像编辑任务
curl --request POST \
  --url https://api.apipod.ai/v1/images/edits \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "seedream-v4.5-edit",
    "prompt": "将这张肖像照转换为油画风格,保持原有构图但添加丰富的笔触和纹理",
    "image_urls": [
      "https://example.com/images/source.jpg"
    ],
    "aspect_ratio": "3:4",
    "quality": "2K"
  }'

# 响应示例:
# {"code": 0, "message": "success", "data": {"task_id": "task_edit_abc123xyz"}}

# 步骤 2: 轮询任务状态
curl --request GET \
  --url https://api.apipod.ai/v1/images/status/task_edit_abc123xyz \
  --header 'Authorization: Bearer <token>'
import requests
import time

API_KEY = "<token>"
BASE_URL = "https://api.apipod.ai/v1"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

# 步骤 1: 提交图像编辑任务
response = requests.post(
    f"{BASE_URL}/images/edits",
    headers=headers,
    json={
        "model": "seedream-v4.5-edit",
        "prompt": "将这张肖像照转换为油画风格,保持原有构图但添加丰富的笔触",
        "image_urls": [
            "https://example.com/images/source.jpg"
        ],
        "aspect_ratio": "3:4",
        "quality": "2K"
    }
)

task_id = response.json()["data"]["task_id"]
print(f"任务已提交: {task_id}")

# 步骤 2: 轮询任务状态
while True:
    status_response = requests.get(
        f"{BASE_URL}/images/status/{task_id}",
        headers=headers
    )
    data = status_response.json()["data"]

    if data["status"] == "completed":
        print("图像编辑完成!")
        print("图片 URL:", data["result"])
        break
    elif data["status"] == "failed":
        print("任务失败")
        break
    else:
        print(f"状态: {data['status']},等待中...")
        time.sleep(2)  # 每 2 秒轮询一次
const API_KEY = "<token>";
const BASE_URL = "https://api.apipod.ai/v1";

const headers = {
  "Authorization": `Bearer ${API_KEY}`,
  "Content-Type": "application/json"
};

async function editImage() {
  // 步骤 1: 提交图像编辑任务
  const submitResponse = await fetch(`${BASE_URL}/images/edits`, {
    method: "POST",
    headers,
    body: JSON.stringify({
      model: "seedream-v4.5-edit",
      prompt: "将这张肖像照转换为油画风格,保持原有构图",
      image_urls: [
        "https://example.com/images/source.jpg"
      ],
      aspect_ratio: "3:4",
      quality: "2K"
    })
  });

  const { data: { task_id } } = await submitResponse.json();
  console.log(`任务已提交: ${task_id}`);

  // 步骤 2: 轮询任务状态
  while (true) {
    const statusResponse = await fetch(
      `${BASE_URL}/images/status/${task_id}`,
      { headers }
    );
    const { data } = await statusResponse.json();

    if (data.status === "completed") {
      console.log("图像编辑完成!");
      console.log("图片 URL:", data.result);
      break;
    } else if (data.status === "failed") {
      console.log("任务失败");
      break;
    } else {
      console.log(`状态: ${data.status},等待中...`);
      await new Promise(resolve => setTimeout(resolve, 2000));
    }
  }
}

editImage();
package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io/ioutil"
    "net/http"
    "time"
)

const (
    apiKey  = "<token>"
    baseURL = "https://api.apipod.ai/v1"
)

type SubmitResponse struct {
    Code    int    `json:"code"`
    Message string `json:"message"`
    Data    struct {
        TaskID string `json:"task_id"`
    } `json:"data"`
}

type StatusResponse struct {
    Code    int    `json:"code"`
    Message string `json:"message"`
    Data    struct {
        TaskID      string   `json:"task_id"`
        Status      string   `json:"status"`
        CompletedAt int64    `json:"completed_at"`
        Result      []string `json:"result"`
    } `json:"data"`
}

func main() {
    // 步骤 1: 提交图像编辑任务
    payload := map[string]interface{}{
        "model":  "seedream-v4.5-edit",
        "prompt": "将这张肖像照转换为油画风格",
        "image_urls": []string{
            "https://example.com/images/source.jpg",
        },
        "aspect_ratio": "3:4",
        "quality":      "2K",
    }

    jsonData, _ := json.Marshal(payload)

    req, _ := http.NewRequest("POST", baseURL+"/images/edits", bytes.NewBuffer(jsonData))
    req.Header.Set("Authorization", "Bearer "+apiKey)
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, _ := ioutil.ReadAll(resp.Body)
    var submitResp SubmitResponse
    json.Unmarshal(body, &submitResp)

    taskID := submitResp.Data.TaskID
    fmt.Printf("任务已提交: %s\n", taskID)

    // 步骤 2: 轮询任务状态
    for {
        req, _ := http.NewRequest("GET", baseURL+"/images/status/"+taskID, nil)
        req.Header.Set("Authorization", "Bearer "+apiKey)

        resp, _ := client.Do(req)
        body, _ := ioutil.ReadAll(resp.Body)
        resp.Body.Close()

        var statusResp StatusResponse
        json.Unmarshal(body, &statusResp)

        if statusResp.Data.Status == "completed" {
            fmt.Println("图像编辑完成!")
            fmt.Println("图片 URL:", statusResp.Data.Result)
            break
        } else if statusResp.Data.Status == "failed" {
            fmt.Println("任务失败")
            break
        } else {
            fmt.Printf("状态: %s,等待中...\n", statusResp.Data.Status)
            time.Sleep(2 * time.Second)
        }
    }
}
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;
import com.google.gson.JsonObject;
import com.google.gson.JsonParser;

public class SeedreamEditExample {
    private static final String API_KEY = "<token>";
    private static final String BASE_URL = "https://api.apipod.ai/v1";

    public static void main(String[] args) throws Exception {
        HttpClient client = HttpClient.newHttpClient();

        // 步骤 1: 提交图像编辑任务
        String payload = """
        {
          "model": "seedream-v4.5-edit",
          "prompt": "将这张肖像照转换为油画风格",
          "image_urls": ["https://example.com/images/source.jpg"],
          "aspect_ratio": "3:4",
          "quality": "2K"
        }
        """;

        HttpRequest submitRequest = HttpRequest.newBuilder()
            .uri(URI.create(BASE_URL + "/images/edits"))
            .header("Authorization", "Bearer " + API_KEY)
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(payload))
            .build();

        HttpResponse<String> submitResponse = client.send(submitRequest,
            HttpResponse.BodyHandlers.ofString());

        JsonObject submitJson = JsonParser.parseString(submitResponse.body()).getAsJsonObject();
        String taskId = submitJson.getAsJsonObject("data").get("task_id").getAsString();
        System.out.println("任务已提交: " + taskId);

        // 步骤 2: 轮询任务状态
        while (true) {
            HttpRequest statusRequest = HttpRequest.newBuilder()
                .uri(URI.create(BASE_URL + "/images/status/" + taskId))
                .header("Authorization", "Bearer " + API_KEY)
                .GET()
                .build();

            HttpResponse<String> statusResponse = client.send(statusRequest,
                HttpResponse.BodyHandlers.ofString());

            JsonObject statusJson = JsonParser.parseString(statusResponse.body()).getAsJsonObject();
            String status = statusJson.getAsJsonObject("data").get("status").getAsString();

            if ("completed".equals(status)) {
                System.out.println("图像编辑完成!");
                System.out.println("图片 URL: " + statusJson.getAsJsonObject("data").get("result"));
                break;
            } else if ("failed".equals(status)) {
                System.out.println("任务失败");
                break;
            } else {
                System.out.println("状态: " + status + ",等待中...");
                Thread.sleep(2000);
            }
        }
    }
}

认证鉴权

所有接口调用均需在 Header 中包含 Bearer Token。

安全提示

请勿在浏览器前端代码中直接暴露您的 API Key。建议仅在服务器端使用。

Authorization: Bearer sk-xxxxxxxxxxxxxxxx

请求参数

核心参数

参数名类型必填默认值说明
modelstringseedream-v4.5-edit模型标识符
promptstring-描述如何编辑图像,最大长度 4000 字符
image_urlsarray-源图片 URL 列表(需要 1-14 张图片)
aspect_ratiostring-1:1输出图像的宽高比
qualitystring-2K输出图像分辨率

源图片要求

图片要求

  • 最少:需要 1 张图片
  • 最多:支持最多 14 张图片
  • 格式:JPEG、PNG、WebP
  • 可访问性:图片必须是可公开访问的 URL

多图片使用场景:

图片数量使用场景
1 张图片单图风格迁移或编辑
2-3 张图片多参考图的风格融合
4 张以上复杂场景合成或多参考编辑

图像编辑 Prompt 编写技巧

描述转换方式

清晰描述您希望如何转换源图片。

将这张照片转换为水彩画风格

指定风格细节

添加您想要应用的具体风格特征。

边缘柔和、粉彩色调、可见的笔触效果

保留或修改元素

指定从原图中要保留什么、要改变什么。

保持原有构图但将背景更换为日落场景

完整 Prompt 示例:

将这张肖像照转换为油画风格,保持原有构图和面部特征,
但添加丰富的笔触、饱满的纹理,以及温暖的金色光线,呈现文艺复兴肖像画的风格。

宽高比选项

比例适用场景
1:1正方形头像、社交媒体图片
2:3竖版人像摄影
3:2横版风景摄影
3:4竖版杂志封面、海报
4:3横版传统照片
16:9宽屏视频封面、Banner
9:16竖屏手机壁纸、短视频封面
21:9超宽屏电影画幅、网站 Hero 图

分辨率选项

说明
2K标准分辨率,生成速度较快
4K高分辨率,适合印刷和大尺寸展示

响应结构

任务提交响应

提交图像编辑请求后,API 会返回任务 ID:

字段类型说明
codeinteger响应状态码,0 表示成功
messagestring响应消息
data.task_idstring编辑任务的唯一标识
{
  "code": 0,
  "message": "success",
  "data": {
    "task_id": "task_edit_abc123xyz"
  }
}

状态查询接口

GET
https://api.apipod.ai/v1/images/status/{task_id}
路径参数类型必填说明
task_idstring图像编辑任务 ID

状态响应字段

字段类型说明
codeinteger响应状态码,0 表示成功
messagestring响应消息
data.task_idstring任务 ID
data.error_messagestring错误消息
data.statusstring任务状态:pending / processing / completed / failed
data.completed_atinteger完成时间戳(Unix timestamp)
data.resultarray编辑后的图片 URL 列表

任务状态说明

状态说明建议操作
pending任务已提交,等待处理继续轮询,建议间隔 2 秒
processing任务正在处理中继续轮询,建议间隔 2 秒
completed任务完成,图像已编辑获取 result 中的图片 URL
failed任务失败检查错误信息,重新提交任务

轮询建议

建议每 2-3 秒轮询一次任务状态,图像编辑通常需要 15-45 秒,具体取决于源图片数量。请勿过于频繁轮询,以免触发速率限制。

错误处理

状态码说明
400请求参数错误(如 image_urls 无效、图片数量超限等)
401认证失败,API Key 无效或缺失
403余额不足或权限不足
404任务不存在(查询状态时)
429请求过于频繁,触发速率限制
500服务器内部错误
{
  "error": {
    "message": "image_urls 必须包含 1 到 14 张图片",
    "type": "invalid_request_error",
    "code": "invalid_parameter"
  }
}

最佳实践

确保图片可访问

确保所有源图片 URL 可公开访问并返回有效的图片内容。

优化源图片质量

使用高质量的源图片以获得更好的效果。建议最低分辨率为 512x512。

合理设置轮询间隔

建议每 2-3 秒轮询一次,设置最大轮询次数(如 90 次),避免无限等待。

缓存编辑后的图片

图片 URL 有效期有限,建议下载并存储到自己的服务器或 CDN。

相关链接

On this page

Seedream v4.5 图生图 | APIPod Docs