Abni API Reference

{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Your client balance (4 credits) is below the required 12 for this operation.",
    "details": { "balance": 4, "required": 12 },
    "requestId": "abni-req-xyz123"
  }
}

# GET/v1/brands/{brandSlug}/sub-brands?withHero=true

Single round-trip that returns the brand’s sub-brands and campaigns plus their hero images. Designed to feed a UI selector.

curl https://api.abni.ai/v1/brands/cor2ed/sub-brands?withHero=true \
  -H "x-api-key: $ABNI_KEY"

Response (200)

{
  "brand": { "slug": "cor2ed", "name": "Cor2ED" },
  "subBrands": [
    {
      "slug": "expert-how-to-video",
      "name": "Expert How To Video",
      "hero": {
        "url": "https://cdn.abni.ai/...",
        "width": 2048,
        "height": 2048,
        "imageId": "lib_..."
      },
      "campaigns": [
        {
          "slug": "accepted-style",
          "name": "Accepted Style",
          "hero": { "url": "...", "width": ..., "height": ..., "imageId": "..." }
        }
      ]
    }
  ]
}

hero bubbles up: a campaign without its own hero inherits its sub-brand’s; a sub-brand without one inherits the brand’s. Returns null only when no level in the chain has a hero tagged. Omit ?withHero=true to skip the lookups (faster, but hero will not be populated).

Errors: 404 NOT_FOUND if the brand isn’t yours.

# POST/v1/images — generate

curl https://api.abni.ai/v1/images \
  -X POST \
  -H "x-api-key: $ABNI_KEY" \
  -H "content-type: application/json" \
  -d '{
    "brand": "cor2ed",
    "subBrand": "expert-how-to-video",
    "campaign": "accepted-style",
    "prompt": "a doctor holding a brochure on a clinical background",
    "aspectRatio": "1:1",
    "resolution": "2K",
    "outputFormat": "png",
    "clientReferenceId": "your-internal-id-123"
  }'

Field reference

Field	Type	Default	Notes
brand	string (slug)	required
subBrand	string (slug)	optional	Must belong to brand
campaign	string (slug)	optional	Must belong to subBrand
prompt	string	required	Max 4000 chars
aspectRatio	enum	"1:1"	1:1 4:5 9:16 16:9 2:3 5:4
resolution	enum	"2K"	1K 2K 4K
outputFormat	enum	"png"	png jpg
clientReferenceId	string	optional	Echoed back in GET and webhook payloads

Response (202)

{ "id": "img_a1b2c3d4...", "jobId": "job_...", "status": "processing" }

Then poll GET /v1/images/{id} or wait for the webhook.

Errors: UNSUPPORTED_HIERARCHY, INSUFFICIENT_CREDITS, VALIDATION_ERROR.

# GET/v1/images/{imageId}

curl https://api.abni.ai/v1/images/img_a1b2c3d4 \
  -H "x-api-key: $ABNI_KEY"

Response (200)

{
  "id": "img_a1b2c3d4...",
  "status": "completed",
  "url": "https://cdn.abni.ai/...",
  "currentVersion": 1,
  "brand": "cor2ed",
  "subBrand": "expert-how-to-video",
  "campaign": "accepted-style",
  "clientReferenceId": "your-internal-id-123",
  "versions": [
    {
      "version": 1,
      "url": "https://cdn.abni.ai/...",
      "createdAt": "2026-05-05T10:30:00.000Z",
      "prompt": "a doctor holding a brochure on a clinical background",
      "aspectRatio": "1:1",
      "resolution": "2K",
      "outputFormat": "png",
      "score": 84
    }
  ],
  "error": null
}

status is processing (poll again), completed (you have a URL), or failed (error populated). The image URL is a CloudFront link, signed and stable.

# POST/v1/images/{imageId}/revise — edit

Asks for a content-level change to an existing image. Produces a new version of the same imageId.

