Depicta Support
Overview
Depicta Public API 1.0.0
Section titled “ Depicta Public API 1.0.0 ”Depicta Public API
Depicta is an API-first generative image service. Generate images, edit them, create multi-scene stories, and process images for a small fixed price per operation — all through a simple REST API.
Authentication
Every request (except /health, /v1/openapi.yaml, /v1/openapi.json, /v1/pricing, /v1/verify and /v1/verify/keys) requires a
Bearer token in the Authorization header. API keys start with the dpct_
prefix:
Authorization: Bearer dpct_a1B2c3D4e5F6g7H8i9J0k1L2m3N4o5P6q7R8s9T0u1VCreate keys in the dashboard (API Keys, or a skill file download, which embeds
one). An API key can create, edit, combine and process images, run stories,
upload input images, list models and skill files, search guidelines and read
your profile and balance. Everything that manages the account (keys, billing,
settings, data export, closure) needs a dashboard session: an API key gets
403 auth_session_required there.
/v1/verify, the free check for Depicta’s AI marks, takes an API key or, from the page at https://depicta.ai/verify, a Cloudflare Turnstile token instead.
Image Generation Workflow
- POST one of the generation endpoints (e.g. /v1/generate/image) with a prompt, model, and optional parameters.
- The response includes a signed URL (valid for 1 hour) pointing to the generated image, the cost charged, and your remaining balance.
- Download or display the image before the URL expires.
Every generation response includes an X-Depicta-Job-Id header. If the response is lost (network error, timeout), use GET /v1/jobs to find your recent generations — the result will be there once the generation completes.
Story Workflow (Async)
Multi-scene story generation runs asynchronously:
- POST /v1/generate/story — returns HTTP 202 with a job_id and poll URL.
- GET /v1/jobs/{id} — poll until status is “completed” or “failed”. The response includes scenes_completed/scenes_total for progress.
- On completion, the result field contains signed URLs for each scene image.
Credits
- Prices and charges are in credits: EUR, excluding VAT (VAT is added when you buy credits).
- Image generation costs credits. The exact cost depends on the model and is returned in every generation response.
- Image processing (crop, resize, convert, optimize, remove-background and
the rest) costs a fixed price per operation:
processing_cost_eurin GET /v1/pricing, or its override inprocessing_operation_costs(vectorize). - Credits expire 12 months after your last paid top-up. Free trial and admin-granted credits do not reset the expiry clock.
- Check your balance via the dashboard or the account profile endpoint.
Error Handling
All errors return a JSON object with this shape:
{
"error": "validation_error",
"message": "The request contains invalid or missing fields.",
"details": {"prompt": "required"},
"request_id": "req_a1b2c3d4e5f60708"
}Error Code Catalog
| Code | HTTP | Description |
|---|---|---|
| auth_missing_api_key | 401 | No API key provided |
| auth_invalid_api_key | 401 | API key is invalid or revoked |
| auth_revoked_api_key | 401 | API key has been revoked |
| auth_account_suspended | 403 | Account suspended |
| auth_session_required | 403 | Dashboard session needed; API keys not accepted |
| auth_email_not_verified | 403 | Email verification required |
| generation_paused | 403 | Generation paused pending review |
| rate_limit_exceeded | 429 | Too many concurrent requests |
| credit_insufficient_balance | 402 | Not enough credits |
| credit_expired | 402 | Credits have expired |
| model_not_available | 400 | Requested model is not available |
| model_restricted | 402 | Model requires higher credit balance |
| model_not_allowed | 403 | Model not in your allowed_models preference |
| model_not_capable | 422 | Model does not support this operation |
| content_rejected | 451 | Content violates usage policy |
| model_content_rejected | 451 | Model returned no image; nothing charged |
| output_withheld | 451 | Generated image withheld by our check; no charge |
| classifier_unavailable | 503 | Content moderation service temporarily down |
| validation_error | 422 | Invalid or missing fields (see details) |
| input_image_unreachable | 422 | Input/reference image URL could not be fetched |
| not_found | 404 | Resource not found |
| internal_error | 500 | Unexpected server error |
| upstream_error | 502 | Upstream model rejected request (not retryable) |
| service_unavailable | 503 | Service temporarily unavailable |
input_image_unreachable means the gateway could not download an input or
reference image before checking it. The message and details name the field
(e.g. input_image_urls[1]) and the reason: blocked_address (private or
internal address), http_status (the host answered an error such as 403 or
404), timeout, too_large (over 50 MB, or a request’s images over 100 MB
together), not_an_image (not PNG, JPEG, WebP or GIF) or connection_failed.
A story’s references are named by position (e.g. characters[0].reference_url,
locations[1].reference_url). Fix the URL or upload the image with POST /v1/upload;
retrying unchanged will fail again. No credits are charged.
validation_error (422) also answers an input image the content check cannot
use, with one of these messages:
- “An input image could not be read. Send a PNG, JPEG, WebP or GIF file.” The file is damaged, or in another format.
- “An input image is too large: the limit is 40 megapixels.”
- “An input image is too narrow or too wide: the limit is 4:1.”
- “Animated images are not supported. Send a single still image.” (an animated GIF, PNG or WebP)
- “An input image cannot be checked in this encoding. Re-save it as a baseline JPEG or a PNG.” (some 16-bit, interlaced, progressive or CMYK files)
- “The input images are too large to check together.” Up to 10 images are always checked together; send fewer or smaller images.
When one image is at fault, details names its field (e.g. input_image_urls[1],
or image for POST /v1/upload). Retrying unchanged will fail again. No credits
are charged.
Rate Limits
Each limit counts requests in progress per account, from the request until its answer (for a story, until its job is completed or failed):
- 10 generation requests.
- 5 processing requests (/v1/process/*), a pool of their own.
- 3 uploads (POST /v1/upload). The CLIs upload reference and input images this way before a generation starts, so at most 3 such runs can upload at once.
- 3 stories, counted from POST /v1/generate/story until the story’s job is completed or failed.
- Exceeding a limit returns HTTP 429 rate_limit_exceeded with a Retry-After header; the message names the limit. A 429 is never charged: wait the Retry-After seconds and retry.
- /v1/verify has its own limits: per account with an API key, per address from the page. Over a limit it answers 429 with a Retry-After header.
Authentication
Section titled “ Authentication ”ApiKeyAuth
Section titled “ ApiKeyAuth ”API key with dpct_ prefix. Pass as: Authorization: Bearer dpct_…
Security scheme type: http
UploadTokenAuth
Section titled “ UploadTokenAuth ”An upload token (dpup_…) from Depicta’s picture picker. Valid only on POST /v1/upload; agents use an API key.
Security scheme type: http