Media capabilities

Generate images

Create text-to-image and reference-guided image jobs without holding an HTTP connection open. Byta reserves credits when the job is accepted, processes it in the background, and stores completed outputs as private account files.

Asynchronous and idempotent

Catalog last synchronized: October 3, 2026 (UTC)

Asynchronous workflow

Every image generation uses the same durable three-step lifecycle.

Submit

POST a prompt and receive HTTP 202 with a job ID.

Poll

GET the status URL every 2–5 seconds until terminal.

Download

Fetch each private images[].url with the same Bearer key.

Models and pricing

Prices are credits per completed image. Reference-guided pricing applies whenever at least one reference image is used.

Model	Best for	T2I	Reference	Max refs	Runtime
`byta-image-1-5`	Our signature default model for reliable everyday image generation.	16	16	Up to 5	~30s / ~45s
`byta-image-1-5-pro`	Flagship high-resolution model with exceptional detail and precision.	25	30	Up to 5	~80s / ~100s
`byta-image-1-6-pro`	Premium image generation with a choice of quality-focused or accelerated inference.	60	60	Up to 5	~150s / ~180s
`byta-image-1-5-turbo`	Fast text-to-image model for reliable everyday results.	12	Not supported	None	~18s

Which model should I use?

Need	Choose	Trade-off
Current default	`byta-image-1-5`	Our signature default model for reliable everyday image generation.
Alternative active model	`byta-image-1-5-pro`	Flagship high-resolution model with exceptional detail and precision.
Alternative active model	`byta-image-1-6-pro`	Premium image generation with a choice of quality-focused or accelerated inference.
Alternative active model	`byta-image-1-5-turbo`	Fast text-to-image model for reliable everyday results.

Configuration

Use aspectRatio for direct control or an OpenAI-style size alias. Unknown values normalize to auto.

Aspect ratios

These are all accepted aspectRatio values for the public image endpoint.

Value	Shape	Good for
`auto`	Model-selected	Letting the model choose from the prompt.
`16:9`	Wide landscape	Hero images, presentations, cinematic scenes.
`9:16`	Tall portrait	Stories, reels, mobile-first artwork.
`3:2`	Landscape photo	Photography and editorial compositions.
`2:3`	Portrait photo	Posters, covers, full-body portraits.
`1:1`	Square	Thumbnails, product shots, social posts.

OpenAI-style size aliases

When both size and aspectRatio are supplied, the explicit aspectRatio field wins.

size	Resolved aspect ratio
`auto`	`auto`
`1024x1024`	`1:1`
`1536x1024`	`3:2`
`1792x1024`	`16:9`
`1024x1536`	`2:3`
`1024x1792`	`9:16`

Image count

Use n or imageCount. The endpoint accepts 1–10, although an active site policy may temporarily cap one job to a single output.

Create an image job

Send a unique Idempotency-Key for each logical generation. Reuse that key only when retrying the same request.

POST/v1/images/generations

Returns 202 Accepted

Text-to-image

import os
import requests

response = requests.post(
    "https://api.byta-ai.com/v1/images/generations",
    headers={
        "Authorization": f"Bearer {os.environ['BYTA_API_KEY']}",
        "Idempotency-Key": "campaign-hero-001",
    },
    json={
        "model": "byta-image-1-5",
        "prompt": "A cobalt glass perfume bottle on black stone, soft rim light",
        "size": "1792x1024",
        "n": 1,
    },
)
response.raise_for_status()
job = response.json()
print(job["statusUrl"])

202 Accepted · JSON

{
  "id": "9d8f0c7a2b4e4c96a3819a2a2f1e6d12",
  "jobId": "9d8f0c7a2b4e4c96a3819a2a2f1e6d12",
  "object": "image_generation",
  "status": "running",
  "statusUrl": "https://api.byta-ai.com/v1/images/generations/9d8f0c7a2b4e4c96a3819a2a2f1e6d12",
  "creditsReserved": 20,
  "modelId": "byta-image-1-5",
  "modelName": "Byta-Image-1.5"
}

