Endpoint
Scoped keys require
content:render. The bearer key selects the organization.
If you use an explicit organization, set the SDK’s orgId or the HTTP query
parameter ?orgId=YOUR_ORG_ID; it must be an organization your key can access.Request body
The body is anIMessageConversationInput. Supply exactly one of contact or
group, plus messages. All other top-level fields are optional.
TypeScript
Requiresugcinc@4.27.0 or later.
HTTP
Response
HTTP200 means the request was accepted or the existing idempotent job was
returned. It does not mean rendering has finished. Raw HTTP returns
{ "code": 200, "data": { ... } }. The SDK adds ok: true and a message to
its normalized ApiResponse.
data is an IMessageConversationJob:
jobId, status, progress, fps, output, contentType, durationMs, and
durationInFrames. A completed job includes a public HTTPS url. Failed or
cancelled jobs include an error object. Render failures appear as a terminal
job state; request failures use the HTTP errors below.
Idempotency and retry
AnidempotencyKey is 1–128 characters. Within an organization, retry the same
body with the same key to recover the same job. Object-key ordering does not
matter; changing the body with that key returns 409 IDEMPOTENCY_CONFLICT.
Omitting the key creates a new job. To rerender a failed or cancelled job, use
a new key or omit it. Job-ownership records are retained for seven days.
Errors and limits
Native request errors include
code, message, errorCode, and retryable.
Authentication errors may omit the last two fields. Do not automatically retry
an invalid body or reuse a conflicting idempotency key.
The contract accepts at most 30 messages, 6,000 animated visible grapheme
clusters, a 120-second compiled timeline, and a 16 MiB request. Image and avatar
constraints also apply. See all validation rules.
