Artwork sizes

An artwork size is a label your organization gives to a size and crop — tile-600: 600×600, FILL, JPEG. Your apps then ask for a cover by the label: artwork(size: "tile-600") on a Resource. Sizes belong to the organization and apply to every catalog it owns. Owners and admins manage them in the console under Settings, or with config_write.

Crop	Result
`FILL`	Exactly the size: the cover is scaled to cover it and center-cropped.
`FIT`	Within the size: the cover is scaled to fit, aspect kept, nothing cropped.

A cover smaller than the size is not scaled up unless the size says upscale: true; width and height always say what you will get.

Every cover your catalogs hold is rendered at every size ahead of time, within moments of the size being saved or the cover arriving. Until then artwork answers PENDING, with the dimensions it will have, and no URL. Renaming a size re-renders nothing; changing its dimensions, crop, format or quality makes a new rendition.

Rendered covers are stored files and count toward your storage, as audio encodings do. See Size cover art.

Errors#

Code	Meaning
`UNKNOWN_ARTWORK_SIZE`	No size with that label in your organization. The message lists the labels you have.
`ENCODING_NOT_AVAILABLE`	The resource is not an image.
`INVALID_ARTWORK_SIZE`	A size outside the limits, a malformed label, or a quality on PNG.
`ARTWORK_SIZE_LABEL_TAKEN`	Your organization already has a size with that label.
`ARTWORK_SIZE_LIMIT`	Your organization has as many sizes as it may have.

Operations

queryartworkSizes
queryartworkSizeLimits
mutationcreateArtworkSize
mutationupdateArtworkSize
mutationdeleteArtworkSize

The ArtworkSize object#

One of your organization's artwork sizes, from artworkSizes.

Attributes

artworkSizePkInt!
Unique identifier.
labelString!
What Resource.artwork takes. Unique in your organization.
widthInt!
Width bound, in pixels.
heightInt!
Height bound, in pixels.
cropArtworkCrop!
FILL or FIT.
formatArtworkFormat!
JPEG or PNG.
qualityIntnullable
JPEG quality, 1–100. null for PNG.
upscaleBoolean!
Whether a cover smaller than the size is scaled up to it.
specString!
What is rendered, e.g. img-fill-600x600-jpeg-q85-v1. Sizes with the same spec share renditions; renaming a size keeps it.
configuredFromDateTime!
When the size started rendering its current spec — when it was created, or when its dimensions, crop, format or quality last changed. A rename keeps it.
updatedAtDateTime!
When it last changed.

The Artwork object#

One cover at one of your artwork sizes, from Resource.artwork.

Attributes