Poll and download

GET/v1/images/generations/{jobId}

cURL · job status

curl https://api.byta-ai.com/v1/images/generations/9d8f0c7a2b4e4c96a3819a2a2f1e6d12 \
  -H "Authorization: Bearer $BYTA_API_KEY"

200 OK · completed

{
  "id": "9d8f0c7a2b4e4c96a3819a2a2f1e6d12",
  "object": "image_generation",
  "status": "completed",
  "creditsCharged": 20,
  "images": [
    {
      "id": "3b42f8c04ca84b29af927a486f40f18e",
      "mimeType": "image/jpeg",
      "sizeBytes": 1842032,
      "url": "https://api.byta-ai.com/v1/images/generations/9d8f.../files/3b42..."
    }
  ]
}

Terminal states

Stop polling when status becomes completed or failed. Active credit holds settle on completion and release on ordinary failure.

Status	Meaning	Client action
`running`	Generation or storage is still in progress.	Poll again in 2–5 seconds.
`completed`	Private image files are ready.	Download every images[].url.
`failed`	The job reached a terminal error.	Read error; retry only when appropriate.

Use reference images

Use an owned Studio file, a public image URL, or an inline base64 image. Generated images[].id values can be reused as references immediately.

cURL · reference edit

curl https://api.byta-ai.com/v1/images/generations \
  -H "Authorization: Bearer $BYTA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: reference-edit-001" \
  -d '{
    "modelId": "byta-image-1-5",
    "prompt": "Preserve the product and label; move it into a warm sandstone spa.",
    "aspectRatio": "1:1",
    "imageCount": 1,
    "input_reference": {"file_id": "owned_file_id"}
  }'

Accepted reference sources

JSON · accepted reference shapes

// Existing image uploaded to Byta Studio
{"input_reference": {"file_id": "owned_image_file_id"}}

// Publicly reachable image
{"input_reference": {"image_url": "https://cdn.example.com/reference.jpg"}}

// Inline base64 image
{"input_reference": {"image_url": "data:image/jpeg;base64,/9j/4AAQ..."}}

Source	Field	Behavior
Byta Studio upload	`file_id`	Must be owned by the API-key account.
Public image	`image_url`	Fetched through SSRF-safe public HTTP(S) validation.
Inline image	`image_url`	Base64 data URI decoded and verified before import.

Import and ownership

file_idmust identify an existing Byta Studio image owned by the API-key account. Public URLs and base64 data URIs are verified, imported into that account's Studio storage, and count toward its upload quota. JPEG, PNG, and WebP inputs up to 20 MiB are accepted. Use referenceFileIds when the selected model supports multiple owned references.

API reference

promptrequired

string

Description of the image to create or edit.

modeloptional

string

Public image model ID. modelId is also accepted.

noptional

integer

Number of images. imageCount is also accepted.

sizeoptional

string

OpenAI-style widthxheight alias. aspectRatio is also accepted.

input_referenceoptional

object

Exactly one file_id or image_url. image_url accepts a public HTTP(S) URL or base64 data URI.

referenceFileIdsoptional

string[]

Owned input files for reference-guided generation.

GET/v1/images/generations/{jobId}/files/{fileId}

Add ?download=1 for attachment disposition

Errors

Public API failures use a structured error object. Input-validation errors are safe to fix and resubmit with a new logical idempotency key.

Code	Meaning	What to do
`invalid_input_reference`	input_reference is malformed or ambiguous.	Send exactly one file_id or image_url.
`unsafe_reference_url`	URL resolves to a non-public address.	Use a publicly reachable image host.
`invalid_reference_image`	Downloaded or decoded bytes are not a valid image.	Send a valid JPEG, PNG, or WebP.
`reference_image_too_large`	Reference exceeds 20 MiB.	Resize or recompress the image.
`reference_import_failed`	The account cannot store the imported reference.	Check upload quota and account storage.
`insufficient_credits`	The account cannot reserve the job price.	Add credits or select a lower-cost model.