Developer API

Overview

VisioArt exposes a developer-facing REST API for the same generation pipeline used by the product UI. API requests run against the caller's account, consume the same credit balance, and write the same generation records and usage events that appear in the dashboard.

Use the Developer API when you need to:

• discover the active model catalog, supported modes, and pricing evidence for your workspace
• create generations from your own application
• poll job status without scraping the dashboard
• download generated assets through a stable API route
• reconcile credit charges and refunds with your own backend

Base URL

Use your deployed VisioArt origin as the API base:

https://your-domain.com/api/v1

Authentication

Create API keys from Settings -> API Keys. Each key inherits the account's balance and scoped permissions.

API key creation is available to paid plans only.

You can send the key in either header:

Authorization: Bearer visioart_your_api_key

or

x-api-key: visioart_your_api_key

Do not send both headers in the same request unless the values are identical. Mixed credentials are rejected.

Credit Model

• API generations use the same credit wallet as the signed-in product experience.
• A generation is charged when the job is queued successfully.
• Failed or cancelled jobs refund credits automatically when the job transitions to a refundable final state.
• If the account balance is lower than the estimated cost, generation creation fails with 402 insufficient_credits.

Idempotency

POST /api/v1/generations requires an Idempotency-Key header.

Rules:

• Replaying the same body with the same key returns the original request result.
• Reusing the same key with a different request body returns 409 idempotency_conflict.
• The header accepts up to 200 characters and only allows A-Z a-z 0-9 . _ : -.

Example:

Idempotency-Key: 6d1d0f58-d65b-474a-8d1d-7a91fd8bd8dc

Response Shape

Successful JSON responses include a request identifier:

{
  "request_id": "38285b04-43a5-440f-8bb8-5e8c32e86920",
  "data": {}
}

Error responses use the same envelope:

{
  "request_id": "1f1f8258-ae62-4c65-8e06-f9633dc518df",
  "error": {
    "code": "insufficient_credits",
    "message": "Insufficient credits"
  }
}

The same value is also returned in the x-request-id response header.

Endpoints

List models and capabilities

curl -X GET "https://your-domain.com/api/v1/models" \
  -H "Authorization: Bearer visioart_your_api_key"

Response:

{
  "request_id": "2b4fa4fa-3419-4d92-95ad-d4d08a838bea",
  "data": {
    "object": "list",
    "total": 26,
    "items": [
      {
        "object": "model",
        "model_id": "qwen2",
        "display_name": "Qwen2",
        "availability": "active",
        "modes": [
          {
            "generator_mode": "text-to-image",
            "supported_aspect_ratios": ["16:9", "9:16", "1:1"],
            "supported_duration_seconds": [5],
            "supported_output_formats": ["png", "jpg"],
            "public_model_options": [],
            "pricing": {
              "variants": [
                {
                  "id": "default",
                  "request_model_options": null,
                  "credit_matrix": [
                    {
                      "aspect_ratio": "16:9",
                      "duration_seconds": 5,
                      "credits": 6,
                      "source_type": "legacy_exact_matrix",
                      "source_updated_at": "2026-04-22T11:09:35.262Z"
                    }
                  ]
                }
              ]
            }
          }
        ]
      }
    ]
  }
}

Model directory notes:

• The endpoint returns the workspace's currently active, enumerable models only. Unsupported or partially configured models are omitted instead of guessed.
• modes[*].public_model_options lists only option families that are currently valid on the public POST /generations schema and accepted by the business validation path.
• pricing.variants[*].request_model_options intentionally mirrors the modelOptions request payload shape from POST /generations, so you can copy the object directly.
• credit_matrix[*].source_type shows where each credit value came from: workspace_override, market_catalog, legacy_exact_matrix, or built_in_estimate.
• credit_matrix[*].source_updated_at is populated when the value came from a reviewed market catalog rule or the generated exact credit matrix. Override-backed or heuristic rows may return null.

Read credit balance

