Aisma / For developers
Scripts, automation tools and AI agents can edit a video you already shot, the way the app does: upload a clip of 2–60 seconds, describe the change in plain words, get the price in credits, start the edit and fetch the private result. It’s the same account, the same credits and the same Library as the app.
Paid editing · Your Aisma credits · Price quoted before you start
change the background to a snowy forest
What stays
What changes
What you bring
An Aisma account signed in with Google, Apple or email, credits, and a clip of 2–60 seconds (MP4 or MOV, up to 500 MB). Photos are optional, up to 10.
Two ways in
JSON over HTTPS under https://api.aisma.ai/v1, described by an OpenAPI 3.1 document. Upload, price, start, follow and fetch an edit with a personal API key.
Webhooks tell your server when an edit finishes, fails or is settled.
Open the OpenAPI documentA remote MCP server at https://api.aisma.ai/mcp for AI assistants and agents. It speaks Streamable HTTP and signs in with OAuth.
Nine tools cover the whole edit, and the assistant asks you before it spends credits.
Connect an assistantEdits started through the API use your Aisma credits at the app’s prices and land in your Library beside the ones you made in the app.
The API never buys credits. You top up in Aisma.
See pricingUploads and results stay private to your account, and every link to them is signed and short-lived.
Each key and connected app has its own permissions and a monthly credit cap you choose. Revoke it and it stops working at once.
Read the privacy policyHow an edit runs
An edit takes the same path in the app, over REST and over MCP. Nothing is charged until you start a quoted edit, and the finished video lands privately in your Library.
| Step | REST | MCP tool | What happens |
|---|---|---|---|
| Upload | POST /v1/uploads | create_upload | Returns a one-time upload link. PUT the file to it with the headers it names. |
| Or reuse | POST /v1/assets/from-library | use_library_video | Takes a finished edit from your Library as the source instead. |
| Check | GET /v1/assets/{id} | get_asset | Wait until the upload is ready; quote only with ready files. |
| Price | POST /v1/quotes | quote_edit | Prices your request, photos and quality in credits. Nothing is charged; the price holds for 15 minutes. |
| Start | POST /v1/jobs | start_edit | Starts the quoted edit and reserves its credits. An Idempotency-Key makes a retry return the same edit. |
| Follow | GET /v1/jobs/{id} | get_job | Status and confirmed progress, which reaches 100 only once the edited video is stored. |
| Fetch | POST /v1/jobs/{id}/result | get_result_link | A private link to the finished video, valid for one hour. |
REST quickstart
Send your key as a bearer token. Bodies are JSON, ids are UUIDs and times are ISO 8601. The request below is the one behind the snowy forest at the top of this page.
aisma# 1. Ask for an upload link
curl -X POST https://api.aisma.ai/v1/uploads \
-H "Authorization: Bearer $AISMA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"kind":"video","contentType":"video/mp4","bytes":12345678}'
# Then PUT the file to uploadUrl with the headers it returns
curl -X PUT "$UPLOAD_URL" \
-H "Content-Type: video/mp4" \
--data-binary @clip.mp4
# 2. Price the edit once GET /v1/assets/ASSET_ID says ready (nothing is charged)
curl -X POST https://api.aisma.ai/v1/quotes \
-H "Authorization: Bearer $AISMA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"sourceId":"ASSET_ID","brief":"change the background to a snowy forest","quality":"720p"}'
# 3. Start it; the Idempotency-Key makes a retry return the same edit
curl -X POST https://api.aisma.ai/v1/jobs \
-H "Authorization: Bearer $AISMA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: first-edit-0001" \
-d '{"quoteId":"QUOTE_ID"}'
# 4. When GET /v1/jobs/JOB_ID says resultReady, get the one-hour link
curl -X POST https://api.aisma.ai/v1/jobs/JOB_ID/result \
-H "Authorization: Bearer $AISMA_API_KEY"While Aisma is still checking a new clip, a quote answers 202 with retryAfterMs; ask again after that delay. Follow an edit no more often than every 10 seconds, or register a webhook and wait for it.
MCP server
Add https://api.aisma.ai/mcp as a remote MCP server or custom connector in any assistant or coding agent that supports them. The server speaks Streamable HTTP without sessions and answers the protocol revisions 2025-11-25, 2025-06-18 and 2025-03-26.
The first call opens Aisma’s sign-in page (OAuth 2.1 with PKCE and dynamic client registration). There you choose what the connection may do and its monthly credit cap. You can disconnect it at any time under Profile → Settings & help → Connected apps and keys.
{
"mcpServers": {
"aisma": { "url": "https://api.aisma.ai/mcp" }
}
}Prefer a key? Send it in the Authorization header as Bearer aisma_live_… instead of signing in.
New clips travel over HTTPS, never through the chat, so uploading one needs an assistant that can read your files, such as a coding agent with a shell. In a chat-only assistant, re-edit the videos already finished in your Library.
MCP tools
Every tool has a title, read-only or destructive hints and an output schema, and answers with structured content. start_edit is marked destructive and tells the assistant to confirm the price with you first; asking it twice for the same quote returns the same edit.
| Tool | What it does | Spends credits |
|---|---|---|
create_upload | A one-time HTTPS link to upload a video or photo. The assistant PUTs the file itself. | No |
get_asset | Where an upload stands: uploading, checking, ready, failed or expired. | No |
use_library_video | Makes a finished video from your Library the source of a new edit. | No |
quote_edit | Prices an edit in credits. Nothing is charged, and the price holds for 15 minutes. | No |
start_edit | Starts a quoted edit and reserves its credits, after you confirm the price. | Yes, after you confirm |
get_job | Status and confirmed progress of an edit. | No |
list_library | Your Library, newest first. | No |
get_result_link | A private link to the finished video, valid for one hour. | No |
get_account | Your credit balance, this connection’s monthly cap and what it has used. | No |
Sign-in
Personal API keys: create one in the web app under Profile → Settings & help → Connected apps and keys. A key starts with aisma_live_ and is shown once; Aisma keeps only its hash. Send it in the Authorization header as Bearer aisma_live_…, never in a link.
Connected apps: MCP clients and other apps sign in with OAuth 2.1 (authorization code with PKCE, rotating refresh tokens and dynamic client registration). Discovery starts at https://api.aisma.ai/.well-known/oauth-protected-resource.
Each key and connected app has its own scopes and a monthly credit cap, 300 credits until you change it, plus an optional cap per edit. Revoke a key or disconnect an app and it stops working at once.
Keys and connected apps need an account signed in with Google, Apple or email. Guest profiles can’t hold them.
| Scope | Allows |
|---|---|
media:write | Upload videos and photos, and use Library videos as sources |
media:read | Check uploads and get links to finished videos |
jobs:read | See edit status and the Library |
jobs:write | Get prices and start edits that spend credits |
account:read | See the credit balance and limits |
webhooks:write | Register webhook endpoints |
Limits
Webhooks
Register an HTTPS endpoint with POST /v1/webhooks (scope webhooks:write). Aisma sends job.completed, job.failed and job.settled for the edits the API started.
Deliveries follow Standard Webhooks: each carries webhook-id, webhook-timestamp and webhook-signature, an HMAC-SHA256 of the id, the timestamp and the body, signed with the secret you get once when you register. A failed delivery is retried for up to 24 hours. Following the edit with GET /v1/jobs/{id} stays the source of truth.
Errors
Every error is JSON in one shape, {"error": {"code", "message"}}, and the message is written for people. Include the X-Request-Id of the response when you write to us.
| Code | HTTP | What it means |
|---|---|---|
invalid_request | 400 | A field or parameter is missing or invalid; the message names it. |
unauthorized | 401 | The key or token is missing, invalid or revoked. An MCP client signs in again. |
insufficient_credits | 402 | The balance doesn’t cover this edit. GET /v1/account returns the link to buy credits in Aisma. |
cap_reached | 402 | The key’s or app’s monthly cap, or its cap per edit, would be passed. |
forbidden_scope | 403 | The key or app wasn’t given the scope this call needs. |
not_found | 404 | No such upload, quote or edit on this account. |
quote_expired | 409 | The quote is older than 15 minutes. Ask for a new one. |
not_ready | 409 | The finished video isn’t stored yet. Keep following the edit. |
idempotency_mismatch | 409 | This Idempotency-Key was already used with a different body. |
rate_limited | 429 | Too many requests in this window. Wait for Retry-After. |
unavailable | 503 | Editing is briefly unavailable. Try again shortly. |
internal | 500 | Something failed on Aisma’s side. Retry, or write to support with the X-Request-Id. |
Questions developers ask
There is no separate API fee. An edit costs the same credits as in the app, Aisma shows the price before you start, and a quote is never charged. The current rates are on the pricing page.
No. The API never buys anything. When the balance is short, starting an edit answers 402 insufficient_credits, and GET /v1/account returns the link to top up in Aisma.
Any assistant or coding agent that supports remote MCP servers over Streamable HTTP, signing in with OAuth or sending an API key. Uploading a new clip needs one that can read your files; a chat-only assistant can re-edit the videos already in your Library.
Yes. POST /v1/assets/from-library, or use_library_video over MCP, takes a finished edit from your Library and makes it the source of a new one.
One hour. Ask for a new link whenever you need one; the video itself stays in your Library under the same rules as the edits you make in the app.
Yes. Uploads and results are private to your account and open only through signed, short-lived links. Section 8 of the terms covers the API and connected apps, and the privacy policy says how your data is handled.
SDKs are on our roadmap. The OpenAPI 3.1 document describes every endpoint today, so most code generators can build a client from it.
Updated
Write to support@aisma.ai about higher limits, batch work or the integration you have in mind.
Product questions are answered in the help center.