EDITLY / API REFERENCE

Let’s build
something original.

Connect your workflow to Editly’s image and video engines. Start small, authenticate securely, and follow every generation to its final result.

BASE URL   https://api.editly.studio

01 / Quickstart

This read-only request requires no account and uses no credits:

GET /health
curl --fail-with-body https://api.editly.studio/health

A healthy API process responds with {"status":"ok"}. This check does not test upstream AI providers, billing, or storage.

Create your key, then connect.

Sign in to the developer dashboard, name your key, choose permissions and an expiry, then copy it once. Store it server-side as EDITLY_API_KEY. Start with the free credits check below.

02 / Authentication

Create your key in the Editly developer dashboard. Sign-in and applicable 18+ eligibility checks are required. Each key is bound to your account, has an expiry and is displayed only once.

  • Authentication: send Authorization: Bearer $EDITLY_API_KEY from your server. Never use an AI-provider key or share your account session.
  • Permissions: credits:read reads the balance; generations:read lists, polls and downloads your results; generations:write creates images and Seedance videos; uploads:write enables temporary video/audio uploads.
  • Limits: up to 10 active keys, with 30, 90 or 365 day expiry. All keys share 60 requests and 10 submissions/uploads per minute per account. A 429 includes Retry-After.
  • Revocation: revoke any key in the dashboard. New requests are rejected immediately; already accepted jobs may finish. Keys are independent of sign-in sessions, so signing out does not revoke them.
Keep your keys on your server.

Never put keys in frontend code, a mobile app bundle, query strings, logs or public repositories. Only a hash is stored by Editly. API keys cannot access account, payment, admin or key-management routes. A read-only key cannot submit paid jobs.

03 / Models & inputs

Developer keys support the image and Seedance selections below. Other in-app engines and client-completed job mutations are not enabled for developer keys. JSON requests are limited to 20 MB; image references can use image URLs or image data URLs.

ModelRequest fieldValue
Nano Banana 2modelgemini-3.1-flash-image
Nano Banana Promodelgemini-3-pro-image
GPT Image 2modelgpt-image-2
Seedance 2.0providerseedance
Seedance 2.5providerseedance25

Image generation

Send type: "image", a prompt, a model, and an aspect ratio to POST /api/generations. Optional inputImage or inputImages provide references. Supported media limits depend on the selected model.

Seedance generation

Use POST /api/generations/seedance. For a first integration, use a text-only prompt, 5 seconds, 480p, and 16:9. Other durations, resolutions and media combinations are validated against the selected model and server configuration.

  • seedanceImageMode: "reference" accepts up to nine image references.
  • seedanceImageMode: "first_frame" uses a first image and optionally a last image; first-frame output framing follows the image constraints.
  • Video and audio references use POST /api/uploads/seedance/presign with filename, contentType, kind (video/audio), sizeBytes and durationSeconds. PUT the file bytes to the returned data.uploadUrl using the same Content-Type, then send referenceVideo or referenceAudio as {key: data.key, durationSeconds: …}. Do not attach your Editly key to the storage PUT. Uploads are temporary, validated and account-bound; submit before expiry. Arbitrary video URLs are not supported. Audio must be paired with a visual reference.
  • Seedance 2.5 video-edit requests follow the selected input clip’s duration and native output framing; do not assume generation-mode timing and ratios apply to video editing.
  • When using a video template, its stored model, configured resolution, and fixed credit price take precedence.

Upload only content you have rights and any required consent to use. Provider moderation and Editly’s terms still apply.

04 / Generation lifecycle

queuedgeneratingcompleted / failed
  1. Submit once and retain data.id. A 200 create response means the job was accepted, not that the output is ready.
  2. Poll GET /api/generations/{id} approximately every 3–6 seconds. Responses can include intermediate states such as pending; treat non-terminal states as still in progress.
  3. On completed, read data.imageUrl or data.videoUrl, or use the authenticated download endpoint. On failed, inspect the returned failure information.

Use the Editly generation ID—not the provider’s task ID or the filename UUID. Generation detail and download endpoints are restricted to the owning account.

Output URLs are shareable media links.

The API checks ownership, but an output’s underlying media URL may be publicly reachable by anyone who has it. Do not assume that hiding a URL or requiring API login makes the media storage private.

05 / Credits & billing

API generation uses the same account credit balance as Editly. Read GET /api/credits to see purchased credits, subscription credits, applicable expiration information and general cost settings.

  • Video-template generations use the template’s fixed server-side credit cost and configured resolution.
  • Direct Seedance requests are priced by the server using validated duration and resolution. The general costs object is not a universal quote for every video configuration.
  • An insufficient-balance response uses HTTP 402 and can include the required/current amounts.
  • Failed generation refunds are processed by the existing backend workflow. Refresh the balance and inspect the final record; do not assume every network error means the request was rejected.

