generation

The methods of pd.generation. Inputs and outputs are described in Conventions; every method can also fail as described in Errors.

Methods

pd.generation.estimate(input, init?)

Quote the credit cost of generating this article

GET /api/articles/{articleId}/estimate

Needs articles.read. Prices the article's stored generation configuration (400 when it has none) and compares the quote with the workspace's available credits. Nothing is reserved or charged: estimate.total is the most a run can cost, and the amount POST /api/articles/{articleId}/generate reserves. Research and fact checking are priced only when the article asks for them and the deployment's web_research and fact_checking features are on. What a run finally charges is the delivered part of this quote, never more.

Input

Returns 200 OK

Errors 400 invalid input, 401 missing or invalid key, 403 the key's roles lack the permission, 404 not found, 429 rate limited or out of quota. See Errors.

Example

import { PrismDraft } from "@prism-draft/sdk";

const pd = new PrismDraft({ apiKey: process.env.PRISMDRAFT_API_KEY! });

const result = await pd.generation.estimate({
  articleId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
});
console.log(result);

pd.generation.getOutline(input, init?)

The outline awaiting review

GET /api/articles/{articleId}/outline

Needs articles.read. Returns the outline stored on the article, null when it has none or the stored one no longer validates, and whether it can still be edited (editable: the article is a DRAFT holding an outline). Every run stores its outline on the article, so it can also be read after an ordinary generation; a run with reviewOutline set stops there for review. Submit the reviewed version to POST /api/articles/{articleId}/outline/approve.

Input

Returns 200 OK

Errors 400 invalid input, 401 missing or invalid key, 403 the key's roles lack the permission, 404 not found, 429 rate limited or out of quota. See Errors.

Example

import { PrismDraft } from "@prism-draft/sdk";

const pd = new PrismDraft({ apiKey: process.env.PRISMDRAFT_API_KEY! });

const result = await pd.generation.getOutline({
  articleId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
});
console.log(result);

pd.generation.approveOutline(input, init?)

Approve an outline and resume writing

POST /api/articles/{articleId}/outline/approve

Needs articles.generate. Stores the reviewed outline (or approves the stored one when the body has none), then starts the writing leg from it: writing resumes from the reviewer's version, not the generated one. Research is not repeated. Answers 400 when the article has no generation configuration or no outline, 409 when a run is already active or the article's status cannot move to QUEUED, 429 QUOTA_EXCEEDED when the plan's articles or images quota would be passed, and 402 INSUFFICIENT_CREDITS when the available credits do not cover the writing leg. The credits reserved are the full quote less research, which the first leg already spent; on completion only the delivered work is charged and the rest is released. Answers 202 with the QUEUED job (poll GET /api/articles/{articleId}/status, or listen for article.generation.completed); a repeated idempotencyKey answers 200 with the original job and reused: true, once that job has ended. Records an articles.outline_approved audit entry.

Input

Returns 200 OK, 202 Accepted

Errors 400 invalid input, 401 missing or invalid key, 403 the key's roles lack the permission, 404 not found, 429 rate limited or out of quota. See Errors.

Example

import { PrismDraft } from "@prism-draft/sdk";

const pd = new PrismDraft({ apiKey: process.env.PRISMDRAFT_API_KEY! });

const result = await pd.generation.approveOutline({
  articleId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
});
console.log(result);

pd.generation.aiEdit(input, init?)

Expand, shorten, rewrite, simplify or change the tone of a passage

POST /api/articles/{articleId}/ai-edit

Needs articles.update. Runs synchronously, with no job: the edited passage comes back in the 200 and the article is not changed, so the caller decides whether to apply it. It costs no credits, but each call counts toward the plan's monthly ai_operations quota (429 QUOTA_EXCEEDED once reached). The text is written in the article's generation language, or its primaryLanguage when it has no configuration, and follows the project's default brand voice. change_tone without a tone answers 400.

Input

Returns 200 OK

Errors 400 invalid input, 401 missing or invalid key, 403 the key's roles lack the permission, 404 not found, 429 rate limited or out of quota. See Errors.

Example

