API Access

API Key

Get your api key here https://dashboard.ravenra.io/api-dashboard

Base URL

https://api.ravenra.io

Headers

Content-Type: application/json
Authorization: Include if your environment requires it (for example: x-api-key: <YOUR_API_KEY>)

Workflow Overview

Text-to-3D generation (Preview)
Poll task status to retrieve results
Optional refinement step for texturing/colorizing
Text-to-Image generation
3D-from-Image generation (Preview)

Common Response Fields

Field

Type

Description

id

string

Internal identifier for the record.

taskId

string

The external task identifier to use when polling for results.

status

string

Processing status (e.g., IN_PROGRESS).

obj_url

string or null

URL to the generated OBJ file (when available).

created_at

string

ISO timestamp when the task was created.

updated_at

string

ISO timestamp when the task was last updated.

created_by

string

Creator identifier.

thumbnail_url

string or null

URL to a preview/thumbnail image (when available).

texture_url

string or null

URL to textures (when available).

mtl_url

string or null

URL to the MTL file (material library) for OBJ (when available).

progress

number

A numeric indicator of task progress.

image_source_url

string or null

If an image source was used, the resolved URL (when available).

type

string

Task type (e.g., text-to-3d).

prompt

string

The original prompt.

parent_task_id

string or null

Reference to a parent task (for refinement flows).

Notes:

Poll with the taskId.
Treat non-null asset URLs (obj_url, texture_url, thumbnail_url, mtl_url) as signals that output is ready.
progress increases during processing; use it to inform UI updates.

Endpoints

1) Create Task: Text to 3D (Preview)

URL: https://api.ravenra.io/task/create-task
Method: POST
Use case: Kick off a text-to-3D generation in preview mode.

Request payload:

{
  "prompt": "string",
  "mode": "preview"
}

Response:

{
  "id": "string",
  "taskId": "string",
  "status": "string",
  "obj_url": "string|null",
  "created_at": "string",
  "updated_at": "string",
  "created_by": "string",
  "thumbnail_url": "string|null",
  "texture_url": "string|null",
  "mtl_url": "string|null",
  "progress": 0,
  "image_source_url": "string|null",
  "type": "string",
  "prompt": "string",
  "parent_task_id": "string|null"
}

Example request:

curl -X POST https://api.ravenra.io/task/create-task \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A detailed 3D model of a heroic male warrior for an RPG game, muscular build, wearing medieval fantasy armor with leather straps, metal breastplate, shoulder guards, and a long cape flowing behind. He carries a large sword on his back and a round shield strapped to his arm. Rugged face with short hair and a small scar across his cheek. Stylized in a semi-realistic RPG style, optimized for game characters, PBR textures, low-poly base with high-poly details for baking.",
    "mode": "preview"
  }'

Example response:

{
  "id": "a11a5ae4-d161-446a-920a-7b00c1398590",
  "taskId": "0199392c-ccb4-7ec7-9ebe-2ddd06c704b5",
  "status": "IN_PROGRESS",
  "obj_url": null,
  "created_at": "2025-09-11T14:27:43.821Z",
  "updated_at": "2025-09-11T14:27:43.821Z",
  "created_by": "oii2k6qf0djwu8zrnigkppk2m6f6q1x8",
  "thumbnail_url": null,
  "texture_url": null,
  "mtl_url": null,
  "progress": 0,
  "image_source_url": null,
  "type": "text-to-3d",
  "prompt": "A detailed 3D model of a heroic male warrior for an RPG game, muscular build, wearing medieval fantasy armor with leather straps, metal breastplate, shoulder guards, and a long cape flowing behind. He carries a large sword on his back and a round shield strapped to his arm. Rugged face with short hair and a small scar across his cheek. Stylized in a semi-realistic RPG style, optimized for game characters, PBR textures, low-poly base with high-poly details for baking.",
  "parent_task_id": null
}

2) Get Task Result (Poll)

URL: https://api.ravenra.io/task/result/:task-id
Method: GET
Use case: Poll to check task status and retrieve asset URLs.

Example:

curl https://api.ravenra.io/task/result/0199392c-ccb4-7ec7-9ebe-2ddd06c704b5

Response (shape):

{
  "id": "string",
  "taskId": "string",
  "status": "string",
  "obj_url": "string|null",
  "created_at": "string",
  "updated_at": "string",
  "created_by": "string",
  "thumbnail_url": "string|null",
  "texture_url": "string|null",
  "mtl_url": "string|null",
  "progress": 0,
  "prompt": "string",
  "parent_task_id": "string|null",
  "type": "string",
  "image_source_url": "string|null"
}

Tips:

Poll every 3–10 seconds.
Consider the task ready when the relevant URLs (e.g., obj_url, texture_url) are non-null.

