Avelika API
Public API V1 · OpenAPI 3.1

Build product visuals from your backend.

The LIVE API shares Avelika Workspace ownership, generation admission, jobs and credit accounting. Start with zero-provider TEST validation before using the commercial PHOTO endpoint.

Bearer API keyPHOTO onlyAsync LIVE jobsTEST: 0 provider calls

Authentication

Create an API key in Account → API. The secret is displayed once. Store it only on your server and send it as a Bearer credential. Revoked and expired keys are rejected.

Authorization: Bearer avk_live_…

TEST quickstart

TEST validation is available only on deployments where an operator enabled the bounded TEST seam. It validates the real PHOTO schema, ownership and idempotency format. It creates no job or output, reserves no credits and calls no provider. VALIDATED is not a generation success.

No public TEST host is invented by this documentation. Obtain an approved TEST base URL from Avelika; if the seam is disabled, the endpoint returns test_mode_unavailable.

export AVELIKA_TEST_BASE_URL="https://<approved-test-host>"
export AVELIKA_API_KEY="<one-time-secret>"

curl --fail-with-body --request POST \
  "$AVELIKA_TEST_BASE_URL/api/v1/test/validate" \
  --header "Authorization: Bearer $AVELIKA_API_KEY" \
  --header "Idempotency-Key: docs-test-0001" \
  --header "Content-Type: application/json" \
  --data '{
  "product_id": "11111111-1111-4111-8111-111111111111",
  "concept_id": "studio-clean",
  "image_role": "main",
  "context": {
    "market": "RU",
    "locale": "ru-RU"
  },
  "settings": {
    "aspect_ratio": "3:4",
    "quality": "1K",
    "output_count": 1
  }
}'

LIVE semantics

POST /api/v1/generate is a LIVE commercial operation. A newly admitted request may reserve credits and dispatch exactly once through the canonical runtime. Poll the returned job_id. Do not retry UNKNOWN with a new idempotency key; wait for reconciliation.

export AVELIKA_API_KEY="<one-time-secret>"

curl --fail-with-body --request POST \
  "https://app.avelika.com/api/v1/generate" \
  --header "Authorization: Bearer $AVELIKA_API_KEY" \
  --header "Idempotency-Key: catalog-live-0001" \
  --header "Content-Type: application/json" \
  --data '{
  "product_id": "11111111-1111-4111-8111-111111111111",
  "concept_id": "studio-clean",
  "image_role": "main",
  "context": {
    "market": "RU",
    "locale": "ru-RU"
  },
  "settings": {
    "aspect_ratio": "3:4",
    "quality": "1K",
    "output_count": 1
  }
}'

curl --fail-with-body \
  "https://app.avelika.com/api/v1/jobs/<job_id>" \
  --header "Authorization: Bearer $AVELIKA_API_KEY"

Reference

POST/api/v1/test/validate

Validate a PHOTO request without generation

Requires AVELIKA_PUBLIC_API_TEST_MODE=enabled on the target deployment. Uses the canonical API key and request schema, but creates no job, performs no provider dispatch and changes no credit balance. This response is not a generation success.

Responses: 200, 400, 401, 404, 500
POST/api/v1/generate

Create an asynchronous PHOTO generation job

LIVE operation. A newly admitted request may reserve credits and dispatch to the configured generation runtime. Replaying the same Idempotency-Key with the same request returns the same canonical operation; changing the request for that key returns idempotency_conflict.

Responses: 202, 400, 401, 402, 403, 404, 409, 429, 500, 503
GET/api/v1/jobs/{id}

Read a PHOTO job and its available results

Returns only jobs created through the Public API session for the authenticated Account family and Workspace. UNKNOWN is unresolved/reconciliation-required and must not be blindly retried.

Responses: 200, 400, 401, 404, 500

Errors and retry safety

Every error uses a bounded error.code, message and request_id. Reuse an Idempotency-Key only for the exact same logical request. A changed payload returns idempotency_conflict. 429 is retryable after capacity frees; UNKNOWN is not permission to resubmit.

{
  "error": {
    "code": "idempotency_conflict",
    "message": "…",
    "request_id": "00000000-0000-4000-8000-000000000000"
  }
}