接口
上传到你的存储
每个文件给一个预签名上传地址,生成结果直接存进你自己的桶:R2、S3、GCS、Azure、OSS、COS 都行。
默认情况下,任务生成的文件存在我们这里,output.files[].url 指向我们的地址;任务完成后保留 24 小时,过期删除,链接随之失效。想让文件直接进你自己的桶:在你的后端为每个文件签一个上传地址,提交任务时放进 upload。任务一完成我们就把文件传过去,然后删掉我们这份。
我们不保存你存储的任何密钥:预签名地址只能写那一个文件,过期就失效。只要能接收 HTTP PUT 的地址都可以:Cloudflare R2、AWS S3、Google Cloud Storage、Azure Blob Storage、阿里云 OSS、腾讯云 COS,或者你自己的接口。上传不收费。
不传 upload 就和以前一样,文件存在我们这里。
提交时带上 upload
{
"model": "gpt-image-2",
"input": { "prompt": "a red fox in the snow", "count": 2 },
"upload": {
"files": [
{
"url": "https://ACCOUNT_ID.r2.cloudflarestorage.com/my-bucket/foxes/1.png?X-Amz-Algorithm=...",
"public_url": "https://img.example.com/foxes/1.png"
},
{
"url": "https://ACCOUNT_ID.r2.cloudflarestorage.com/my-bucket/foxes/2.png?X-Amz-Algorithm=...",
"public_url": "https://img.example.com/foxes/2.png"
}
]
}
}upload.files 列 1–4 个目标,任务的第 1 个文件传到第 1 个目标,第 2 个传到第 2 个,依此类推:
url(必填):能接收文件PUT的 https 地址,最长 4096 个字符。public_url(可选):文件上传后的访问地址,比如你桶的自定义域名。任务里显示它,不显示url。R2 的预签名地址只能用r2.cloudflarestorage.com域名,所以想在任务里看到自己的域名,就填这个。headers(可选):PUT时要带的 Header,用于你签进地址里的那些,比如{"Content-Type": "image/png"}或{"x-amz-acl": "public-read"}。最多 10 个,只能是Content-Type、Cache-Control、Content-Disposition、Content-Language,以及x-amz-*、x-goog-*、x-ms-*、x-oss-*、x-cos-*。
任务出几个文件就给几个目标:图片是 input.count(没填就是 1),视频和音频通常是 1 个。文件比目标少时,多出来的目标跳过;文件比目标多时,多出来的文件留在我们这里。
怎么签名
为每个文件路径签一个 PUT(不是表单 POST),有效期要够排队加生成的时间。建议签 24 小时,S3 和 R2 最长 7 天。剩余有效期不到 5 分钟的地址,提交时直接拒绝。
Content-Type:签名时没签,我们按文件的实际类型发(image/png、video/mp4 等);签了的话,在 headers 里传同样的值。如果和文件对不上(比如签的是 image/webp,模型出的是 PNG),这个文件不上传,留在我们这里。
Cloudflare R2,Node.js(@aws-sdk/client-s3 和 @aws-sdk/s3-request-presigner):
import { PutObjectCommand, S3Client } from '@aws-sdk/client-s3';
import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
const s3 = new S3Client({
region: 'auto',
endpoint: `https://${ACCOUNT_ID}.r2.cloudflarestorage.com`,
credentials: {
accessKeyId: R2_ACCESS_KEY_ID,
secretAccessKey: R2_SECRET_ACCESS_KEY,
},
// 必须加:否则 SDK 会把空文件的校验值签进地址,任何上传都对不上。
requestChecksumCalculation: 'WHEN_REQUIRED',
});
const key = `foxes/${crypto.randomUUID()}.png`;
const url = await getSignedUrl(
s3,
new PutObjectCommand({ Bucket: 'my-bucket', Key: key }),
{ expiresIn: 24 * 3600 }
);
const response = await fetch('https://api.janvia.io/v1/tasks', {
method: 'POST',
headers: {
Authorization: `Bearer ${API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
model: 'gpt-image-2',
input: { prompt: 'a red fox in the snow' },
upload: { files: [{ url, public_url: `https://img.example.com/${key}` }] },
}),
});AWS S3 的话,region 填桶所在区域,不要 endpoint。SDK 从 3.729.0 版起默认加校验值,requestChecksumCalculation: 'WHEN_REQUIRED' 一定要留着,否则提交时会被拒绝。
Python(boto3),R2 和 S3 写法一样:
import boto3
from botocore.config import Config
s3 = boto3.client(
's3',
endpoint_url=f'https://{ACCOUNT_ID}.r2.cloudflarestorage.com', # AWS S3 不要这一行
aws_access_key_id=R2_ACCESS_KEY_ID,
aws_secret_access_key=R2_SECRET_ACCESS_KEY,
region_name='auto',
# botocore 1.36 起默认加校验值;更早的版本不需要这一项。
config=Config(signature_version='s3v4', request_checksum_calculation='when_required'),
)
url = s3.generate_presigned_url(
'put_object',
Params={'Bucket': 'my-bucket', 'Key': 'foxes/1.png'},
ExpiresIn=24 * 3600,
)其它存储:
- Google Cloud Storage:签一个
PUT用的 V4 签名地址。签名时指定了 content type,就在headers里传同样的Content-Type。 - Azure Blob Storage:给这个 blob 签一个带写权限的 SAS 地址。Azure 要求的
x-ms-blob-type: BlockBlob我们会自动加上。 - 阿里云 OSS、腾讯云 COS:用它们的 SDK 签
PUT预签名地址;它们的 S3 兼容接口也可以照上面的例子来。OSS V1 签名(地址里有OSSAccessKeyId=)会把空的 Content-Type 签进去,这种情况我们不发 Content-Type。
执行过程
- 任务照常运行、照常扣费。
- 任务完成后开始上传。上传期间任务仍是
in_progress,progress为 99,upload.status是uploading;这时它已不占你的"运行中任务"名额。 - 可能过一会儿就能成功的失败,会在 10 秒、1 分钟、5 分钟、30 分钟后重试:没有响应、408、429、5xx,或
RequestTimeout、SlowDown错误。其它失败对这个文件就是最终结果:地址过期、签名不对、没有权限,或者跳转(我们不跟随跳转)。 - 所有文件都有结果后,任务变成
completed,然后才发回调,所以回调里就是最终结果。
传成功的文件会从我们这里删除。传失败的文件留在我们这里,用我们的地址访问,和其它生成文件一样只保留 24 小时,请在这之前下载。上传失败不会让任务失败,也不会退款。如果任务本身失败,就什么都不传,upload.status 是 skipped。
upload 字段
"output": {
"files": [
{
"type": "image",
"url": "https://img.example.com/foxes/1.png",
"mime_type": "image/png",
"width": 1024,
"height": 1024
},
{
"type": "image",
"url": "https://api.janvia.io/v1/tasks/task_9f2c.../content/1",
"mime_type": "image/png",
"width": 1024,
"height": 1024
}
]
},
"upload": {
"status": "partial",
"attempts": 1,
"files": [
{
"status": "uploaded",
"url": "https://img.example.com/foxes/1.png",
"error": null
},
{
"status": "failed",
"url": "https://img.example.com/foxes/2.png",
"error": "HTTP 403 SignatureDoesNotMatch"
}
]
}output.files[].url:每个文件现在在哪。传成功的是你的public_url(没填就是去掉签名的目标地址),没传成功的是我们的地址。upload.status:waiting(任务还在运行)、uploading、uploaded(全部成功)、partial(部分成功)、failed(全部失败)或skipped(任务失败了)。upload.files[]:每个目标一项,顺序和提交时一样。status是pending、uploaded、failed或skipped(任务没有对应这个目标的文件)。url是你的public_url,没填就是去掉查询参数的目标地址:我们从不回显签名,上传结束后也会删掉保存的目标地址。upload.files[].error:没传上去的原因:HTTP <状态码>,你的存储返回了错误代码时会附在后面;或者url_expired、content_type_mismatch、timeout、connection_failed、source_unavailable、host_not_allowed。upload.attempts:一共跑了几轮上传。
和平时一样,等 status 变成 completed 再读 output。回调只会在上传结束后到达。
带 Idempotency-Key 重试
用同一个 Idempotency-Key 重试时,可以换成重新签名的地址:只要文件去的地方一样(地址去掉查询参数后相同)就算同一个请求。换了路径会返回 409 idempotency_conflict。重放返回的任务仍用第一次请求的地址。