API implementation notes
Krea 2 API controls need a durable product boundary.
Krea2 currently submits Krea 2 Medium and Large through Fal’s production queue. The product preserves prompt, model, creativity, aspect ratio, reference URLs, provider request ID, credit state, and output outside the browser request. This guide explains that implementation pattern without presenting Krea2 as the official Krea API.
Field note
Updated 2026-07-21
Independent Krea 2 resource
Direct answer
How does the Krea 2 API workflow operate?
A Krea 2 API workflow submits a prompt and controls to a hosted model endpoint, stores the returned request identifier, polls or receives completion asynchronously, and persists the final image. Production integrations should make credit debits, retries, and refunds idempotent so a browser refresh or duplicate callback cannot lose work or charge twice.
Key takeaways
- Use Medium and Large as explicit product choices.
- Validate every public request before it reaches the provider.
- Persist provider request IDs before polling for completion.
- Keep credit debit and failure refund logic idempotent.
- Never expose provider secrets or make the browser own a paid job.
Which Krea 2 endpoints does Krea2 use?
Krea2 maps Medium to the Fal queue endpoint krea/v2/medium/text-to-image and Large to krea/v2/large/text-to-image. Both use the same public workbench controls, so switching model size does not require a different prompt shape in the UI.
The provider adapter is intentionally behind a workflow boundary. Application code selects the model and normalized controls; the adapter converts them into provider field names. This keeps billing, history, and retry behavior stable if the transport changes later.
| Product model | Fal queue endpoint | Typical stage |
|---|---|---|
| Krea 2 Medium | krea/v2/medium/text-to-image | Exploration |
| Krea 2 Large | krea/v2/large/text-to-image | Refinement |
What parameters are sent?
The prompt is required. Krea2 also sends aspect_ratio and creativity. When reference images exist, the adapter maps them to image_style_references objects with an image_url and a strength. The workbench accepts up to five references even though the underlying hosted model may support a larger limit; the smaller product limit keeps the interface and upload lifecycle manageable.
The API boundary validates values before the workflow starts. Validation prevents unsupported ratios, unknown creativity values, oversized prompts, or untrusted reference shapes from becoming paid provider requests.
| Field | Required | Krea2 behavior |
|---|---|---|
| prompt | Yes | Validated creative direction |
| aspect_ratio | Yes | One of eight supported ratios |
| creativity | Yes | raw, low, medium, or high |
| image_style_references | No | Uploaded HTTPS references with strength |
| model | Yes | Medium or Large product selection |
Example Fal queue request body
json{
"prompt": "A chrome bicycle above a salt lake...",
"aspect_ratio": "16:9",
"creativity": "medium",
"image_style_references": [
{
"image_url": "https://uploads.example/reference.webp",
"strength": 1
}
]
}How do you submit and poll a Krea 2 job?
Fal returns a request_id for queued work. Persist that identifier with the internal generation record before the next network step. Status checks use the base model endpoint, and a completed status provides a response URL from which the final image can be retrieved.
Polling belongs inside a durable workflow rather than a browser tab. A tab can close, a device can sleep, and an edge request can time out. The workflow can retry provider checks, preserve progress, and finish the same generation without depending on the original page.
- 1Validate prompt, model, creativity, ratio, reference count, and user entitlement.
- 2Create an internal generation record with a stable idempotency boundary.
- 3Submit to the selected Fal Krea 2 endpoint with the server-side FAL_KEY.
- 4Persist the returned request_id before beginning status polling.
- 5Poll the base endpoint until completed, failed, or the workflow retry policy ends.
- 6Store the output in the dedicated Krea2 R2 bucket and mark the record complete.
- 7Refund the credit debit exactly once when a terminal failure qualifies for a refund.
What can fail in a Krea 2 integration?
Provider submission, status polling, result retrieval, storage, and database persistence are separate failure points. Treating them as one browser request makes recovery ambiguous. A durable record should state which step owns the next retry and whether the user has already been charged or refunded.
| Failure | Safe response | Do not |
|---|---|---|
| Submission rejected | Record provider error and refund once | Retry an invalid request forever |
| Polling timeout | Retry from the saved request ID | Create a second paid request |
| Completed without image | Mark failed and preserve evidence | Pretend the task succeeded |
| R2 write failure | Retry storage with the same output URL | Charge for another generation |
| Duplicate callback | Use idempotent completion | Apply credits twice |
How should references and secrets be handled?
Upload references to the dedicated Krea2 R2 bucket and pass short-lived or controlled HTTPS URLs to the provider. Validate file type, size, count, and ownership before submission. Do not let arbitrary remote URLs become a server-side fetch path without allow-listing and request protections.
FAL_KEY is a Worker secret and must never enter client JavaScript, Git, logs, or analytics. The browser calls the Krea2 server function, which validates the request and starts the workflow. Provider responses should be logged with identifiers and bounded error text, not secret-bearing headers or full sensitive payloads.
How should Krea 2 API pricing map to credits?
Provider prices and request shapes can change. Krea2 therefore exposes a product credit amount before Generate and keeps pricing policy separate from the raw adapter. Credit cost should cover the most expensive enabled form of the selected model, including reference inputs when they change provider cost.
Do not hard-code a volatile provider dollar amount into evergreen guidance without a source and update process. For purchasing decisions, verify the current official or hosting-provider price. For user experience, show the current Krea2 credit charge in the workbench before submission and preserve it on the generation record.
- Version credit rules when model economics change.
- Store the charged amount with each generation for later reconciliation.
- Keep provider cost and retail credit policy as separate concepts.
- Test duplicate submit, retry, completion, and refund paths before enabling payments.
Practical questions
Krea 2 API guide FAQ
Is this the official Krea 2 API documentation?
No. This is an independent implementation guide describing how Krea2 integrates hosted Krea 2 endpoints through Fal. Verify official model access, terms, and current provider fields before building your own integration.
Which Krea 2 API models does Krea2 expose?
Krea2 exposes Krea 2 Medium for exploration and Krea 2 Large for refinement through separate Fal queue endpoints.
Why does Krea2 use a workflow instead of waiting in the browser?
A durable workflow survives refreshes and timeouts, preserves the provider request ID, and makes retries, completion, credit debit, and refunds idempotent.
Where should the Fal API key be stored?
Store FAL_KEY as a Cloudflare Worker secret. Never expose it in client JavaScript, committed environment files, analytics, or user-visible error messages.