{
  "openapi": "3.1.0",
  "info": {
    "title": "Editly API — Core Reference",
    "version": "2026-10-03",
    "description": "Editly developer API for image and Seedance generation. Create a scoped, expiring API key at https://editly.studio/developer. Keep keys server-side. Limits: 60 requests and 10 submissions/uploads per minute per account across keys. Generation uses existing account credits. Repeating a create request can create and charge another job.",
    "contact": {
      "name": "Editly Support",
      "url": "https://editly.studio/support"
    }
  },
  "servers": [
    {
      "url": "https://api.editly.studio"
    }
  ],
  "tags": [
    {
      "name": "Status"
    },
    {
      "name": "Generations"
    },
    {
      "name": "Account"
    }
  ],
  "paths": {
    "/health": {
      "get": {
        "operationId": "getHealth",
        "tags": [
          "Status"
        ],
        "summary": "Check API process health",
        "security": [],
        "responses": {
          "200": {
            "description": "Process is responding; does not certify every upstream provider.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "const": "ok"
                    }
                  },
                  "required": [
                    "status"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/credits": {
      "get": {
        "operationId": "getCredits",
        "tags": [
          "Account"
        ],
        "summary": "Read current account credits",
        "security": [
          {
            "developerKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Balance, cost configuration, subscription and expiration information.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "A valid Editly developer API key is required.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/generations": {
      "get": {
        "operationId": "listGenerations",
        "tags": [
          "Generations"
        ],
        "summary": "List your account's generation history",
        "security": [
          {
            "developerKey": []
          }
        ],
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated account-owned history. data is an array, with current_page, total_pages, total_items and per_page alongside it.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true
                      }
                    },
                    "current_page": {
                      "type": "integer"
                    },
                    "total_pages": {
                      "type": "integer"
                    },
                    "total_items": {
                      "type": "integer"
                    },
                    "per_page": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "A valid Editly developer API key is required.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "createImage",
        "tags": [
          "Generations"
        ],
        "summary": "Submit an image generation",
        "description": "This documented subset covers image requests only. Use the dedicated Seedance route below for video. Complete the account age checks and hold sufficient credits. The returned data.id is used for polling.",
        "security": [
          {
            "developerKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "type",
                  "prompt"
                ],
                "properties": {
                  "type": {
                    "const": "image"
                  },
                  "prompt": {
                    "type": "string",
                    "minLength": 1
                  },
                  "model": {
                    "type": "string",
                    "enum": [
                      "gemini-3.1-flash-image",
                      "gemini-3-pro-image",
                      "gpt-image-2"
                    ]
                  },
                  "aspectRatio": {
                    "type": "string",
                    "enum": [
                      "1:1",
                      "16:9",
                      "9:16"
                    ]
                  },
                  "inputImage": {
                    "type": "string",
                    "description": "Optional image URL or image data URL."
                  },
                  "inputImages": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Optional image references; supported limits depend on the selected model."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Job accepted, not a completed output. Additional response fields may be present.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "A valid Editly developer API key is required.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Insufficient credits.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Account eligibility check required or account restricted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/generations/template/catalog": {
      "get": {
        "operationId": "listProductVideoTemplates",
        "tags": [
          "Generations"
        ],
        "summary": "List active product-video templates",
        "description": "Requires generations:read. Returns display metadata and fixed engine credit prices for compatible templates. Does not expose template prompts or preparation configuration.",
        "security": [
          {
            "developerKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Active product templates in data.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "A valid Editly developer API key is required.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/generations/template/quote": {
      "post": {
        "operationId": "quoteProductVideoTemplate",
        "tags": [
          "Generations"
        ],
        "summary": "Quote a product-video template",
        "description": "Requires generations:read. Read-only; does not submit or charge a job. Returns templateVersion, creditCost, duration and aspectRatio. Review these before submission.",
        "security": [
          {
            "developerKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "templateId"
                ],
                "properties": {
                  "templateId": {
                    "type": "string",
                    "format": "uuid"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Authoritative price and template version in data.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "A valid Editly developer API key is required.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Template unavailable.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/generations/template": {
      "post": {
        "operationId": "createProductTemplateVideo",
        "tags": [
          "Generations"
        ],
        "summary": "Submit a quoted Salla product video",
        "description": "Requires generations:write. Settings and price come from the active template. Only Salla CDN product photos are accepted. Repeat the SAME Idempotency-Key and body after a lost response; a different body returns 409. An unresolved request stays reserved and must be checked in history or by support before intentionally starting another job.",
        "security": [
          {
            "developerKey": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 8,
              "maxLength": 120,
              "pattern": "^[A-Za-z0-9_.:-]+$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "templateId",
                  "expectedTemplateVersion",
                  "maxCreditCost",
                  "product"
                ],
                "properties": {
                  "templateId": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "expectedTemplateVersion": {
                    "type": "string",
                    "pattern": "^[a-f0-9]{64}$"
                  },
                  "maxCreditCost": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 100000
                  },
                  "product": {
                    "type": "object",
                    "additionalProperties": false,
                    "required": [
                      "name",
                      "imageUrl"
                    ],
                    "properties": {
                      "name": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 200
                      },
                      "description": {
                        "type": "string",
                        "maxLength": 2000
                      },
                      "imageUrl": {
                        "type": "string",
                        "format": "uri",
                        "description": "HTTPS image on cdn.salla.sa or a .salla.cloud host, without credentials or an explicit port."
                      }
                    }
                  },
                  "campaignGoal": {
                    "type": "string",
                    "maxLength": 1500
                  },
                  "language": {
                    "type": "string",
                    "enum": [
                      "ar",
                      "en"
                    ],
                    "default": "ar"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Accepted generation in data. Poll data.id; this is not a finished video.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input or quote ceiling.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "A valid Editly developer API key is required.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Insufficient integration-account credits.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Template changed, request conflict or request already in progress.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/generations/seedance": {
      "post": {
        "operationId": "createSeedanceVideo",
        "tags": [
          "Generations"
        ],
        "summary": "Submit a Seedance video",
        "description": "Text/image-to-video and video editing. Video/audio references use POST /api/uploads/seedance/presign; upload bytes to the returned uploadUrl, then pass referenceVideo or referenceAudio with key and durationSeconds. Template configuration and server billing rules are authoritative. Client creditCost values cannot set the price.",
        "security": [
          {
            "developerKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "provider",
                  "prompt"
                ],
                "properties": {
                  "provider": {
                    "type": "string",
                    "enum": [
                      "seedance",
                      "seedance25"
                    ]
                  },
                  "prompt": {
                    "type": "string",
                    "minLength": 1
                  },
                  "duration": {
                    "type": "integer",
                    "minimum": 4,
                    "maximum": 30,
                    "description": "Model-dependent. The 5-second quickstart works with either provider; do not assume every provider accepts 30 seconds."
                  },
                  "resolution": {
                    "type": "string",
                    "enum": [
                      "480p",
                      "720p",
                      "1080p"
                    ],
                    "description": "480p, 720p and 1080p are supported by the current Seedance 2.0/2.5 server configuration. Template resolution is admin-controlled; provider availability can change."
                  },
                  "aspectRatio": {
                    "type": "string",
                    "enum": [
                      "16:9",
                      "9:16",
                      "1:1",
                      "4:3",
                      "3:4",
                      "21:9",
                      "adaptive"
                    ]
                  },
                  "seedanceImageMode": {
                    "type": "string",
                    "enum": [
                      "reference",
                      "first_frame"
                    ]
                  },
                  "referenceImages": {
                    "type": "array",
                    "maxItems": 9,
                    "items": {
                      "type": "string"
                    },
                    "description": "Reference mode accepts up to 9 images. First-frame mode accepts up to 2 (first and last); provide only media you are entitled to use."
                  },
                  "referenceVideo": {
                    "type": "object",
                    "required": [
                      "key",
                      "durationSeconds"
                    ],
                    "properties": {
                      "key": {
                        "type": "string"
                      },
                      "durationSeconds": {
                        "type": "number"
                      }
                    }
                  },
                  "referenceAudio": {
                    "type": "object",
                    "required": [
                      "key",
                      "durationSeconds"
                    ],
                    "properties": {
                      "key": {
                        "type": "string"
                      },
                      "durationSeconds": {
                        "type": "number"
                      }
                    }
                  },
                  "inputImage": {
                    "type": "string"
                  },
                  "endImage": {
                    "type": "string"
                  },
                  "templateId": {
                    "type": "string",
                    "description": "Video template ID. Its stored model, resolution and fixed credit cost are authoritative."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Job accepted. Poll data.id until completed or failed.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid model, media or settings.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "A valid Editly developer API key is required.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Insufficient credits.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Account eligibility check required or account restricted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/uploads/seedance/presign": {
      "post": {
        "operationId": "createTemporaryUpload",
        "tags": [
          "Generations"
        ],
        "summary": "Create an account-bound temporary video/audio upload",
        "security": [
          {
            "developerKey": []
          }
        ],
        "description": "Requires uploads:write. Video: MP4/MOV, max 100 MB, max 30 seconds (Seedance 2.0 max 15 seconds at generation). Audio: MP3/WAV, max 15 MB, 2–15 seconds, paired with a visual reference. PUT bytes directly to uploadUrl with the same Content-Type within 15 minutes. Do not send your Editly Authorization header to storage. Include the key and durationSeconds in referenceVideo/referenceAudio when generating.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "filename",
                  "contentType",
                  "kind",
                  "sizeBytes",
                  "durationSeconds"
                ],
                "properties": {
                  "filename": {
                    "type": "string"
                  },
                  "contentType": {
                    "type": "string",
                    "enum": [
                      "video/mp4",
                      "video/quicktime",
                      "audio/mpeg",
                      "audio/wav"
                    ]
                  },
                  "kind": {
                    "type": "string",
                    "enum": [
                      "video",
                      "audio"
                    ]
                  },
                  "sizeBytes": {
                    "type": "integer",
                    "minimum": 1
                  },
                  "durationSeconds": {
                    "type": "number",
                    "minimum": 2,
                    "maximum": 30
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Signed temporary PUT URL and account-bound object key.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid media kind, format, size or duration.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "A valid Editly developer API key is required.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Required scope or eligibility is missing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/generations/{id}": {
      "get": {
        "operationId": "getGeneration",
        "tags": [
          "Generations"
        ],
        "summary": "Read your generation and its output",
        "security": [
          {
            "developerKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Generation ID returned by a create request, not a provider task ID."
          }
        ],
        "responses": {
          "200": {
            "description": "Generation including status, optional imageUrl/videoUrl, and failure information.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "A valid Editly developer API key is required.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found or not owned by the authenticated account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/generations/{id}/download": {
      "get": {
        "operationId": "downloadGeneration",
        "tags": [
          "Generations"
        ],
        "summary": "Download your completed output",
        "security": [
          {
            "developerKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Generation ID returned by a create request, not a provider task ID."
          }
        ],
        "responses": {
          "200": {
            "description": "Binary media; Content-Type and Content-Disposition describe the returned file.",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "401": {
            "description": "A valid Editly developer API key is required.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Generation is unavailable, not owned, or has no output yet."
          },
          "502": {
            "description": "Upstream media fetch failed."
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "developerKey": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "ed_live_<id>_<secret>",
        "description": "Create a key at https://editly.studio/developer. Permissions: credits:read, generations:read, generations:write, uploads:write. Keys are shown once and can be revoked. Never expose keys in browser/mobile bundles."
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "oneOf": [
              {
                "type": "object",
                "properties": {
                  "message": {
                    "type": "string"
                  },
                  "code": {
                    "type": "string"
                  }
                },
                "additionalProperties": true
              },
              {
                "type": "string"
              }
            ]
          }
        }
      }
    }
  }
}