API 参考Seedream
Seedream v4.5 文生图
Seedream v4.5 文生图 API 文档,支持多种宽高比和分辨率的高质量图像生成。
Seedream v4.5 是字节跳动推出的高质量 AI 图像生成模型,具有出色的中英文理解能力和图像生成质量。
- 支持中英文 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/generations \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"model": "seedream-v4.5",
"prompt": "充满活力的特写编辑肖像,模特眼神犀利,头戴雕塑感帽子,色彩拼接丰富,眼部焦点锐利,景深较浅,具有Vogue杂志封面的美学风格",
"aspect_ratio": "3:4",
"quality": "2K"
}'
# 响应示例:
# {"code": 0, "message": "success", "data": {"task_id": "task_abc123xyz"}}
# 步骤 2: 轮询任务状态
curl --request GET \
--url https://api.apipod.ai/v1/images/status/task_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/generations",
headers=headers,
json={
"model": "seedream-v4.5",
"prompt": "充满活力的特写编辑肖像,模特眼神犀利,头戴雕塑感帽子,色彩拼接丰富",
"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 generateImage() {
// 步骤 1: 提交图像生成任务
const submitResponse = await fetch(`${BASE_URL}/images/generations`, {
method: "POST",
headers,
body: JSON.stringify({
model: "seedream-v4.5",
prompt: "充满活力的特写编辑肖像,模特眼神犀利,头戴雕塑感帽子,色彩拼接丰富",
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));
}
}
}
generateImage();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",
"prompt": "充满活力的特写编辑肖像,模特眼神犀利,头戴雕塑感帽子",
"aspect_ratio": "3:4",
"quality": "2K",
}
jsonData, _ := json.Marshal(payload)
req, _ := http.NewRequest("POST", baseURL+"/images/generations", 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 SeedreamExample {
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",
"prompt": "充满活力的特写编辑肖像,模特眼神犀利,头戴雕塑感帽子",
"aspect_ratio": "3:4",
"quality": "2K"
}
""";
HttpRequest submitRequest = HttpRequest.newBuilder()
.uri(URI.create(BASE_URL + "/images/generations"))
.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请求参数
核心参数
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
model | string | ✅ | seedream-v4.5 | 模型标识符 |
prompt | string | ✅ | - | 描述要生成的图像内容,最大长度 4000 字符 |
aspect_ratio | string | - | 1:1 | 生成图像的宽高比 |
quality | string | - | 2K | 输出图像分辨率 |
Prompt 编写技巧
描述主体
清晰描述图像的主要主体,包括人物、物体或场景。
一位年轻女性,穿着白色连衣裙,站在樱花树下添加细节
补充光线、色彩、风格等细节信息。
柔和的自然光,粉色调,日系清新风格指定风格
明确指定艺术风格或摄影风格。
电影感,浅景深,中画幅拍摄,35mm胶片质感完整 Prompt 示例:
充满活力的特写编辑肖像,模特眼神犀利,头戴雕塑感帽子(有一个 APIPod.ai 的 LOGO 在帽子上),
色彩拼接丰富,眼部焦点锐利,景深较浅,具有Vogue杂志封面的美学风格,采用中画幅拍摄,工作室灯光效果强烈。宽高比选项
| 值 | 比例 | 适用场景 |
|---|---|---|
1:1 | 正方形 | 头像、社交媒体图片 |
2:3 | 竖版 | 人像摄影 |
3:2 | 横版 | 风景摄影 |
3:4 | 竖版 | 杂志封面、海报 |
4:3 | 横版 | 传统照片 |
16:9 | 宽屏 | 视频封面、Banner |
9:16 | 竖屏 | 手机壁纸、短视频封面 |
21:9 | 超宽屏 | 电影画幅、网站 Hero 图 |
分辨率选项
| 值 | 说明 |
|---|---|
2K | 标准分辨率,生成速度较快 |
4K | 高分辨率,适合印刷和大尺寸展示 |
响应结构
任务提交响应
提交图像生成请求后,API 会返回任务 ID:
| 字段 | 类型 | 说明 |
|---|---|---|
code | integer | 响应状态码,0 表示成功 |
message | string | 响应消息 |
data.task_id | string | 生成任务的唯一标识 |
{
"code": 0,
"message": "success",
"data": {
"task_id": "task_abc123xyz"
}
}状态查询接口
GET
https://api.apipod.ai/v1/images/status/{task_id}
| 路径参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
task_id | string | ✅ | 图像生成任务 ID |
状态响应字段
| 字段 | 类型 | 说明 |
|---|---|---|
code | integer | 响应状态码,0 表示成功 |
message | string | 响应消息 |
data.task_id | string | 任务 ID |
data.error_message | string | 错误消息 |
data.status | string | 任务状态:pending / processing / completed / failed |
data.completed_at | integer | 完成时间戳(Unix timestamp) |
data.result | array | 生成的图片 URL 列表 |
任务状态说明
| 状态 | 说明 | 建议操作 |
|---|---|---|
pending | 任务已提交,等待处理 | 继续轮询,建议间隔 2 秒 |
processing | 任务正在处理中 | 继续轮询,建议间隔 2 秒 |
completed | 任务完成,图像已生成 | 获取 result 中的图片 URL |
failed | 任务失败 | 检查错误信息,重新提交任务 |
轮询建议
建议每 2-3 秒轮询一次任务状态,图像生成通常需要 10-30 秒。请勿过于频繁轮询,以免触发速率限制。
错误处理
| 状态码 | 说明 |
|---|---|
400 | 请求参数错误(如 prompt 过长、aspect_ratio 无效等) |
401 | 认证失败,API Key 无效或缺失 |
403 | 余额不足或权限不足 |
404 | 任务不存在(查询状态时) |
429 | 请求过于频繁,触发速率限制 |
500 | 服务器内部错误 |
{
"error": {
"message": "Invalid aspect_ratio value",
"type": "invalid_request_error",
"code": "invalid_parameter"
}
}最佳实践
合理设置轮询间隔
建议每 2-3 秒轮询一次,设置最大轮询次数(如 60 次),避免无限等待。
处理超时情况
如果超过 2 分钟任务仍未完成,建议提示用户稍后重试。
缓存生成的图片
图片 URL 有效期有限,建议下载并存储到自己的服务器或 CDN。