Reference

API reference for every route

Models

The models a key may call, with what each is sold for.

The models this key may call. A model with no price is absent; it is not for sale.

GET/v1/models

Example request

curl https://sven.swedishembedded.com/v1/models \
  -H "Authorization: Bearer $SVEN_API_KEY"

Responses

200 The models this key may call, as a list. `pricing` states what a model is sold for in exact US dollars, as text: per token for `prompt` and `completion`, per image for `image`, "0" for a fee not charged. `supported_parameters` is as the model's provider listed it, null where nobody did.

The models this key may call. A model with no price is absent; it is not for sale.: 200 response
Name	Type	Description
objectrequired	string, only list
default_model	string	The model this account's sessions start with when none is named.
datarequired	array of object	The models, one entry each.
data[].idrequired	string	The name to send as `model`.
data[].objectrequired	string, only model
data[].name	string	What people call the model.
data[].description	string	A line about the model.
data[].context_length	integer	How many tokens of conversation it can take; null where unknown.
data[].architecture	object	What the model reads and writes.
data[].architecture.input_modalities	array of string	For example text and image.
data[].architecture.output_modalities	array of string
data[].architecture.tokenizer	string
data[].top_provider	object
data[].top_provider.max_completion_tokens	integer	The longest answer it can write; null where unknown.
data[].supported_parameters	array of string	The request parameters the model takes.
data[].image_parameters	object	For an image model: the parameters it takes with their allowed values, and how many reference images a call may carry.
data[].image_parameters.parameters	object	By name: `{type: enum, values}`, `{type: range, min, max}` or `{type: boolean}`.
data[].image_parameters.max_references	integer	The most reference images one call may carry.
data[].capabilitiesrequired	array of string, one of chat, tools, embeddings, images, transcription, speech	What the model can be called for.
data[].pricingrequired	object	What the model is sold for, in exact US dollars as text.
data[].pricing.prompt	string	Per input token (per second of audio for a speech-to-text model
data[].pricing.completion	string	Per output token.
data[].pricing.image	string	Per image: what a typical image is charged (about a megapixel, a short prompt, no reference image). A call is charged what its image cost, so a larger image or one with references costs more, never more than `image_max`.
data[].pricing.image_max	string	For an image model: the most one image is ever charged, the largest size and every reference counted. What a call is held at before it runs.
data[].pricing.request	string
data[].pricing.web_search	string
data[].pricing.internal_reasoning	string
data[].zero_data_retention	boolean	True when a call to the model keeps no data anywhere.
data[].needs_data_sharing	boolean, only true	Present when the model is served only by providers that may keep data and the person the key acts for has not allowed sharing data with it: a call is refused (403, `data_sharing_not_allowed`) until they allow it.
data[].supported_voices	array of string	The voices a text-to-speech model can say a text in.

json

{
  "object": "list",
  "default_model": "MODEL_ID",
  "data": [
    {
      "id": "MODEL_ID",
      "object": "model",
      "name": "Model name",
      "context_length": 131072,
      "capabilities": [
        "chat",
        "tools"
      ],
      "zero_data_retention": true,
      "pricing": {
        "prompt": "0.0000001",
        "completion": "0.0000004",
        "request": "0",
        "image": "0",
        "web_search": "0",
        "internal_reasoning": "0"
      }
    }
  ]
}

Errors

The models this key may call. A model with no price is absent; it is not for sale.: errors
Status	Type	When
401	authentication_error	No key, or a key that is unknown, expired or removed.

Every refusal carries the error object described on Errors.

Allow a model that may keep data, for the next call or from now on.

POST/v1/data-sharing

The answer a person gives in their own terminal when an agent asks to use a model served only by providers that may keep data (needs_data_sharing in the model list). once lets the next call to it through within 15 minutes; always sets the model to Allow under Settings, Models. Only a key the person issued and that acts for them may send it: a key of a hosted or cloud environment or of a case run is refused, so an agent cannot allow a model for itself.

Request body application/json

Allow a model that may keep data, for the next call or from now on.: application/json body
Name	Type	Description
modelrequired	string	The model to allow.
allowrequired	string, one of once, always	`once`: the next call; `always`: from now on.

Example request

curl https://sven.swedishembedded.com/v1/data-sharing \
  -H "Authorization: Bearer $SVEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "MODEL_ID", "allow": "once"}'

Responses

200 Recorded.

Allow a model that may keep data, for the next call or from now on.: 200 response
Name	Type	Description
modelrequired	string
allowrequired	string, one of once, always

json

{
  "model": "MODEL_ID",
  "allow": "once"
}

Errors

Allow a model that may keep data, for the next call or from now on.: errors
Status	Type	When
400	invalid_request_error	The request is malformed, sets a parameter the model does not accept (`error.param` names it), or carries a conversation longer than the model can take.
401	authentication_error	No key, or a key that is unknown, expired or removed.
403	permission_error	The key was not issued by the person it acts for (a key of an environment or a case run), or `error.code` is `data_sharing_forbidden`: the person's organisation does not allow sharing data with model providers.

Every refusal carries the error object described on Errors.

Chat

Chat with a model, streamed or whole, with tools and images.

Chat completion, optionally streamed as server-sent events.

POST/v1/chat/completions

Send a conversation, get the model's reply.

Limits: at least one message; n is 1; images are base64 data URLs of PNG, JPEG, GIF or WebP, up to 10 MiB each; the body is at most 32 MiB; a conversation longer than the model can take is refused with 400 on messages. A key and an account have rate limits; a call refused for one says when to retry in Retry-After.

Parameters

Chat completion, optionally streamed as server-sent events.: parameters
Name	Type	Description
Idempotency-Key	string, 1 to 255 characters	1 to 255 printable characters. A retry with the same value, API key and request body answers the first call's result without a second charge.

Request body application/json

Chat completion, optionally streamed as server-sent events.: application/json body
Name	Type	Description
modelrequired	string	A model id from GET /v1/models.
messagesrequired	array of object, at least 1 item	The conversation. Each message has a `role` (system, user, assistant or tool) and `content`: text, or for a user message a list of `text` and `image_url` parts (an image is a base64 data URL).
temperature	number, 0 to 2
top_p	number, 0 to 1
max_tokens	integer, at least 1	The most tokens to write.
max_completion_tokens	integer, at least 1	The same limit under its newer name; it wins when both are sent.
stop	string or array of string	Where the model stops writing.
n	integer, only 1	Only 1 is accepted.
tools	array of object	Functions the model may call, as `{type: function, function: {name, description, parameters}}`.
tool_choice	string or object	`none`, `auto`, `required`, or a named function.
stream	boolean	Server-sent events instead of one JSON body.
stream_options	object

Example request

curl https://sven.swedishembedded.com/v1/chat/completions \
  -H "Authorization: Bearer $SVEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "MODEL_ID", "messages": [{"role": "user", "content": "Hello"}]}'

Responses

200 The completion (`application/json`), or with `stream` an event stream (`text/event-stream`) of `chat.completion.chunk` objects that ends with `data: [DONE]`.

Chat completion, optionally streamed as server-sent events.: 200 response
Name	Type	Description
idrequired	string	The completion's id.
objectrequired	string, only chat.completion
createdrequired	integer	When it was made
modelrequired	string	The model that answered.
choicesrequired	array of object	The reply; always one choice.
choices[].index	integer
choices[].message	object
choices[].message.role	string, only assistant
choices[].message.content	string	The text; null when the model called a tool.
choices[].message.tool_calls	array of object	The tools the model called, each with the `id` to answer in a `tool` message.
choices[].message.tool_calls[].id	string
choices[].message.tool_calls[].type	string, only function
choices[].message.tool_calls[].function	object
choices[].finish_reason	string, one of stop, length, tool_calls, content_filter	Why the reply ended.
usagerequired	object	What the call is charged for.
usage.prompt_tokens	integer	Every input token
usage.completion_tokens	integer
usage.total_tokens	integer
usage.prompt_tokens_details	object	Present where the model reported it.
usage.prompt_tokens_details.cached_tokens	integer	Input tokens the model had just read and reused
usage.cost	number	What the call was charged

json

{
  "id": "chatcmpl-1",
  "object": "chat.completion",
  "model": "MODEL_ID",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 9,
    "completion_tokens": 8,
    "total_tokens": 17,
    "cost": 0.000041
  }
}

