Skip to main content
POST

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

string
required
Your Submagic API key starting with sk-

Request Body

string
required
A direct link to the video file, or a public Google Drive or Dropbox link
string
required
The Iris template to edit in: an id from Iris Templates, e.g. ref:paprika-ref
string
Project title (1-100 characters). Defaults to the video’s file name, or “Untitled video” when the link has none.
string
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.
string
The edit’s frame: 9:16, 4:5, 1:1 or 16:9. Defaults to 9:16.
boolean
Cut pauses and bad takes. Defaults to true.
boolean
Add b-roll. Defaults to true.
boolean
Add music. Defaults to true.
boolean
Put text behind the speaker, on templates that do it. Costs more credits. Defaults to false.
string
The ID (UUID) of one of your brand kits to apply. See List Brand Kits.
string
A URL Submagic calls with a POST once Iris has made the edit, or could not. See Webhook below.

Response

string
The new project’s ID (UUID format)
string
ID of the video download
string
The project’s title
string
The Iris template the project uses, e.g. ref:paprika-ref
string
Always processing

Error Responses

string
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.
string
What went wrong, in plain words
string
When Submagic refused the edit, the refusal’s code, e.g. unknown_template, irisPaidPlan or irisMonthlyCap

Webhook

With a webhookUrl, 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). error says why. When Iris ran but made no edit, the project itself still completes, with captions only.
The edit has no video file yet: call Export Project to render it. If your endpoint does not answer with a 2xx, Submagic makes up to 3 attempts in all. The same webhook can arrive more than once: use projectId to ignore a repeat.

After creating

  1. Wait for the webhook, or call Get Project with the returned id until status is completed or failed. A failed project has its reason in failureReason.
  2. To change the edit, send Iris a message with Message Iris.
  3. To get the video file, call Export Project, then Get Project until downloadUrl is set.