Developer API
REST · JSON · MCP · version v1 · Changelog · Service status
Create videos from your own code, or let an AI agent do it through our MCP server. Both are for business accounts, which sign in to this console. Prices and balances are in US dollars. Business accounts prepay in USDC: 1 USDC adds $1 of balance.
Create tokenApply for API accessOpenAPI document
At a glance
| Format | Business price | Top-up of 1,000 USDC or more | |
|---|---|---|---|
| Video | 720p portrait (736 × 1280), 3, 5, 7 seconds, up to 3 reference images | $0.10 per second | $0.08 per second |
| Image | 720p portrait (736 × 1280), up to 3 reference images | $0.05 each | $0.04 each |
Prices in US dollars. The API and MCP are for business accounts, which prepay in USDC: 1 USDC for $1 of balance, minimum top-up 1 USDC. A single top-up of 1,000 USDC or more adds 25% extra balance. Contact us for a business account (sales@mytype.video).
Default limits: 60 reads and 10 writes per minute per token; 2 jobs running and 20 waiting per account. Volume pricing and higher limits on request.
Quick start
- Create a token on the Tokens page (sign in first) and copy it: it is shown once.
- Send it as a bearer token on every request to
https://api.mytype.video/v1.
curl
curl https://api.mytype.video/v1/session \
-H "Authorization: Bearer $MYTYPE_TOKEN"Python
import os, requests
response = requests.get("https://api.mytype.video/v1/session",
headers={"Authorization": f"Bearer {os.environ['MYTYPE_TOKEN']}"})
print(response.json())Node.js
const response = await fetch("https://api.mytype.video/v1/session", {
headers: { Authorization: `Bearer ${process.env.MYTYPE_TOKEN}` },
});
console.log(await response.json());Tokens
- Business accounts create tokens on the Tokens page. Each account can have up to five active tokens, for example one for testing and one for production. To replace a token without downtime, create the new one, switch your servers to it, then revoke the old one. A sixth returns
409 TOKEN_LIMIT_REACHED. - A token expires after 30, 90 or 365 days. We store only a hash, so a lost token cannot be recovered: revoke it and create a new one.
- Access. A
readtoken can read your account, wallet, templates, media and jobs, and ask for quotes. Starting videos and uploading images needsgenerate. A request outside the token’s access returns403 SCOPE_REQUIRED. - IP allowlist (optional). On the Tokens page you can limit a token to up to 20 IPv4/IPv6 addresses or CIDR ranges. Tokens have no allowlist unless you set one. A request from another address returns
403 IP_NOT_ALLOWED. Through MCP the address is the one your MCP client connects from. - Usage. The Usage page shows what each token spent, in US dollars. Tokens have no spending limit: what a token can spend is your prepaid balance.
- Tokens act as your account. Suspensions are checked on every request.
Prices and billing
Prices are in US dollars. At a glance lists them.
- Business accounts only. API and MCP jobs are paid from a business balance, so an account needs a business balance to use them. Contact us to open one; we can add trial credit for a first test.
- Business price. For business accounts that prepay in USDC: 1 USDC adds $1 to your balance. The minimum top-up is 1 USDC. A single top-up of 1,000 USDC or more adds 25% extra balance ($0.08 per second of video, $0.04 per image); separate top-ups are not added together.
GET /walletreturnsaccount.type"business". Contact us to open one. - Separate balances. The API and MCP spend only the business balance (USDC top-ups and trial credit).
GET /walletshows it inbalanceByPool. - Every way of starting a video has a
quotetwin that validates the same body and returns its cost in US dollars (amountUsd) without starting or charging anything.
How a job is charged
- Quote. Free. Nothing is reserved and no job is created.
- Accepted. The quoted amount is moved from your balance to a hold. If your balance is too small the request returns
402 INSUFFICIENT_BALANCEand creates nothing; top up and send the samerequestIdagain. - Completed. The hold is charged. You pay only for jobs that finish.
- Failed. The hold is returned in full: on a technical failure, when a job has not finished 20 minutes after it was accepted, or when its result cannot be published within 15 minutes after rendering.
GET /walletreturns your balance in US dollars (balanceUsd), your account type and price (account), and every hold, charge and return.- Paying for API use. Business customers prepay in USDC, at least 1 USDC at a time. Once your account is open, the Billing page shows your own deposit address on Base and the payment is added to your balance automatically. Apply or write to sales@mytype.video to get started. A prepaid balance does not expire while the account is in use, and there is no automatic top-up: keep an eye on your balance. The API terms of use have the details.
- Planning a high monthly volume? Contact us to discuss pricing and limits.
Upload, generate, download
Upload a PNG, JPEG or WebP image up to 2 MiB. You must confirm that you have the right to use it (rightsAttested: true); NSFW content also requires adultSubjectsVerified: true. Everyone depicted must be an adult.
# 1. Reserve the upload. sha256 is the hex SHA-256 of the file, bytes its size.
curl -X POST https://api.mytype.video/v1/assets \
-H "Authorization: Bearer $MYTYPE_TOKEN" -H "Content-Type: application/json" \
-d '{"filename":"photo.jpg","title":"My photo","contentType":"image/jpeg",
"bytes":183204,"sha256":"<sha256 of the file>",
"contentRating":"sfw","style":"realism","rightsAttested":true}'
# -> {"uploadId":"upl_…","assetVersionId":"av_…","upload":{"url":"…","headers":{…},"expiresAt":"…"}}
# 2. PUT the file bytes to upload.url with every header in upload.headers, before upload.expiresAt.
# 3. Ask for validation, then read the image until it is available.
curl -X POST https://api.mytype.video/v1/assets/uploads/<uploadId>/complete -H "Authorization: Bearer $MYTYPE_TOKEN"
curl https://api.mytype.video/v1/assets/<assetVersionId> -H "Authorization: Bearer $MYTYPE_TOKEN"
Then quote, start and follow the video. The examples are complete programs; replace <assetVersionId> with your uploaded image.
curl
# Price it first (read scope, nothing is charged).
curl -X POST https://api.mytype.video/v1/generations/direct/quote \
-H "Authorization: Bearer $MYTYPE_TOKEN" -H "Content-Type: application/json" \
-d '{"mode":"ref2va","requestId":"<a new UUID>","resolution":"736p","duration":5,"seed":42,
"prompt":"The person in <Picture 1> turns and smiles at the camera.",
"contentRating":"sfw","style":"realism","motion":"idle",
"referenceAssetVersionIds":["<assetVersionId>"]}'
# -> {"amountUsd":0.5,"currency":"USD","accountType":"business","points":50,"pointsPerSecond":10}
# Start it: the same body to /generations/direct. Reuse the same requestId when you retry.
# -> 202 {"jobId":"job_piper_…","status":"accepted"}
# Read the job every 5 to 10 seconds until it is completed or failed.
curl https://api.mytype.video/v1/generations/<jobId> -H "Authorization: Bearer $MYTYPE_TOKEN"Python
import os, time, uuid, requests
BASE = "https://api.mytype.video/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['MYTYPE_TOKEN']}"}
def call(method, path, body=None):
response = requests.request(method, BASE + path, json=body, headers=HEADERS, timeout=30)
response.raise_for_status()
return response.json()
body = {
"mode": "ref2va", "requestId": str(uuid.uuid4()), "resolution": "736p", "duration": 5, "seed": 42,
"prompt": "The person in <Picture 1> turns and smiles at the camera.",
"contentRating": "sfw", "style": "realism", "motion": "idle",
"referenceAssetVersionIds": ["<assetVersionId>"],
}
print("Cost: $", call("POST", "/generations/direct/quote", body)["amountUsd"])
job_id = call("POST", "/generations/direct", body)["jobId"] # same requestId on retry: never charged twice
while True:
time.sleep(8)
job = call("GET", f"/generations/{job_id}")
if job["status"] in ("completed", "failed"):
break
print(job["status"], [item.get("downloadUrl") for item in job.get("items", [])])Node.js
const BASE = "https://api.mytype.video/v1";
const headers = { Authorization: `Bearer ${process.env.MYTYPE_TOKEN}`, "Content-Type": "application/json" };
async function call(path, body) {
const response = await fetch(BASE + path, { method: body ? "POST" : "GET", headers, body: body && JSON.stringify(body) });
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
return response.json();
}
const body = {
mode: "ref2va", requestId: crypto.randomUUID(), resolution: "736p", duration: 5, seed: 42,
prompt: "The person in <Picture 1> turns and smiles at the camera.",
contentRating: "sfw", style: "realism", motion: "idle",
referenceAssetVersionIds: ["<assetVersionId>"],
};
console.log("Cost: $" + (await call("/generations/direct/quote", body)).amountUsd);
const { jobId } = await call("/generations/direct", body); // same requestId on retry: never charged twice
let job;
do {
await new Promise(resolve => setTimeout(resolve, 8000));
job = await call(`/generations/${jobId}`);
} while (!["completed", "failed"].includes(job.status));
console.log(job.status, job.items?.map(item => item.downloadUrl));A started video cannot be cancelled. Media links are signed and expire (expiresAt); read the job or asset again for a fresh link. Finished videos are kept with your account and have no automatic expiry.
Video and image formats
- Video. 720p portrait (736 × 1280), 3, 5 or 7 seconds, from a prompt and up to three reference images. Send
"resolution":"736p"with the request. Priced per second (see Prices and billing). - First and last frame.
POST /generations/frame-to-framemakes a video that moves from one of your images to another, in the same format and lengths. - Images.
POST /generations/imagemakes a 720p portrait picture (736 × 1280) from a prompt and up to three reference images. Priced per image. GET /capabilitieslists what your account can use right now.
MCP server
AI agents can use the same account through our MCP server instead of calling the REST API. It speaks Streamable HTTP at https://mcp.mytype.video/mcp and takes the same token as a bearer header. Reading and quoting need read access; uploading and generating need generate. Prices, balance, limits and content rules are the same as for the API.
- Create a token. Give an agent its own token, so you can see what it spends and revoke it on its own.
- Add the server to your client. Pick yours:
Claude Code
claude mcp add --transport http mytype https://mcp.mytype.video/mcp \
--header "Authorization: Bearer $MYTYPE_TOKEN"Cursor
// ~/.cursor/mcp.json
{
"mcpServers": {
"mytype": {
"url": "https://mcp.mytype.video/mcp",
"headers": { "Authorization": "Bearer <your MyType.video token>" }
}
}
}VS Code
// .vscode/mcp.json: VS Code asks for the token once and stores it securely.
{
"inputs": [{ "type": "promptString", "id": "mytype-token", "description": "MyType.video API token", "password": true }],
"servers": {
"mytype": {
"type": "http",
"url": "https://mcp.mytype.video/mcp",
"headers": { "Authorization": "Bearer ${input:mytype-token}" }
}
}
}Codex
# ~/.codex/config.toml. Set MYTYPE_TOKEN in the environment that starts Codex.
[mcp_servers.mytype]
url = "https://mcp.mytype.video/mcp"
bearer_token_env_var = "MYTYPE_TOKEN"Grok
# Grok CLI
grok mcp add --transport http mytype https://mcp.mytype.video/mcp \
--header "Authorization: Bearer ${MYTYPE_TOKEN}"
# xAI API: add the server as a remote MCP tool.
curl https://api.x.ai/v1/responses \
-H "Authorization: Bearer $XAI_API_KEY" -H "Content-Type: application/json" \
-d '{"model":"<a Grok model>",
"input":[{"role":"user","content":"Read my MyType.video balance, then quote a 5 second 720p video."}],
"tools":[{"type":"mcp","server_label":"mytype","server_url":"https://mcp.mytype.video/mcp",
"headers":{"Authorization":"Bearer <your MyType.video token>"}}]}'Any other client that supports Streamable HTTP with a custom Authorization header works the same way. Or let your coding agent do it: paste this message into Claude Code, Cursor, Codex or another agent that can edit its own settings.
Connect the MyType.video MCP server for me.
Server: https://mcp.mytype.video/mcp (Streamable HTTP).
Authentication: send my token as the header "Authorization: Bearer <token>". The token is in the environment variable MYTYPE_TOKEN; never print it or write it into a file that is committed.
After connecting, call get_capabilities and get_video_workflow, tell me my balance in US dollars, and quote a 5 second 720p video before you start anything that costs money.
Documentation: https://console.mytype.video/docs#mcp
Apps that connect through a sign-in, such as the Claude and ChatGPT apps, can add the server as a connector without a token: they open this console, you sign in and choose Allow.
- Ask the agent to call
get_capabilitiesandget_video_workflowfirst. They return the current formats and the recipes for multi-clip videos. quote_generationprices a request without charging;submit_generationstarts it andget_generationreads the result. Both take{"request": {"kind": "direct", "body": {…}}}, wherebodyis the same JSON as the REST request. For 720p video the body must include"resolution":"736p".
Job status
Read a job with GET /generations/{jobId} every 5 to 10 seconds, or set a webhook and skip polling. Its status moves through:
queued: accepted and waiting for a worker (progress.phaseispending_dispatch). The first job after a quiet period can wait about 2 minutes while a worker starts.running: rendering.uploading: rendering is done and the result is being stored. Keep polling.completed: each item has adownloadUrl. Download it promptly; read the job again for a fresh link.failed: the held amount is returned. Send a new job with a newrequestId.
Webhooks
Instead of polling, your account can receive a POST when each of its jobs ends.
- Open Settings and enter a Webhook address. The first save shows a signing secret once: keep it on your server. The address must be public
httpswith a host name, on the default port. API tokens cannot change this setting. - One POST per job when it becomes
completedorfailed, for every job of the account (API and MCP).eventisgeneration.completedorgeneration.failed; a failed job charges nothing and has no items. No prompts or other inputs are sent. downloadUrlexpires after a few minutes: download at once, or readGET /generations/{jobId}for a fresh link.- Signature.
X-MyType-Signature: t=<unix seconds>,v1=<hex>is HMAC-SHA256 with your secret overt + "." + raw body. Reject atmore than 5 minutes old. For 24 hours after you rotate the secret there are twov1values, one per secret. - Delivery. Answer with any 2xx within 10 seconds. Otherwise we retry after 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours, then stop. Redirects are not followed. A timeout after you processed it causes a retry, so deduplicate on
jobId. - Turning webhooks off drops deliveries that have not gone out yet. Keep polling as a fallback if a delivery can be missed.
{"event":"generation.completed","jobId":"job_piper_…","requestId":"<your requestId>",
"status":"completed","points":30,"occurredAt":"…",
"items":[{"assetVersionId":"av_…","kind":"video","downloadUrl":"https://…","expiresAt":"…"}]}
// Node.js: verify before trusting the body. rawBody is the exact bytes received.
import {createHmac, timingSafeEqual} from "node:crypto";
function verified(header, rawBody, secret) {
const parts = header.split(","), t = parts.find(p => p.startsWith("t="))?.slice(2);
if (!t || Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
const expected = createHmac("sha256", secret).update(t + "." + rawBody).digest();
return parts.filter(p => p.startsWith("v1=")).some(p => {
const given = Buffer.from(p.slice(3), "hex");
return given.length === expected.length && timingSafeEqual(given, expected);
});
}
Low-balance alerts
Jobs stop with 402 when the balance runs out, and prepaid USDC is never charged automatically. Set an alert so you can add funds first.
- In Settings, enter a Low-balance alert amount in US dollars ($1 to $100,000). API tokens cannot change this setting.
- When your available balance falls below it, we email the account address and, if a webhook is set, POST a
balance.lowevent to it. Balances are checked every few minutes, not on each job. - One notice per drop. The alert resets once the balance is back at or above the amount, usually after a top-up. Changing the amount checks again.
- The POST uses the same signature, headers and retries as job webhooks.
X-MyType-Deliveryis theeventId: deduplicate on it.
{"event":"balance.low","eventId":"balance_low_…","balanceUsd":42.5,"thresholdUsd":100,
"currency":"USD","occurredAt":"…"}
Retries
Every request that starts a video carries a requestId (a UUID you generate). If a request times out or you are unsure it arrived, send it again with the same requestId and the same body: you get the original job back and are never charged twice. The same requestId with a different body returns 409.
Limits
- Request rate. By default each token may make 60 reads and 10 writes per minute; quotes and
POST /generations/eventscount as reads. Each account may make twice that across all its tokens. We may set different limits for your account. Over the limit you get429 RATE_LIMITEDwith aRetry-Afterheader in seconds. - Jobs at a time. By default each account runs 2 jobs at once and keeps up to 20 waiting; further jobs wait in your queue.
GET /queuereturns the limits that apply to your account. Need more? Contact us. When your queue or the service queue is full the API returns429(ACCOUNT_QUEUE_FULLorQUEUE_FULL) withRetry-After.GET /capabilitiesreturns the limits andGET /queueyour current counts. - A rejected request creates nothing and charges nothing.
Errors
Errors are JSON: {"error": "message", "code": "CODE"}. code is present when the status alone is not enough.
Loading…
Endpoints
All paths are relative to https://api.mytype.video/v1. This list is built from the live OpenAPI document, which also has the full response schemas.
- Loading…
Help
Questions or a problem with the API: support@mytype.video. Prepayment, volume pricing and higher limits: sales@mytype.video or the application form. The API terms of use and the terms of service apply to API use. Price changes and deprecations are announced in the changelog and by email at least 30 days before they take effect; live service status is on the status page.
Changes. API version v1 only gains fields; existing fields keep their meaning. A change that breaks existing requests is announced the same way, at least 30 days ahead.