Use files with Compute

What works today

Neither upload step is open. POST /v1/artifacts/prepare and POST /v1/artifacts/complete both return 503 UNAVAILABLE, so no input file can be registered yet. The shape below is settled; the endpoints are not serving.

Files are never inline

Your request body is capped at 64 KiB, and input never travels inside it. A file becomes an artifact first, and your job references it by artifact_id.

That indirection is the whole design. Compute's control plane holds metadata and encrypted bytes — not your content. An executor may hold plaintext in working memory while it does the work, but nothing in the submission path carries readable content.

The two steps

1. Prepare. Declare the artifact's size, chunk count, and data profile. You get back an artifact_id, an upload target, a chunk size, and an expiry.
2. Complete. Seal it by supplying the manifest digest and chunk root digest. After this the artifact_id is a stable reference you can put in a job.

Uploads are chunked and each chunk is digested, so a partial or reordered upload is detected rather than silently accepted.

What metadata travels

An artifact carries deliberately little about itself: a stable id, a modality, the ciphertext size and digest, a chunk count, an expiry, and a small set of public bounds.

The modality is one of text, image, audio, video, document, or archive.

The public bounds describe shape without describing content — duration, frame count, page count, image count, a pixel budget, audio channels, and a sample-rate bucket. These exist so a capability can be matched and priced without anything reading the file.

What must never travel

Do not send a filename. The metadata contract is explicitly public-bounds-only and carries no customer content and no filename. This is the single most common first-attempt mistake, because every other file API in the world takes one. There is no field for it; sending one is a rejected unknown field.

For the same reason, do not put content, identifiers, or descriptive text into any metadata field. If something in your request looks like a secret, the request is refused with CREDENTIAL_DETECTED rather than stored.

Size, and where it actually binds

Three different ceilings apply, and they are not the same number. The one that binds you is the smallest:

• The transport layer accepts very large artifacts — this is not your constraint.
• The artifact contract permits up to 1 GiB.
• The capability you are calling permits 4 MiB, 8 MiB, or 16 MiB depending on which one it is.

So the capability's max_ciphertext_bytes is the real limit, and it is well below what the surrounding layers allow. For long audio or video this is a genuine constraint today: the artifact contract can describe a recording hours long, while no current capability accepts an input that size. If your media exceeds the capability's ceiling, segment it and submit the parts as separate jobs.

Related

• Capabilities — the per-capability limits that bind your file
• Submit work — how a job references an artifact
• Errors — what an oversized or malformed artifact returns