Full API Reference

Body Fields

Request Example Body

{
  "grant_type": "client_credentials",
  "client_id": "gfo_oauth_123",
  "client_secret": "gfs_live_secret",
  "scope": "models:read runs:read images:write"
}

Notes

• You can also send `client_id:client_secret` with HTTP Basic auth instead of putting them in JSON.
• The returned access token is used in the same `Authorization: Bearer ...` header as an API key.

Body Fields

Request Example Body

{
  "client_id": "genfire-cli",
  "code_challenge": "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM",
  "code_challenge_method": "S256",
  "scopes": [
    "account:read",
    "credits:read",
    "models:read",
    "runs:read",
    "images:write",
    "videos:write",
    "uploads:write"
  ],
  "label": "genfire-cli (laptop)"
}

Notes

• Sessions expire after 10 minutes if not approved.
• Poll `GET /cli/auth/sessions/{sessionId}` to discover when the user has approved (or denied) the session.

Parameters

Body Fields

No body fields for this endpoint.

Notes

• Status transitions: `pending` → `approved` (or `denied`) → `consumed` (after exchange).
• A `consumed` or `expired` status means the CLI must restart the login flow.

Parameters

Body Fields

Request Example Body

{
  "code_verifier": "M25iVXpKU3puUjFaYWg3T1NDTDQtcW1ROUY5YXlwalNoc0hhakxifmZHag"
}

Notes

• The `api_key` is returned exactly once. Store it securely (the CLI uses the OS keychain).
• Sessions are single-use. Once exchanged, the same session cannot be exchanged again.
• A 428 response means the user has not yet approved the session — keep polling.
• A 410 response means the session expired or was already exchanged. Restart the CLI login.

Body Fields

No body fields for this endpoint.

Body Fields

No body fields for this endpoint.

Body Fields

No body fields for this endpoint.

Body Fields

No body fields for this endpoint.

Notes

• Unit values: `per_image` (image models, max 4 per request), `per_second` (video / music / SFX / lipsync), `per_character` (speech).
• Some video models add a multiplier when `generate_audio=true`. Check the `notes` field on each entry.

Parameters

Body Fields

No body fields for this endpoint.

Notes

• Cloned voices are scoped to the authenticated account — you only ever see your own.
• Stock voices are large and account-global, so they are excluded unless `include=stock` is passed.

Parameters

Body Fields

No body fields for this endpoint.

Notes

• Buckets are sorted by `credits_spent` descending, except `group_by=day` which is sorted chronologically.
• Counts only include runs that hit `/v1` endpoints. Dashboard generations and workflow runs initiated outside the public API are not included.

Body Fields

Request Example Body

{
  "filename": "reference.png",
  "content_type": "image/png",
  "size_bytes": 124000
}

Notes

• PUT the file bytes to `upload_url` within 15 minutes. The signed URL is pinned to the `content_type` you submitted — sending a different `Content-Type` header will be rejected by the storage layer.
• `asset_url` is a 7-day signed READ URL. Re-upload the asset before this point if you need long-lived references.
• Maximum upload size is 5 GB.

Body Fields

No body fields for this endpoint.

Notes

• Drafts and archived influencers are NOT returned. Train and finalize them in the dashboard before they can be referenced.

Parameters

Body Fields

No body fields for this endpoint.

Notes

• 404 if the influencer does not exist or is not owned by the authenticated account.

Parameters

Body Fields

No body fields for this endpoint.

Parameters

Body Fields

No body fields for this endpoint.

Parameters

Body Fields

No body fields for this endpoint.

Body Fields

Request Example Body

{
  "prompt": "Studio product photo of a matte black water bottle on dark stone",
  "model": "image.nano_banana_2",
  "aspect_ratio": "1:1",
  "count": 1
}

Notes

• When `mentions` is supplied: the model must have an internal edit variant (most do — see `/models`). The server resolves the influencer, replaces `@<handle>` in the prompt with `the character`, appends an identity directive, and adds up to four reference images as conditioning.
• Influencers must be in status `ready`. Drafts and archived ones cannot be referenced.

Body Fields

Request Example Body

{
  "prompt": "Cinematic close-up of a luxury watch with soft lighting",
  "model": "video.veo_3_1",
  "aspect_ratio": "16:9",
  "duration": 8,
  "generate_audio": true
}

