Buckets

Working with buckets

A bucket is a label attached to each image. Use them to separate generations by Discord server, customer, project, or anything else you want to filter on later.

How buckets work

• Every image belongs to exactly one bucket. If you don't pass bucket, it goes into default.
• Buckets are created automatically the first time you use them — no setup endpoint required.
• Buckets are scoped to your account. Two different users can both have a bucket called memes without conflict.
• You can browse and toggle bucket visibility on the public gallery from the gallery page.

Naming rules

Bucket names are normalized server-side. The final stored name always matches /^[a-z0-9-]+$/ and is at most 64 characters.

• Lowercased.
• Trimmed.
• Any run of non-alphanumerics becomes a single -.
• Leading and trailing dashes are stripped.
• Truncated to 64 characters.

Examples

"Cats And Dogs"      → "cats-and-dogs"
"client_acme/v2"     → "client-acme-v2"
"  HELLO  "          → "hello"
"!!!"                → 400 (must contain at least one alphanumeric)

Putting an image into a bucket

Pass bucket when creating an image. See Creating images for the full schema.

POST https://qaves.me/api/v1/images/generations
Authorization: Bearer sk_qu_YOUR_KEY
Content-Type: application/json

{
  "model": "gpt-image-2",
  "prompt": "A neon orange fox",
  "bucket": "client-acme"
}

Reading images from a bucket

Use the listing endpoint with ?bucket=. See Listing images for query params and pagination.

GET https://qaves.me/api/v1/images/generations?bucket=client-acme&limit=50
Authorization: Bearer sk_qu_YOUR_KEY

Common patterns

One bucket per Discord server

{
  "model": "gpt-image-2",
  "prompt": userPrompt,
  "bucket": interaction.guildId
}

One bucket per customer or project

Use a stable identifier (database ID, slug) so you can later list all images you've generated for that customer.

{ "bucket": `customer-${customerId}` }