> ## Documentation Index > Fetch the complete documentation index at: https://docs.tryflowy.ai/llms.txt > Use this file to discover all available pages before exploring further. # Start a generation > Generate an image or video directly. Bills the key's wallet, or an explicit workspace. The generation starts asynchronously and returns a `generationId` immediately. Poll [Get a generation](/api/get-generation) until its `status` is `completed`, then read `outputs[0].url`. By default the generation is billed to the key's own wallet — for account-bound keys, your **account wallet**. Pass `workspace_id` (see [List workspaces](/api/list-workspaces)) to act in and bill another workspace you can manage. ## OpenAPI ````yaml api-reference/openapi.json POST /v1/generations openapi: 3.0.3 info: title: Flowy App API version: 1.3.1 description: >- Run Flowy apps and direct generations programmatically. Authenticate with a workspace API key in the `Authorization: Bearer` header. A **secret** key (`flowy_…`) is for servers; a **publishable** key (`flowy_pk_…`) is browser-safe and only works from its allowlisted domains. Every run or generation bills the API key's own workspace credits (caller-pays), so a leaked key can never spend another workspace's balance. Keys carry **scopes**: `apps:read` (list/inspect apps), `runs:read` (poll runs), `runs:write` (start runs), `generations:read` (poll direct generations), `generations:write` (start direct generations), `assets:read` (list/read workspace assets), and `credits:read` (read the credit balance). A request that needs a scope the key doesn't hold returns `403`. A published (public) app is runnable by any key; a private app is runnable only by a key of its own workspace. servers: - url: https://apis.tryflowy.ai/genstudio-svc-v2/api description: Flowy production API security: - ApiKeyAuth: [] tags: - name: Apps description: Discover apps and inspect their input/output schema. - name: Runs description: Start runs and poll for their results. - name: Generations description: Start direct image/video generations and poll for their results. - name: Assets description: Browse the workspace's asset library (uploads + generated media). - name: Credits description: Read the workspace's credit balance. - name: Spec description: The machine-readable OpenAPI document. paths: /v1/generations: post: tags: - Generations summary: Start a generation description: >- Starts an asynchronous image or video generation, billed to the key's workspace. Returns immediately with a `generationId` — poll `GET /v1/generations/{generationId}` for the result. Completed outputs are also recorded in the workspace asset library. **Requires the `generations:write` scope.** operationId: startGeneration requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/GenerationRequest' properties: workspace_id: type: string description: >- Optionally bill a different workspace the account can manage; default is the key's own wallet. mode: type: string enum: - sfx - music description: Audio only; default sfx geometry_format: type: string enum: - glb - usdz - fbx - obj - stl description: 3d only; default glb material: type: string enum: - All - PBR - Shaded description: 3d only; default All example: type: image prompt: a studio photo of a ceramic mug on a marble counter aspect_ratio: '1:1' resolution: 1K responses: '202': description: Generation accepted. Poll GET /v1/generations/{generationId}. headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/json: schema: $ref: '#/components/schemas/GenerationAccepted' '400': description: >- Invalid request (unknown type/model, bad aspect ratio or resolution, bad input media) content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/Error' '402': description: Daily spend cap reached or insufficient workspace credits content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: The key lacks the generations:write scope content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: Rate limit or concurrency limit exceeded headers: Retry-After: $ref: '#/components/headers/Retry-After' content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: GenerationRequest: type: object required: - type - prompt properties: type: type: string enum: - image - video example: image prompt: type: string example: a studio photo of a ceramic mug on a marble counter model: type: string description: 'image: gemini-3-flash (default). video: seedance-2.0 (default).' example: gemini-3-flash input_media: type: array description: >- Optional reference media: an asset from your workspace library (asset_id) or a public URL. Video generations accept up to 9 images, 3 videos and 3 audio references (12 total). items: type: object properties: asset_id: type: string example: 64c3f2a1e8b9c0d1f2e3a4b5 url: type: string example: https://example.com/reference.jpg aspect_ratio: type: string description: >- image: 1:1 (default), 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9. video: 16:9 (default), 9:16, 1:1. example: '1:1' resolution: type: string description: 'image: 1K (default), 2K, 4K. video: 720p (default), 1080p.' example: 1K duration_seconds: type: number description: Video only. Default 5; clamped to 4–10. example: 5 GenerationAccepted: type: object properties: data: type: object properties: generationId: type: string example: 64c3f2a1e8b9c0d1f2e3a4b5 status: type: string enum: - processing example: processing type: type: string enum: - image - video example: image model: type: string example: gemini-3-flash estimatedCredits: type: number description: >- Credits reserved for this generation; the settled charge arrives on the generation view. example: 12 Error: type: object properties: error: type: string example: this API key lacks the runs:write scope required: - error headers: X-RateLimit-Limit: description: Maximum requests allowed in the current window (per minute). schema: type: integer example: 60 X-RateLimit-Remaining: description: Requests remaining in the current window. schema: type: integer example: 59 X-RateLimit-Reset: description: Unix epoch second at which the current window resets. schema: type: integer example: 1893456000 Retry-After: description: Seconds to wait before retrying (sent on 429). schema: type: integer example: 12 securitySchemes: ApiKeyAuth: type: http scheme: bearer bearerFormat: flowy_* description: >- A workspace API key. Secret keys (`flowy_…`) are server-side — keep them private. Publishable keys (`flowy_pk_…`) are browser-safe but only work from their allowlisted domains. ````