Errors

Chat completion, optionally streamed as server-sent events.: errors
Status	Type	When
400	invalid_request_error	The request is malformed, sets a parameter the model does not accept (`error.param` names it), or carries a conversation longer than the model can take.
401	authentication_error	No key, or a key that is unknown, expired or removed.
402	insufficient_quota	The account's credit, the key's spending limit or the monthly budget cannot cover what the call could cost. `error.code` is `key_spend_limit` or `monthly_budget` when a limit refused it, and absent when credit ran out.
403	permission_error	The key is restricted to other models, or the model is served only by providers that may keep data and sharing data with it is not allowed. `error.code` is `data_sharing_not_allowed` when the person the key acts for has not allowed it (they can: once, or always under Settings, Models), and `data_sharing_forbidden` when their organization does not allow it (they cannot).
404	model_not_found	There is no such model, or it has no price and is not for sale.
409	idempotency_error	A call with this Idempotency-Key is still running, or it finished and its stored answer is gone.
413	invalid_request_error	The body is past the size limit.
429	rate_limit_error	Too many calls per minute or at once, or the model is busy. `error.code` is `key_rate` or `workspace_concurrency` when a limit refused it; `Retry-After` says when to retry.
500	server_error	Something failed inside the service. The response says nothing about how.
503	server_error	The model is temporarily unavailable, or is not for sale right now.

