curl -X POST "https://api.submagic.co/v1/iris/projects" \
-H "x-api-key: sk-your-api-key-here" \
-H "Content-Type: application/json" \
-d '{
"videoUrl": "https://cdn.example.com/talk.mp4",
"template": "ref:paprika-ref",
"ratio": "9:16",
"music": false
}'
const createIrisProject = async () => {
const response = await fetch("https://api.submagic.co/v1/iris/projects", {
method: "POST",
headers: {
"x-api-key": "sk-your-api-key-here",
"Content-Type": "application/json",
},
body: JSON.stringify({
videoUrl: "https://cdn.example.com/talk.mp4",
template: "ref:paprika-ref",
ratio: "9:16",
music: false,
}),
});
return response.json();
};
const project = await createIrisProject();
console.log("Iris project:", project.id);
import requests
def create_iris_project():
url = 'https://api.submagic.co/v1/iris/projects'
headers = {
'x-api-key': 'sk-your-api-key-here',
'Content-Type': 'application/json'
}
data = {
'videoUrl': 'https://cdn.example.com/talk.mp4',
'template': 'ref:paprika-ref',
'ratio': '9:16',
'music': False
}
response = requests.post(url, headers=headers, json=data)
return response.json()
project = create_iris_project()
print(f"Iris project: {project['id']}")
{
"id": "33333333-3333-4333-8333-333333333333",
"uploadId": "9b2f6c1e-4d3a-4f5b-8e7c-1a2b3c4d5e6f",
"title": "talk",
"template": "ref:paprika-ref",
"status": "processing"
}
{
"error": "VALIDATION_ERROR",
"message": "Unknown Iris template. List the ones this account can use with GET /v1/iris/templates.",
"reason": "unknown_template"
}
{
"error": "VALIDATION_ERROR",
"message": "ratio invalid value '3:4'. Expected one of: 9:16, 4:5, 1:1, 16:9"
}
{
"error": "FORBIDDEN",
"message": "You have made 20 Iris edits this month. Write to us to get more.",
"reason": "irisMonthlyCap"
}
{
"error": "CONFLICT",
"message": "Another Iris edit is starting on this account. Try again in a few seconds.",
"reason": "iris_starting"
}
API Reference
Create Iris Project
Have Iris edit a video from a link in one of her templates
POST
/
v1
/
iris
/
projects
curl -X POST "https://api.submagic.co/v1/iris/projects" \
-H "x-api-key: sk-your-api-key-here" \
-H "Content-Type: application/json" \
-d '{
"videoUrl": "https://cdn.example.com/talk.mp4",
"template": "ref:paprika-ref",
"ratio": "9:16",
"music": false
}'
const createIrisProject = async () => {
const response = await fetch("https://api.submagic.co/v1/iris/projects", {
method: "POST",
headers: {
"x-api-key": "sk-your-api-key-here",
"Content-Type": "application/json",
},
body: JSON.stringify({
videoUrl: "https://cdn.example.com/talk.mp4",
template: "ref:paprika-ref",
ratio: "9:16",
music: false,
}),
});
return response.json();
};
const project = await createIrisProject();
console.log("Iris project:", project.id);
import requests
def create_iris_project():
url = 'https://api.submagic.co/v1/iris/projects'
headers = {
'x-api-key': 'sk-your-api-key-here',
'Content-Type': 'application/json'
}
data = {
'videoUrl': 'https://cdn.example.com/talk.mp4',
'template': 'ref:paprika-ref',
'ratio': '9:16',
'music': False
}
response = requests.post(url, headers=headers, json=data)
return response.json()
project = create_iris_project()
print(f"Iris project: {project['id']}")
{
"id": "33333333-3333-4333-8333-333333333333",
"uploadId": "9b2f6c1e-4d3a-4f5b-8e7c-1a2b3c4d5e6f",
"title": "talk",
"template": "ref:paprika-ref",
"status": "processing"
}
{
"error": "VALIDATION_ERROR",
"message": "Unknown Iris template. List the ones this account can use with GET /v1/iris/templates.",
"reason": "unknown_template"
}
{
"error": "VALIDATION_ERROR",
"message": "ratio invalid value '3:4'. Expected one of: 9:16, 4:5, 1:1, 16:9"
}
{
"error": "FORBIDDEN",
"message": "You have made 20 Iris edits this month. Write to us to get more.",
"reason": "irisMonthlyCap"
}
{
"error": "CONFLICT",
"message": "Another Iris edit is starting on this account. Try again in a few seconds.",
"reason": "iris_starting"
}
Create Iris Project
Have Iris, Submagic’s editing assistant, edit a video from a link. From a talking video of up to 3 minutes, she makes a finished short-form edit in the template you pick: cuts, captions, b-roll from stock, music, sound effects and graphics. She edits your own footage; she does not make AI-generated video. The project is made as it is when you upload to Iris in the Submagic app, with the same checks. The edit takes a few minutes.This endpoint requires authentication and has a rate limit of 500 requests per
hour. The same
videoUrl can be sent at most 10 times a minute.An Iris edit is charged as in the Submagic app, from your account’s credits,
never from API credits (see Credits). Each call starts
and charges a new edit, so do not retry a call that succeeded. A request that
is refused, or a project that fails, is not charged.
Requirements
- A paid plan, or the one free Iris edit a free account has
- A video of up to 3 minutes. A longer one is not refused by this call: the project fails, with the reason in
failureReason - One Iris edit starting at a time per account
Authentication
Request Body
The Iris template to edit in: an
id from Iris
Templates, e.g. ref:paprika-refProject title (1-100 characters). Defaults to the video’s file name, or
“Untitled video” when the link has none.
The video’s spoken language, as a language code (e.g.
en). Defaults to your
account’s language preference, else it is detected. See
Languages.The ID (UUID) of one of your brand kits to apply. See List Brand
Kits.
A URL Submagic calls with a
POST once Iris has made the edit, or could not.
See Webhook below.Response
Error Responses
Error code:
VALIDATION_ERROR, UNAUTHORIZED, INSUFFICIENT_CREDITS,
FORBIDDEN, NOT_FOUND, CONFLICT, BAD_REQUEST, RATE_LIMIT_EXCEEDED or
INTERNAL_SERVER_ERROR. INTERNAL_SERVER_ERROR always comes with a 5xx
status.When Submagic refused the edit, the refusal’s code, e.g.
unknown_template,
irisPaidPlan or irisMonthlyCapWebhook
With awebhookUrl, Submagic sends one POST with a JSON body when the edit ends:
status: "completed": Iris made the edit.status: "failed": Iris could not make it, or never started (for example, a video over 3 minutes, or one whose speech could not be transcribed).errorsays why. When Iris ran but made no edit, the project itself still completes, with captions only.
{
"projectId": "3f2b8c1e-6d4a-4f0b-9a7e-2c5d8e1f4a6b",
"status": "completed",
"title": "talk",
"previewUrl": "https://app.submagic.co/view/3f2b8c1e-6d4a-4f0b-9a7e-2c5d8e1f4a6b",
"duration": 42,
"completedAt": "2026-11-18T10:00:00.000Z"
}
projectId to ignore a repeat.
After creating
- Wait for the webhook, or call Get Project with the returned
iduntilstatusiscompletedorfailed. A failed project has its reason infailureReason. - To change the edit, send Iris a message with Message Iris.
- To get the video file, call Export Project, then Get Project until
downloadUrlis set.
curl -X POST "https://api.submagic.co/v1/iris/projects" \
-H "x-api-key: sk-your-api-key-here" \
-H "Content-Type: application/json" \
-d '{
"videoUrl": "https://cdn.example.com/talk.mp4",
"template": "ref:paprika-ref",
"ratio": "9:16",
"music": false
}'
const createIrisProject = async () => {
const response = await fetch("https://api.submagic.co/v1/iris/projects", {
method: "POST",
headers: {
"x-api-key": "sk-your-api-key-here",
"Content-Type": "application/json",
},
body: JSON.stringify({
videoUrl: "https://cdn.example.com/talk.mp4",
template: "ref:paprika-ref",
ratio: "9:16",
music: false,
}),
});
return response.json();
};
const project = await createIrisProject();
console.log("Iris project:", project.id);
import requests
def create_iris_project():
url = 'https://api.submagic.co/v1/iris/projects'
headers = {
'x-api-key': 'sk-your-api-key-here',
'Content-Type': 'application/json'
}
data = {
'videoUrl': 'https://cdn.example.com/talk.mp4',
'template': 'ref:paprika-ref',
'ratio': '9:16',
'music': False
}
response = requests.post(url, headers=headers, json=data)
return response.json()
project = create_iris_project()
print(f"Iris project: {project['id']}")
{
"id": "33333333-3333-4333-8333-333333333333",
"uploadId": "9b2f6c1e-4d3a-4f5b-8e7c-1a2b3c4d5e6f",
"title": "talk",
"template": "ref:paprika-ref",
"status": "processing"
}
{
"error": "VALIDATION_ERROR",
"message": "Unknown Iris template. List the ones this account can use with GET /v1/iris/templates.",
"reason": "unknown_template"
}
{
"error": "VALIDATION_ERROR",
"message": "ratio invalid value '3:4'. Expected one of: 9:16, 4:5, 1:1, 16:9"
}
{
"error": "FORBIDDEN",
"message": "You have made 20 Iris edits this month. Write to us to get more.",
"reason": "irisMonthlyCap"
}
{
"error": "CONFLICT",
"message": "Another Iris edit is starting on this account. Try again in a few seconds.",
"reason": "iris_starting"
}

