Generations, Assets, and Artifacts

The resource hierarchy

• A Generation owns the accepted input, quote, cost reservation, and aggregate lifecycle.
• An Asset is one requested first-class output and carries its own status, contract version, and frozen resources.
• An Artifact is a concrete file or machine-readable result with its media type, size, and download URL.

Asynchronous states

Creation returns quickly. Poll GET /generations/{id} or consume signed webhooks until succeeded, partially_succeeded, failed, or cancelled. Asset failures remain explicit; partial success never masquerades as complete success.

Full-Asset edits

Editing creates a new priced Generation from the original frozen context. Preview the edit first, select the target Asset IDs, provide replacement instructions, then accept under a new max_cost_usd. Existing Artifacts remain immutable.

const edit = { asset_ids: ['ast_example'], instructions: 'Make the tone more concise.' }
const quote = await client.generations.previewEdit('gen_example', edit)

await client.generations.edit('gen_example', {
  ...edit,
  max_cost_usd: quote.total_cost_usd,
})