上传图片

  • 平台不提供图片上传接口
  • 参考图只能用公网 URL 或 Base64
  • 编辑接口支持 multipart 直接带文件
image/reference

认证

string必填

所有接口均使用 Bearer Token 进行认证。获取 API Key：访问控制台 创建。请求时在请求头中添加：

结论

没有 POST /v1/uploads/images 这类上传接口。New-API 底座的 /v1/files 标注为未实现，调用不会成功。

所有需要参考图的接口（/v1/images/generations、/v1/images/edits、视频接口的首帧等）都接受两种图片表示：

形式写法
公网 URLhttps://your-cdn.com/photo.png
Base64data:image/png;base64,iVBORw0KGgo...

格式标识必须小写。不接受本地文件路径，也不接受 file://。

两种形式的取舍

方式优点缺点
公网 URL请求体最小，一次上传可反复引用需要可公网访问的存储
Base64不依赖外部存储请求体膨胀约 33%，大图容易触发 413 或超时

用公网 URL

最省事的做法。把图片放到任意可公开访问的对象存储或图床，把地址填进 image 字段。

curl --request POST \
  --url 'https://api.oairoute.com/v1/images/generations' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "doubao-seedream-5-0-flash-260915",
  "prompt": "把这张照片改成夜景",
  "image": "https://your-cdn.com/photo.png",
  "size": "2K"
}'

地址必须能被平台侧直接拉取。带鉴权的私有桶地址会失败，需要签发带过期时间的临时 URL。

用 Base64

把文件转成 data URI 内联进请求体。格式标识取实际图片格式，小写。

import base64, pathlib, requests

data = base64.b64encode(pathlib.Path("photo.png").read_bytes()).decode()
res = requests.post(
    "https://api.oairoute.com/v1/images/edits",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "model": "doubao-seedream-5-0-pro-260628",
        "prompt": "换成纯白背景",
        "image": "data:image/png;base64," + data,
        "size": "2K",
    },
)
print(res.json())

一张 5MB 的图转成 Base64 后请求体约 6.7MB。网关对请求体有上限，超过会直接返回 413，不要把大图内联。

multipart 上传

POST /v1/images/edits 支持 multipart/form-data，但那是在编辑请求里一并带上文件，不是先上传再引用：

curl --request POST \
  --url 'https://api.oairoute.com/v1/images/edits' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --form 'model=doubao-seedream-5-0-pro-260628' \
  --form '[email protected]' \
  --form 'prompt=Turn this photo into a night scene' \
  --form 'size=2K'

这是唯一能直接传本地文件的路径，且只限编辑接口。生成接口只接受 URL 或 Base64。

常见问题

为什么没有上传接口？

图片在网关侧不落盘，每次请求都是直传到上游，因此没有可复用的文件标识。

想反复用同一张图怎么办？

放到自己的对象存储，用固定 URL 引用，不要每次重新 Base64。

本地开发没有图床？

可以临时用任意可公网访问的静态托管，或在编辑接口上用 multipart。

错误码

HTTP含义
400图片地址不可访问，或 Base64 格式标识未小写
413请求体过大，通常是 Base64 内联了大图

更多状态码与重试建议见错误码与限流，常见报错的排查步骤见常见问题。

使用示例

公网 URL 引用

适合已有图床、或图片本身就在对象存储里的场景。

Base64 内联

适合一次性小图，或内网环境下不宜暴露图片地址的场景。

本地文件直接编辑

只有编辑接口支持 multipart，把文件随请求一起发出。