> ## Documentation Index
> Fetch the complete documentation index at: https://docs.samsa.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Genera un video
> Invia un job video in modalità image-to-video, text-to-video, o text-to-video-styled.
Invia un job di generazione di video. Il campo `mode` seleziona la forma della
richiesta (`image_to_video`, `text_to_video` o `text_to_video_styled`) e la
chiamata restituisce **`202 Accepted`** con un `id` del job; interroga
[`GET /videos/generations/{id}`](/it/api-reference/videos/get-generation) per il
risultato. Controlla
[`GET /videos/models`](/it/api-reference/videos/list-engines) per il supporto di
ciascun engine a `duration`, `resolution`, `aspect_ratio`, frame finale e audio.
## Esempio: image-to-video con frame iniziale e finale
In modalità `image_to_video`, `image` è il frame iniziale ed `end_image` un frame
finale facoltativo (solo sugli engine che supportano il frame finale — vedi
`supports_end_frame` in
[`GET /videos/models`](/it/api-reference/videos/list-engines)). Ogni frame accetta
**esattamente uno** tra `image_id`, `url`, oppure `base64` + `mime_type`.
```bash curl theme={null}
curl -X POST https://api.samsa.ai/public/v1/videos/generations \
-H "Authorization: Bearer $SAMSA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"mode": "image_to_video",
"image": { "url": "https://cdn.example.com/start-frame.png" },
"end_image": { "url": "https://cdn.example.com/end-frame.png" },
"prompt": "The camera slowly pans right as waves roll in",
"engine": "veo_3_1_lite",
"duration": 8,
"aspect_ratio": "16:9",
"resolution": "720p"
}'
```
```json Body theme={null}
{
"mode": "image_to_video",
"image": { "url": "https://cdn.example.com/start-frame.png" },
"end_image": { "url": "https://cdn.example.com/end-frame.png" },
"prompt": "The camera slowly pans right as waves roll in",
"engine": "veo_3_1_lite",
"duration": 8,
"aspect_ratio": "16:9",
"resolution": "720p"
}
```
`duration` è obbligatorio e deve essere uno tra quelli supportati dall'engine
(vedi `durations` in
[`GET /videos/models`](/it/api-reference/videos/list-engines)) — un valore non
supportato restituisce `422`. Per `text_to_video_styled`, `style_id` è
obbligatorio insieme a `prompt` e `duration`; il menu a tendina del corpo della
richiesta qui sopra mostra tutte e tre le modalità.
## OpenAPI
````yaml api-reference/openapi.json POST /videos/generations
openapi: 3.1.0
info:
title: Samsa API
description: >-
The Samsa public REST API. Authenticate with an organization API key as a
bearer token (`Authorization: Bearer samsa_sk_...`). Errors follow a single
envelope shape; every response carries an `X-Request-ID`.
version: 1.0.0
servers:
- url: https://api.samsa.ai/public/v1
security:
- BearerAuth: []
paths:
/videos/generations:
post:
tags:
- Videos
summary: Generate a video (image-to-video, text-to-video, or styled)
description: >-
Submits a video-generation job and returns `202` immediately with the
job `id` and a credit estimate; poll `GET /videos/generations/{id}` for
the result. The `mode` field selects the workflow: `image_to_video`
animates a start frame (`image_id`, https `url`, or
`base64`+`mime_type`; optional `end_image` on end-frame-capable
engines), `text_to_video` generates from a `prompt`, and
`text_to_video_styled` combines a `prompt` with trained models you own
(including your own private models) or shared within your organization
(`style_id`, `object_ids`, `person_ids`, `setting_ids` — each accepts a
model NAME or its UUID `id` from `GET /models`; a name matching more
than one visible model is rejected, pass the `id` — plus
`color_palette_id`, a palette NAME or its UUID `id`). Engines,
durations, resolutions, and audio support are engine-specific — discover
them via `GET /videos/models`. Billing: base 5 credits/second x engine
multiplier x resolution multiplier x audio multiplier (styled adds a
flat 10 for the intermediate image). Requires the `videos.generate`
scope.
operationId: create_video_generation_videos_generations_post
requestBody:
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/PublicImageToVideoRequest'
- $ref: '#/components/schemas/PublicTextToVideoRequest'
- $ref: '#/components/schemas/PublicTextToVideoStyledRequest'
title: Request
examples:
image_to_video:
summary: Animate an image (start + end frame)
value:
mode: image_to_video
image:
url: https://cdn.example.com/start-frame.png
end_image:
url: https://cdn.example.com/end-frame.png
prompt: The camera slowly pans right as waves roll in
engine: veo_3_1_lite
duration: 8
aspect_ratio: '16:9'
resolution: 720p
text_to_video:
summary: Generate a video from a prompt
value:
mode: text_to_video
prompt: A drone shot over a foggy pine forest at sunrise
engine: veo_3_1
duration: 8
aspect_ratio: '16:9'
generate_audio: true
text_to_video_styled:
summary: Generate a video with your trained models
value:
mode: text_to_video_styled
prompt: The product rotating on a marble pedestal, studio lighting
style_id: 11111111-1111-1111-1111-111111111111
setting_ids:
- 22222222-2222-2222-2222-222222222222
engine: kling_2_5_pro_turbo
duration: 5
aspect_ratio: '1:1'
required: true
responses:
'202':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/PublicVideoGenerationAccepted'
'401':
description: Missing, invalid, expired, or revoked API key.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'402':
description: Insufficient credits, or no usable org subscription.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'403':
description: The API key lacks the required scope for this operation.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'404':
description: Generation, or a referenced model/palette/image, not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'409':
description: A referenced model is not ready for generation.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'422':
description: >-
Request validation failed (engine, duration, resolution, frames,
...).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'429':
description: Per-key rate limit or per-org concurrency cap exceeded.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
components:
schemas:
PublicImageToVideoRequest:
properties:
engine:
anyOf:
- type: string
- type: 'null'
title: Engine
description: >-
Video engine — a public engine id from `GET /videos/models` (e.g.
`veo_3_1_lite`, the default). Unknown engines return `422`.
examples:
- veo_3_1_lite
duration:
type: integer
title: Duration
description: >-
Clip length in seconds. Each engine supports a specific set — see
`durations` in `GET /videos/models`. Unsupported values return
`422`.
examples:
- 8
aspect_ratio:
type: string
title: Aspect Ratio
description: >-
Aspect ratio — `16:9`, `9:16`, or `1:1` (engine-dependent; see
`aspect_ratios` in `GET /videos/models`).
default: '16:9'
examples:
- '16:9'
resolution:
anyOf:
- type: string
- type: 'null'
title: Resolution
description: >-
Output resolution — `720p`, `1080p`, or `4k` where the engine
supports it (see `resolutions` in `GET /videos/models`). Omit to use
the engine default. Credits scale with the engine's resolution
multipliers.
examples:
- 720p
generate_audio:
type: boolean
title: Generate Audio
description: >-
Generate audio with the video — audio-capable engines only (see
`supports_audio` in `GET /videos/models`); adds the engine's audio
credit multiplier.
default: false
examples:
- false
webhook_url:
anyOf:
- type: string
- type: 'null'
title: Webhook Url
description: >-
Optional https webhook notified once on terminal status (signed per
the webhook signature scheme; see the webhooks docs).
examples:
- https://example.com/webhooks/samsa
mode:
type: string
const: image_to_video
title: Mode
default: image_to_video
image:
$ref: '#/components/schemas/PublicVideoFrame'
description: >-
The start frame: exactly one of `image_id`, `url`, or
`base64`+`mime_type`.
end_image:
anyOf:
- $ref: '#/components/schemas/PublicVideoFrame'
- type: 'null'
description: >-
Optional end frame — only for end-frame-capable engines (see
`supports_end_frame` in `GET /videos/models`).
prompt:
anyOf:
- type: string
minLength: 1
- type: 'null'
title: Prompt
description: Optional text prompt guiding the motion.
examples:
- The camera slowly pans right as waves roll in
type: object
required:
- duration
- image
title: PublicImageToVideoRequest
description: '`mode: image_to_video` — animate a start frame (optional end frame).'
PublicTextToVideoRequest:
properties:
engine:
anyOf:
- type: string
- type: 'null'
title: Engine
description: >-
Video engine — a public engine id from `GET /videos/models` (e.g.
`veo_3_1_lite`, the default). Unknown engines return `422`.
examples:
- veo_3_1_lite
duration:
type: integer
title: Duration
description: >-
Clip length in seconds. Each engine supports a specific set — see
`durations` in `GET /videos/models`. Unsupported values return
`422`.
examples:
- 8
aspect_ratio:
type: string
title: Aspect Ratio
description: >-
Aspect ratio — `16:9`, `9:16`, or `1:1` (engine-dependent; see
`aspect_ratios` in `GET /videos/models`).
default: '16:9'
examples:
- '16:9'
resolution:
anyOf:
- type: string
- type: 'null'
title: Resolution
description: >-
Output resolution — `720p`, `1080p`, or `4k` where the engine
supports it (see `resolutions` in `GET /videos/models`). Omit to use
the engine default. Credits scale with the engine's resolution
multipliers.
examples:
- 720p
generate_audio:
type: boolean
title: Generate Audio
description: >-
Generate audio with the video — audio-capable engines only (see
`supports_audio` in `GET /videos/models`); adds the engine's audio
credit multiplier.
default: false
examples:
- false
webhook_url:
anyOf:
- type: string
- type: 'null'
title: Webhook Url
description: >-
Optional https webhook notified once on terminal status (signed per
the webhook signature scheme; see the webhooks docs).
examples:
- https://example.com/webhooks/samsa
mode:
type: string
const: text_to_video
title: Mode
default: text_to_video
prompt:
type: string
minLength: 1
title: Prompt
description: >-
Text prompt. Runs the same validation as the app (rejects empty /
malformed / policy-violating prompts with a `422`).
examples:
- A drone shot over a foggy pine forest at sunrise
type: object
required:
- duration
- prompt
title: PublicTextToVideoRequest
description: '`mode: text_to_video` — generate a video from a prompt.'
PublicTextToVideoStyledRequest:
properties:
engine:
anyOf:
- type: string
- type: 'null'
title: Engine
description: >-
Video engine — a public engine id from `GET /videos/models` (e.g.
`veo_3_1_lite`, the default). Unknown engines return `422`.
examples:
- veo_3_1_lite
duration:
type: integer
title: Duration
description: >-
Clip length in seconds. Each engine supports a specific set — see
`durations` in `GET /videos/models`. Unsupported values return
`422`.
examples:
- 8
aspect_ratio:
type: string
title: Aspect Ratio
description: >-
Aspect ratio — `16:9`, `9:16`, or `1:1` (engine-dependent; see
`aspect_ratios` in `GET /videos/models`).
default: '16:9'
examples:
- '16:9'
resolution:
anyOf:
- type: string
- type: 'null'
title: Resolution
description: >-
Output resolution — `720p`, `1080p`, or `4k` where the engine
supports it (see `resolutions` in `GET /videos/models`). Omit to use
the engine default. Credits scale with the engine's resolution
multipliers.
examples:
- 720p
generate_audio:
type: boolean
title: Generate Audio
description: >-
Generate audio with the video — audio-capable engines only (see
`supports_audio` in `GET /videos/models`); adds the engine's audio
credit multiplier.
default: false
examples:
- false
webhook_url:
anyOf:
- type: string
- type: 'null'
title: Webhook Url
description: >-
Optional https webhook notified once on terminal status (signed per
the webhook signature scheme; see the webhooks docs).
examples:
- https://example.com/webhooks/samsa
mode:
type: string
const: text_to_video_styled
title: Mode
default: text_to_video_styled
prompt:
type: string
minLength: 1
title: Prompt
description: Text prompt. Runs the same validation as the app.
examples:
- The product rotating on a marble pedestal, studio lighting
style_id:
anyOf:
- type: string
format: uuid
- type: string
maxLength: 100
minLength: 1
title: Style Id
description: >-
A `style` model NAME or its UUID `id` (from `list_models`), resolved
within your visible set — a model you own (including your own
private models) or a non-private one shared with your organization.
A name matching more than one visible model is rejected — pass the
`id`. Must be `completed`.
object_ids:
items:
anyOf:
- type: string
format: uuid
- type: string
maxLength: 100
minLength: 1
type: array
title: Object Ids
description: >-
`object` models to compose in — each a model NAME or its UUID `id`
(from `list_models`), resolved within your visible set (a model you
own, including private, or a non-private one your organization
shares). A name matching more than one visible model is rejected —
pass the `id`.
person_ids:
items:
anyOf:
- type: string
format: uuid
- type: string
maxLength: 100
minLength: 1
type: array
title: Person Ids
description: >-
`person` models to compose in — each a model NAME or its UUID `id`
(from `list_models`), resolved within your visible set (a model you
own, including private, or a non-private one your organization
shares). A name matching more than one visible model is rejected —
pass the `id`.
setting_ids:
items:
anyOf:
- type: string
format: uuid
- type: string
maxLength: 100
minLength: 1
type: array
title: Setting Ids
description: >-
`setting` models to compose in — each a model NAME or its UUID `id`
(from `list_models`), resolved within your visible set (a model you
own, including private, or a non-private one your organization
shares). A name matching more than one visible model is rejected —
pass the `id`. Maps to internal scenes.
color_palette_id:
anyOf:
- type: string
format: uuid
- type: string
maxLength: 100
minLength: 1
- type: 'null'
title: Color Palette Id
description: >-
A color palette NAME or its UUID `id`, resolved within your visible
set — a palette you created (including private ones) or a
non-private palette shared with your organization. A name matching
more than one visible palette is rejected — pass the `id`.
type: object
required:
- duration
- prompt
- style_id
title: PublicTextToVideoStyledRequest
description: >-
`mode: text_to_video_styled` — prompt + trained models you own or shared
with your org.
PublicVideoGenerationAccepted:
properties:
id:
type: string
format: uuid
title: Id
description: The video job id — poll `GET /videos/generations/{id}`.
status:
$ref: '#/components/schemas/PublicVideoStatus'
description: 'Initial status: always `pending` at submit.'
examples:
- pending
mode:
type: string
title: Mode
description: >-
The requested mode — `image_to_video`, `text_to_video`, or
`text_to_video_styled`.
examples:
- text_to_video
estimated_credits:
type: integer
title: Estimated Credits
description: >-
Credits this job is expected to cost (base 5/sec x engine multiplier
x resolution x audio; styled adds a flat 10 for the intermediate
image).
examples:
- 80
type: object
required:
- id
- status
- mode
- estimated_credits
title: PublicVideoGenerationAccepted
description: '`202` body for `POST /videos/generations` (ADR §7.1).'
ErrorEnvelope:
properties:
error:
$ref: '#/components/schemas/ErrorDetail'
type: object
required:
- error
title: ErrorEnvelope
description: The complete public error body — an ``error`` object wrapper (ADR §5).
PublicVideoFrame:
properties:
image_id:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Image Id
description: Id of an image in your organization's context to edit.
url:
anyOf:
- type: string
- type: 'null'
title: Url
description: https URL of the source image (downloaded under SSRF guards).
examples:
- https://cdn.example.com/photo.png
base64:
anyOf:
- type: string
- type: 'null'
title: Base64
description: Base64-encoded source image bytes (send with `mime_type`).
mime_type:
anyOf:
- type: string
- type: 'null'
title: Mime Type
description: >-
MIME type for a base64 source — one of: image/jpeg, image/png,
image/webp.
examples:
- image/png
type: object
title: PublicVideoFrame
description: >-
A start or end frame for video generation — exactly one of three modes.
Same contract as the image-edit source (SAM-556): ``image_id`` (an image
in
the key creator's context, ownership enforced in the route -> 404), an
``https`` ``url`` downloaded under the SSRF guard, or inline ``base64``
+
``mime_type``. Zero or more than one mode is a ``422``.
PublicVideoStatus:
type: string
enum:
- pending
- processing
- completed
- failed
- cancelled
title: PublicVideoStatus
description: >-
Public video-job status — the lower-cased internal ``VideoTaskStatus``.
Same convention as the shipped image/models surfaces (plain lower-case,
NOT
the ADR §7.2 ``queued`` remap): the ticket's 202 uses ``status:
"pending"``.
ErrorDetail:
properties:
type:
type: string
title: Type
examples:
- authentication_error
code:
type: string
title: Code
examples:
- invalid_api_key
message:
type: string
title: Message
examples:
- The provided API key is invalid, expired, or revoked.
request_id:
type: string
title: Request Id
examples:
- 8f14e45fceea167a5a36dedd4bea2543
param:
anyOf:
- type: string
- type: 'null'
title: Param
description: Present on validation errors — names the offending field.
examples:
- aspect_ratio
type: object
required:
- type
- code
- message
- request_id
title: ErrorDetail
description: The ``error`` object of the public envelope (ADR §5).
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: >-
Organization API key as a bearer token: `Authorization: Bearer
samsa_sk_...`.
````