Creative Studio API

Describe it, see it, use it — product photos, posts, story videos, voice-overs and music, made by AI.

Module code creative · 26 actions · 5 data models · 8 events. A key or token never does more here than the person behind it can; row-level security applies exactly as in the app. Scopes: creative (everything), creative:read (read only) or creative:<capability>.

Resources

Lists take limit (up to 200), cursor, order (e.g. -created_at), fields and q; every other query parameter is a column filter: ?status=paid, ?total[gte]=100, ?id[in]=a,b, ?x=null.

Actions

creative.cancel

Cancel a generation — Stops a generation that has not started.

Needs creative:write · removes or cannot be undone

• Canonical address: POST /api/v1/actions/creative.cancel

Input

Preconditions

The action is refused with 409 and one of these codes:

What it writes: creative_generation (update) — queued → cancelled

curl -X POST https://app.getera.io/api/v1/creative_generations/CREATIVE_GENERATION_ID/actions/cancel \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

{
  "ok": true,
  "result": "…",
  "events": []
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.creativeGenerations.cancel("CREATIVE_GENERATION_ID")

era creative_generations cancel CREATIVE_GENERATION_ID

{
  "name": "era__creative__cancel",
  "arguments": {
    "id": "CREATIVE_GENERATION_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold creative:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_queued · 429 slow down

creative.cancel_post

Cancel a scheduled post — Stops a post that has not gone out yet.

Needs creative:write · removes or cannot be undone

• Canonical address: POST /api/v1/actions/creative.cancel_post

Input

Preconditions

The action is refused with 409 and one of these codes:

What it writes: creative_post (update) — scheduled → cancelled

curl -X POST https://app.getera.io/api/v1/creative_posts/CREATIVE_POST_ID/actions/cancel_post \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

{
  "ok": true,
  "result": "…",
  "events": []
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.creativePosts.cancelPost("CREATIVE_POST_ID")

era creative_posts cancel_post CREATIVE_POST_ID

{
  "name": "era__creative__cancel_post",
  "arguments": {
    "id": "CREATIVE_POST_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold creative:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_scheduled · 429 slow down

creative.clone_voice

Clone a voice — Makes a voice from your own recordings, for voice-overs and lip sync. Only with the speaker’s consent.

Needs creative:write · reaches outside (sends, publishes or charges) · asks a person to confirm when Era runs it

• Canonical address: POST /api/v1/actions/creative.clone_voice

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: creative.voice_requested

What it writes: creative_voice (insert) — A pending voice, made by the studio right after

curl -X POST https://app.getera.io/api/v1/creative_voices/actions/clone_voice \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"name":"Voice name","sampleFileIds":{},"consent":true}'

{
  "ok": true,
  "result": "…",
  "events": [
    "creative.voice_requested"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.creativeVoices.cloneVoice({
  name: "Voice name",
  sampleFileIds: {},
  consent: true
})

era creative_voices clone_voice --data '{"name":"Voice name","sampleFileIds":{},"consent":true}'

{
  "name": "era__creative__clone_voice",
  "arguments": {
    "name": "Voice name",
    "sampleFileIds": {},
    "consent": true
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold creative:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 empty_name, consent_required, needs_samples · 429 slow down

creative.complete_generation

Finish a generation — Records the results (files) and the real cost. Machine-only.

Needs creative:handle · changes data

• Canonical address: POST /api/v1/actions/creative.complete_generation

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: creative.generated

What it writes: creative_generation (update) — running → succeeded, with results and cost

Errors: 401 no or expired credential · 403 the credential does not hold creative:handle · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_running, no_outputs · 429 slow down

creative.compose

Set text on a picture, or make a photo reel — Made by Era itself — no AI model, no cost. A layout sets real, correctly spelled text over a picture in the brand’s colours and font with the logo (campaign, new_product, price_tag, announcement, story_cta, menu_card, marketplace_band, quote). A photo reel turns 2–10 photos into a vertical video with gentle motion, the hook, music and an end card.

Needs creative:write · changes data

• Canonical address: POST /api/v1/actions/creative.compose

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: creative.requested

What it writes: creative_generation (insert) — Queues the layout or reel; Era makes it without a model

curl -X POST https://app.getera.io/api/v1/creative_generations/CREATIVE_GENERATION_ID/actions/compose \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"kind":"layout","fileIds":{}}'

{
  "ok": true,
  "result": "…",
  "events": [
    "creative.requested"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.creativeGenerations.compose("CREATIVE_GENERATION_ID", {
  kind: "layout",
  fileIds: {}
})

era creative_generations compose CREATIVE_GENERATION_ID --data '{"kind":"layout","fileIds":{}}'

{
  "name": "era__creative__compose",
  "arguments": {
    "sourceGenerationId": "CREATIVE_GENERATION_ID",
    "kind": "layout",
    "fileIds": {}
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold creative:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 unknown_layout, needs_image, empty_text, needs_photos, unknown_track, not_found · 429 slow down

creative.edit_again

Edit the video again — Makes a new version of a finished AI video edit from a note ("shorter intro, no music"); the earlier versions stay.

Needs creative:write · changes data

• Canonical address: POST /api/v1/actions/creative.edit_again

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: creative.requested

What it writes: creative_generation (insert) — A queued video edit: the next version, pointing at the one it changes

curl -X POST https://app.getera.io/api/v1/creative_generations/CREATIVE_GENERATION_ID/actions/edit_again \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"note":"What should change"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "creative.requested"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.creativeGenerations.editAgain("CREATIVE_GENERATION_ID", {
  note: "What should change"
})

era creative_generations edit_again CREATIVE_GENERATION_ID \
  --note "What should change"

{
  "name": "era__creative__edit_again",
  "arguments": {
    "id": "CREATIVE_GENERATION_ID",
    "note": "What should change"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold creative:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 empty_note, not_editable · 429 slow down

creative.fail_generation

Mark a generation failed — Records why it failed. Machine-only.

Needs creative:handle · changes data

• Canonical address: POST /api/v1/actions/creative.fail_generation

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: creative.failed

What it writes: creative_generation (update) — → failed

Errors: 401 no or expired credential · 403 the credential does not hold creative:handle · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_open · 429 slow down

creative.finish_voice

Finish cloning a voice — Records the provider’s voice, or why it failed. Machine-only.

Needs creative:handle · changes data

• Canonical address: POST /api/v1/actions/creative.finish_voice

Input

Preconditions

The action is refused with 409 and one of these codes:

What it writes: creative_voice (update) — pending → ready / failed

Errors: 401 no or expired credential · 403 the credential does not hold creative:handle · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_pending · 429 slow down

creative.generate

Generate an image, video, voice-over or music — Describe it (or pick a preset like a white-background product shot, an Instagram post, a story video or a menu photo); it is made in the background and lands in Creative Studio and the Files library. The cost is shown first; it runs on your own subscription or key.

Needs creative:write · changes data

• Canonical address: POST /api/v1/actions/creative.generate

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: creative.requested

What it writes: creative_generation (insert) — Queues the generation with its estimate

curl -X POST https://app.getera.io/api/v1/creative_generations/CREATIVE_GENERATION_ID/actions/generate \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"higgsfield":{}}'

{
  "ok": true,
  "result": "…",
  "events": [
    "creative.requested"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.creativeGenerations.generate("CREATIVE_GENERATION_ID", {
  higgsfield: {}
})

era creative_generations generate CREATIVE_GENERATION_ID --data '{"higgsfield":{}}'

{
  "name": "era__creative__generate",
  "arguments": {
    "sourceGenerationId": "CREATIVE_GENERATION_ID",
    "higgsfield": {}
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold creative:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 empty_prompt, unknown_preset, needs_image, no_source, budget_exceeded, voice_not_ready · 429 slow down

creative.generate_batch

Make a batch — One template for many products, photos or lines at once (up to 20): "these 12 products on white", "a story for every dish on the menu". Each one is its own generation in one batch.

Needs creative:write · changes data

• Canonical address: POST /api/v1/actions/creative.generate_batch

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: creative.requested

What it writes: creative_generation (insert) — Queues one generation per line, sharing a batch

curl -X POST https://app.getera.io/api/v1/creative_generations/actions/generate_batch \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"items":{}}'

{
  "ok": true,
  "result": "…",
  "events": [
    "creative.requested"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.creativeGenerations.generateBatch({
  items: {}
})

era creative_generations generate_batch --data '{"items":{}}'

{
  "name": "era__creative__generate_batch",
  "arguments": {
    "items": {}
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold creative:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 empty_batch, batch_too_big, unknown_preset, empty_prompt, needs_image, no_source, budget_exceeded · 429 slow down

creative.generate_set

Product photo studio: make a set — One photo of a product becomes a set of shots, each made separately so the product stays the product: clean (on white), angles (front · three-quarter · side · back), lifestyle (three scenes for your sector) or listing (main on white · angle · detail · in use, cut for Trendyol or Hepsiburada).

Needs creative:write · changes data

• Canonical address: POST /api/v1/actions/creative.generate_set

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: creative.requested

What it writes: creative_generation (insert) — Queues one generation per shot, sharing a batch

curl -X POST https://app.getera.io/api/v1/creative_generations/actions/generate_set \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"set":"Set"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "creative.requested"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.creativeGenerations.generateSet({
  set: "Set"
})

era creative_generations generate_set \
  --set "Set"

{
  "name": "era__creative__generate_set",
  "arguments": {
    "set": "Set"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold creative:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 unknown_set, needs_image, no_source, budget_exceeded · 429 slow down

creative.mark_post

Record a post’s progress — scheduled → posting → posted / failed. Machine-only.

Needs creative:handle · changes data

• Canonical address: POST /api/v1/actions/creative.mark_post

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: creative.posted, creative.post_failed

What it writes: creative_post (update) — Moves the post forward; creative_generation (update) — Adds "used on <channel>"

Errors: 401 no or expired credential · 403 the credential does not hold creative:handle · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_open · 429 slow down

creative.note_provider_job

Record the provider job — Persists a MuAPI request before polling so recovery never submits it twice. Machine-only.

Needs creative:handle · changes data

• Canonical address: POST /api/v1/actions/creative.note_provider_job

Input

Preconditions

The action is refused with 409 and one of these codes:

What it writes: creative_generation (update) — Saves the provider request id

Errors: 401 no or expired credential · 403 the credential does not hold creative:handle · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_running · 429 slow down

creative.park_generation

Wait for the owner’s computer — Parks a generation that runs on a person’s own plan until their computer is back. Machine-only.

Needs creative:handle · changes data

• Canonical address: POST /api/v1/actions/creative.park_generation

Input

Preconditions

The action is refused with 409 and one of these codes:

What it writes: creative_generation (update) — running → waiting

Errors: 401 no or expired credential · 403 the credential does not hold creative:handle · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_running, bad_waiting · 429 slow down

creative.record_use

Record where a result was used — Remembers that a result went onto a product, a post, an email or the website.

Needs creative:write · changes data

• Canonical address: POST /api/v1/actions/creative.record_use

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: creative.used

What it writes: creative_generation (update) — Appends the use

curl -X POST https://app.getera.io/api/v1/creative_generations/CREATIVE_GENERATION_ID/actions/record_use \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"target":"Used on"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "creative.used"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.creativeGenerations.recordUse("CREATIVE_GENERATION_ID", {
  target: "Used on"
})

era creative_generations record_use CREATIVE_GENERATION_ID \
  --target "Used on"

{
  "name": "era__creative__record_use",
  "arguments": {
    "id": "CREATIVE_GENERATION_ID",
    "target": "Used on"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold creative:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_found, bad_target · 429 slow down

creative.remove

Remove from history — Takes a finished generation off the history. Its files stay in the Files library.

Needs creative:delete · removes or cannot be undone · asks a person to confirm when Era runs it

• Canonical address: POST /api/v1/actions/creative.remove

Input

Preconditions

The action is refused with 409 and one of these codes:

What it writes: creative_generation (delete) — Deletes the history row

curl -X POST https://app.getera.io/api/v1/creative_generations/CREATIVE_GENERATION_ID/actions/remove \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

{
  "ok": true,
  "result": "…",
  "events": []
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.creativeGenerations.remove("CREATIVE_GENERATION_ID")

era creative_generations remove CREATIVE_GENERATION_ID

{
  "name": "era__creative__remove",
  "arguments": {
    "id": "CREATIVE_GENERATION_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold creative:delete · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_found · 429 slow down

creative.remove_ad

Remove from the ad library — Takes an ad out of the library.

Needs creative:delete · removes or cannot be undone

• Canonical address: POST /api/v1/actions/creative.remove_ad

Input

Preconditions

The action is refused with 409 and one of these codes:

What it writes: creative_ad (delete) — Deletes the ad

curl -X POST https://app.getera.io/api/v1/creative_ads/CREATIVE_AD_ID/actions/remove_ad \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

{
  "ok": true,
  "result": "…",
  "events": []
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.creativeAds.removeAd("CREATIVE_AD_ID")

era creative_ads remove_ad CREATIVE_AD_ID

{
  "name": "era__creative__remove_ad",
  "arguments": {
    "id": "CREATIVE_AD_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold creative:delete · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_found · 429 slow down

creative.remove_voice

Remove a voice — Deletes a cloned voice (also at the provider).

Needs creative:delete · removes or cannot be undone · asks a person to confirm when Era runs it

• Canonical address: POST /api/v1/actions/creative.remove_voice

Input

Preconditions

The action is refused with 409 and one of these codes:

What it writes: creative_voice (delete) — Deletes the voice

curl -X POST https://app.getera.io/api/v1/creative_voices/CREATIVE_VOICE_ID/actions/remove_voice \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

{
  "ok": true,
  "result": "…",
  "events": []
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.creativeVoices.removeVoice("CREATIVE_VOICE_ID")

era creative_voices remove_voice CREATIVE_VOICE_ID

{
  "name": "era__creative__remove_voice",
  "arguments": {
    "id": "CREATIVE_VOICE_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold creative:delete · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_found · 429 slow down

creative.resume_provider

Check the provider result again — Polls the saved MuAPI job again, without purchasing another generation.

Needs creative:write · changes data

• Canonical address: POST /api/v1/actions/creative.resume_provider

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: creative.requested

What it writes: creative_generation (update) — Requeues polling of the saved provider job

curl -X POST https://app.getera.io/api/v1/creative_generations/CREATIVE_GENERATION_ID/actions/resume_provider \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

{
  "ok": true,
  "result": "…",
  "events": [
    "creative.requested"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.creativeGenerations.resumeProvider("CREATIVE_GENERATION_ID")

era creative_generations resume_provider CREATIVE_GENERATION_ID

{
  "name": "era__creative__resume_provider",
  "arguments": {
    "id": "CREATIVE_GENERATION_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold creative:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_found · 429 slow down

creative.save_ad

Save an ad to the library — Keeps an ad you like (from the Meta Ad Library, a link or a screenshot) so Creative Studio can make one like it for your product.

Needs creative:write · changes data

• Canonical address: POST /api/v1/actions/creative.save_ad

Input

Preconditions

The action is refused with 409 and one of these codes:

What it writes: creative_ad (upsert) — Adds (or refreshes) the ad in the library

curl -X POST https://app.getera.io/api/v1/creative_ads/actions/save_ad \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"source":"From","title":"Name"}'

{
  "ok": true,
  "result": "…",
  "events": []
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.creativeAds.saveAd({
  source: "From",
  title: "Name"
})

era creative_ads save_ad \
  --source "From" \
  --title "Name"

{
  "name": "era__creative__save_ad",
  "arguments": {
    "source": "From",
    "title": "Name"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold creative:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 bad_source, empty_title · 429 slow down

creative.save_brand_kit

Save the brand kit — Name, colours, fonts, logo and tone of voice — Creative Studio adds them to every generation unless you switch it off for one.

Needs creative:write · changes data

• Canonical address: POST /api/v1/actions/creative.save_brand_kit

Input

Preconditions

The action is refused with 409 and one of these codes:

What it writes: creative_brand_kit (upsert) — Writes the one brand kit of the workspace

curl -X POST https://app.getera.io/api/v1/creative_brand_kits/actions/save_brand_kit \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"name":"Brand name"}'

{
  "ok": true,
  "result": "…",
  "events": []
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.creativeBrandKits.saveBrandKit({
  name: "Brand name"
})

era creative_brand_kits save_brand_kit \
  --name "Brand name"

{
  "name": "era__creative__save_brand_kit",
  "arguments": {
    "name": "Brand name"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold creative:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 empty_name, bad_colour, unknown_sector · 429 slow down

creative.save_caption

Save the post text — Keeps the caption and hashtags that go with a result, for posting and sharing.

Needs creative:write · changes data

• Canonical address: POST /api/v1/actions/creative.save_caption

Input

Preconditions

The action is refused with 409 and one of these codes:

What it writes: creative_generation (update) — Sets the caption

curl -X POST https://app.getera.io/api/v1/creative_generations/CREATIVE_GENERATION_ID/actions/save_caption \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"text":"Text"}'

{
  "ok": true,
  "result": "…",
  "events": []
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.creativeGenerations.saveCaption("CREATIVE_GENERATION_ID", {
  text: "Text"
})

era creative_generations save_caption CREATIVE_GENERATION_ID \
  --text "Text"

{
  "name": "era__creative__save_caption",
  "arguments": {
    "id": "CREATIVE_GENERATION_ID",
    "text": "Text"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold creative:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 empty_caption, not_found · 429 slow down

creative.schedule_post

Post to social media — Posts a Creative Studio result (or files) to an Instagram, Facebook, TikTok or YouTube account now or at a time. Always asks before posting.

Needs creative:write · reaches outside (sends, publishes or charges) · asks a person to confirm when Era runs it

• Canonical address: POST /api/v1/actions/creative.schedule_post

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: creative.post_scheduled

What it writes: creative_post (insert) — A scheduled post; the studio posts it when it is due

curl -X POST https://app.getera.io/api/v1/creative_posts/actions/schedule_post \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"channel":"Where","connectionId":"CONNECTION_ID"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "creative.post_scheduled"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.creativePosts.schedulePost({
  channel: "Where",
  connectionId: "CONNECTION_ID"
})

era creative_posts schedule_post \
  --channel "Where" \
  --connection-id "CONNECTION_ID"

{
  "name": "era__creative__schedule_post",
  "arguments": {
    "channel": "Where",
    "connectionId": "CONNECTION_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold creative:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 bad_channel, not_ready, nothing_to_post, wrong_media, no_connection, bad_time · 429 slow down

creative.set_favourite

Favourite — Stars a generation so it is easy to find again.

Needs creative:write · changes data

• Canonical address: POST /api/v1/actions/creative.set_favourite

Input

Preconditions

The action is refused with 409 and one of these codes:

What it writes: creative_generation (update) — Sets the star

curl -X POST https://app.getera.io/api/v1/creative_generations/CREATIVE_GENERATION_ID/actions/set_favourite \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"favourite":true}'

{
  "ok": true,
  "result": "…",
  "events": []
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.creativeGenerations.setFavourite("CREATIVE_GENERATION_ID", {
  favourite: true
})

era creative_generations set_favourite CREATIVE_GENERATION_ID \
  --favourite true

{
  "name": "era__creative__set_favourite",
  "arguments": {
    "id": "CREATIVE_GENERATION_ID",
    "favourite": true
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold creative:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_found · 429 slow down

creative.start_generation

Start a generation — Claims a queued generation for the worker that will make it. Machine-only.

Needs creative:handle · changes data

• Canonical address: POST /api/v1/actions/creative.start_generation

Input

Preconditions

The action is refused with 409 and one of these codes:

What it writes: creative_generation (update) — queued → running

Errors: 401 no or expired credential · 403 the credential does not hold creative:handle · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_queued · 429 slow down

creative.vary

More like this — New takes on a finished picture: the same subject and product, a fresh composition, angle and light. 1–4 at a time.

Needs creative:write · changes data

• Canonical address: POST /api/v1/actions/creative.vary

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: creative.requested

What it writes: creative_generation (insert) — Queues the variations

curl -X POST https://app.getera.io/api/v1/creative_generations/CREATIVE_GENERATION_ID/actions/vary \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"count":1}'

{
  "ok": true,
  "result": "…",
  "events": [
    "creative.requested"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.creativeGenerations.vary("CREATIVE_GENERATION_ID", {
  count: 1
})

era creative_generations vary CREATIVE_GENERATION_ID \
  --count 1

{
  "name": "era__creative__vary",
  "arguments": {
    "id": "CREATIVE_GENERATION_ID",
    "count": 1
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold creative:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_found, no_source, budget_exceeded · 429 slow down

Data models

CreativeAd

Table creative_ad · Resource creative_ads

• GET /api/v1/creative_ads
• GET /api/v1/creative_ads/{id}

Primary key: id

CreativeBrandKit

Table creative_brand_kit · Resource creative_brand_kits

• GET /api/v1/creative_brand_kits
• GET /api/v1/creative_brand_kits/{id}

Primary key: id

Checks:

• CHECK (((array_length(colours, 1) IS NULL) OR (array_length(colours, 1) <= 8)))

CreativeGeneration

Table creative_generation · Resource creative_generations

• GET /api/v1/creative_generations
• GET /api/v1/creative_generations/{id}

Primary key: id

Checks:

• CHECK (((batch_kind IS NULL) OR (batch_kind = ANY (ARRAY['set'::text, 'batch'::text, 'variations'::text]))))
• CHECK (((batch_label IS NULL) OR (length(batch_label) <= 120)))
• CHECK (((count >= 1) AND (count <= 4)))
• CHECK (((edit_note IS NULL) OR (length(edit_note) <= 2000)))
• CHECK (((resolution IS NULL) OR (resolution = ANY (ARRAY['480p'::text, '720p'::text, '1080p'::text]))))
• CHECK (((source_kind IS NULL) OR (source_kind = ANY (ARRAY['native'::text, 'byos'::text, 'byok'::text])))) NOT VALID
• CHECK (((studio IS NULL) OR (studio = ANY (ARRAY['image'::text, 'video'::text, 'cinema'::text, 'character'::text, 'lipsync'::text, 'motion'::text, 'recast'::text, 'clip'::text, 'layers'::text, 'audio'::text, 'marketing'::text, 'product'::text]))))
• CHECK (((tool IS NULL) OR (tool = ANY (ARRAY['lip_sync'::text, 'talking_photo'::text, 'face_swap'::text, 'upscale'::text, 'video_edit'::text, 'layout'::text, 'photo_reel'::text, 'higgsfield'::text, 'image_grade'::text]))))
• CHECK (((upscale IS NULL) OR (upscale = ANY (ARRAY[2, 4]))))
• CHECK (((version >= 1) AND (version <= 999)))

CreativePost

Table creative_post · Resource creative_posts

• GET /api/v1/creative_posts
• GET /api/v1/creative_posts/{id}

Primary key: id

CreativeVoice

Table creative_voice · Resource creative_voices

• GET /api/v1/creative_voices
• GET /api/v1/creative_voices/{id}

Primary key: id

Checks:

• CHECK ((provider = 'elevenlabs'::text))
• CHECK (((source_kind IS NULL) OR (source_kind = 'byok'::text)))

Events

Workflows and webhooks react to these events.