import { PrismDraft } from "@prism-draft/sdk";

const pd = new PrismDraft({ apiKey: process.env.PRISMDRAFT_API_KEY! });

const result = await pd.generation.aiEdit({
  articleId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
  body: {
    action: "expand",
    selection: "example",
  },
});
console.log(result);

pd.generation.start(input, init?)

Start generating an article

POST /api/articles/{articleId}/generate

Needs articles.generate. Queues a run of the pipeline that researches (when asked), outlines, writes, illustrates and finalizes the article from its generation configuration, which config can set first. The body may be omitted. Credits. The quote (estimate.total, the most the run can cost) is reserved against the wallet before any provider is called; 402 INSUFFICIENT_CREDITS when the available credits are lower. When the run ends only what was delivered is charged and the rest of the hold is released: an image the provider refused, research that found no source or a fact check that checked nothing is not charged. A run that fails before the article is saved, or is cancelled, charges nothing. With reviewOutline the run stops after the outline and charges only research. consumedCredits on the job reports the charge. Refusals. 400 when no configuration exists; 409 when a run is already active for the article or its status cannot move to QUEUED (PUBLISHED, QUEUED, PROCESSING); 429 QUOTA_EXCEEDED when the plan's articles or images quota would be passed, or ai_operations for a reviewOutline run. Asynchronous and idempotent. A new run answers 202 with the QUEUED job; follow it with GET /api/articles/{articleId}/status or the SSE stream, and see article.generation.started, image.generated, credits.consumed, article.generation.completed and article.generation.failed on the webhook. The key comes from idempotencyKey, else the Idempotency-Key header; repeating it after the run has ended answers 200 with the original job and reused: true, and while it is running answers 409. On success the article becomes NEEDS_REVIEW with a new document; on failure, cancellation or an outline-only run it returns to DRAFT. Emits article.generation.started and records an articles.generation_started audit entry.

Input

Returns 200 OK, 202 Accepted

Errors 400 invalid input, 401 missing or invalid key, 403 the key's roles lack the permission, 404 not found, 429 rate limited or out of quota. See Errors.

Example

import { PrismDraft } from "@prism-draft/sdk";

const pd = new PrismDraft({ apiKey: process.env.PRISMDRAFT_API_KEY! });

const result = await pd.generation.start({
  articleId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
});
console.log(result);

pd.generation.getStatus(input, init?)

Generation progress for an article

GET /api/articles/{articleId}/status

Needs articles.read. Returns the article's workflow status and its most recent run of any kind (generation or translation), null when none was ever started: status, currentStep and progress say where it is, and a FAILED run carries errorCode and errorMessage. Poll this, or listen to GET /api/articles/{articleId}/events, after POST /api/articles/{articleId}/generate. A run that stopped at an outline for review reads COMPLETED while the article is back to DRAFT. An image regeneration has no run to read here.

Input

Returns 200 OK

Errors 400 invalid input, 401 missing or invalid key, 403 the key's roles lack the permission, 404 not found, 429 rate limited or out of quota. See Errors.

Example

import { PrismDraft } from "@prism-draft/sdk";

const pd = new PrismDraft({ apiKey: process.env.PRISMDRAFT_API_KEY! });

const result = await pd.generation.getStatus({
  articleId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
});
console.log(result);

pd.generation.cancel(input, init?)

Cancel a running generation

POST /api/articles/{articleId}/cancel

Needs articles.generate. Cancels the article's latest run; 409 when there is none or it has already ended (COMPLETED, FAILED, CANCELLED). The answer is immediate and says how: removed means the run had not started and is cancelled now (its reservation is released, the job is CANCELLED and the article returns to DRAFT); signalled means it is running and stops at its next checkpoint, which come before the outline, before each section and before each image, not during a provider call. Poll GET /api/articles/{articleId}/status for CANCELLED. A cancelled run is charged nothing, whatever it had finished. A cancel that arrives after the last image checkpoint does not stop the run, which completes and is charged normally. No webhook event is sent for a cancellation.

Input

Returns 200 OK