Every refusal carries the error object described on Errors.

Messages

The same chat as messages in the shape Anthropic's clients send, for code that already uses them.

Chat as messages, optionally streamed as server-sent events.

POST/v1/messages

The chat of POST /v1/chat/completions as messages, for code written for Anthropic's clients, which work against it unchanged: they send their anthropic-version for you, and take the API's address without /v1 as their base URL. Versions 2023-06-01 and 2026-10-21 are spoken; under 2026-10-21, temperature, top_p and top_k and a user's text with citations are refused with 400, as that version removed them. Any other version, and the anthropic-beta header, are refused with 400, and extended thinking cannot be switched on. The key may be sent as x-api-key or as a bearer token. Errors come back as {type: error, error: {type, message}}.

Parameters

Chat as messages, optionally streamed as server-sent events.: parameters
Name	Type	Description
Idempotency-Key	string, 1 to 255 characters	1 to 255 printable characters. A retry with the same value, API key and request body answers the first call's result without a second charge.
anthropic-versionrequired	string, one of 2023-06-01, 2026-10-21	The API version, `2026-10-21` (what current clients send) or `2023-06-01`.

Request body application/json

Chat as messages, optionally streamed as server-sent events.: application/json body
Name	Type	Description
modelrequired	string	A model id from GET /v1/models.
messagesrequired	array of object	The conversation, as Anthropic's client sends it: alternating user and assistant messages.
max_tokensrequired	integer, at least 1	The most tokens to write.
system	string or array of object	Instructions for the whole conversation, as text or text blocks.
temperature	number, 0 to 1
top_p	number, 0 to 1
top_k	integer, 1 to 1000
stop_sequences	array of string
tools	array of object	Tools the model may call, as Anthropic's clients send them.
tool_choice	object	How the model chooses among the tools.
thinking	object	Only `{"type": "disabled"}` is accepted.
stream	boolean	Server-sent events instead of one JSON body.

Example request

curl https://sven.swedishembedded.com/v1/messages \
  -H "x-api-key: $SVEN_API_KEY" \
  -H "anthropic-version: 2026-10-21" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_ID",
    "max_tokens": 256,
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Responses

200 The message, or with `stream` an event stream (`message_start`, `content_block_delta`, `message_delta`, `message_stop` and the others of that kind).

Chat as messages, optionally streamed as server-sent events.: 200 response
Name	Type	Description
idrequired	string
typerequired	string, only message
rolerequired	string, only assistant
modelrequired	string	The model that answered.
contentrequired	array of object	The reply as blocks, `text` or `tool_use`.
content[].type	string, one of text, tool_use
content[].text	string	The text of a `text` block.
content[].id	string	The id of a `tool_use` block.
content[].name	string	The tool a `tool_use` block calls.
content[].input	object	The arguments of a `tool_use` block.
stop_reasonrequired	string, one of end_turn, max_tokens, stop_sequence, tool_use	Why the reply ended.
usagerequired	object	What the call is charged for.
usage.input_tokens	integer	Input read afresh.
usage.output_tokens	integer
usage.cache_read_input_tokens	integer	Input reused from the cache

json

{
  "id": "msg_1",
  "type": "message",
  "role": "assistant",
  "model": "MODEL_ID",
  "content": [
    {
      "type": "text",
      "text": "Hello! How can I help?"
    }
  ],
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 9,
    "output_tokens": 8
  }
}

Errors

Chat as messages, optionally streamed as server-sent events.: errors
Status	Type	When
400	invalid_request_error	The request is malformed, sets a parameter or version that is not supported, or carries a conversation longer than the model can take.
401	authentication_error	No key, or a key that is unknown, expired or removed.
402	billing_error	The account's credit, the key's spending limit or the monthly budget cannot cover what the call could cost.
403	permission_error	The key is restricted to other models, or the model is served only by providers that may keep data and sharing data with it is not allowed. The `x-error-code` header is `data_sharing_not_allowed` when the person the key acts for has not allowed it (they can), and `data_sharing_forbidden` when their organization does not allow it (they cannot).
404	not_found_error	There is no such model, or it is not for sale.
409	invalid_request_error	A call with this Idempotency-Key is still running, or it finished and its stored answer is gone.
429	rate_limit_error	Too many calls per minute or at once, or the model is busy; `Retry-After` says when to retry.
500	api_error	Something failed inside the service.
529	overloaded_error	The model is temporarily unavailable.

Every refusal carries the error object described on Errors.

