Быстрый старт API

Запустите первую генерацию через API.

Проверьте кредиты, загрузите материалы, запустите генерацию и скачайте готовые файлы.

Проверьте доступный баланс

Проверьте кредиты или активную месячную квоту перед созданием оплачиваемого запроса.

curl "$FORMATRY_CC_ORIGIN/api/v1/balance" \
  -H "Authorization: Bearer $FORMATRY_CC_API_KEY"

Создайте запрос на загрузку

Зарегистрируйте изображение кампании; логотип загрузите отдельно как SVG.

curl -X POST "$FORMATRY_CC_ORIGIN/api/v1/assets/uploads" \
  -H "Authorization: Bearer $FORMATRY_CC_API_KEY" \
  -H "Idempotency-Key: asset-upload-001" \
  -H "Content-Type: application/json" \
  -d '{"slotId":"media","fileName":"hero.jpg","mimeType":"image/jpeg","byteLength":240000,"width":1600,"height":900}' \
  > upload-intent.json

Завершите загрузку

Отправьте файл по временной ссылке из запроса, затем подтвердите готовность материала.

UPLOAD_METHOD="$(jq -r '.data.method' upload-intent.json)"
UPLOAD_URL="$(jq -r '.data.url' upload-intent.json)"
UPLOAD_ID="$(jq -r '.data.uploadId' upload-intent.json)"
UPLOAD_HEADERS=()
while IFS=$'\t' read -r name value; do
  UPLOAD_HEADERS+=(-H "$name: $value")
done < <(jq -r '.data.headers | to_entries[] | [.key,.value] | @tsv' upload-intent.json)

curl -X "$UPLOAD_METHOD" "$UPLOAD_URL" \
  "${UPLOAD_HEADERS[@]}" \
  --data-binary @hero.jpg

curl -X POST "$FORMATRY_CC_ORIGIN/api/v1/assets/uploads/$UPLOAD_ID/complete" \
  -H "Authorization: Bearer $FORMATRY_CC_API_KEY" \
  -H "Idempotency-Key: asset-complete-001" \
  -H "Content-Type: application/json" \
  -d '{"assetId":"<media-asset-id>","byteLength":240000}'

Запустите генерацию

Статичный экспорт — 1 кредит за размер, анимированный — 3 кредита за размер. Передайте изображение; запрос резервирует баланс один раз.

curl -X POST "$FORMATRY_CC_ORIGIN/api/v1/jobs" \
  -H "Authorization: Bearer $FORMATRY_CC_API_KEY" \
  -H "Idempotency-Key: generation-job-001" \
  -H "Content-Type: application/json" \
  -d '{"contractId":"formatry-default","selectedSizeIds":["square-1080"],"assetIds":{"media":"<media-asset-id>"}}'

Проверьте статус, манифест и скачайте

Проверяйте статус, пока файлы не будут готовы, затем запросите их список и временную ссылку на скачивание.

curl "$FORMATRY_CC_ORIGIN/api/v1/jobs/$JOB_ID" \
  -H "Authorization: Bearer $FORMATRY_CC_API_KEY"

curl "$FORMATRY_CC_ORIGIN/api/v1/artifacts/$ARTIFACT_ID" \
  -H "Authorization: Bearer $FORMATRY_CC_API_KEY"

curl "$FORMATRY_CC_ORIGIN/api/v1/artifacts/$ARTIFACT_ID/download" \
  -H "Authorization: Bearer $FORMATRY_CC_API_KEY"

Сверьте списания

Получите историю использования после генерации, чтобы сверить баланс и возвраты.

curl "$FORMATRY_CC_ORIGIN/api/v1/usage" \
  -H "Authorization: Bearer $FORMATRY_CC_API_KEY"

API

Перед стартом

Используйте Authorization: Bearer или X-API-Key с правами из схемы. Схема описывает контракт, но не доказывает live-готовность API; не храните ключи и временные ссылки. Слоты: media — основное изображение, logo — отдельный SVG, product/person/device — специальные визуалы, font — шрифт. Статусы: 400 ввод · 401 ключ · 402 кредиты · 403 права · 409 повтор · 429 лимит · 501 провайдер.

curl -X POST "$FORMATRY_CC_ORIGIN/api/v1/assets/uploads" \ -H "Authorization: Bearer $FORMATRY_CC_API_KEY" \ -H "Idempotency-Key: asset-upload-001" \ -H "Content-Type: application/json" \ -d '{"slotId":"media","fileName":"hero.jpg","mimeType":"image/jpeg","byteLength":240000,"width":1600,"height":900}' \ > upload-intent.json

UPLOAD_METHOD="$(jq -r '.data.method' upload-intent.json)" UPLOAD_URL="$(jq -r '.data.url' upload-intent.json)" UPLOAD_ID="$(jq -r '.data.uploadId' upload-intent.json)" UPLOAD_HEADERS=() while IFS=$'\t' read -r name value; do UPLOAD_HEADERS+=(-H "$name: $value") done < <(jq -r '.data.headers | to_entries[] | [.key,.value] | @tsv' upload-intent.json) curl -X "$UPLOAD_METHOD" "$UPLOAD_URL" \ "${UPLOAD_HEADERS[@]}" \ --data-binary @hero.jpg curl -X POST "$FORMATRY_CC_ORIGIN/api/v1/assets/uploads/$UPLOAD_ID/complete" \ -H "Authorization: Bearer $FORMATRY_CC_API_KEY" \ -H "Idempotency-Key: asset-complete-001" \ -H "Content-Type: application/json" \ -d '{"assetId":"<media-asset-id>","byteLength":240000}'

curl -X POST "$FORMATRY_CC_ORIGIN/api/v1/jobs" \ -H "Authorization: Bearer $FORMATRY_CC_API_KEY" \ -H "Idempotency-Key: generation-job-001" \ -H "Content-Type: application/json" \ -d '{"contractId":"formatry-default","selectedSizeIds":["square-1080"],"assetIds":{"media":"<media-asset-id>"}}'

curl "$FORMATRY_CC_ORIGIN/api/v1/jobs/$JOB_ID" \ -H "Authorization: Bearer $FORMATRY_CC_API_KEY" curl "$FORMATRY_CC_ORIGIN/api/v1/artifacts/$ARTIFACT_ID" \ -H "Authorization: Bearer $FORMATRY_CC_API_KEY" curl "$FORMATRY_CC_ORIGIN/api/v1/artifacts/$ARTIFACT_ID/download" \ -H "Authorization: Bearer $FORMATRY_CC_API_KEY"