Check current plans in Editly pricing. This portal does not introduce new plans, discounts, payment methods, or billing terms.

06 / Endpoint reference

8 operations

GET

/health

Check API process availability. No authentication or credit charge.

GET /health
curl --fail-with-body https://api.editly.studio/health
Response example

Illustrative, simplified response. Additional fields may be returned.

{ "status": "ok" }
POST

/api/generations

Submit a prompt-based image job using an authenticated account with sufficient credits.

POST /api/generations
curl --fail-with-body https://api.editly.studio/api/generations \
  -H "Authorization: Bearer $EDITLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "image",
    "model": "gemini-3.1-flash-image",
    "prompt": "A blue origami boat on a sunlit pond",
    "aspectRatio": "16:9"
  }'
Response example

Illustrative, simplified response. Additional fields may be returned.

{ "data": { "id": "<generation-id>", "status": "queued" } }
POST

/api/generations/seedance

Submit a Seedance text-to-video job. The server selects the matching model from the provider.

POST /api/generations/seedance
curl --fail-with-body https://api.editly.studio/api/generations/seedance \
  -H "Authorization: Bearer $EDITLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "seedance25",
    "prompt": "A blue origami boat glides across a pond",
    "duration": 5,
    "resolution": "480p",
    "aspectRatio": "16:9"
  }'
Response example

Illustrative, simplified response. Additional fields may be returned.

{ "data": { "id": "<generation-id>", "status": "queued" } }
GET

/api/generations/{id}

Read the status and output of a generation owned by the authenticated account.

GET /api/generations/{id}
curl --fail-with-body \
  "https://api.editly.studio/api/generations/$GENERATION_ID" \
  -H "Authorization: Bearer $EDITLY_API_KEY"
Response example

Illustrative, simplified response. Additional fields may be returned.

{ "data": { "id": "<generation-id>", "status": "completed",
  "videoUrl": "https://<media-host>/<output>.mp4" } }
GET

/api/credits

Read the authenticated account’s balance, subscription and expiration information.

GET /api/credits
curl --fail-with-body https://api.editly.studio/api/credits \
  -H "Authorization: Bearer $EDITLY_API_KEY"
Response example

Illustrative, simplified response. Additional fields may be returned.

{ "data": { "credits": 120,
  "purchasedCredits": 100, "subscriptionCredits": 20 } }
GET

/api/generations/{id}/download

Download completed media owned by the authenticated account. Returns binary media, not a JSON URL.

GET /api/generations/{id}/download
curl --fail-with-body \
  "https://api.editly.studio/api/generations/$GENERATION_ID/download" \
  -H "Authorization: Bearer $EDITLY_API_KEY" \
  --output editly-output.mp4
Response example

Illustrative, simplified response. Additional fields may be returned.

Binary file response · use .jpg or the returned image format for image jobs.
GET

/api/generations

List your account’s generation history, with page and limit query parameters. Requires generations:read.

GET /api/generations
curl --fail-with-body "https://api.editly.studio/api/generations?page=1&limit=20" \
  -H "Authorization: Bearer $EDITLY_API_KEY"
Response example

Illustrative, simplified response. Additional fields may be returned.

{ "data": [], "current_page": 1, "total_pages": 0, "total_items": 0, "per_page": 20 }
POST

/api/uploads/seedance/presign

Create a temporary video/audio upload. Requires uploads:write. Replace the example file size and duration with the real values, then upload bytes to the returned URL.

POST /api/uploads/seedance/presign
curl --fail-with-body https://api.editly.studio/api/uploads/seedance/presign \
  -H "Authorization: Bearer $EDITLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename":"reference.mp4","contentType":"video/mp4",
    "kind":"video","sizeBytes":1048576,"durationSeconds":5}'
Response example

Illustrative, simplified response. Additional fields may be returned.

{ "data": { "key": "<temporary-object-key>",
  "uploadUrl": "<signed-PUT-url>", "expiresInSeconds": 900,
  "maxBytes": 104857600 } }

07 / Errors & retries

HTTP statusWhat to do
400Check model, settings and media constraints. Read the error message.
401Check your API key, expiry and revocation status.
402Check the account balance and required credits.
403Check the required permission, permitted endpoint and account eligibility.
404Check the route and generation ID. Private records owned by another account also return 404.
429Slow down and honor Retry-After if returned.
5xxBack off on reads. Check an existing job before submitting another paid request.

Most errors use {"error":{"message":"…","code":"…"}}; some legacy endpoints return an error string. Handle both without logging credentials.

Create requests are not documented as idempotent.

Do not automatically repeat a paid POST after a timeout. It may already have created a job and charged credits. Check your recent generations or contact support first.

Open the machine-readable reference