Skip to content
GFlow4AI
VIGet for Windows
Guide/Connect AI agents

REST API reference

Technical referenceUpdated 2026-11-04Try the web sample

Inspect real routes, authenticate locally, submit idempotently and retrieve your own results.

Local API address
Local API address · Real app screen with web sample data · App labels are currently in Vietnamese

Before you start

  • Use a same-PC script or HTTP client, not a web page or cloud connector.
  • Enable the desktop server and prepare a key with the scopes your workflow needs.

Steps

  1. Check health and the live schema

    Use the current base URL from Settings. GET /v1/health and GET /v1/openapi.json do not need a key, but still enforce Origin/Host checks. All other REST routes below require a bearer key.

    curl.exe http://127.0.0.1:47831/v1/status -H "Authorization: Bearer <your local API key>"

  2. Use only implemented routes

    • GET /v1/health — health, no key required.
    • GET /v1/openapi.json — OpenAPI 3.1, no key required.
    • GET /v1/status
    • GET /v1/models
    • GET /v1/voices
    • GET /v1/characters
    • POST /v1/characters
    • PATCH /v1/characters/{id}
    • POST /v1/references
    • POST /v1/jobs
    • GET /v1/jobs
    • GET /v1/jobs/{id}
    • GET /v1/jobs/{id}/wait
    • POST /v1/jobs/{id}/cancel
    • POST /v1/outputs/{id}/extend
    • POST /v1/outputs/{id}/edit
    • POST /v1/outputs/{id}/upscale
    • GET /v1/outputs/{id}/content
    • HEAD /v1/outputs/{id}/content

    Replace {id} with the relevant character, job or output identifier. Read operations need read; reference uploads, job submission, cancellation and output follow-ups need generate; character writes need characters. /mcp is the separate MCP transport, not a REST operation.

  3. Prepare references and submit once

    Read /v1/models before choosing a model and job fields from OpenAPI. Send JSON with Content-Type: application/json. POST /v1/jobs and output extend/edit/upscale require Idempotency-Key (1–200 visible ASCII characters). Keep that key and identical body on retry: replay returns the same job, while different content with the same key returns 409. New work returns 201; a replay returns 200 with idempotent-replayed: true.

    Upload references as raw media bytes to /v1/references, not JSON file paths. Video requires X-Rights-Confirmed: true; optional X-File-Name supplies a name.

  4. Wait, paginate and download

    Use GET /v1/jobs/{id}/wait?timeout=50; timeout is clamped to 0–50 seconds (default 30). Inspect x-wait-result and the returned job; a wait timeout is not job failure. Wait again on the same job until done, failed or cancelled.

    GET /v1/jobs?limit=20&cursor=… returns newest first with nextCursor; the maximum page size is 100. Download your own output with GET content; HEAD reads headers and single byte ranges are supported.

  5. Handle errors without duplicate spending

    REST errors use application/problem+json with code, detail and optional field errors. Resolve 401 credentials, 403 scope/Origin, 404 ownership or missing resource, 409 conflict, 422 field validation, and 429 rate/cap separately. Honour Retry-After for rate limiting. Never create a replacement generation merely because waiting or downloading failed.

When it worked

Your client reads the schema, submits one idempotent job, waits by ID and downloads a key-owned output.

If something goes wrong

Why is a job visible in the app but 404 through my key?

Keys can only access their own jobs, outputs and references, not UI jobs or another key’s resources.

Why does retry return 409?

Check the problem code. idempotency_conflict means the same idempotency key was reused with different content; restore the original request rather than blindly generating a new key.