Janvia

API reference

Upload to your storage

Give a presigned upload URL per file and we put the results straight into your own bucket: R2, S3, GCS, Azure, OSS or COS.

By default a task's files stay on our storage and output.files[].url points there. We keep them for 24 hours after the task completes, then delete them and their URLs stop working. To have them land in your own bucket instead, sign an upload URL for each file in your backend and pass the URLs as upload when you submit. We upload the files as soon as the task completes, then delete our copies.

We never hold keys to your storage: a presigned URL lets us write that one object, and only until it expires. Anything that takes an HTTP PUT to a URL works: Cloudflare R2, AWS S3, Google Cloud Storage, Azure Blob Storage, Alibaba Cloud OSS, Tencent Cloud COS, or an endpoint of your own. Uploading costs nothing.

Without upload, nothing changes: the files stay on our storage.

Submit with 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 lists 1–4 targets. The task's first file goes to the first target, the second to the second, and so on:

  • url (required): an https URL that accepts a PUT of the file, at most 4096 characters.
  • public_url (optional): where the file can be read once it is uploaded, such as your bucket's custom domain. We show it instead of url. R2's presigned URLs only work on the r2.cloudflarestorage.com domain, so this is how your own domain shows up in the task.
  • headers (optional): headers to send with the PUT, for those you signed into the URL, such as {"Content-Type": "image/png"} or {"x-amz-acl": "public-read"}. Up to 10 of: Content-Type, Cache-Control, Content-Disposition, Content-Language, and x-amz-*, x-goog-*, x-ms-*, x-oss-*, x-cos-*.

Give one target per file the task makes: input.count for images (1 when not set), usually one for video and audio. If the task makes fewer files than there are targets, the extra targets are skipped; files beyond the last target stay with us.

Signing the URLs

Sign a PUT (not a form POST) for each object key, valid long enough to cover the queue and the generation. 24 hours is a good choice; the maximum on S3 and R2 is 7 days. A URL with less than 5 minutes left is refused at submit.

Content-Type: if you don't sign one, we send the file's real type (image/png, video/mp4 and so on). If you do, pass the same value in headers. When it doesn't match the file (you signed image/webp and the model made a PNG), that file isn't uploaded and stays with us.

Cloudflare R2 with Node.js (@aws-sdk/client-s3 and @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,
  },
  // Required: otherwise the SDK signs the checksum of an empty body into
  // the URL, and no upload can match it.
  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}` }] },
  }),
});

For AWS S3, give your bucket's region and leave out endpoint. Since version 3.729.0 the SDK adds checksums by default: keep requestChecksumCalculation: 'WHEN_REQUIRED', or we refuse the URL at submit.

Python (boto3), the same for R2 and S3:

import boto3
from botocore.config import Config

s3 = boto3.client(
    's3',
    endpoint_url=f'https://{ACCOUNT_ID}.r2.cloudflarestorage.com',  # leave out for AWS S3
    aws_access_key_id=R2_ACCESS_KEY_ID,
    aws_secret_access_key=R2_SECRET_ACCESS_KEY,
    region_name='auto',
    # botocore 1.36+ adds checksums by default; older versions don't need this.
    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,
)

Other storage:

  • Google Cloud Storage: a V4 signed URL for PUT. If you set a content type when signing, pass the same Content-Type in headers.
  • Azure Blob Storage: a SAS URL for the blob with write permission. We add the x-ms-blob-type: BlockBlob header Azure requires.
  • Alibaba Cloud OSS, Tencent Cloud COS: a presigned PUT URL from their SDK. Their S3-compatible endpoints work like the examples above. OSS V1 signatures (the URL has OSSAccessKeyId=) sign an empty Content-Type, so we send none.

How it runs

  1. The task runs and is charged as usual.
  2. When it completes, we upload its files. Meanwhile the task stays in_progress with progress 99, and upload.status is uploading. It no longer counts toward your running-task limit.
  3. A PUT that may pass later is tried again after 10 seconds, 1 minute, 5 minutes and 30 minutes: no answer, a 408, 429 or 5xx, or a RequestTimeout or SlowDown error. Any other answer is final for that file: an expired URL, a bad signature, access denied, or a redirect (we don't follow them).
  4. When every file is done, the task becomes completed and then its callback goes out, so the callback carries the result.

Uploaded files are deleted from our storage. A file that couldn't be uploaded stays with us, at our URL, and like any file we store it is kept for only 24 hours: download it before then. An upload never fails a task or refunds it. If the task itself fails, nothing is uploaded and upload.status is skipped.

The upload field

"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: where each file is now. Your public_url (or the target URL without its signature) once uploaded, our URL otherwise.
  • upload.status: waiting (the task is running), uploading, uploaded (every file), partial (some), failed (none) or skipped (the task failed).
  • upload.files[]: one per target, in order. status is pending, uploaded, failed or skipped (the task made no file for this target). url is your public_url, or the target URL without its query string: we never show a signature back, and we delete the targets once the upload is over.
  • upload.files[].error: why the file didn't go up: HTTP <status> followed by your storage's error code when it sent one, url_expired, content_type_mismatch, timeout, connection_failed, source_unavailable or host_not_allowed.
  • upload.attempts: how many rounds ran.

As always, wait for status: "completed" before reading output. A callback only arrives after the upload.

Retries with an Idempotency-Key

A retry with the same Idempotency-Key may carry freshly signed URLs: only where the files go has to match (each URL without its query string). A retry that sends them elsewhere returns 409 idempotency_conflict. A replayed task keeps the first request's URLs.