Ein Video generieren

curl --request POST \
  --url https://api.samsa.ai/public/v1/videos/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "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": "minimax_h3_max",
  "duration": 8,
  "aspect_ratio": "16:9",
  "resolution": "768p"
}
'

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "pending",
  "mode": "text_to_video",
  "estimated_credits": 80
}

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "The provided API key is invalid, expired, or revoked.",
    "request_id": "8f14e45fceea167a5a36dedd4bea2543",
    "param": "aspect_ratio"
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "The provided API key is invalid, expired, or revoked.",
    "request_id": "8f14e45fceea167a5a36dedd4bea2543",
    "param": "aspect_ratio"
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "The provided API key is invalid, expired, or revoked.",
    "request_id": "8f14e45fceea167a5a36dedd4bea2543",
    "param": "aspect_ratio"
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "The provided API key is invalid, expired, or revoked.",
    "request_id": "8f14e45fceea167a5a36dedd4bea2543",
    "param": "aspect_ratio"
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "The provided API key is invalid, expired, or revoked.",
    "request_id": "8f14e45fceea167a5a36dedd4bea2543",
    "param": "aspect_ratio"
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "The provided API key is invalid, expired, or revoked.",
    "request_id": "8f14e45fceea167a5a36dedd4bea2543",
    "param": "aspect_ratio"
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "The provided API key is invalid, expired, or revoked.",
    "request_id": "8f14e45fceea167a5a36dedd4bea2543",
    "param": "aspect_ratio"
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "The provided API key is invalid, expired, or revoked.",
    "request_id": "8f14e45fceea167a5a36dedd4bea2543",
    "param": "aspect_ratio"
  }
}

POST

videos

generations

curl --request POST \
  --url https://api.samsa.ai/public/v1/videos/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "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": "minimax_h3_max",
  "duration": 8,
  "aspect_ratio": "16:9",
  "resolution": "768p"
}
'

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "pending",
  "mode": "text_to_video",
  "estimated_credits": 80
}

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "The provided API key is invalid, expired, or revoked.",
    "request_id": "8f14e45fceea167a5a36dedd4bea2543",
    "param": "aspect_ratio"
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "The provided API key is invalid, expired, or revoked.",
    "request_id": "8f14e45fceea167a5a36dedd4bea2543",
    "param": "aspect_ratio"
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "The provided API key is invalid, expired, or revoked.",
    "request_id": "8f14e45fceea167a5a36dedd4bea2543",
    "param": "aspect_ratio"
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "The provided API key is invalid, expired, or revoked.",
    "request_id": "8f14e45fceea167a5a36dedd4bea2543",
    "param": "aspect_ratio"
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "The provided API key is invalid, expired, or revoked.",
    "request_id": "8f14e45fceea167a5a36dedd4bea2543",
    "param": "aspect_ratio"
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "The provided API key is invalid, expired, or revoked.",
    "request_id": "8f14e45fceea167a5a36dedd4bea2543",
    "param": "aspect_ratio"
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "The provided API key is invalid, expired, or revoked.",
    "request_id": "8f14e45fceea167a5a36dedd4bea2543",
    "param": "aspect_ratio"
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "The provided API key is invalid, expired, or revoked.",
    "request_id": "8f14e45fceea167a5a36dedd4bea2543",
    "param": "aspect_ratio"
  }
}

Reiche einen Videogenerierungs-Job ein. Das Feld mode wählt die Form der Anfrage (image_to_video, text_to_video oder text_to_video_styled) und der Aufruf gibt 202 Accepted mit einer Job-id zurück; frage GET /videos/generations/{id} nach dem Ergebnis ab. Prüfe GET /videos/models für die von jeder Engine unterstützte duration, resolution, aspect_ratio, Endframe- und Audio-Unterstützung.

Beispiel: image-to-video mit Start- und Endframe

Im Modus image_to_video ist image der Startframe und end_image ein optionaler Endframe (nur auf endframe-fähigen Engines — siehe supports_end_frame in GET /videos/models). Jeder Frame nimmt genau eines von image_id, url oder base64 + mime_type.

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"
  }'

{
  "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 ist erforderlich und muss ein von der Engine unterstützter Wert sein (siehe durations in GET /videos/models) — ein nicht unterstützter Wert liefert 422. Für text_to_video_styled ist style_id zusätzlich zu prompt und duration erforderlich; das Dropdown des Request-Bodys oben zeigt alle drei Modi.

Autorisierungen

Authorization

string

header

erforderlich

Organization API key (Authorization: Bearer samsa_sk_...) or OAuth 2.1 access token (Authorization: Bearer samsa_at_...).

Body

application/json

PublicImageToVideoRequest
PublicTextToVideoRequest
PublicTextToVideoStyledRequest

mode: image_to_video — animate a start frame (optional end frame).

duration

integer

erforderlich

Clip length in seconds. Each engine supports a specific set — see durations in GET /videos/models. Unsupported values return 422.

Beispiel:

8

image

PublicVideoFrame · object

erforderlich

The start frame: exactly one of image_id, url, or base64+mime_type.

Show child attributes

engine

string | null

Video engine — a public engine id from GET /videos/models (e.g. minimax_h3_max, the default). Unknown engines return 422.

Beispiel:

"minimax_h3_max"

aspect_ratio

string

Standard:16:9

Aspect ratio — 16:9, 9:16, or 1:1 (engine-dependent; see aspect_ratios in GET /videos/models). On image_to_video some engines follow the framing of the supplied image and ignore this field — the MiniMax H3 family and Seedance 2.5, whose provider endpoints expose no honoured aspect-ratio input. On the text modes it selects the intermediate image and always applies.

Beispiel:

"16:9"

resolution

string | null

Output resolution — one of 720p, 768p, 1080p, 2k, 4k where the engine supports it (see resolutions in GET /videos/models; 768p and 2k are the MiniMax H3 ladder). Omit to use the engine default. Credits scale with the engine's resolution multipliers.

Beispiel:

"768p"

generate_audio

boolean

Standard:false

Generate audio with the video — audio-capable engines only (see supports_audio in GET /videos/models); adds the engine's audio credit multiplier.

Beispiel:

false

webhook_url

string | null

Optional https webhook notified once on terminal status (signed per the webhook signature scheme; see the webhooks docs).

Beispiel:

"https://example.com/webhooks/samsa"

mode

string

Standard:image_to_video

Allowed value: "image_to_video"

end_image

PublicVideoFrame · object | null

Optional end frame — only for end-frame-capable engines (see supports_end_frame in GET /videos/models).

Show child attributes

prompt

string | null

Optional text prompt guiding the motion.

Minimum string length: 1

Beispiel:

"The camera slowly pans right as waves roll in"

Antwort

Successful Response

202 body for POST /videos/generations (ADR §7.1).

string<uuid>

erforderlich

The video job id — poll GET /videos/generations/{id}.

status

enum<string>

erforderlich

Initial status: always pending at submit.

Verfügbare Optionen:

pending,

processing,

completed,

failed,

cancelled

Beispiel:

"pending"

mode

string

erforderlich

The requested mode — image_to_video, text_to_video, or text_to_video_styled.

Beispiel:

"text_to_video"

estimated_credits

integer

erforderlich

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).

Beispiel:

80

Übersicht

Endpunkte

Ein Video generieren

Beispiel: image-to-video mit Start- und Endframe

Autorisierungen

Body

Antwort

​Beispiel: image-to-video mit Start- und Endframe

Autorisierungen

Body

Antwort

Beispiel: image-to-video mit Start- und Endframe