Janvia

接口

上传到你的存储

每个文件给一个预签名上传地址,生成结果直接存进你自己的桶: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。

执行过程

  1. 任务照常运行、照常扣费。
  2. 任务完成后开始上传。上传期间任务仍是 in_progress,progress 为 99,upload.status 是 uploading;这时它已不占你的"运行中任务"名额。
  3. 可能过一会儿就能成功的失败,会在 10 秒、1 分钟、5 分钟、30 分钟后重试:没有响应、408、429、5xx,或 RequestTimeout、SlowDown 错误。其它失败对这个文件就是最终结果:地址过期、签名不对、没有权限,或者跳转(我们不跟随跳转)。
  4. 所有文件都有结果后,任务变成 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。重放返回的任务仍用第一次请求的地址。