curl -X POST "https://api.submagic.co/v1/projects/11111111-1111-4111-8111-111111111111/iris" \
-H "x-api-key: sk-your-api-key-here" \
-H "Content-Type: application/json" \
-d '{
"message": "Make the music quieter"
}'
const messageIris = async (projectId, message) => {
const response = await fetch(
`https://api.submagic.co/v1/projects/${projectId}/iris`,
{
method: "POST",
headers: {
"x-api-key": "sk-your-api-key-here",
"Content-Type": "application/json",
},
body: JSON.stringify({ message }),
}
);
return response.json();
};
const { jobId } = await messageIris(
"11111111-1111-4111-8111-111111111111",
"Make the music quieter"
);
import requests
def message_iris(project_id, message):
url = f'https://api.submagic.co/v1/projects/{project_id}/iris'
headers = {
'x-api-key': 'sk-your-api-key-here',
'Content-Type': 'application/json'
}
response = requests.post(url, headers=headers, json={'message': message})
return response.json()
job = message_iris(
'11111111-1111-4111-8111-111111111111',
'Make the music quieter'
)
{
"jobId": "22222222-2222-4222-8222-222222222222",
"projectId": "11111111-1111-4111-8111-111111111111",
"fromVersion": 2,
"status": "running"
}
{
"error": "VALIDATION_ERROR",
"message": "This project was not edited by Iris. Iris works on projects made with an Iris template in the Submagic app.",
"reason": "not_iris"
}
{
"error": "FORBIDDEN",
"message": "You've used all 20 messages for this video.",
"reason": "chat_limit"
}
{
"error": "NOT_FOUND",
"message": "Project not found",
"reason": "not_found"
}
{
"error": "CONFLICT",
"message": "Iris is still making this edit. Try again once the project is completed.",
"reason": "iris_making"
}
{
"error": "CONFLICT",
"message": "Iris is still working on your last message.",
"jobId": "22222222-2222-4222-8222-222222222222"
}
API Reference
Message Iris
Ask Iris to change an edit she made, in plain words
POST
/
v1
/
projects
/
{id}
/
iris
curl -X POST "https://api.submagic.co/v1/projects/11111111-1111-4111-8111-111111111111/iris" \
-H "x-api-key: sk-your-api-key-here" \
-H "Content-Type: application/json" \
-d '{
"message": "Make the music quieter"
}'
const messageIris = async (projectId, message) => {
const response = await fetch(
`https://api.submagic.co/v1/projects/${projectId}/iris`,
{
method: "POST",
headers: {
"x-api-key": "sk-your-api-key-here",
"Content-Type": "application/json",
},
body: JSON.stringify({ message }),
}
);
return response.json();
};
const { jobId } = await messageIris(
"11111111-1111-4111-8111-111111111111",
"Make the music quieter"
);
import requests
def message_iris(project_id, message):
url = f'https://api.submagic.co/v1/projects/{project_id}/iris'
headers = {
'x-api-key': 'sk-your-api-key-here',
'Content-Type': 'application/json'
}
response = requests.post(url, headers=headers, json={'message': message})
return response.json()
job = message_iris(
'11111111-1111-4111-8111-111111111111',
'Make the music quieter'
)
{
"jobId": "22222222-2222-4222-8222-222222222222",
"projectId": "11111111-1111-4111-8111-111111111111",
"fromVersion": 2,
"status": "running"
}
{
"error": "VALIDATION_ERROR",
"message": "This project was not edited by Iris. Iris works on projects made with an Iris template in the Submagic app.",
"reason": "not_iris"
}
{
"error": "FORBIDDEN",
"message": "You've used all 20 messages for this video.",
"reason": "chat_limit"
}
{
"error": "NOT_FOUND",
"message": "Project not found",
"reason": "not_found"
}
{
"error": "CONFLICT",
"message": "Iris is still making this edit. Try again once the project is completed.",
"reason": "iris_making"
}
{
"error": "CONFLICT",
"message": "Iris is still working on your last message.",
"jobId": "22222222-2222-4222-8222-222222222222"
}
Message Iris
Send Iris one change to an edit she made, in plain words, as you would type it in her chat in Submagic: b-roll, music, sound effects, voice volume, captions and their style, cuts and pauses, framing, the hook title and graphics, eye contact, clean audio, translation. Iris works in the background. This call returns ajobId at once; read the job with Get Iris Job until its status is no longer running. A change saves a new version of the edit, and the versions before it are kept.
This endpoint requires authentication and has a rate limit of 500 requests per
hour. Messages to Iris do not use credits.
Limits
- Iris only changes projects she edited: ones made with Create Iris Project or an Iris template in the Submagic app. Their
aiEditTemplatein Get Project starts withref:. - The edit must be finished: wait until the project’s
statusiscompleted. - Iris needs a paid plan.
- Iris works on one message at a time. A message sent while she is still working is refused with
409and thejobIdto wait for. - Each video allows a limited number of messages, the same as in the app, and an account can send up to 30 messages an hour. Send everything you want changed in one message rather than one message per change.
- The messages show in the project’s chat in Submagic.
Authentication
Path Parameters
Request Body
What to change, in your words (1-4000 characters), e.g. “make the music
quieter” or “add a b-roll of a city at night when I mention New York”
Response
The message’s job ID. Read it with Get Iris Job.
Error Responses
Error code:
VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, NOT_FOUND,
CONFLICT, RATE_LIMIT_EXCEEDED or INTERNAL_SERVER_ERRORWhen Iris refused the message, the refusal’s code, e.g.
not_iris,
iris_making, no_edit, iris_paid_plan or chat_limitcurl -X POST "https://api.submagic.co/v1/projects/11111111-1111-4111-8111-111111111111/iris" \
-H "x-api-key: sk-your-api-key-here" \
-H "Content-Type: application/json" \
-d '{
"message": "Make the music quieter"
}'
const messageIris = async (projectId, message) => {
const response = await fetch(
`https://api.submagic.co/v1/projects/${projectId}/iris`,
{
method: "POST",
headers: {
"x-api-key": "sk-your-api-key-here",
"Content-Type": "application/json",
},
body: JSON.stringify({ message }),
}
);
return response.json();
};
const { jobId } = await messageIris(
"11111111-1111-4111-8111-111111111111",
"Make the music quieter"
);
import requests
def message_iris(project_id, message):
url = f'https://api.submagic.co/v1/projects/{project_id}/iris'
headers = {
'x-api-key': 'sk-your-api-key-here',
'Content-Type': 'application/json'
}
response = requests.post(url, headers=headers, json={'message': message})
return response.json()
job = message_iris(
'11111111-1111-4111-8111-111111111111',
'Make the music quieter'
)
{
"jobId": "22222222-2222-4222-8222-222222222222",
"projectId": "11111111-1111-4111-8111-111111111111",
"fromVersion": 2,
"status": "running"
}
{
"error": "VALIDATION_ERROR",
"message": "This project was not edited by Iris. Iris works on projects made with an Iris template in the Submagic app.",
"reason": "not_iris"
}
{
"error": "FORBIDDEN",
"message": "You've used all 20 messages for this video.",
"reason": "chat_limit"
}
{
"error": "NOT_FOUND",
"message": "Project not found",
"reason": "not_found"
}
{
"error": "CONFLICT",
"message": "Iris is still making this edit. Try again once the project is completed.",
"reason": "iris_making"
}
{
"error": "CONFLICT",
"message": "Iris is still working on your last message.",
"jobId": "22222222-2222-4222-8222-222222222222"
}