curl https://api.abni.ai/v1/images/img_a1b2c3d4/revise \
  -X POST \
  -H "x-api-key: $ABNI_KEY" \
  -H "content-type: application/json" \
  -d '{
    "instructions": "make the brochure red instead of blue",
    "version": 1,
    "clientReferenceId": "your-internal-id-123"
  }'

Field	Type	Default
instructions	string	required, max 4000
version	number	optional; defaults to currentVersion
clientReferenceId	string	optional

Response: 202 with the same shape as POST /v1/images. The new version writes as version: N+1 of the same image. Poll GET /v1/images/{id} to see it appear in versions.

# POST/v1/images/{imageId}/resize

Surgical — preserves the image content, changes only frame and resolution. Brand context, refs, and rules are NOT re-applied.

curl https://api.abni.ai/v1/images/img_a1b2c3d4/resize \
  -X POST \
  -H "x-api-key: $ABNI_KEY" \
  -H "content-type: application/json" \
  -d '{
    "aspectRatio": "9:16",
    "resolution": "2K",
    "outputFormat": "png"
  }'

Field	Type	Default
aspectRatio	enum	required
resolution	enum	required
outputFormat	enum	"png"
version	number	optional; defaults to currentVersion
clientReferenceId	string	optional

Response: 202. New version of the same imageId.

# POST/v1/images/brandify

Take an external image and re-style it to match a brand. Two input modes; pick one.

Mode A — JSON with source URL

curl https://api.abni.ai/v1/images/brandify \
  -X POST \
  -H "x-api-key: $ABNI_KEY" \
  -H "content-type: application/json" \
  -d '{
    "brand": "cor2ed",
    "subBrand": "expert-how-to-video",
    "sourceUrl": "https://your-cdn.example.com/source.jpg",
    "instructions": "make this look like a Cor2ED clinical photo",
    "aspectRatio": "1:1",
    "resolution": "2K",
    "outputFormat": "png",
    "clientReferenceId": "your-internal-id-123"
  }'

sourceUrl constraints: HTTPS, reachable from AWS eu-north-1, max 20MB, image content-type.

Mode B — multipart upload

curl https://api.abni.ai/v1/images/brandify \
  -X POST \
  -H "x-api-key: $ABNI_KEY" \
  -F "brand=cor2ed" \
  -F "subBrand=expert-how-to-video" \
  -F "instructions=make this look like a Cor2ED clinical photo" \
  -F "aspectRatio=1:1" \
  -F "resolution=2K" \
  -F "clientReferenceId=your-internal-id-123" \
  -F "source=@./photo.jpg;type=image/jpeg"

Form fields mirror the JSON body. The file must be in a source field, max 20MB.

Response (both modes): 202 { id, jobId, status: "processing" }. The original is preserved as version 1; the brandified version writes as version 2 of the same imageId.

Errors: INVALID_SOURCE_URL, PAYLOAD_TOO_LARGE, UNSUPPORTED_MEDIA_TYPE, UNSUPPORTED_HIERARCHY, INSUFFICIENT_CREDITS.

POST https://your-bot.example.com/abni-callback
content-type: application/json
x-abni-event: image.completed
x-abni-signature: t=1714928400,v1=<HMAC-SHA256 hex of "t=<ts>|<raw body>" using your secret>

{
  "event": "image.completed",
  "id": "img_a1b2c3d4...",
  "version": 1,
  "url": "https://cdn.abni.ai/...",
  "createdAt": "2026-05-05T10:30:00.000Z",
  "metadata": {
    "brand": "cor2ed",
    "subBrand": "expert-how-to-video",
    "campaign": "accepted-style",
    "prompt": "a doctor holding a brochure...",
    "clientReferenceId": "your-internal-id-123"
  }
}

const [tPart, v1Part] = headerValue.split(",");
const ts = parseInt(tPart.split("=")[1], 10);
const sig = v1Part.split("=")[1];
if (Math.abs(Date.now() / 1000 - ts) > 300) reject();
const expected = crypto.createHmac("sha256", secret).update(`t=${ts}|${rawBody}`).digest("hex");
if (!crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) reject();