How-to guides

Size cover art

Name the sizes your apps use — a 600 px tile, a 1200×630 share card — and //SCHEMA renders every cover at each, ahead of time. Your code asks for a cover by the name.

Define your sizes#

Owners and admins define sizes in the console under Settings, or with any credential holding config_write:

Request

mutation {
  createArtworkSize(input: {
    label: "tile-600"
    width: 600
    height: 600
    crop: FILL
    format: JPEG
  }) {
    label
    quality
    spec
  }
}

curl https://api.schema.fm/graphql \
  -H "Authorization: Bearer $SCHEMA_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'EOF'
{
  "query": "mutation {\n  createArtworkSize(input: {\n    label: \"tile-600\"\n    width: 600\n    height: 600\n    crop: FILL\n    format: JPEG\n  }) {\n    label\n    quality\n    spec\n  }\n}"
}
EOF

const res = await fetch("https://api.schema.fm/graphql", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SCHEMA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: `
      mutation {
        createArtworkSize(input: {
          label: "tile-600"
          width: 600
          height: 600
          crop: FILL
          format: JPEG
        }) {
          label
          quality
          spec
        }
      }
    `,
  }),
});
const { data, errors } = await res.json();

Response

{
  "data": {
    "createArtworkSize": {
      "label": "tile-600",
      "quality": 85,
      "spec": "img-fill-600x600-jpeg-q85-v1"
    }
  }
}

Crop	Result
`FILL`	Exactly 600×600: the cover is scaled to cover the box and center-cropped.
`FIT`	At most 600×600: scaled to fit, aspect kept, nothing cropped.

A size belongs to your organization and applies to every catalog it owns, so production and sandbox draw covers alike. Members, and keys with catalog_read, can list the sizes with artworkSizes but cannot change them.

An organization may have up to 20 sizes, on every plan.

Every front cover you hold is rendered at a new size within moments of saving it, and every new cover within moments of arriving. Sizes are made of each release's FrontCoverImage only — back covers, booklet pages and other images are not rendered. Rendered covers are stored files and count toward your storage while one of your sizes asks for them: if another organization holds the same cover at the same size, you are not charged for theirs.

Fetch a cover by name#

Ask the release for its coverArt at the label:

Request

query {
  release(upc: "0196871402293") {
    coverArt(size: "tile-600") {
      status
      width
      height
      url(ttlSeconds: 600)
    }
  }
}

curl https://api.schema.fm/graphql \
  -H "Authorization: Bearer $SCHEMA_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'EOF'
{
  "query": "query {\n  release(upc: \"0196871402293\") {\n    coverArt(size: \"tile-600\") {\n      status\n      width\n      height\n      url(ttlSeconds: 600)\n    }\n  }\n}"
}
EOF

const res = await fetch("https://api.schema.fm/graphql", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SCHEMA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: `
      query {
        release(upc: "0196871402293") {
          coverArt(size: "tile-600") {
            status
            width
            height
            url(ttlSeconds: 600)
          }
        }
      }
    `,
  }),
});
const { data, errors } = await res.json();

Response

{
  "data": {
    "release": {
      "coverArt": {
        "status": "READY",
        "width": 600,
        "height": 600,
        "url": "https://media.schema.fm/sha256/7c/1e/7c1e…?X-Amz-Expires=600&X-Amz-Signature=…"
      }
    }
  }
}

coverArt is null when the release has no front cover yet. If you already have the resource, artwork(size:) on it answers the same; asked of any image but the FrontCoverImage, it is an ARTWORK_NOT_FRONT_COVER error.

It needs media_read, as the original cover does. The URL is minted and logged only when you select url, so asking for width and height to lay out a page mints nothing. Use contentVersion on the resource as your cache key: it changes when the cover is replaced.

When a cover is not ready#

Until a rendition is made, status is PENDING, url is null, and width and height already say what it will be — lay the page out and fetch again shortly. FAILED means the cover could not be decoded; //SCHEMA has the reason. A label your organization does not have is an UNKNOWN_ARTWORK_SIZE error whose message lists the labels you do.

Changing sizes#

Renaming a size renders nothing: what is stored is keyed by spec, not by the label. Changing the dimensions, crop, format or quality makes a new rendition, PENDING until made, and returns the size under a new artworkSizePk — the old definition is kept, retired, so past storage still prices from it. The label carries over, so code that asks by label is unaffected.

A cover smaller than a size is never scaled up unless the size sets upscale: true, and width and height always say what you will get.