Embeddings

Vectors for texts, charged per input token.

Embeddings of one or more texts, as float arrays.

POST/v1/embeddings

Limits: one text or up to 2048, none empty; encoding_format is float (send it explicitly, because some clients ask for another encoding unless told otherwise); dimensions is not accepted.

Parameters

Embeddings of one or more texts, as float arrays.: parameters
Name	Type	Description
Idempotency-Key	string, 1 to 255 characters	1 to 255 printable characters. A retry with the same value, API key and request body answers the first call's result without a second charge.

Request body application/json

Embeddings of one or more texts, as float arrays.: application/json body
Name	Type	Description
modelrequired	string	An embedding model id from GET /v1/models.
inputrequired	string, at least 1 characters or array of string, at least 1 characters, 1 to 2048 items	One text, or up to 2048 texts.
encoding_format	string, only float

Example request

curl https://sven.swedishembedded.com/v1/embeddings \
  -H "Authorization: Bearer $SVEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "MODEL_ID", "input": ["Hello", "World"]}'

Responses

200 One embedding per input, charged per input token.

Embeddings of one or more texts, as float arrays.: 200 response
Name	Type	Description
objectrequired	string, only list
modelrequired	string
datarequired	array of object	One embedding per input, in order.
data[].object	string, only embedding
data[].index	integer	The input this is the embedding of.
data[].embedding	array of number	The vector.
usagerequired	object	What the call is charged for.
usage.prompt_tokens	integer
usage.total_tokens	integer

json

{
  "object": "list",
  "model": "MODEL_ID",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [
        0.0123,
        -0.0456,
        0.0789
      ]
    },
    {
      "object": "embedding",
      "index": 1,
      "embedding": [
        0.0345,
        0.0211,
        -0.0102
      ]
    }
  ],
  "usage": {
    "prompt_tokens": 2,
    "total_tokens": 2
  }
}

Errors

Embeddings of one or more texts, as float arrays.: errors
Status	Type	When
400	invalid_request_error	The request is malformed, sets a parameter the model does not accept (`error.param` names it), or carries a conversation longer than the model can take.
401	authentication_error	No key, or a key that is unknown, expired or removed.
402	insufficient_quota	The account's credit, the key's spending limit or the monthly budget cannot cover what the call could cost. `error.code` is `key_spend_limit` or `monthly_budget` when a limit refused it, and absent when credit ran out.
404	model_not_found	There is no such model, or it has no price and is not for sale.
409	idempotency_error	A call with this Idempotency-Key is still running, or it finished and its stored answer is gone.
429	rate_limit_error	Too many calls per minute or at once, or the model is busy. `error.code` is `key_rate` or `workspace_concurrency` when a limit refused it; `Retry-After` says when to retry.
500	server_error	Something failed inside the service. The response says nothing about how.
503	server_error	The model is temporarily unavailable, or is not for sale right now.

Every refusal carries the error object described on Errors.

Images

Images from a prompt, charged per image delivered.

Images from a prompt, returned inline as base64 PNG.

POST/v1/images/generations

Limits: 1 to 10 images a call, each side of size 1 to 4096; response_format is b64_json, because images are returned inline, never as links.

Parameters

Images from a prompt, returned inline as base64 PNG.: parameters
Name	Type	Description
Idempotency-Key	string, 1 to 255 characters	1 to 255 printable characters. A retry with the same value, API key and request body answers the first call's result without a second charge.

Request body application/json

Images from a prompt, returned inline as base64 PNG.: application/json body
Name	Type	Description
modelrequired	string	A model id from GET /v1/models.
promptrequired	string, at least 1 characters	What to draw.
n	integer, 1 to 10	How many images. Default: 1.
size	string	WIDTHxHEIGHT, each side 1 to 4096.
response_format	string, only b64_json

Example request

curl https://sven.swedishembedded.com/v1/images/generations \
  -H "Authorization: Bearer $SVEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_ID",
    "prompt": "A lighthouse at dawn",
    "n": 1,
    "size": "1024x1024"
  }'

Responses

200 The images, inline; charged per image delivered.

Images from a prompt, returned inline as base64 PNG.: 200 response
Name	Type	Description
createdrequired	integer	When they were made
datarequired	array of object	The images, in order.
data[].b64_json	string	The image as base64 PNG.

json

{
  "created": 1767225600,
  "data": [
    {
      "b64_json": "iVBORw0KGgo..."
    }
  ]
}

Errors

