Skip to content
Jami3D
Developer docs menu

REST API: Embeds

Every operation of this group with its parameters, body, answer and errors, as the OpenAPI document states them.

Public reads a page makes before anything plays: a project's card (the SDK's facade), oEmbed, and the keys viewer tokens are signed with.

Read a project's card

GET/v1/projects/{id}/cardNo bearer token

Public and cached a minute. With publishableKey it is also the origin check the SDK makes before mounting the iframe; with cardToken it describes a private or secure-only project (and is never cached).

Parameters

NameInTypeDescription
idRequiredpathstring

The project's id.

cardTokenquerystring
publishableKeyquerystring
localequerystring

A UI or reply language: a BCP 47 tag (en, pt-BR, zh-Hant-TW).

Response 200

GET /v1/projects/{id}/card — EmbedMeta v1: the title, the creator, the poster (renditions, blurhash and dominant colour for the placeholder), the length, and the EU AI Act Art. 50 disclosure the facade shows before anything plays — and, added within v1 (P9), the poster's <picture> sources, the hover preview, who a viewer may talk to and the chapters with their thumbnails. Fields added later are optional: a reader branches on their absence.

FieldTypeDescription
vRequiredinteger0–9007199254740991
projectIdRequiredstring (uuid)

A server-minted id (sessions, projects, releases, users): a UUID.

releaseIdRequiredstring (uuid)

A server-minted id (sessions, projects, releases, users): a UUID.

titleRequiredstring
creatorRequiredobject
creator.nameRequiredstring
contentLanguageRequiredstring≤ 35 characters

A UI or reply language: a BCP 47 tag (en, pt-BR, zh-Hant-TW).

durationMsRequiredinteger0–9007199254740991

The timeline scenes' authored length; interactive scenes add none.

scenesRequiredinteger0–9007199254740991
interactiveRequiredboolean

Viewers act in it: Beats, or an interactive scene.

posterobject
poster.widthRequiredinteger0–9007199254740991
poster.heightRequiredinteger0–9007199254740991
poster.blurhashRequiredstring≥ 1 characters
poster.colorRequiredstring≥ 1 characters

#rrggbb.

poster.variantsRequiredobject[]≥ 1 items
poster.variants[].typeRequiredstring≥ 1 characters

image/avif, image/webp or image/jpeg.

poster.variants[].widthRequiredinteger0–9007199254740991
poster.variants[].heightRequiredinteger0–9007199254740991
poster.variants[].urlRequiredstring≥ 1 characters
poster.sourcesobject[]≥ 1 items

The renditions as <picture> sources, lightest format first (P9).

poster.sources[].typeRequiredstring≥ 1 characters

image/avif, image/webp or image/jpeg; a reader skips a type it does not know.

poster.sources[].srcsetRequiredstring≥ 1 characters
poster.fallbackUrlstring≥ 1 characters

One rendition every browser reads (a JPEG), for the <img> (P9).

previewobject

The hover preview (P9): a few silent seconds of the experience, small enough to play on hover (a 640 × 360, 24 fps H.264 MP4 under 1.5 MB). Absent until one is rendered.

preview.urlRequiredstring≥ 1 characters
preview.typeRequiredstring≥ 1 characters

video/mp4.

preview.widthRequiredinteger0–9007199254740991
preview.heightRequiredinteger0–9007199254740991
preview.durationMsRequiredinteger0–9007199254740991
preview.bytesRequiredinteger0–9007199254740991
aiRequiredobject

EU AI Act Art. 50: who is AI and what is synthetic. Never hidden by a host option.

ai.aiCharactersRequiredboolean
ai.narratorAiRequiredboolean
ai.syntheticVoiceRequiredboolean
ai.liveAiRequiredboolean
ai.charactersobject[]

Who a viewer may talk to — the AI characters (and speaking props) that answer, by name, in the release's cast order; empty when the experience has no live conversation (P9).

ai.characters[].nameRequiredstring
ai.voiceboolean

A viewer may also talk to them by voice (P9).

ai.noticestring≥ 1 characters

The disclosure in words, as the facade says it before anything plays ("Made with AI: AI characters and synthetic voices."), in the UI language nearest to the request's locale (P8). Absent when nothing is AI — and from a server before it: a reader then words the flags itself.

ai.unknownboolean

The release's stored disclosure could not be read: the flags keep what could, and notice is the generic AI notice — the card fails closed, never "no AI" (P8). Absent: the flags are exact.

chaptersobject[]

The chapters in play order: each scene, then its named or tagged Beats (P9).

chapters[].kindRequiredstring≥ 1 characters

scene or beat; a reader skips a kind it does not know.

chapters[].idRequiredstring≥ 1 characters

The scene's id, or the Beat's.

chapters[].sceneIdRequiredstring≥ 1 characters

The scene the chapter is in.

chapters[].titleRequiredstring

The scene's name, or the Beat's.

