API quickstart

Create a paid creative-pack request.

Check credits, upload assets, create a job, and download the pack.

Check balance

Confirm credits or active quota before creating a paid request.

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

Create an upload intent

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

Complete the upload

Send the bytes to the upload link returned by the request, then mark the material ready.

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}'

Create a pack request

1 credit renders 1 selected output size after paid access. Attach the uploaded visual; the request reserves balance once.

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>"}}'

Poll, review, and download

Read the request until it returns a ready pack, review the delivery manifest, then request a short-lived download link.

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"

Review credit history

Check credit changes after a request to match pack cost and refunds.

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

API

Before you start

Use Authorization: Bearer or X-API-Key with schema-defined scopes. Treat the schema as the contract, not live proof; never store keys or temporary links. Slots: media for the main visual, logo for a separate SVG, product/person/device for specialized visuals, and font for typography. Status: 400 input · 401 key · 402 credits · 403 scope · 409 idempotency · 429 rate · 501 provider.

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"