Errors 400 invalid input, 401 missing or invalid key, 403 the key's roles lack the permission, 404 not found, 429 rate limited or out of quota. See Errors.

Example

import { PrismDraft } from "@prism-draft/sdk";

const pd = new PrismDraft({ apiKey: process.env.PRISMDRAFT_API_KEY! });

const result = await pd.generation.cancel({
  articleId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
});
console.log(result);

pd.generation.regenerateImage(input, init?)

Regenerate an image, optionally with a new prompt or style

POST /api/articles/{articleId}/regenerate-image

Needs images.regenerate. Starts replacing the picture of one of the article's images in the background (404 when assetId is not this article's). The asset keeps its id and its place in the body; the new picture is stored under a new URL, so read publicUrl again once it is done. Always answers 202 and returns no job: completion is signalled by the image.regenerated webhook event (and article.updated when the article is published), or seen by reading the image again. Credits. 1 credit (3 when the article's imageQuality is hd) is reserved at once (402 INSUFFICIENT_CREDITS when unavailable) and charged when the new image is stored; a failed regeneration releases it. The plan's images quota applies (429 QUOTA_EXCEEDED). The idempotencyKey guards against double charging: a key used before, while its earlier request is still on record, reserves nothing, starts no second regeneration and still answers 202. The prompt and style rules are on prompt and style; the shape of the image comes from the project's image settings. Records an images.regenerated audit entry when the new image is stored.

Input

Returns 202 Accepted

Errors 400 invalid input, 401 missing or invalid key, 403 the key's roles lack the permission, 404 not found, 429 rate limited or out of quota. See Errors.

Example

import { PrismDraft } from "@prism-draft/sdk";

const pd = new PrismDraft({ apiKey: process.env.PRISMDRAFT_API_KEY! });

const result = await pd.generation.regenerateImage({
  articleId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
  body: {
    assetId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
  },
});
console.log(result);

pd.generation.updateAsset(input, init?)

Edit an image's alt text, or make it the hero or an inline image

PATCH /api/articles/{articleId}/assets/{assetId}

Send altText, type, or both (neither: 400). altText is copied to every body block showing the image. type: "hero" makes an image of the article its cover and removes every body block showing it (a new version; contentHtml and contentMarkdown are re-rendered); bodyBlocksRemoved says how many. The article has one hero: while another image is the hero the answer is 409 CONFLICT, details: { reason: "hero_exists", heroAssetId }, and nothing changes; make that one inline first. type: "inline" only changes the type: no block is put back, so the image stays unused until placed. The type the image already has changes nothing. A PUBLISHED article sends article.updated when the edit changes what it shows: a promote or demote, or an alt text that appears in the rendered content (the alt text of a cover, which no block shows, sends nothing). Needs images.update.

Input

Returns 200 OK

Errors 400 invalid input, 401 missing or invalid key, 403 the key's roles lack the permission, 404 not found, 429 rate limited or out of quota. See Errors.

Example

import { PrismDraft } from "@prism-draft/sdk";

const pd = new PrismDraft({ apiKey: process.env.PRISMDRAFT_API_KEY! });

const result = await pd.generation.updateAsset({
  articleId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
  assetId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
});
console.log(result);

pd.generation.deleteAsset(input, init?)

Delete an image

DELETE /api/articles/{articleId}/assets/{assetId}

Needs images.delete. Deletes one of the article's images, the cover or an inline one (404 when assetId is not this article's), and removes every body block that showed it, saving a new version of the document (and, for a published article, sending article.updated). The stored file is removed afterwards unless another row still uses it. Nothing is refunded: the credits the image cost were spent when it was made. Records an images.deleted audit entry.

Input

Returns 200 OK

Errors 400 invalid input, 401 missing or invalid key, 403 the key's roles lack the permission, 404 not found, 429 rate limited or out of quota. See Errors.

Example

import { PrismDraft } from "@prism-draft/sdk";

const pd = new PrismDraft({ apiKey: process.env.PRISMDRAFT_API_KEY! });

const result = await pd.generation.deleteAsset({
  articleId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
  assetId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
});
console.log(result);