curl -X GET "https://your-domain.com/api/v1/credits/balance" \
  -H "Authorization: Bearer visioart_your_api_key"

Response:

{
  "request_id": "38285b04-43a5-440f-8bb8-5e8c32e86920",
  "data": {
    "balance": 1000,
    "unit": "credits"
  }
}

Create a generation

curl -X POST "https://your-domain.com/api/v1/generations" \
  -H "Authorization: Bearer visioart_your_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6d1d0f58-d65b-474a-8d1d-7a91fd8bd8dc" \
  -d '{
    "title": "veo31-fast text-to-video",
    "modelId": "veo31-fast",
    "generatorMode": "text-to-video",
    "prompt": "A clean product reveal with cinematic camera movement",
    "aspectRatio": "16:9",
    "durationSeconds": 8,
    "uploads": []
  }'

Response:

{
  "request_id": "d587724c-df59-4333-9d4a-2ce8d2988466",
  "idempotent_replay": false,
  "data": {
    "id": "9a87675c-1e1a-4b16-873c-19ffd8e79cdc",
    "object": "generation",
    "status": "processing",
    "title": "veo31-fast text-to-video",
    "model_id": "veo31-fast",
    "generator_mode": "text-to-video",
    "prompt": "A clean product reveal with cinematic camera movement",
    "aspect_ratio": "16:9",
    "duration_seconds": 8,
    "output_format": null,
    "estimated_credits": 30,
    "error_message": null,
    "result_url": null,
    "outputs": [],
    "queued_at": "2026-04-05T13:27:59.824Z",
    "completed_at": null,
    "created_at": "2026-04-05T13:27:59.824Z",
    "updated_at": "2026-04-05T13:28:01.903Z"
  }
}

Request body rules:

• The public create-generation schema is strict. Unknown or internal-only fields are rejected with 400 invalid_request.
• uploads only accepts objects shaped like { "kind": "...", "url": "https://..." }.
• Each upload url must already point to a trusted remote asset URL from workspace storage or a trusted provider-hosted origin.
• modelOptions, when provided, must only use public option families that apply to the selected modelId. Irrelevant or unknown nested option fields are rejected.
• imageCount, when present inside modelOptions, is only accepted on models whose /models entry exposes public_model_options[].path = "modelOptions.imageCount"; pricing variants show the exact credit cost before submission.
• Omit empty no-op objects such as modelOptions: {} or modelOptions: { "kling30": {} }.
• Do not send internal fields such as landingRecordId, landingKind, landingPathname, estimatedCredits, storagePath, fileName, or required.

Generation response fields:

Generation output object (outputs[i]):

Read a generation

curl -X GET "https://your-domain.com/api/v1/generations/9a87675c-1e1a-4b16-873c-19ffd8e79cdc" \
  -H "Authorization: Bearer visioart_your_api_key"

Cancel a generation

curl -X POST "https://your-domain.com/api/v1/generations/9a87675c-1e1a-4b16-873c-19ffd8e79cdc/cancel" \
  -H "Authorization: Bearer visioart_your_api_key"

Cancellation is only available while the job is still in VisioArt's local queue and has not started upstream submission yet.

In practice, that means the job must still be queued, must not have a provider task ID yet, and must not already be claimed by a worker for submission.

If cancellation succeeds, the job transitions to cancelled and writes a refund event for the previously charged credits.

Once a job has started the upstream submission flow, the API returns 409 generation_not_cancellable. This avoids promising a cancellation that the upstream provider may not actually support.

Read usage events

curl -X GET "https://your-domain.com/api/v1/usage?limit=20&offset=0" \
  -H "Authorization: Bearer visioart_your_api_key"

Query parameters:

Response envelope:

