Generate

Generate creates new visuals from a text prompt. There are three content types, each with its own endpoint and optimized prompt handling.

depicta uvx depicta npx depicta

Content types

Image

Photos, illustrations, artistic renders, concept art, and backgrounds.

depicta image "A sunset over Greek mountains, warm golden light, oil painting style"

curl

curl -X POST https://api.depicta.ai/v1/generate/image \
  -H "Authorization: Bearer dpct_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 900 \
  -d '{"prompt": "A sunset over Greek mountains, warm golden light"}'

Python

response = httpx.post(
    "https://api.depicta.ai/v1/generate/image",
    headers={"Authorization": "Bearer dpct_YOUR_API_KEY"},
    json={"prompt": "A sunset over Greek mountains, warm golden light"},
    timeout=900,  # generations can take several minutes
)

Graphic

Icons, logos, clipart, and UI elements. Optimized for non-photorealistic, clean-edged output.

depicta graphic "A minimal rocket icon, white on a solid navy background, 256x256"

Graphics come on a solid background. For a transparent one, run process remove-bg afterwards, or color-to-alpha for a flat background.

API endpoint: POST /v1/generate/graphic

Diagram

Flowcharts, architecture diagrams, ER diagrams, sequence diagrams, and more. Use --type to specify the diagram style.

depicta diagram "User authentication flow with OAuth and email" --type flowchart

API endpoint: POST /v1/generate/diagram

Available diagram types: flowchart, sequence, architecture, mindmap, er, class, timeline, org-chart

Options

Model selection

model is optional. Without it, the API uses your default model if it can handle the request, otherwise the recommended model for the operation: mai-fast for images, mai for graphics and diagrams, gemini for edit, combine and story. The response’s model field names the model used. To choose explicitly:

depicta image "A mountain landscape" --model mai-fast

{"prompt": "A mountain landscape", "model": "mai-fast"}

See Models for the full list with capabilities and pricing.

Aspect ratio

depicta image "A hero banner" --size 16:9

Use one of the model’s aspect_ratios (or fixed_sizes) from GET /v1/models. Any other value is refused with 422 validation_error before anything is charged. For example:

Models	Ratios
gemini, gemini-pro, gemini-fast	1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9
mai, mai-fast	1:1, 2:3, 3:2, 3:4, 4:3, 9:16, 16:9
Named only: seedream (processed in Malaysia by a ByteDance company; filtered content kept up to 180 days)	1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9
Named only: gpt-image, gpt-image-pro (OpenAI keeps inputs for up to 30 days, or longer where the law requires; avoid for photos of people.)	1:1, 2:3, 3:2, 3:4, 4:3, 9:16, 16:9, 21:9

Image size

depicta image "A product photo" --model gemini --image-size 2K

Size tiers depend on the model (image_sizes in GET /v1/models). Omit image_size to get the model’s default size; larger sizes cost more. A size the model doesn’t list is refused with 422 validation_error before anything is charged.

Model	Sizes
gemini	1K, 2K, 4K
gemini-pro	1K, 2K
gemini-fast	1K
mai, mai-fast	No size tiers — sending image_size returns 422 validation_error
Named only: seedream (processed in Malaysia by a ByteDance company; filtered content kept up to 180 days)	2K
Named only: gpt-image, gpt-image-pro (OpenAI keeps inputs for up to 30 days, or longer where the law requires; avoid for photos of people.)	No size tiers — sending image_size returns 422 validation_error

Reference images

Anchor style or composition with up to 5 reference images. The limit depends on the model: mai and mai-fast accept one image in total. The default models for images, graphics and diagrams are MAI models, so when you send more than one reference, choose a model that accepts them (for example, --model gemini):

depicta image "A product photo in this style" --reference brand-guide.png:"Brand color palette and style"

{
  "prompt": "A product photo in this style",
  "reference_images": [
    {"url": "https://example.com/brand-guide.png", "description": "Brand color palette and style"}
  ]
}

Connection drops and retries

Generations usually take 60–120 seconds and sometimes up to 5 minutes; the server limit is 12 minutes. If you call the API directly, set your HTTP timeout to at least 15 minutes.

Once a generation request is accepted, it cannot be cancelled. Even if your connection drops, the image will be generated and available for download for one hour. Do not resend the request — a new request is a new, separately charged generation. The CLIs re-download the result using the job ID; if the request itself is interrupted, they point you to depicta jobs list to find it.

If you’re using the API directly, the job ID is returned in the x-depicta-job-id response header. Use GET /v1/jobs/{id} to retrieve the result after a disconnection.

Failed generations are not charged. If the model returns no image, you get 451 model_content_rejected and nothing is charged: try again, or pick another model.

Response format

All generate endpoints return the same structure. See API getting started for the full response schema.