Images from a prompt, returned inline as base64 PNG.: errors
Status	Type	When
400	invalid_request_error	The request is malformed, sets a parameter the model does not accept (`error.param` names it), or carries a conversation longer than the model can take.
401	authentication_error	No key, or a key that is unknown, expired or removed.
402	insufficient_quota	The account's credit, the key's spending limit or the monthly budget cannot cover what the call could cost. `error.code` is `key_spend_limit` or `monthly_budget` when a limit refused it, and absent when credit ran out.
404	model_not_found	There is no such model, or it has no price and is not for sale.
409	idempotency_error	A call with this Idempotency-Key is still running, or it finished and its stored answer is gone.
429	rate_limit_error	Too many calls per minute or at once, or the model is busy. `error.code` is `key_rate` or `workspace_concurrency` when a limit refused it; `Retry-After` says when to retry.
500	server_error	Something failed inside the service. The response says nothing about how.
503	server_error	The model is temporarily unavailable, or is not for sale right now.

Every refusal carries the error object described on Errors.

Audio

Speech to text, charged by the second of audio.

Speech to text for one recording.

POST/v1/audio/transcriptions

Send the recording as a file in a form, or as base64 in a JSON body. Limits: a WAV, Ogg/Opus or WebM/Opus recording of at most 300 seconds and 8 MiB. Streaming recognition over one connection is not available.

Parameters

Speech to text for one recording.: parameters
Name	Type	Description
Idempotency-Key	string, 1 to 255 characters	1 to 255 printable characters. A retry with the same value, API key and request body answers the first call's result without a second charge.

Request body multipart/form-data

Speech to text for one recording.: multipart/form-data body
Name	Type	Description
filerequired	file	A WAV, Ogg/Opus or WebM/Opus recording, at most 300 s and 8 MiB.
modelrequired	string	A speech-to-text model id from GET /v1/models.
language	string	The spoken language as an ISO-639-1 code; detected when absent.
response_format	string, only json

Request body application/json

Speech to text for one recording.: application/json body
Name	Type	Description
modelrequired	string
input_audiorequired	object
language	string

Example request

curl https://sven.swedishembedded.com/v1/audio/transcriptions \
  -H "Authorization: Bearer $SVEN_API_KEY" \
  -F "file=@recording.wav" \
  -F "model=MODEL_ID" \
  -F "language=en"

Responses

200 The text of the recording; charged per second of audio transcribed.

Speech to text for one recording.: 200 response
Name	Type	Description
textrequired	string	What was said.
usagerequired	object	What the call is charged for.
usage.type	string, only duration
usage.seconds	integer	The seconds of audio transcribed.

json

{
  "text": "Hello and welcome.",
  "usage": {
    "type": "duration",
    "seconds": 3
  }
}

Errors

Speech to text for one recording.: errors
Status	Type	When
400	invalid_request_error	The request is malformed, sets a parameter the model does not accept (`error.param` names it), or carries a conversation longer than the model can take.
401	authentication_error	No key, or a key that is unknown, expired or removed.
402	insufficient_quota	The account's credit, the key's spending limit or the monthly budget cannot cover what the call could cost. `error.code` is `key_spend_limit` or `monthly_budget` when a limit refused it, and absent when credit ran out.
404	model_not_found	There is no such model, or it has no price and is not for sale.
409	idempotency_error	A call with this Idempotency-Key is still running, or it finished and its stored answer is gone.
413	invalid_request_error	The body is past the size limit.
429	rate_limit_error	Too many calls per minute or at once, or the model is busy. `error.code` is `key_rate` or `workspace_concurrency` when a limit refused it; `Retry-After` says when to retry.
500	server_error	Something failed inside the service. The response says nothing about how.
503	server_error	The model is temporarily unavailable, or is not for sale right now.

Every refusal carries the error object described on Errors.

Search

Web search, charged once per search.

Web search results for a query, charged once per search.

POST/v1/search

One search is one charge, at the per-search price on the pricing page; a search that fails is not charged. sven's web_search tool calls this route when it is signed in to this service.

Parameters

Web search results for a query, charged once per search.: parameters
Name	Type	Description
Idempotency-Key	string, 1 to 255 characters	1 to 255 printable characters. A retry with the same value, API key and request body answers the first call's result without a second charge.

Request body application/json

Web search results for a query, charged once per search.: application/json body
Name	Type	Description
queryrequired	string, 1 to 400 characters	What to search for.
count	integer, 1 to 20	How many results. Default: 5.

Example request

curl https://sven.swedishembedded.com/v1/search \
  -H "Authorization: Bearer $SVEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "how do solar panels work", "count": 3}'

Responses

200 The results, best first.

Web search results for a query, charged once per search.: 200 response
Name	Type	Description
objectrequired	string, only search.results
queryrequired	string
resultsrequired	array of object
results[].titlerequired	string
results[].urlrequired	string
results[].descriptionrequired	string

json

{
  "object": "search.results",
  "query": "how do solar panels work",
  "results": [
    {
      "title": "How solar panels work",
      "url": "https://example.com/solar",
      "description": "A short explanation of photovoltaic cells."
    }
  ]
}