Notes

• Poll `GET /runs/{runId}` until the run moves to `completed` or `failed`.
• Per-model duration / aspect-ratio / resolution limits are returned by `/models`; passing an unsupported value returns a 400 listing the allowed values.
• If you provide an input combination the model does not declare in `capabilities`, you get `unsupported_input_combination`.

Body Fields

Request Example Body

{
  "image_url": "https://example.com/photo.jpg"
}

Body Fields

Request Example Body

{
  "source_video_url": "https://cdn.genfire.ai/video.mp4",
  "scale_factor": 2
}

Notes

• Costs more credits than generation per-second, scaled by the scale factor.
• Poll `GET /runs/{runId}` until status is `completed` or `failed`.

Body Fields

Request Example Body

{
  "video_url": "https://example.com/source-video.mp4",
  "audio_url": "https://example.com/source-audio.mp3",
  "sync_mode": "cut_off",
  "model": "lipsync.lipsync_2_pro"
}

Notes

• Provide either `audio_url` or `audio_base64`.
• This endpoint is async and usually returns a queued run first.

Body Fields

Request Example Body

{
  "text": "Introducing the new GenFire creative workflow.",
  "voice_id": "voice_abc123",
  "model": "speech.elevenlabs_turbo_v2_5"
}

Body Fields

Request Example Body

{
  "prompt": "Confident electronic music bed for a product launch video",
  "model": "music.elevenlabs_music_v1",
  "duration_seconds": 30,
  "include_details": false
}

Body Fields

Request Example Body

{
  "prompt": "Heavy metal door slam in a large warehouse",
  "model": "sfx.elevenlabs_v1",
  "duration_seconds": 4
}

Body Fields

Request Example Body

{
  "audio_url": "https://cdn.genfire.ai/uploads/interview.mp3",
  "model": "transcription.whisper_v1"
}

Notes

• Max media size 500MB; max duration 2 hours.
• Async — usually returns a queued run first; poll the run until `status` is `completed`, then read `output.text` / `output.words` / `output.segments`.
• YouTube transcription is supported but downloads third-party content — ensure your use complies with the source platform’s terms.

Body Fields

Request Example Body

{
  "url": "https://example.com/products/matte-black-water-bottle"
}

Notes

• Unsafe or private-network targets are rejected before scraping begins.

Body Fields

No body fields for this endpoint.

Parameters

Body Fields

No body fields for this endpoint.

Parameters

Body Fields

Request Example Body

{
  "prompt": "Portable blender for busy professionals",
  "audience": "Remote workers who skip breakfast",
  "tone": "persuasive",
  "length": "short",
  "target_duration": 20,
  "keywords": [
    "protein shake",
    "commute",
    "healthy"
  ],
  "additional_requirements": "Lead with convenience and save time."
}

Notes

• The workflow catalog below includes example payloads for every supported workflow.

Parameters

Body Fields

No body fields for this endpoint.

Parameters

Body Fields

No body fields for this endpoint.

Parameters

Body Fields

No body fields for this endpoint.

Body Fields

Request Example Body

{
  "mode": "workflow",
  "target": "hook_pack",
  "concurrency": 2,
  "items": [
    {
      "input": {
        "prompt": "Portable blender for busy professionals"
      }
    },
    {
      "input": {
        "prompt": "Portable blender for college students"
      }
    }
  ]
}

Notes

• Current operation batches support `images.generations.create` and `videos.generations.create`.
• Workflow batches support any workflow listed by `GET /workflows`.
• Items in `operation`-mode batches accept the same body fields as the operation `target` — e.g. `quality` and `resolution` are honored when batching `images.generations.create`.

Body Fields

No body fields for this endpoint.

Parameters

Body Fields

No body fields for this endpoint.

Body Fields

Request Example Body

{
  "url": "https://example.com/webhooks/genfire",
  "description": "Agency production endpoint",
  "events": [
    "run.completed",
    "run.failed"
  ]
}

Notes

• Store the signing secret immediately. It is only returned when the endpoint is created.

Parameters

Body Fields

No body fields for this endpoint.

Parameters

Body Fields

Request Example Body

{
  "status": "disabled"
}

Parameters

Body Fields

No body fields for this endpoint.