開發者 API
REST · JSON · MCP · 版本 v1 · 更新日誌 · 服務狀態
用你自己的程式生成影片,或透過我們的 MCP 伺服器讓 AI 代理代勞。兩者僅供企業帳戶使用,企業帳戶在本控制台登入。價格和餘額都以美元計。企業帳戶以 USDC 預付,1 USDC 即 1 美元餘額。
一覽
| 規格 | 企業價 | 單筆儲值 1,000 USDC 以上 | |
|---|---|---|---|
| 影片 | 720p 直式(736 × 1280),3, 5, 7 秒,最多 3 張參考圖 | 每秒 $0.10 | 每秒 $0.08 |
| 圖片 | 720p 直式(736 × 1280),最多 3 張參考圖 | 每張 $0.05 | 每張 $0.04 |
價格以美元計。API 和 MCP 僅供企業帳戶使用,企業帳戶以 USDC 預付:1 USDC 即 1 美元餘額,每次最低儲值 1 USDC。單筆儲值 1,000 USDC 以上多送 25% 餘額。聯絡我們開通企業帳戶 (sales@mytype.video).
預設限額:每個令牌每分鐘 60 次讀取、10 次寫入;每個帳戶同時執行 2 個任務,最多 20 個排隊。大量用量的價格和更高限額可另議。
快速開始
- 在令牌頁建立令牌(需先登入)並複製下來:令牌只會顯示一次。
- 每次呼叫
https://api.mytype.video/v1時,以 Bearer 令牌傳送。
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());令牌
- 企業帳戶在令牌頁建立令牌。每個帳戶最多 5 個有效令牌,例如測試用和正式用各一個。不中斷地更換令牌:先建立新的,把伺服器切換過去,再撤銷舊的。建立第 6 個會回傳
409 TOKEN_LIMIT_REACHED。 - 令牌在 30、90 或 365 天後到期。我們只保存雜湊值,遺失的令牌無法找回:請撤銷後重新建立。
- 權限。
read令牌可讀取帳戶、錢包、範本、媒體和任務,並可報價。開始生成影片和上傳圖片需要generate。超出令牌權限的請求回傳403 SCOPE_REQUIRED。 - IP 允許清單(選填)。可在令牌頁為令牌設定最多 20 個 IPv4/IPv6 位址或 CIDR 範圍;不設定就不限制。來自其他位址的請求回傳
403 IP_NOT_ALLOWED。經 MCP 呼叫時,以你的 MCP 用戶端連線的位址為準。 - 用量。用量頁會以美元顯示每個令牌本月的花費。令牌不設花費上限:可花費的就是你的預付餘額。
- 令牌代表你的帳戶運作,每次請求都會檢查停權狀態。
價格與計費
價格以美元計,見一覽。
- 僅限企業帳戶。API 和 MCP 任務從企業餘額扣款,帳戶需有企業餘額才能使用。請聯絡我們開通,可先提供試用額度。
- 企業價。適用以 USDC 預付的企業帳戶:1 USDC 即 1 美元餘額,每次最低儲值 1 USDC。單筆儲值 1,000 USDC 以上多送 25% 餘額(影片每秒 $0.08、圖片每張 $0.04);多筆儲值不合併計算。
GET /wallet的account.type為"business"。聯絡我們開通。 - 餘額分開。API 和 MCP 只使用企業餘額(USDC 儲值與試用額度)。
GET /wallet的balanceByPool會顯示。 - 每種生成方式都有對應的
quote端點:驗證相同的請求內容並以美元回傳費用(amountUsd),不會開始任務也不會扣款。
任務如何計費
- 報價。免費,不保留金額,也不建立任務。
- 受理。報價的金額從餘額轉為保留。餘額不足時回傳
402 INSUFFICIENT_BALANCE,不建立任何東西;儲值後以相同的requestId重送即可。 - 完成。扣除保留的金額。只有完成的任務才收費。
- 失敗。保留的金額全數退回:技術故障、受理後 20 分鐘仍未完成,或算圖後 15 分鐘內無法發布結果時皆同。
GET /wallet以美元回傳餘額(balanceUsd)、帳戶類型和價格(account),以及每一筆保留、扣款和退回。- API 費用支付。企業客戶以 USDC 預付,每次至少 1 USDC。帳戶開通後,充值頁會顯示你專屬的 Base 儲值地址,款項到帳後自動加入餘額。請申請或寫信到 sales@mytype.video 開始。預付餘額在帳戶持續使用期間不會過期;沒有自動儲值,請留意餘額。詳見 API 使用條款。
- 預計每月用量很大?聯絡我們商談價格和限額。
上傳、生成、下載
上傳 2 MiB 以內的 PNG、JPEG 或 WebP 圖片。你必須確認有權使用該圖片(rightsAttested: true);NSFW 內容另需 adultSubjectsVerified: true。畫面中的每個人都必須是成年人。
# 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"
接著報價、開始並追蹤影片。範例都是完整程式;請把 <assetVersionId> 換成你上傳的圖片。
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));已開始的影片無法取消。媒體連結有簽章且會過期(expiresAt);重新讀取任務或素材即可取得新連結。完成的影片保存在你的帳戶中,不會自動刪除。
影片與圖片規格
- 影片。720p 直式(736 × 1280),3、5 或 7 秒,依提示詞和最多三張參考圖生成。請求中請帶
"resolution":"736p"。按秒計價(見價格與計費)。 - 首尾幀。
POST /generations/frame-to-frame生成從一張圖片過渡到另一張的影片,規格和長度相同。 - 圖片。
POST /generations/image依提示詞和最多三張參考圖生成 720p 直式圖片(736 × 1280)。按張計價。 GET /capabilities列出帳戶目前可用的功能。
MCP 伺服器
AI 代理可透過我們的 MCP 伺服器使用同一個帳戶,不必直接呼叫 REST API。伺服器位址 https://mcp.mytype.video/mcp,使用 Streamable HTTP,以相同的令牌作為 Bearer 標頭。讀取和報價需要 read 權限;上傳和生成需要 generate。價格、餘額、限額和內容規範與 API 相同。
- 建立令牌。請給代理專用的令牌,方便查看它的花費並單獨撤銷。
- 把伺服器加入你的用戶端,選擇你使用的工具:
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>"}}]}'其他支援 Streamable HTTP 並可自訂 Authorization 標頭的用戶端,設定方式相同。也可以讓你的程式代理自己設定:把下面這段訊息貼到 Claude Code、Cursor、Codex 或其他能修改自身設定的代理。
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
透過登入方式連線的應用(例如 Claude 和 ChatGPT 應用程式)不需令牌即可把伺服器加為連接器:應用會開啟本控制台,你登入後選擇允許。
- 請代理先呼叫
get_capabilities和get_video_workflow,取得目前規格和多段影片的做法。 quote_generation報價不扣款;submit_generation開始任務,get_generation讀取結果。兩者都接受{"request": {"kind": "direct", "body": {…}}},body與 REST 請求的 JSON 相同。720p 影片的 body 必須包含"resolution":"736p"。
任務狀態
每 5 到 10 秒以 GET /generations/{jobId} 讀取任務,或設定 Webhook 省去輪詢。status 依序為:
queued:已受理,等待算圖節點(progress.phase為pending_dispatch)。閒置一段時間後的第一個任務,可能需等待約 2 分鐘啟動節點。running:算圖中。uploading:算圖完成,正在儲存結果。請繼續輪詢。completed:每個項目都有downloadUrl。請盡快下載;重新讀取任務可取得新連結。failed:保留的金額已退回。請以新的requestId送出新任務。
Webhook
不想輪詢的話,帳戶可在每個任務結束時收到一個 POST。
- 開啟設定,填入 Webhook 位址。第一次儲存會顯示一次簽章密鑰,請保存在你的伺服器上。位址必須是公開的
https、有主機名稱、使用預設連接埠。API 令牌無法變更此設定。 - 帳戶的每個任務(API 和 MCP)在變成
completed或failed時各發送一次 POST。event為generation.completed或generation.failed;失敗任務不扣款,也沒有項目。不會傳送提示詞或其他輸入。 downloadUrl幾分鐘後失效:請立即下載,或讀取GET /generations/{jobId}取得新連結。- 簽章。
X-MyType-Signature: t=<unix 秒>,v1=<hex>是以你的密鑰對t + "." + 原始 body計算的 HMAC-SHA256。請拒絕超過 5 分鐘的t。更換密鑰後 24 小時內會有兩個v1,每個密鑰一個。 - 投遞。請在 10 秒內回應任何 2xx,否則我們會在 1 分鐘、5 分鐘、30 分鐘、2 小時和 6 小時後重試,之後停止。不跟隨重新導向。處理完才逾時也會觸發重試,請以
jobId去重。 - 關閉 Webhook 會丟棄尚未送出的投遞。若不能漏接,請保留輪詢作為備援。
{"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);
});
}
低餘額提醒
餘額用完時任務會回傳 402 而停止,USDC 預付也不會自動扣款。設定提醒,就能在用完前加值。
- 在設定填入以美元計的低餘額提醒金額($1 至 $100,000)。API 令牌無法變更此設定。
- 可用餘額低於此金額時,我們會寄信到帳戶信箱;若已設定 Webhook,也會 POST 一個
balance.low事件。餘額每隔幾分鐘檢查一次,不是每個任務都檢查。 - 每次跌破只通知一次。餘額回到此金額以上(通常是加值後)會重新啟用;修改金額也會重新檢查。
- POST 的簽章、標頭和重試與任務 Webhook 相同。
X-MyType-Delivery就是eventId,請以它去重。
{"event":"balance.low","eventId":"balance_low_…","balanceUsd":42.5,"thresholdUsd":100,
"currency":"USD","occurredAt":"…"}
重試
每個開始影片的請求都帶有 requestId(由你產生的 UUID)。請求逾時或不確定是否送達時,用相同的 requestId 和相同的內容重送:會拿回原本的任務,絕不重複扣款。相同 requestId 但內容不同會回傳 409。
限額
- 請求頻率。預設每個令牌每分鐘 60 次讀取、10 次寫入;報價和
POST /generations/events算讀取。每個帳戶所有令牌合計可達兩倍。我們可能為你的帳戶設定不同的限額。超過時回傳429 RATE_LIMITED,並附Retry-After標頭(秒)。 - 同時任務數。預設每個帳戶同時執行 2 個任務、最多 20 個排隊,其餘在你的佇列中等待。
GET /queue回傳適用於你帳戶的限額。需要更多?聯絡我們。你的佇列或服務佇列已滿時回傳429(ACCOUNT_QUEUE_FULL或QUEUE_FULL)並附Retry-After。GET /capabilities回傳限額,GET /queue回傳目前數量。 - 被拒絕的請求不會建立任何東西,也不會扣款。
錯誤
錯誤以 JSON 回傳:{"error": "message", "code": "CODE"}。只有狀態碼不足以說明時才會有 code。下表取自 OpenAPI 文件,為英文。
載入中…
端點
所有路徑都相對於 https://api.mytype.video/v1。此清單由線上的 OpenAPI 文件產生(英文),其中也有完整的回應結構。
- 載入中…
協助
API 問題或故障:support@mytype.video。預付、大量用量價格和更高限額:sales@mytype.video 或申請表單。API 使用適用 API 使用條款和服務條款。價格調整與功能停用會在生效前至少 30 天公佈於更新日誌並以電子郵件通知;服務即時狀態請見狀態頁。
變更。API 版本 v1 只會新增欄位,現有欄位的意義不變。會使現有請求失效的變更同樣至少提前 30 天公佈並通知。