3) Create Task: Texturized / Colorized (Refine)

URL: https://api.ravenra.io/task/create-task
Method: POST
Use case: Refine a preview 3D task to add textures or colorization.

Request payload:

{
  "prompt": "string",
  "mode": "refine",
  "preview_task_id": "string"
}

Response:

{
  "id": "string",
  "taskId": "string",
  "status": "string",
  "obj_url": "string|null",
  "created_at": "string",
  "updated_at": "string",
  "created_by": "string",
  "thumbnail_url": "string|null",
  "texture_url": "string|null",
  "mtl_url": "string|null",
  "progress": 0,
  "image_source_url": "string|null",
  "type": "string",
  "prompt": "string",
  "parent_task_id": "string|null"
}

Example request:

curl -X POST https://api.ravenra.io/task/create-task \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Apply PBR textures and finalize materials for game-ready export.",
    "mode": "refine",
    "preview_task_id": "0199392c-ccb4-7ec7-9ebe-2ddd06c704b5"
  }'

4) Text to Image

URL: https://api.ravenra.io/task/text-to-image
Method: POST
Use case: Generate an image from a text prompt.

Request payload:

{
  "prompt": "string"
}

Response:

{
  "id": "string",
  "taskId": "string",
  "status": "string",
  "obj_url": "string|null",
  "created_at": "string",
  "updated_at": "string",
  "created_by": "string",
  "thumbnail_url": "string|null",
  "texture_url": "string|null",
  "mtl_url": "string|null",
  "progress": 0,
  "image_source_url": "string|null",
  "type": "string",
  "prompt": "string",
  "parent_task_id": "string|null"
}

Example request:

curl -X POST https://api.ravenra.io/task/text-to-image \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Epic fantasy warrior concept art, semi-realistic, dramatic lighting"
  }'

Note:

For image generation tasks, look for thumbnail_url or similar fields for the output image.

5) Create Task: 3D from Image (Preview)

URL: https://api.ravenra.io/task/create-task
Method: POST
Use case: Generate a 3D model using a text prompt plus an image reference.

Request payload:

{
  "prompt": "string",
  "mode": "preview",
  "image_source": "string"
}

image_source: Provide a string pointing to your image source. In most setups this is a publicly accessible image URL.

Response:

{
  "id": "string",
  "taskId": "string",
  "status": "string",
  "obj_url": "string|null",
  "created_at": "string",
  "updated_at": "string",
  "created_by": "string",
  "thumbnail_url": "string|null",
  "texture_url": "string|null",
  "mtl_url": "string|null",
  "progress": 0,
  "image_source_url": "string|null",
  "type": "string",
  "prompt": "string",
  "parent_task_id": "string|null"
}

Example request:

curl -X POST https://api.ravenra.io/task/create-task \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Create a low-poly 3D model with PBR-ready UVs inspired by this reference.",
    "mode": "preview",
    "image_source": "https://example.com/reference.jpg"
  }'

Implementation Tips

Polling:
- Start polling immediately after receiving taskId.
- Back off your polling interval if needed (e.g., 3s → 5s → 10s).
- Consider a timeout to fail gracefully in UI/clients.
Completion detection:
- Consider the task complete when required asset URLs are present (e.g., obj_url and texture_url).
- status will also update when processing finishes. The exact list of possible statuses may vary.
File handling:
- obj_url points to the OBJ mesh.
- mtl_url is the material library for OBJ.
- texture_url may point to a texture bundle or a specific texture asset.
- thumbnail_url is useful for quick previews in UI.

Minimal Client Examples

JavaScript (fetch):

async function createTextTo3D(prompt) {
  const res = await fetch("https://api.ravenra.io/task/create-task", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ prompt, mode: "preview" })
  });
  return res.json();
}

async function pollResult(taskId) {
  const url = `https://api.ravenra.io/task/result/${taskId}`;
  const res = await fetch(url);
  return res.json();
}

Python (requests):

import time
import requests

BASE = "https://api.ravenra.io"

def create_text_to_3d(prompt: str):
    r = requests.post(f"{BASE}/task/create-task", json={"prompt": prompt, "mode": "preview"})
    r.raise_for_status()
    return r.json()

def get_result(task_id: str):
    r = requests.get(f"{BASE}/task/result/{task_id}")
    r.raise_for_status()
    return r.json()

def wait_for_assets(task_id: str, interval=5, timeout=600):
    start = time.time()
    while time.time() - start < timeout:
        res = get_result(task_id)
        if res.get("obj_url") or res.get("thumbnail_url") or res.get("texture_url"):
            return res
        time.sleep(interval)
    raise TimeoutError("Task did not complete within the expected time window.")

PreviousGenerative Technologies NextSecurity and Uptime

Last updated 4 minutes ago