chapters[].aliasstring≥ 1 characters

A Beat's alias: what goToBeat and a watch link's ?beat= take. Absent for a scene.

chapters[].tagsstring[]

A Beat's chapter tags.

chapters[].startMsRequiredinteger0–9007199254740991

Where the chapter starts in its scene, in authored milliseconds.

chapters[].thumbnailobject

A 16:9 frame of the chapter (480 × 270 and narrower); absent until one is rendered.

chapters[].thumbnail.widthRequiredinteger0–9007199254740991
chapters[].thumbnail.heightRequiredinteger0–9007199254740991
chapters[].thumbnail.blurhashRequiredstring≥ 1 characters
chapters[].thumbnail.colorRequiredstring≥ 1 characters

#rrggbb.

chapters[].thumbnail.sourcesRequiredobject[]≥ 1 items
chapters[].thumbnail.sources[].typeRequiredstring≥ 1 characters

image/avif, image/webp or image/jpeg; a reader skips a type it does not know.

chapters[].thumbnail.sources[].srcsetRequiredstring≥ 1 characters
chapters[].thumbnail.fallbackUrlRequiredstring≥ 1 characters
aspectstring≥ 1 characters

The frame the experience is authored for (16:9, 9:16, 1:1, 4:3) (P9).

embedUrlRequiredstring≥ 1 characters

