POST
/
v1
/
teams
/
{teamId}
/
ai-media
/
generations
TypeScript client
import { OctosparkClient } from '@octospark/sdk'

const client = new OctosparkClient({
  token: process.env.OCTOSPARK_TOKEN
})

const response = await client.aiMedia.createGeneration({
  teamId: process.env.OCTOSPARK_TEAM_ID ?? "teamId",
  body: {},
})
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "teamId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "organizationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "modelId": "<string>",
  "statusError": "<string>",
  "primaryAssetId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "assetIds": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "estimatedCostDecimillicents": 123,
  "actualCostDecimillicents": 123,
  "callerIdempotencyKey": "<string>",
  "createdAt": "<string>",
  "updatedAt": "<string>"
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

​
teamId
string
required

Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context.

Body

application/json
​
sourceSurface
enum<string>
required

Where the generation was started from (studio, agent, or editor). Used for attribution; it does not change how the media is produced.

Available options:
studio,
agent,
editor
​
modality
enum<string>
required

What to generate: image or video. Must match the chosen model and the shape of params.

Available options:
image,
video
​
modelId
string
required

Catalog model id to generate with, e.g. "google/veo-3.1-fast". List models to see the available ids and their capabilities.

​
params
object
required

Generation parameters for the chosen modality (prompt, aspect ratio, duration, reference images, and so on). The shape must match the model's capabilities; mismatches are rejected.

​
promptPreview
string

Short human-readable summary of the prompt, stored on the generation row for display in lists and history.

​
folderId
string<uuid> | null

Media-library folder id to place the generated asset in. null or omitted uses the team default location.

Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
​
chatSessionId
string<uuid> | null

Agent chat session id to associate this generation with when it was started from /agent chat.

Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
​
targetPostId
string | null

Id of a post to attach the generated media to once it completes.

​
idempotencyKey
string

Client-supplied key so a retried request returns the original generation instead of starting (and charging for) a second one.

Response

Success

​
id
string<uuid>
required

a Universally Unique Identifier

Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
​
teamId
string<uuid>
required

a Universally Unique Identifier

Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
​
organizationId
string<uuid>
required

a Universally Unique Identifier

Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
​
sourceSurface
enum<string>
required
Available options:
studio,
agent,
editor
​
modelId
string
required
​
modality
enum<string>
required
Available options:
image,
video
​
route
enum<string>
required
Available options:
openrouter,
fal
​
status
enum<string>
required
Available options:
queued,
reserved,
running,
rate_limited,
ready,
failed,
cancelled,
skipped_insufficient_credits
​
statusError
string | null
required
​
primaryAssetId
string<uuid> | null
required

a Universally Unique Identifier

Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
​
assetIds
string<uuid>[]
required

a Universally Unique Identifier

Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
​
estimatedCostDecimillicents
number
required
​
actualCostDecimillicents
number
required
​
callerIdempotencyKey
string | null
required
​
createdAt
string
required
​
updatedAt
string
required