Errors

Web search results for a query, charged once per search.: errors
Status	Type	When
400	invalid_request_error	The request is malformed, sets a parameter the model does not accept (`error.param` names it), or carries a conversation longer than the model can take.
401	authentication_error	No key, or a key that is unknown, expired or removed.
402	insufficient_quota	The account's credit, the key's spending limit or the monthly budget cannot cover what the call could cost. `error.code` is `key_spend_limit` or `monthly_budget` when a limit refused it, and absent when credit ran out.
409	idempotency_error	A call with this Idempotency-Key is still running, or it finished and its stored answer is gone.
429	rate_limit_error	Too many calls per minute or at once, or the model is busy. `error.code` is `key_rate` or `workspace_concurrency` when a limit refused it; `Retry-After` says when to retry.
500	server_error	Something failed inside the service. The response says nothing about how.
503	server_error	The model is temporarily unavailable, or is not for sale right now.

Every refusal carries the error object described on Errors.

Video

Video generation, rolled out account by account.

Start generating a video; answers at once with the job to poll.

POST/v1/videos

Video generation is being rolled out; for an account it is not available to yet, the video routes answer 404. A job is charged once, when its video is stored, for the seconds delivered at the rate of its resolution, never more than the longest video the request could produce. The result is a file of the person the key acts for, kept until they delete it, and counts against their storage quota: once that is full a new video is refused with 507 before anything is charged.

Parameters

Start generating a video; answers at once with the job to poll.: parameters
Name	Type	Description
Idempotency-Key	string, 1 to 255 characters	1 to 255 printable characters. A retry with the same value, API key and request body answers the first call's result without a second charge.

Request body application/json

Start generating a video; answers at once with the job to poll.: application/json body
Name	Type	Description
modelrequired	string	A video model id from GET /v1/videos/models.
promptrequired	string, at most 8000 characters
duration	number, 1 to 60	Seconds; the model's own default when absent.
resolution	string, one of 480p, 720p, 768p, 1080p, 1K, 2K, 4K
aspect_ratio	string, one of 16:9, 9:16, 1:1, 4:3, 3:4, 3:2, 2:3, 21:9, 9:21
size	string	WIDTHxHEIGHT, instead of resolution and aspect_ratio.
generate_audio	boolean
seed	integer
input_video	object	For an edit: a stored video file, as `file:<id>`, with the model's edit named in provider.options.
provider	object

Example request

curl https://sven.swedishembedded.com/v1/videos \
  -H "Authorization: Bearer $SVEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_ID",
    "prompt": "A paper boat drifting down a rain-soaked street at dusk.",
    "duration": 5,
    "resolution": "720p"
  }'

Responses

200 The job an earlier request with the same Idempotency-Key started.

202 The job, to poll at `polling_url`.

Start generating a video; answers at once with the job to poll.: 202 response
Name	Type	Description
idrequired	string	The job's id.
polling_urlrequired	string	Where to read its status.
statusrequired	string, only pending

json

{
  "id": "job_1",
  "polling_url": "/v1/videos/job_1",
  "status": "pending"
}

Errors

Start generating a video; answers at once with the job to poll.: errors
Status	Type	When
400	invalid_request_error	The request is malformed, sets a parameter the model does not accept (`error.param` names it), or carries a conversation longer than the model can take.
401	authentication_error	No key, or a key that is unknown, expired or removed.
402	insufficient_quota	The account's credit, the key's spending limit or the monthly budget cannot cover what the call could cost. `error.code` is `key_spend_limit` or `monthly_budget` when a limit refused it, and absent when credit ran out.
403	permission_error	The key is restricted to other models, or the model is served only by providers that may keep data and sharing data with it is not allowed. `error.code` is `data_sharing_not_allowed` when the person the key acts for has not allowed it (they can: once, or always under Settings, Models), and `data_sharing_forbidden` when their organization does not allow it (they cannot).
404	not_found_error	There is no such job, or the video routes are not available to this account.
413	invalid_request_error	The body is past the size limit.
429	rate_limit_error	Too many calls per minute or at once, or the model is busy. `error.code` is `key_rate` or `workspace_concurrency` when a limit refused it; `Retry-After` says when to retry.
500	server_error	Something failed inside the service. The response says nothing about how.
503	server_error	The model is temporarily unavailable, or is not for sale right now.
507	storage_full	The storage quota of the person whose file the result would be is full: nothing ran and nothing was charged. They free space under Settings, Storage.

Every refusal carries the error object described on Errors.

The video models for sale, with the durations, sizes and prices each offers.

GET/v1/videos/models

Example request