sizeString!
The label asked for.
specString!
What is rendered for it.
statusEncodingStatus!
READY, PENDING (being made, usually within a minute) or FAILED (the cover could not be decoded; //SCHEMA has the reason).
widthIntnullable
The rendition's width once READY; before that, what it will be. null until the cover has been measured.
heightIntnullable
The rendition's height, likewise.
formatString!
jpeg or png.
contentTypeString!
The type the URL serves, e.g. image/jpeg.
byteSizeIntnullable
File size in bytes, once READY.
urlStringnullable
A short-lived signed URL for the rendition. null unless READY. Minted, and logged, only when you select it.
Arguments
- ttlSecondsInt
  How long the URL stays valid, in seconds. Default 300; values above 3600 are capped at 3600.

The Artwork object

{
  "size": "tile-600",
  "spec": "img-fill-600x600-jpeg-q85-v1",
  "status": "READY",
  "width": 600,
  "height": 600,
  "format": "jpeg",
  "contentType": "image/jpeg",
  "byteSize": 61234,
  "url": "https://media.schema.fm/sha256/7c/1e/7c1e…?X-Amz-Expires=300&X-Amz-Signature=…"
}

The ArtworkCrop enum#

How a cover is fitted to a size.

Values

FILL
Exactly the size — scaled to cover it, center-cropped.
FIT
Within the size — scaled to fit, aspect kept, nothing cropped.

The ArtworkFormat enum#

What a rendition is written as.

Values

JPEG
JPEG at the size's quality. Transparent areas become white.
PNG
Lossless PNG, transparency kept.

The ArtworkSizeLimits object#

The bounds an artwork size must fall within.

Attributes

minPxInt!
The smallest width or height, in pixels.
maxPxInt!
The largest width or height, in pixels.
maxSizesInt!
How many sizes an organization may have.
maxLabelLengthInt!
The longest label, in characters.
defaultJpegQualityInt!
The quality a JPEG size gets when none is given.

The CreateArtworkSizeInput input object#

A new artwork size.

Fields

labelString!required
A short slug: a–z, 0–9, - and _, starting with a letter or digit, e.g. tile-600.
widthInt!required
Width bound, in pixels, within the limits.
heightInt!required
Height bound, in pixels.
cropArtworkCrop!required
FILL or FIT.
formatArtworkFormat!required
JPEG or PNG.
qualityInt
JPEG only, 1–100. Defaults to 85. Leave it out for PNG.
upscaleBoolean!Default: false
Scale a cover smaller than the size up to it. Defaults to false.

The UpdateArtworkSizeInput input object#

What to change on an artwork size. Fields left out are kept.

Fields

artworkSizePkInt!required
The size.
labelString
A new label. Re-renders nothing.
widthInt
A new width bound.
heightInt
A new height bound.
cropArtworkCrop
A new crop.
formatArtworkFormat
A new format.
qualityInt
A new JPEG quality; null for the default. Left out, it is kept unless the format changes.
upscaleBoolean
Whether a smaller cover is scaled up.

List artwork sizes#

queryartworkSizes→[ArtworkSize!]!catalog_read

Your organization's sizes, by label. Read this rather than hardcoding labels: they are your organization's to change.

Arguments

None.

Returns

A list of ArtworkSize.

Request

{
  artworkSizes {
    label
    width
    height
    crop
    format
    quality
    spec
  }
}

curl https://api.schema.fm/graphql \
  -H "Authorization: Bearer $SCHEMA_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'EOF'
{
  "query": "{\n  artworkSizes {\n    label\n    width\n    height\n    crop\n    format\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: `
      {
        artworkSizes {
          label
          width
          height
          crop
          format
          quality
          spec
        }
      }
    `,
  }),
});
const { data, errors } = await res.json();

Response

{
  "data": {
    "artworkSizes": [
      {
        "label": "tile-600",
        "width": 600,
        "height": 600,
        "crop": "FILL",
        "format": "JPEG",
        "quality": 85,
        "spec": "img-fill-600x600-jpeg-q85-v1"
      }
    ]
  }
}

Get artwork size limits#

queryartworkSizeLimits→ArtworkSizeLimits!any credential

The bounds a size must fall within, and how many sizes an organization may have.

Arguments

None.

Returns

ArtworkSizeLimits.

Request

{
  artworkSizeLimits {
    minPx
    maxPx
    maxSizes
  }
}

curl https://api.schema.fm/graphql \
  -H "Authorization: Bearer $SCHEMA_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'EOF'
{
  "query": "{\n  artworkSizeLimits {\n    minPx\n    maxPx\n    maxSizes\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: `
      {
        artworkSizeLimits {
          minPx
          maxPx
          maxSizes
        }
      }
    `,
  }),
});
const { data, errors } = await res.json();

Response

{
  "data": {
    "artworkSizeLimits": {
      "minPx": 16,
      "maxPx": 3000,
      "maxSizes": 20
    }
  }
}

Create an artwork size#

mutationcreateArtworkSize→ArtworkSize!config_write

Add a size. Every cover your catalogs hold is rendered at it from the moment it is saved; Resource.artwork answers PENDING for each until it is ready.

Arguments

inputCreateArtworkSizeInput!required
The size.
Show child parameters
- labelString!required
  A short slug: a–z, 0–9, - and _, starting with a letter or digit, e.g. tile-600.
- widthInt!required
  Width bound, in pixels, within the limits.
- heightInt!required
  Height bound, in pixels.
- cropArtworkCrop!required
  FILL or FIT.
- formatArtworkFormat!required
  JPEG or PNG.
- qualityInt
  JPEG only, 1–100. Defaults to 85. Leave it out for PNG.
- upscaleBoolean!Default: false
  Scale a cover smaller than the size up to it. Defaults to false.

Returns

The new ArtworkSize.

Request

mutation {
  createArtworkSize(input: {
    label: "tile-600"
    width: 600
    height: 600
    crop: FILL
    format: JPEG
  }) {
    artworkSizePk
    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    artworkSizePk\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
        }) {
          artworkSizePk
          quality
          spec
        }
      }
    `,
  }),
});
const { data, errors } = await res.json();

Response

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

Update an artwork size#

mutationupdateArtworkSize→ArtworkSize!config_write

Change a size; only the fields given change. A new label re-renders nothing. New dimensions, crop, format or quality are a new rendition, PENDING until made — and return the size under a new artworkSizePk, because the old definition is kept, retired, to price the days it was configured. Its label carries over.

Arguments

inputUpdateArtworkSizeInput!required
The size and what to change.
Show child parameters
- artworkSizePkInt!required
  The size.
- labelString
  A new label. Re-renders nothing.
- widthInt
  A new width bound.
- heightInt
  A new height bound.
- cropArtworkCrop
  A new crop.
- formatArtworkFormat
  A new format.
- qualityInt
  A new JPEG quality; null for the default. Left out, it is kept unless the format changes.
- upscaleBoolean
  Whether a smaller cover is scaled up.

Returns

The updated ArtworkSize.

Request

mutation {
  updateArtworkSize(input: { artworkSizePk: 41, label: "grid-tile" }) {
    label
    spec
  }
}

curl https://api.schema.fm/graphql \
  -H "Authorization: Bearer $SCHEMA_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'EOF'
{
  "query": "mutation {\n  updateArtworkSize(input: { artworkSizePk: 41, label: \"grid-tile\" }) {\n    label\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 {
        updateArtworkSize(input: { artworkSizePk: 41, label: "grid-tile" }) {
          label
          spec
        }
      }
    `,
  }),
});
const { data, errors } = await res.json();

Response

{
  "data": {
    "updateArtworkSize": {
      "label": "grid-tile",
      "spec": "img-fill-600x600-jpeg-q85-v1"
    }
  }
}

Delete an artwork size#

mutationdeleteArtworkSize→Boolean!config_write

Remove a size. Asking for its label is an UNKNOWN_ARTWORK_SIZE error from then on. false when there was no such size.

Arguments

artworkSizePkInt!required
The size.

Returns

true when a size was deleted.

Request

mutation {
  deleteArtworkSize(artworkSizePk: 41)
}

curl https://api.schema.fm/graphql \
  -H "Authorization: Bearer $SCHEMA_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'EOF'
{
  "query": "mutation {\n  deleteArtworkSize(artworkSizePk: 41)\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 {
        deleteArtworkSize(artworkSizePk: 41)
      }
    `,
  }),
});
const { data, errors } = await res.json();

Response

{
  "data": {
    "deleteArtworkSize": true
  }
}