Avelika API
Public API V1 · OpenAPI 3.1

Создавайте визуалы товаров из своего backend.

LIVE API использует те же права Workspace, admission генерации, jobs и учёт кредитов, что и Avelika Workspace. Сначала проверьте запрос через TEST без провайдера, затем используйте коммерческий PHOTO endpoint.

Bearer API keyPHOTO onlyAsync LIVE jobsTEST: 0 provider calls

Авторизация

Создайте API-ключ в Аккаунт → API. Секрет показывается один раз. Храните его только на сервере и передавайте как Bearer credential. Отозванные и истёкшие ключи отклоняются.

Authorization: Bearer avk_live_…

TEST quickstart

TEST-проверка доступна только в среде, где оператор включил ограниченный TEST seam. Она проверяет реальную PHOTO-схему, ownership и формат idempotency. Job и результат не создаются, кредиты не резервируются, провайдер не вызывается. VALIDATED не означает успешную генерацию.

Документация не придумывает публичный TEST host. Получите разрешённый TEST base URL у Avelika; если seam выключен, endpoint вернёт 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-семантика

POST /api/v1/generate — коммерческая LIVE-операция. Новый принятый запрос может зарезервировать кредиты и выполнить ровно один dispatch через канонический runtime. Проверяйте возвращённый job_id. Не повторяйте UNKNOWN с новым idempotency key — дождитесь 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"

Методы

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

Ошибки и безопасные повторы

Каждая ошибка содержит ограниченные error.code, message и request_id. Повторно используйте Idempotency-Key только для точно того же логического запроса. Изменённое тело вернёт idempotency_conflict. 429 можно повторить после освобождения очереди; UNKNOWN не разрешает повторную отправку.

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