# 图片引用方式
> 平台**不提供独立的图片上传接口**
> 参考图只能用公网 URL 或 Base64 data URI 两种形式
> 需要固定地址时，自行准备一个可公网访问的图床
`参考图传参约定`
## 结论
没有 `POST /v1/uploads/images` 这类上传接口。New-API 底座的 `/v1/files` 标注为未实现，调用不会成功。
所有需要参考图的接口（`/v1/images/generations`、`/v1/images/edits`、视频接口的首帧等）都接受**两种**图片表示：
| 形式 | 写法 |
|---|---|
| 公网 URL | `https://your-cdn.com/photo.png` |
| Base64 | `data:image/png;base64,iVBORw0KGgo...` |
格式标识必须小写。不接受本地文件路径，也不接受 `file://`。
## 两种形式的取舍
| 方式 | 优点 | 缺点 |
|---|---|---|
| 公网 URL | 请求体最小，一次上传可反复引用 | 需要可公网访问的存储 |
| Base64 | 不依赖外部存储 | 请求体膨胀约 33%，大图容易触发 413 或超时 |
## 用公网 URL
最省事的做法。把图片放到任意可公开访问的对象存储或图床，把地址填进 `image` 字段。
```bash
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 内联进请求体。格式标识取实际图片格式，小写。
```bash
python - <<'PY'
import base64, json, 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())
PY
```
> **Note:** 
> 一张 5MB 的图转成 Base64 后请求体约 6.7MB。网关对请求体有上限，超过会直接返回 413，不要把大图内联。
## multipart 上传
`POST /v1/images/edits` 支持 `multipart/form-data`，但那是在编辑请求里**一并**带上文件，不是先上传再引用：
```bash
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 'image=@room.png' \
  --form 'prompt=Turn this photo into a night scene' \
  --form 'size=2K'
```
这是唯一能直接传本地文件的路径，且只限编辑接口。生成接口只接受 URL 或 Base64。
## 常见问题
**为什么没有上传接口？** 图片在网关侧不落盘，每次请求都是直传到上游，因此没有可复用的文件标识。
**想反复用同一张图怎么办？** 放到自己的对象存储，用固定 URL 引用，不要每次重新 Base64。
**本地开发没有图床？** 可以临时用任意可公网访问的静态托管，或在编辑接口上用 multipart。
## 错误码
| HTTP | 含义 |
|---|---|
| 400 | 图片地址不可访问，或 Base64 格式标识未小写 |
| 413 | 请求体过大，通常是 Base64 内联了大图 |
更多状态码与重试建议见[错误码与限流](../support/errors.html)，常见报错的排查步骤见[常见问题](../support/faq.html)。
## 使用示例
### 公网 URL 引用
适合已有图床、或图片本身就在对象存储里的场景。
### Base64 内联
适合一次性小图，或内网环境下不宜暴露图片地址的场景。
### 本地文件直接编辑
只有编辑接口支持 multipart，把文件随请求一起发出。
**公网 URL 引用{Public URL}::cURL**
```
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 引用{Public URL}::Python**
```
import requests
res = requests.post(
    "https://api.oairoute.com/v1/images/generations",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "model": "doubao-seedream-5-0-flash-260915",
        "prompt": "把这张照片改成夜景",
        "image": "https://your-cdn.com/photo.png",
        "size": "2K",
    },
)
print(res.json())
```
**公网 URL 引用{Public URL}::JavaScript**
```
const res = await fetch("https://api.oairoute.com/v1/images/generations", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "doubao-seedream-5-0-flash-260915",
    prompt: "把这张照片改成夜景",
    image: "https://your-cdn.com/photo.png",
    size: "2K",
  }),
});
console.log(await res.json());
```
**Base64 内联{Inline Base64}::Python**
```
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())
```
**本地文件编辑{Multipart upload}::cURL**
```
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 'image=@room.png' \
  --form 'prompt=Turn this photo into a night scene' \
  --form 'size=2K'
```
**Base64 内联{Inline Base64}::cURL**
```
curl --request POST \
  --url 'https://api.oairoute.com/v1/images/edits' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "doubao-seedream-5-0-pro-260628",
  "prompt": "换成纯白背景",
  "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...",
  "size": "2K"
}'
```
**Base64 内联{Inline Base64}::JavaScript**
```
import { readFileSync } from "node:fs";

const data = readFileSync("photo.png").toString("base64");
const res = await fetch("https://api.oairoute.com/v1/images/edits", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "doubao-seedream-5-0-pro-260628",
    prompt: "换成纯白背景",
    image: `data:image/png;base64,${data}`,
    size: "2K",
  }),
});
console.log(await res.json());
```
**200 公网 URL 引用{Public URL}**
```
{
  "data": [
    {
      "url": "https://ark-content-generation-v2-cn-beijing.tos-cn-beijing.volces.com/seedream/xxx.jpeg",
      "size": "2048x2048",
      "output_format": "jpeg"
    }
  ],
  "created": 1757469067,
  "usage": { "generated_images": 1, "input_images": 1, "output_tokens": 15908, "total_tokens": 15908 }
}
```
**200 Base64 内联{Inline Base64}**
```
{
  "data": [
    {
      "url": "https://ark-content-generation-v2-cn-beijing.tos-cn-beijing.volces.com/seedream/edit-xxx.jpeg",
      "size": "2048x2048",
      "output_format": "jpeg"
    }
  ],
  "created": 1757469067,
  "usage": { "generated_images": 1, "input_images": 1, "output_tokens": 15908, "total_tokens": 15908 }
}
```
**200 本地文件编辑{Multipart upload}**
```
{
  "data": [
    {
      "url": "https://ark-content-generation-v2-cn-beijing.tos-cn-beijing.volces.com/seedream/edit-upload.jpeg",
      "size": "2048x2048",
      "output_format": "jpeg"
    }
  ],
  "created": 1757469067,
  "usage": { "generated_images": 1, "input_images": 1, "output_tokens": 15908, "total_tokens": 15908 }
}
```