curl https://sven.swedishembedded.com/v1/videos/models \
  -H "Authorization: Bearer $SVEN_API_KEY"

Responses

200 The video models for sale; prices are dollars per second of video.

The video models for sale, with the durations, sizes and prices each offers.: 200 response
Name	Type	Description
datarequired	array of object
data[].id	string
data[].supported_durations	array of number
data[].supported_resolutions	array of string
data[].supported_aspect_ratios	array of string
data[].supported_sizes	array of string
data[].generate_audio	boolean
data[].seed	boolean
data[].supported_frame_images	array of string	The frames a clip can start or end on: first_frame, last_frame.
data[].allowed_passthrough_parameters	array of string	The model's own options a request may give in provider.options.
data[].providers	array of string	The providers serving the model, by the name their options go under; empty when not known, and then options must name their provider.
data[].pricing_skus	object
data[].needs_data_sharing	boolean, only true	Present when the model is served only by providers that may keep data and the person the key acts for has not allowed sharing data with it: a video is refused (403, `data_sharing_not_allowed`) until they allow it.

Errors

The video models for sale, with the durations, sizes and prices each offers.: errors
Status	Type	When
401	authentication_error	No key, or a key that is unknown, expired or removed.
404	not_found_error	There is no such job, or the video routes are not available to this account.

Every refusal carries the error object described on Errors.

A video job's status.

GET/v1/videos/{jobId}

Parameters

A video job's status.: parameters
Name	Type	Description
jobIdrequired	string

Example request

curl https://sven.swedishembedded.com/v1/videos/{jobId} \
  -H "Authorization: Bearer $SVEN_API_KEY"

Responses

200 The job's status.

A video job's status.: 200 response
Name	Type	Description
idrequired	string
statusrequired	string, one of pending, in_progress, completed, failed, cancelled
progress	number	How far along it is
unsigned_urls	array of string	Where the finished video is.
usage	object
usage.seconds	number
usage.cost	string
file_id	string	The stored file
error	object	Why it failed

Errors

A video job's status.: errors
Status	Type	When
401	authentication_error	No key, or a key that is unknown, expired or removed.
404	not_found_error	There is no such job, or the video routes are not available to this account.

Every refusal carries the error object described on Errors.

Ask a running job to stop; a job that cannot be stopped is still delivered and charged.

DELETE/v1/videos/{jobId}

Parameters

Ask a running job to stop; a job that cannot be stopped is still delivered and charged.: parameters
Name	Type	Description
jobIdrequired	string

Example request

curl -X DELETE https://sven.swedishembedded.com/v1/videos/{jobId} \
  -H "Authorization: Bearer $SVEN_API_KEY"

Responses

200 The job and where it stands.

Ask a running job to stop; a job that cannot be stopped is still delivered and charged.: 200 response
Name	Type	Description
id	string
status	string

Errors

Ask a running job to stop; a job that cannot be stopped is still delivered and charged.: errors
Status	Type	When
401	authentication_error	No key, or a key that is unknown, expired or removed.
404	not_found_error	There is no such job, or the video routes are not available to this account.

Every refusal carries the error object described on Errors.

The finished video (MP4), with the same API key.

GET/v1/videos/{jobId}/content

Parameters

The finished video (MP4), with the same API key.: parameters
Name	Type	Description
jobIdrequired	string
index	integer, only 0

Example request

curl https://sven.swedishembedded.com/v1/videos/{jobId}/content \
  -H "Authorization: Bearer $SVEN_API_KEY"

Responses

200 The video file.

Errors

The finished video (MP4), with the same API key.: errors
Status	Type	When
401	authentication_error	No key, or a key that is unknown, expired or removed.
404	not_found_error	There is no such job, or the video routes are not available to this account.
409	conflict	The video is not ready: poll the job's status.
410	gone	The video has expired.

Every refusal carries the error object described on Errors.

Invocations

Any model run once for an agent, with files in and out by reference, charged as the same call made directly.

Run one model once; what it makes is kept as files and answered by reference.

POST/v1/invocations

For agents that combine models: a chat model reading images, an image model making or editing a picture, a speech model saying a text. Inputs are files by reference (uri, as an earlier answer gave it) or inline base64, at most 16 of at most 15 MiB each. What the model makes is checked to be what it says it is (a PNG, JPEG, GIF or WebP image; an SVG, kept as a file; MP3, or speech in raw PCM kept as a playable WAV) and answered as a file reference, never as its bytes. It is charged as the same call to the model made directly; an output that is not kept is not charged. With X-Sven-Session naming a conversation of the key's computer, the files belong to that conversation and are shown in it; without one they are the key's person's own files. Either way they are kept until deleted and count against that person's storage quota: once it is full an image or speech call is refused with 507 before the model runs. An Idempotency-Key is required: the same key answers the same files again without a second charge.