{
  "request_id": "…",
  "data": {
    "items": [
      {
        "id": "…",
        "api_request_id": "…",
        "api_key_id": "…",
        "generation_job_id": "…",
        "credit_transaction_id": "…",
        "event_type": "charge",
        "credits_delta": -20,
        "balance_before": 1000,
        "balance_after": 980,
        "pricing_snapshot": "{\"schemaVersion\":1,\"modelId\":\"veo31-fast\",\"generatorMode\":\"text-to-video\",\"aspectRatio\":\"16:9\",\"durationSeconds\":8,\"modelOptions\":null,\"variantKey\":null,\"credits\":20,\"listCredits\":20,\"hasPromotion\":false,\"promotionLabel\":null,\"promotionStartsAt\":null,\"promotionEndsAt\":null,\"sourceType\":\"market_catalog\",\"sourceUpdatedAt\":\"2026-05-15\"}",
        "note": null,
        "created_at": "2026-04-05T13:27:59.824Z"
      }
    ],
    "pagination": { "limit": 20, "offset": 0, "total": 137 }
  }
}

Usage item fields:

The pagination.total field reflects the total number of events matching the query, not the current page.

Download an asset

curl -L "https://your-domain.com/api/v1/assets/510522c3-f7fb-4265-82ae-471f12aea62b" \
  -H "Authorization: Bearer visioart_your_api_key" \
  -o output.mp4

Common Error Codes

VisioArt validates generation requests in two layers:

• Schema layer (400 invalid_request) — Shape, type, and format checks. Unknown fields, wrong types, values outside the declared enums or lengths, or internal-only keys (for example landingRecordId, estimatedCredits) are rejected here before any business logic runs.
• Business layer (422 invalid_generation_request) — Semantic checks that depend on workspace state or the resolved model capability. A well-formed request can still fail here if the modelId is not active in the workspace, the combination of modelId × generatorMode × aspectRatio × durationSeconds is not supported, a required upload is missing, an upload URL is not trusted, or the resolved pricing rule is missing.

The set of active models and their supported options is workspace-scoped and can be overridden by administrators, so there is no hard-coded modelId enum on the public schema. Read GET /api/v1/models before large batch submissions or treat 422 invalid_generation_request as a retryable intent to fix input.

Endpoint-Specific Error Notes

Model directory

• 500 models_read_failed

Generation creation

• 400 invalid_request
• 402 insufficient_credits
• 409 idempotency_conflict
• 429 concurrent_job_limit
• 422 invalid_generation_request
• 500 request_state_invalid
• 503 provider_unavailable
• 500 generation_create_failed

Generation read

• 400 invalid_generation_id
• 404 generation_not_found
• 500 generation_read_failed

Generation cancel

• 400 invalid_generation_id
• 404 generation_not_found
• 409 generation_not_cancellable
• 500 generation_cancel_failed

Billing Edge Cases

• 402 insufficient_credits is returned before a new generation job is inserted. No generation ID is created, no credit charge is written, and no refund event is needed.
• Refunds are only written when a previously charged job transitions to failed or to a safely cancellable cancelled state.
• Job status transition, refund ledger mutation, developer API refunded counters, and refund usage events are persisted in the same database transaction. If any local refund persistence step fails, VisioArt rolls the transition back instead of leaving a partial refund state behind.

Credit balance

• 500 credits_read_failed

Usage list

• 400 invalid_query
• 500 usage_read_failed

Asset read

• 400 invalid_asset_id
• 404 asset_not_found
• 500 asset_read_failed

Permission Scopes

New API keys receive these default scopes:

{
  "generation": ["create", "read", "cancel"],
  "credits": ["read"],
  "usage": ["read"],
  "assets": ["read"],
  "models": ["read"]
}

If a key was created before scoped permissions existed, VisioArt preserves backward compatibility and still allows requests unless the key is explicitly restricted later. If a key carries an explicit permissions payload, VisioArt enforces that payload as-is; backward compatibility only applies to legacy keys that predate scoped permissions and therefore have no stored permissions field.

Operational Notes

• The asset URL inside a generation response points to the VisioArt API asset route, not to the raw provider URL.
• Refunds are written to both the user credit ledger and the developer API usage log.
• Credit charges and refunds are part of the same database lifecycle as the generation state transition, which prevents partial refund states where balance changes but job status does not.