The embed document (https://embed.jami.live/p/{projectId}).

Errors

  • 400invalid_input
  • 401key_invalid
  • 403origin_not_allowed
  • 404release_not_found

Read a listing's card

GET/v1/listings/{slug}/cardNo bearer token

Added within v1 (P8): the card of a marketplace listing, named by its slug (an earlier slug too) — the SDK's listing option, which learns the project its embed document plays (projectId) from it. The same card as the project's, reached the way /w/{slug} reaches the listing: an unlisted listing opens to its slug; a private, removed or unpublished one is the 404 of a slug that never existed.

The project card of a marketplace listing, for createPlayer({ listing }): its projectId names the embed document. An unlisted listing answers to its slug; a private, removed or unpublished one is the same 404 as a slug that never existed. Public and cached a minute; the credentials work as on the project's card.

Parameters

NameInTypeDescription
slugRequiredpathstring

The listing's slug, as in https://jami.live/w/{slug} (an earlier slug of a renamed listing works too).

cardTokenquerystring
publishableKeyquerystring
localequerystring

A UI or reply language: a BCP 47 tag (en, pt-BR, zh-Hant-TW).

Response 200

GET /v1/projects/{id}/card — EmbedMeta v1: the title, the creator, the poster (renditions, blurhash and dominant colour for the placeholder), the length, and the EU AI Act Art. 50 disclosure the facade shows before anything plays — and, added within v1 (P9), the poster's <picture> sources, the hover preview, who a viewer may talk to and the chapters with their thumbnails. Fields added later are optional: a reader branches on their absence.

FieldTypeDescription
vRequiredinteger0–9007199254740991
projectIdRequiredstring (uuid)

A server-minted id (sessions, projects, releases, users): a UUID.

releaseIdRequiredstring (uuid)

A server-minted id (sessions, projects, releases, users): a UUID.

titleRequiredstring
creatorRequiredobject
creator.nameRequiredstring
contentLanguageRequiredstring≤ 35 characters

A UI or reply language: a BCP 47 tag (en, pt-BR, zh-Hant-TW).

durationMsRequiredinteger0–9007199254740991

The timeline scenes' authored length; interactive scenes add none.

scenesRequiredinteger0–9007199254740991
interactiveRequiredboolean

Viewers act in it: Beats, or an interactive scene.

posterobject
poster.widthRequiredinteger0–9007199254740991
poster.heightRequiredinteger0–9007199254740991
poster.blurhashRequiredstring≥ 1 characters
poster.colorRequiredstring≥ 1 characters

#rrggbb.

poster.variantsRequiredobject[]≥ 1 items
poster.variants[].typeRequiredstring≥ 1 characters

image/avif, image/webp or image/jpeg.

poster.variants[].widthRequiredinteger0–9007199254740991
poster.variants[].heightRequiredinteger0–9007199254740991
poster.variants[].urlRequiredstring≥ 1 characters
poster.sourcesobject[]≥ 1 items

The renditions as <picture> sources, lightest format first (P9).

poster.sources[].typeRequiredstring≥ 1 characters

image/avif, image/webp or image/jpeg; a reader skips a type it does not know.

poster.sources[].srcsetRequiredstring≥ 1 characters
poster.fallbackUrlstring≥ 1 characters

One rendition every browser reads (a JPEG), for the <img> (P9).

previewobject

The hover preview (P9): a few silent seconds of the experience, small enough to play on hover (a 640 × 360, 24 fps H.264 MP4 under 1.5 MB). Absent until one is rendered.

preview.urlRequiredstring≥ 1 characters
preview.typeRequiredstring≥ 1 characters

video/mp4.

preview.widthRequiredinteger0–9007199254740991
preview.heightRequiredinteger0–9007199254740991
preview.durationMsRequiredinteger0–9007199254740991
preview.bytesRequiredinteger0–9007199254740991
aiRequiredobject

EU AI Act Art. 50: who is AI and what is synthetic. Never hidden by a host option.

ai.aiCharactersRequiredboolean
ai.narratorAiRequiredboolean
ai.syntheticVoiceRequiredboolean
ai.liveAiRequiredboolean
ai.charactersobject[]

Who a viewer may talk to — the AI characters (and speaking props) that answer, by name, in the release's cast order; empty when the experience has no live conversation (P9).

ai.characters[].nameRequiredstring
ai.voiceboolean

A viewer may also talk to them by voice (P9).

ai.noticestring≥ 1 characters

The disclosure in words, as the facade says it before anything plays ("Made with AI: AI characters and synthetic voices."), in the UI language nearest to the request's locale (P8). Absent when nothing is AI — and from a server before it: a reader then words the flags itself.

ai.unknownboolean

The release's stored disclosure could not be read: the flags keep what could, and notice is the generic AI notice — the card fails closed, never "no AI" (P8). Absent: the flags are exact.

chaptersobject[]

The chapters in play order: each scene, then its named or tagged Beats (P9).

chapters[].kindRequiredstring≥ 1 characters

scene or beat; a reader skips a kind it does not know.

chapters[].idRequiredstring≥ 1 characters

The scene's id, or the Beat's.

chapters[].sceneIdRequiredstring≥ 1 characters

The scene the chapter is in.

chapters[].titleRequiredstring

The scene's name, or the Beat's.

chapters[].aliasstring≥ 1 characters

A Beat's alias: what goToBeat and a watch link's ?beat= take. Absent for a scene.

chapters[].tagsstring[]

A Beat's chapter tags.

chapters[].startMsRequiredinteger0–9007199254740991

Where the chapter starts in its scene, in authored milliseconds.

chapters[].thumbnailobject

A 16:9 frame of the chapter (480 × 270 and narrower); absent until one is rendered.

chapters[].thumbnail.widthRequiredinteger0–9007199254740991
chapters[].thumbnail.heightRequiredinteger0–9007199254740991
chapters[].thumbnail.blurhashRequiredstring≥ 1 characters
chapters[].thumbnail.colorRequiredstring≥ 1 characters

#rrggbb.

chapters[].thumbnail.sourcesRequiredobject[]≥ 1 items
chapters[].thumbnail.sources[].typeRequiredstring≥ 1 characters

image/avif, image/webp or image/jpeg; a reader skips a type it does not know.

chapters[].thumbnail.sources[].srcsetRequiredstring≥ 1 characters
chapters[].thumbnail.fallbackUrlRequiredstring≥ 1 characters
aspectstring≥ 1 characters

The frame the experience is authored for (16:9, 9:16, 1:1, 4:3) (P9).

embedUrlRequiredstring≥ 1 characters

The embed document (https://embed.jami.live/p/{projectId}).

Errors

  • 400invalid_input
  • 401key_invalid
  • 403origin_not_allowed
  • 404release_not_found

oEmbed

GET/v1/oembedNo bearer token

oEmbed 1.0 for an experience's embed or watch address: a rich answer with an iframe of the embed document. JSON only.

Parameters

NameInTypeDescription
urlRequiredquerystring
maxwidthqueryinteger
maxheightqueryinteger
formatquery"json" | "xml"Default "json"

Response 200

A rich oEmbed answer: an iframe of the embed document.

FieldTypeDescription
versionRequired"1.0"
typeRequired"rich"
provider_nameRequiredstring
provider_urlRequiredstring
titleRequiredstring
author_namestring
htmlRequiredstring≥ 1 characters
widthRequiredinteger0–9007199254740991
heightRequiredinteger0–9007199254740991
thumbnail_urlstring
thumbnail_widthinteger0–9007199254740991
thumbnail_heightinteger0–9007199254740991
cache_ageinteger0–9007199254740991

Errors

  • 400invalid_input
  • 404not_found
  • 501format_unsupported

The viewer-token signing keys

GET/.well-known/jwks.jsonNo bearer token

Cached five minutes. A new key is published a rotation ahead of signing with it.

Response 200

GET /.well-known/jwks.json: the keys viewer tokens verify against (the signing key and its predecessor).

FieldTypeDescription
keysRequiredobject[]≥ 1 items
keys[].ktyRequired"EC"
keys[].crvRequired"P-256"
keys[].xRequiredstring≥ 1 characters
keys[].yRequiredstring≥ 1 characters
keys[].kidRequiredstring≥ 1 characters
keys[].algRequired"ES256"
keys[].useRequired"sig"