Parameters

Run one model once; what it makes is kept as files and answered by reference.: parameters
Name	Type	Description
Idempotency-Key	string, 1 to 255 characters	1 to 255 printable characters. A retry with the same value, API key and request body answers the first call's result without a second charge.
X-Sven-Session	string	A conversation of the key's computer that the files belong to.

Request body application/json

Run one model once; what it makes is kept as files and answered by reference.: application/json body
Name	Type	Description
modelrequired	string	A model id from GET /v1/models.
operationrequired	string, one of chat, image, speech	How the model is run: `chat` answers text (from images too), `image` makes images, `speech` says the prompt.
promptrequired	string, 1 to 32000 characters	What to ask, draw or say (at most 4096 characters for speech).
inputs	array of object, at most 16 items	Files the model reads, in order.
params	object	The operation's parameters: for `image` `n` (1 to 4), `aspect_ratio`, `resolution`, `size`, `quality`, `output_format`, `background`, `seed`; for `speech` `voice`, `instructions`, `speed`, `format` (`mp3` or `pcm`); for `chat` `system`, `max_tokens`, `temperature`. Which values a model takes is in GET /v1/models.

Example request

curl https://sven.swedishembedded.com/v1/invocations \
  -H "Authorization: Bearer $SVEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_ID",
    "operation": "image",
    "prompt": "A red sports car in the rain",
    "params": {"aspect_ratio": "16:9"}
  }'

Responses

200 The text and the files the model made.

Run one model once; what it makes is kept as files and answered by reference.: 200 response
Name	Type	Description
idrequired	string	The invocation.
statusrequired	string, only completed
modelrequired	string
operationrequired	string
text	string	What a chat model answered.
outputsrequired	array of object	The files made, in order.
outputs[].uri	string	The file's reference, for a later invocation's `inputs` and for GET /v1/files/{fileId}/content.
outputs[].name	string
outputs[].mimeType	string
outputs[].size	integer
outputs[].digest	object	The file's SHA-256, `{algorithm, value}` in base64url.
usagerequired	object
usage.cost_micro_usd	string	What the call was charged

json

{
  "id": "inv-1",
  "status": "completed",
  "model": "MODEL_ID",
  "operation": "image",
  "text": null,
  "outputs": [
    {
      "uri": "mcp-file://files/7b1d6c1e-2f0a-4c3b-9a8d-5e6f7a8b9c0d",
      "name": "image-1.png",
      "mimeType": "image/png",
      "size": 1843202
    }
  ],
  "usage": {
    "cost_micro_usd": "41000"
  }
}

Errors

Run one model once; what it makes is kept as files and answered by reference.: errors
Status	Type	When
400	invalid_request_error	The request is malformed, sets a parameter the model does not accept (`error.param` names it), or carries a conversation longer than the model can take.
401	authentication_error	No key, or a key that is unknown, expired or removed.
402	insufficient_quota	The account's credit, the key's spending limit or the monthly budget cannot cover what the call could cost. `error.code` is `key_spend_limit` or `monthly_budget` when a limit refused it, and absent when credit ran out.
404	not_found_error	There is no such file or conversation for this key, or the model is not for sale. A file of another conversation or another key answers the same.
409	idempotency_error	A call with this Idempotency-Key is still running, or it finished and its stored answer is gone.
429	rate_limit_error	Too many calls per minute or at once, or the model is busy. `error.code` is `key_rate` or `workspace_concurrency` when a limit refused it; `Retry-After` says when to retry.
500	server_error	Something failed inside the service. The response says nothing about how.
502	upstream_error	The model delivered something other than it said, or too much of it; nothing was kept and nothing was charged.
503	server_error	The model is temporarily unavailable, or is not for sale right now.
507	storage_full	The storage quota of the person whose file the result would be is full: nothing ran and nothing was charged. They free space under Settings, Storage.

Every refusal carries the error object described on Errors.

The bytes of a file an invocation made or may read, with the same API key.

GET/v1/files/{fileId}/content

Parameters

The bytes of a file an invocation made or may read, with the same API key.: parameters
Name	Type	Description
fileIdrequired	string
X-Sven-Session	string	The conversation the file belongs to, when it belongs to one.

Example request

curl https://sven.swedishembedded.com/v1/files/{fileId}/content \
  -H "Authorization: Bearer $SVEN_API_KEY"

Responses

200 The file

Errors

The bytes of a file an invocation made or may read, with the same API key.: errors
Status	Type	When
401	authentication_error	No key, or a key that is unknown, expired or removed.
404	not_found_error	There is no such file or conversation for this key, or the model is not for sale. A file of another conversation or another key answers the same.
410	gone	The file is no longer kept.

Every refusal carries the error object described on Errors.